# Skill: co-op

Multi-phase plan protocol with color-coded teammate Claudes and evidence captured in the plan file as you go.

## To install

1. Save this file to `~/.claude/skills/co-op/SKILL.md`
2. Restart Claude Code
3. Trigger with `/co-op start <plan-path>`, `/co-op next`, or `/co-op status`

---

---
name: co-op
description: "Co-op mode protocol — run multi-phase plans with checkpoints, evidence in place, and optional team mode (1 Lead + up to 3 teammate Claudes, color-coded). Triggered by /co-op, /coop, or any subcommand below."
user-invocable: true
trigger: /co-op
---

# Co-op Mode

**Trigger:** `/co-op` or `/coop` (alias) — subcommands: `start <plan-path>` | `next` | `status` | `block "reason"` | `revisit` | `claim <id>` | `release <id>` | `assign <id> <color>` | `sync` | `verify` | `team-up` | `team-down`

Co-op mode is the protocol for you and Claude to work through a multi-phase plan together — one atomic step at a time, with evidence captured in the plan file as you go. Plans live in `plans/co-op/`. The plan file is the source of truth; chat history is not.

Co-op runs in one of two modes:

- **Solo mode** (default) — one Claude session + one human. Original protocol.
- **Team mode** — one Lead Claude session + up to 3 teammate Claude sessions + one human. Lead orchestrates; teammates execute claimed rows. Use for plans with independent parallel workstreams.

---

## Agent Identity — Color Vocabulary

Every session operates under one color ID. Colors map to the user's window colors so visual scan matches the plan file.

| Color | Role | Who |
|---|---|---|
| **P** | Driver / human | The user — always |
| **G** | Lead (default) | Claude — orchestrator, assigns rows, merges state, runs builds |
| **B** | Teammate | Claude — executes claimed rows only |
| **Y** | Teammate | Claude — executes claimed rows only |
| **O** | Teammate | Claude — executes claimed rows only |

Rules:

- **P never takes a Claude role.** The user drives the Lead (G) through prompts; G delegates to B/Y/O.
- **Lead is fixed for the plan's lifetime.** Default Lead = G. Only change at plan start, never mid-flight. If the Lead session dies, a new G session resumes from the plan file.
- **Teammates take orders only from Lead.** The user can observe teammate windows but routes all coordination through the Lead window to keep state consistent.
- **One team per plan.** Don't spawn overlapping teams across plans. Finish or `/co-op team-down` first.
- **Solo mode uses G** by default — single Claude session = G, acts as its own Lead.

---

## Session Start Protocol (`/co-op start <plan-path>`)

1. **New chat required.** Co-op sessions start in a fresh Claude Code chat. Opening message should be: `/co-op start plans/co-op/<filename>.md`
2. **Confirm Opus + 1M context.** Verify model is Opus (1-million-token context) — critical for holding the full plan + state files without mid-session compaction.
3. **Read the plan file** in full. Also read any state files it references.
4. **Revisit blocked steps.** Check every `[⏸]` row. Log a dated comment under each: "YYYY-MM-DD: revisited — [still blocked / now unblocked because X]". Flag any that can now proceed.
5. **Surface third-party flags.** Scan plan for `[3P:...]` markers. List them at session start: "Steps X, Y, Z are flagged for third-party tools — handle those outside this chat."
6. **Announce first unchecked step.** Identify the first `[ ]` row, read it aloud, confirm owner + verification criteria. Ask: "Ready to start?"

---

## Step Execution Loop (`/co-op next`)

For each step:

1. **Brief the step** — restate the action, owner, verify criteria, expected result format
2. **Execute or wait:**
   - Owner = Claude → execute (read files, write code, run commands) and capture output
   - Owner = user → wait for the user to act in UI, paste result/screenshot
   - Owner = both → Claude runs its part first, then waits
3. **Verify** — confirm verification criteria met. If not: diagnose, do not advance
4. **Document in place** — edit the plan file:
   - Flip `[ ]` → `[x]`
   - Fill `Result:` field with evidence (commit SHA, log line, "verified" + date, screenshot ref)
   - Add a dated comment if anything unexpected was found
5. **Announce next step** or report "session complete — blocked on: X, next: Y"

---

## Context Check & Clean Reset (mid-session hygiene)

Long co-op sessions compact mid-flight and quality degrades. Because the plan file IS the handover artifact, resets are cheap — but only if timed correctly. Execute this check at every natural break.

### When to run the context check

Run after **any of**:
- A phase boundary is crossed (e.g., Phase 0 → Phase 1)
- A decision was committed to the plan file
- A major chunk of code was read/written (heavy file reads + edits)
- The user signals fatigue or a shift ("let's come back to this", "ok next area", "new chat?")
- 10+ `/co-op next` steps have been executed in the current chat
- You notice your own recent responses are getting vaguer, repeating earlier context, or losing thread

### The check itself (run silently, report only if action needed)

