Team

/team — Native Claude Code Teams Orchestrator

/team <goal> runs the closed-loop multi-agent protocol from ~/.claude/rules/agent-team-os.md end-to-end with native primitives. Replaces Shipwright; depends only on the Claude Code harness.

The protocol you run

1. SCOPE     — distill goal into 3–8 testable contracts (with user)
2. PLAN      — write the plan; identify which contracts are independent (parallel) vs sequential
3. SPAWN     — Agent tool with isolation: worktree, model: sonnet, tools scoped to role
4. WATCH     — TodoWrite tracks tasks; agents report back via TaskUpdate
5. VERIFY    — for each task close, spawn verifier (model: sonnet)
6. CRITIQUE  — every N completions, spawn critic to find half-fixes & cross-agent regressions
7. REFLEX    — recurring failures from same agent → spawn agent-tuner with /tune-agent
8. MERGE     — git diff each worktree, merge sequentially with tests between, surface conflicts
9. CLOSE     — write closing report + update knowledge + run /mine-transcripts on this session

Hard rules

• Never call TeamDelete, git worktree remove, or ExitWorktree until after all branches are merged. See rules/worktree-merge-before-cleanup.md.
• Never mark a task complete without RESULT_verifier=PASS.
• Never skip the critic on the closure of CRITICAL or REGRESSION-tagged tasks.
• Always keep the active task list in TodoWrite — every spawn updates it.
• Always report cost+token totals in the closing summary. If the run cost >$10, flag it.

Step-by-step

Step 1 — Scope (with user)

• Distill the goal into 3–8 testable contracts. Each contract is one sentence: "X must do Y when Z."
• If you can't list ≥3 contracts, the goal is too small for /team — just do it.
• Confirm with the user before spawning anyone.

Step 2 — Plan

• Group contracts into independent vs sequential clusters.
• For each cluster, decide: which specialist(s) handle this?
  • General task → general-purpose
  • Migration → migration-planner
  • Bug regression → regression-hunter
  • Perf → latency-profiler
  • Security → security-reviewer
  • (See ~/.claude/agents/ for the full roster — match agent description to task.)
• Write the plan inline in this conversation. Don't burn context with a separate plan file unless the user wants one.

Step 3 — Spawn

For each independent unit:

Agent({
  description: "<short description>",
  subagent_type: "general-purpose",  // or specialist
  isolation: "worktree",             // ALWAYS for implementation tasks
  prompt: "..."                       // include: contract, file paths, no-go zones, when to /verify
})

For parallel dispatch: emit multiple Agent calls in a SINGLE message. Don't sequentially await unless there's a real dependency.

Step 4 — Watch

• TodoWrite immediately after spawn: each task in_progress
• When an agent reports back, mark its task completed (after verify passes)
• If the user asks for a status, just TodoWrite view + a 2-line summary

Step 5 — Verify (per task close)

• Spawn /verify (which spawns the verifier agent)
• Read RESULT_verifier=...
• PASS → TodoWrite mark complete
• FAIL → keep task open, surface the failure, prompt the responsible agent to fix
• INCONCLUSIVE → escalate to user; do not silently pass

Step 6 — Critique (every 3 completions, or at fleet end)

• Spawn the critic agent (read-only) with the list of just-completed tasks
• Critic returns CRITICAL / HIGH / MED findings; CRITICAL ones become new tasks (CRITIC- prefix)
• Critic also checks for cross-agent regressions: did Agent A's change break Agent B's work?

Step 7 — Reflexion (only if pattern emerges)

• If verifier or critic finds the SAME failure mode from the SAME agent twice, that's a tuning candidate
• Spawn /tune-agent <agent-name> with the failure evidence
• It proposes a prompt patch; you (lead) approve or reject
• Approved patches land in the agent's .md with backup at ~/.claude/agents-history/

Step 8 — Merge

• git worktree list shows all branches
• For each: git diff <main>..<branch>, then merge
• After every merge, run the project's test suite — surface failures immediately
• DO NOT remove worktrees until all merges complete

Step 9 — Close

• Write a closing report to the conversation:
  • Goal recap, contracts satisfied (link to evidence)
  • Tasks: completed / deferred (with reason)
  • Critic findings: addressed / accepted as known issues
  • Cost / tokens / wall time
  • Lessons learned (auto-extracted from this session)
• Run /mine-transcripts --since 1h to capture this fleet's lessons
• Update ~/.claude/knowledge/connections/ if a new architectural insight emerged

Output discipline

• Status updates: 2 lines max per teammate update — don't paste their work back to the user
• Use TodoWrite as the source of truth, not chat narration
• Closing report under 500 words

Common failure modes you must avoid

1. Spawning a fleet for a 1-hour task — overhead exceeds value
2. Spawning agents without contracts — they thrash because they can't tell when they're done
3. Skipping verifier because "it obviously works" — that exact phrase has cost users tens of hours
4. Removing worktrees before merge — destroys all the agent's work
5. Critic running on unrelated work — scope the critic to just-closed tasks
6. Letting the critic loop run forever — cap at 3 critic passes; remaining findings become explicit deferred tasks