collab

Files (1)

• SKILL.md

SKILL.md (first lines)

# Structured Research & Collaboration Protocol (V3)

Reusable protocol for structured research, design, and multi-agent collaboration in any repo.

Use this when:
- two agents work on the same topic
- you need auditable decisions and explicit convergence
- you want it to work in both sequential and parallel runs
- you start with one agent and may add a second agent later

Born from real collaboration sessions. V3 adds Live Mode for continuous user-driven sessions, based on retro from the CLI mode design collaboration.

## Two Operating Modes

### Round Mode (batch convergence)

Use when agents work asynchronously or need formal agreement on architecture-level changes.

Flow: draft → review → merge → signoff (same as V2).

### Live Mode (continuous collaboration)

Use when the user is actively driving the session, decisions emerge in conversation, and direction changes frequently.

Flow: research notes → decisions logged immediately → signoff when direction stabilizes.

**When to use which:**
- **Live Mode**: user is present, fast-moving design discussion, decisions made in real-time
- **Round Mode**: offline review, major redesign checkpoint, formal disagreement resolution
- You can switch between modes within a session. A live session can trigger a mini-round when there's real disagreement.

## Workspace Location

All collaboration artifacts live in `.local/collab/{topic}/` within the target repo. This directory is **gitignored** — collaboration artifacts are ephemeral working state, not permanent documentation. Ensure `.local/` is in the repository's `.gitignore` before starting.

The durable output is the code itself (committed) and optionally `PLAN.md` if the team wants to preserve the plan alongside the implementation.

## Quick Start

1. Create workspace in target repo:
   - `.local/collab/{topic}/`
2. Create `SESSION.md` (human-owned):
   - Goal, scope, deliverable, agents, merge owner, operating mode.
3. Create `DECISIONS.md` (append-only) and `rounds/r1/`.
4. Follow the flow for your operating mode (see below).

### Round Mode Flow

1. Each agent writes its own draft (`codex.md` / `claude.md`).
2. Each agent reviews the other draft (`*_review.md`), addressing every numbered point.
3. Merge owner writes `merged.md` after both reviews exist.
4. Both agents sign off (`signoff_*.md`) with explicit coverage mapping.
5. Update `PLAN.md` from accepted `merged.md`.

### Live Mode Flow

1. Agents write research notes as needed (`<agent>_<topic>.md`).
2. Decisions are logged to `DECISIONS.md` immediately when made (see Decision Capture SLA).
3. When direction stabilizes, merge owner writes `merged.md` summarizing the agreed state.
4. Both agents sign off.
5. Update `PLAN.md` from accepted `merged.md`.

## Artifact Taxonomy

Every file in a round must declare its type at the top:

| Type | Purpose | Naming |
|------|---------|--------|
| `position` | Agent's stance/draft on the topic | `<agent>.md` |
| `review` | Review of another agent's position | `<agent>_review.md` |
| `research-note` | Mid-round analysis that isn't a position or review | `<agent>_<topic>.md` |
| `merge` | Converged direction (merge owner only) | `merged.md` |
| `signoff` | Explicit approval with coverage mapping | `signoff_<agent>.md` |

Research notes are first-class artifacts. They feed into the eventual merge but don't require the formal review cycle. Use them for: analysis of code, exploration of options, responses to user questions, bootstrap/import mapping, etc.

## Target Structure

```text
.local/collab/{topic}/
  SESSION.md          # human-owned, read-only for agents
  DECISIONS.md        # append-only, shared
  PLAN.md             # authoritative implementation plan
  ARCHITECTURE.md     # optional: diagrams, component maps
  rounds/
    r1/
      codex.md                  # position
      claude.md                 # position
      codex_review.md           # review
      claude_review.md          # review
      codex_<topic>.md          # research-note (zero or more)
      claude_<topic>.md         # research-note (zero or more)
      merged.md                 # merge
      signoff_codex.md          # signoff
      signoff_claude.md         # signoff
```

## Roles and Ownership

- Human/coordinator writes `SESSION.md` and keeps it read-only for agents.
- Each agent edits only its own position/review/signoff/research-note files.
- Merge owner (set in `SESSION.md`) is the only writer of `merged.md`.
- Shared editable files: `DECISIONS.md`, `PLAN.md`.

## Rules

1. Never edit another agent's files.
2. Reviews must address every numbered point from the other draft.
3. No `merged.md` until both reviews exist (Round Mode) or direction has stabilized (Live Mode).
4. Signoff must map each review point to outcome (`addressed`, `dropped via D-xxx`, `escalated`).
5. Disagreements go to `DECISIONS.md`; unresolved items are `ESCALATE`.
6. New round only for substantial redesign; minor issues stay in current round.
7. **Decision Capture SLA**: any non-trivial decision must be written to `DECISIONS.md` within the same interaction cycle it was made. Do not defer to signoff.
8. **User decrees override agent consensus** without requiring a review cycle. Log immediately with `owner: user`.

## Decision Log

Use `DECISIONS.md` as append-only table:

From clemens33/dotfiles, MIT.

More from clemens33/dotfiles