1. **Plan file fully up to date?** Every completed step this session has `[x]`, Result filled, dated comment where applicable. If no → bring it up to date before anything else.
2. **Any committed decision still uncaptured in your decision log?** → capture it before resetting.
3. **Any `[⏸]` logged with today's date?** → good.
4. **Any uncommitted code changes?** → either commit or note state in plan as a dated comment. Never reset with dirty state unreferenced in the plan.
5. **Context weight judgment:** given thread length + files read + decisions made, is quality likely to start degrading soon?

### Safe vs unsafe reset points

| Safe to reset | Unsafe to reset |
|---------------|-----------------|
| Phase boundary just crossed | Mid-step, mid-debug, mid-edit |
| Decision committed to plan | Holding un-committed findings from a recent tool call |
| Just finished a `/co-op next` fully | In the middle of reconciling a conflict |
| User signalled a shift | User is actively waiting on a result |

Never suggest a reset with any of the unsafe conditions present. Finish the unit of work first.

### How to suggest the reset

When a safe reset point hits and context is heavy:

> **Context reset checkpoint.** We're at a clean boundary: [phase X complete / decision committed / Y steps done]. Plan file is up to date, blocked steps logged. Safe to start a fresh chat to preserve quality. Want to reset now or push further?

Then emit a **copy-paste handoff prompt** in a fenced code block:

```
/co-op start plans/co-op/<same-file>.md

Context from previous session ({YYYY-MM-DD}, {color}):

**What shipped:** {1-3 bullet points with commit range}

**What's open:** {numbered list of unfinished items with file paths}

**Decisions made:** {any decisions the next session must respect}

**Parallel sessions:** {what other sessions are working on}

**Start here:** {first unchecked step ID + description}
```

Wait for the user's call. Never reset unilaterally.

### Handover = the plan file only

This is the core invariant. A fresh session must be able to resume **from the plan file alone**. That means:

- No secondary "handover notes" doc
- No "remember to..." messages to future-Claude
- No state living in the chat that isn't also in the plan file

If you find yourself wanting to write a handover note, that's a signal the plan file is missing a dated comment. Add it there instead.

---

## Status Report (`/co-op status`)

Print:
- Total steps: X done / Y total / Z blocked
- Blocked steps (each with blocker name + date first blocked)
- Next unchecked step
- Any `[3P]` steps not yet actioned

---

## Block a Step (`/co-op block "reason"`)

Mark current step `[⏸]` with:
```
[⏸] blocked on: <reason> — <YYYY-MM-DD>
```
Log a comment inline: "YYYY-MM-DD: blocked — <reason>. Will revisit at next session start."
Advance to next unblocked step automatically.

---

## Revisit Blocked Steps (`/co-op revisit`)

Sweep all `[⏸]` rows. For each:
- Log dated revisit comment
- If unblocked: convert to `[ ]` and brief it to the user
- If still blocked: log "still blocked, next revisit: next session"

Blocked steps are never silently abandoned. They get a dated log entry every time they are visited. Nothing rots.

---

## Checkbox Legend

| Symbol | Meaning |
|--------|---------|
| `[ ]` | Not started — unclaimed |
| `[→G]` / `[→B]` / `[→Y]` / `[→O]` | Claimed, in progress by named teammate |
| `[x]` | Complete — evidence recorded |
| `[~]` | Skipped — reason logged inline |
| `[⏸]` | Blocked — blocker named, date logged |
| `[3P]` | Flagged for third-party tool (ChatGPT / Gemini / Codex / Fresh-CC) |

---

## Team Mode Protocol

### Plan header block (required for team mode)

Every team-mode plan file begins with:

```
## Team Config
- Lead: G
- Team: G, B, Y, O
- Permissions: Lead=edit, B=edit, Y=edit, O=read
- Plan branch: co-op/<slug>
- Mode: team
```

Solo-mode plans omit this block or set `Mode: solo`.

### Step template (team mode adds `Touches:`)

```
- [ ] **PhaseN.M — Action title**
  - Owner: G / B / Y / O / P / Both
  - Touches: <file paths this step will read or edit>
  - Verify: <how we know this is done>
  - Result: _pending_
```

`Touches:` is **mandatory in team mode**. Lead uses it to detect collision risk before assigning. Two unfinished rows touching the same path cannot run parallel — Lead sequences them.

### Shared-file lock list (Lead-only edits)

No teammate ever edits these. Lead owns them. Adapt this list for your project:

- `package.json`, `package-lock.json`, `tsconfig.json`
- `CLAUDE.md`, top-level state/config files
- Shared utility libraries
- Database migration directories
- Environment config files

Teammates that need a shared-file change propose the diff in a dated comment on their row; Lead applies it.

### Build / dev-server rule

Only Lead runs `npm run build`, `npm run dev`, lint, or any long-running process. Teammates propose and wait. Prevents port collisions, build cache thrash, and two `dev` servers competing for the same port.

### Claim protocol

Before a teammate executes a row:

1. `git pull --rebase` on the plan branch
2. Edit row `[ ]` → `[→<color>]`, save plan file
3. `git add <plan> && git commit -m "claim: PhaseN.M (<color>)" && git push`
4. If push rejected (someone else claimed), re-pull, pick another row
5. Execute the row
6. Commit + push code changes after each atomic edit (not at end of row)
7. On completion: flip `[→<color>]` → `[x]`, fill Result, commit, push

No row is ever edited without first holding a `[→<color>]` claim. No concurrent claims on the same row.

### Lead duties (each `/co-op next` cycle)

1. `/co-op sync` — pull latest plan + all teammate commits
2. `/co-op verify` — sweep `[→<color>]` rows older than 10 min, check git log for actual commits, flip stale ones to `[x]` or nudge the teammate
3. Scan unclaimed `[ ]` rows for collision-free candidates (no `Touches:` overlap with in-flight rows)
4. Assign next batch: `/co-op assign <id> <color>` — writes owner to plan
5. Report to the user: "Batch dispatched — G: PhaseN.M, B: PhaseN.N, Y: idle, O: idle"
6. Wait for teammate completions, re-sync, repeat

### When to use team mode vs solo

**Use team mode when:**
- Plan has ≥2 independent workstreams (different domains, different files, different subsystems)
- Each workstream has ≥3 rows of real work (otherwise orchestration overhead dominates)
- Shared-file edits are <20% of total rows

**Stay in solo when:**
- Plan is linear (each step depends on the previous)
- Most work touches shared files
- Debug or investigation mode — solo is faster when you don't know what you're looking for
- First run of a new plan pattern — prove it solo before parallelizing

---

## Third-Party Tool Routing

When a step is marked `[3P:Tool]`, surface it at session start. The user handles it outside this chat, then pastes the output summary back. Do not attempt to replicate third-party tasks in this session.

| Marker | When to use |
|--------|-------------|
| `[3P:ChatGPT]` | PDF read, long doc extraction, multi-image screenshot interpretation |
| `[3P:Gemini]` | Red-team / steelman / second opinion / deep web research |
| `[3P:Codex]` | Boilerplate generation, large mechanical refactors, find/replace at scale |
| `[3P:Fresh-CC]` | Independent code review by a parallel Claude Code session |

### Escalation rule — call in a third party after 2 failed attempts

**If Claude's attempted fix fails 2 times on the same underlying problem within a co-op session, stop fixing and escalate to a third-party LLM for a second opinion before attempting a third fix.**

**Why:** context blindness compounds. When Claude is wrong about the shape of a problem, each subsequent fix is built on the same wrong model. A fresh LLM with no prior-attempt baggage can see the issue from a different angle in one shot, and web-search-enabled models (Gemini, ChatGPT with browsing) can surface platform-specific documentation Claude's training data misses.

**How to apply:**
1. Count fix attempts per problem (not per turn). A "fix attempt" = a concrete code or config change intended to resolve the issue, tested, and observed to fail.
2. After attempt #2 fails, Claude writes a **self-contained third-party brief** and hands it to the user.
3. The user pastes the brief into Gemini / ChatGPT / Codex. Web-search-enabled models preferred for platform-specific issues.
4. Third party returns analysis → user pastes back → Claude incorporates findings and writes attempt #3 informed by the second opinion.
5. Do not dismiss the third party's answer without testing it, even if it contradicts Claude's mental model — that contradiction is the whole point of escalation.

**Third-party brief format (Claude writes this):**
- **Stack:** language, framework, deployment, relevant services
- **Goal:** what behavior is desired in one sentence
- **Current setup:** code excerpts, config, workflow details
- **Observed behavior:** what happens, verbatim error messages / responses
- **What we've tried:** each failed attempt with the reasoning behind it
- **Question:** one specific question for the third party to answer
- **Constraints:** what's off the table

Brief should be complete enough that the third party needs zero shared context. Assume fresh eyes.

---

## Rules

- Never skip a step without `[~]` + reason
- Never mark `[x]` without evidence
- Never let a `[⏸]` go unvisited for more than one session
- Never expand scope silently — add sub-steps inline and flag them to the user
- One step at a time — do not race ahead
- Session ends with a status report, always

---

## Writing a New Co-op Plan

When starting a new multi-phase build that will use co-op mode:

1. Write the plan to `plans/co-op/YYYY-MM-DD-<slug>.md`
2. Format each phase as a flat checklist (one checkbox per atomic action)
3. Each step must have: action (imperative), owner (user/Claude/both), verify criteria, result field (blank)
4. Flag `[3P:Tool]` on any step where a third-party tool saves tokens or provides better output
5. Flag `[⏸]` with blocker name on any step known to be blocked at plan creation time

**Step template:**
```
- [ ] **PhaseN.M — Action title**  [3P:Gemini if applicable]
  - Owner: User / Claude / Both
  - Verify: <how we know this is done>
  - Result: _pending_
```