multi-agent

中文文档：README.zh.md

A Claude Code skill for local parallel agent orchestration. Spawn multiple AI agents that work on independent tasks simultaneously — each in an isolated workspace, coordinated through contracts, with a full audit trail.

---

Why this exists

Most AI coding workflows are sequential: one agent, one task, one file at a time. This skill breaks that constraint. You define a task graph, and multiple agents execute in parallel — each owning its own files, communicating through shared interface contracts, and reporting structured results for audit.

The core insight: plan quality determines output quality. Cheaper CLI agents (codex, claude) running in parallel can match or exceed a single expensive model, if the plan is precise enough.

---

How it works

You (CC orchestrator)
  │
  ├── Phase 0: preflight.sh        ← checks tmux, jj, agent CLI
  ├── Phase 1: plan-builder skill  ← produces plan.json + global.md
  ├── Phase 2: jj workspaces       ← one isolated dir per agent
  ├── Phase 3: spawn-agent.sh ×N   ← launches agents in tmux windows
  ├── Phase 4: poll-agents.sh      ← monitors heartbeat + completion
  ├── Phase 5: audit               ← 4-dimension output review
  ├── Phase 6: jj merge            ← combines all agent changes
  └── Phase 7: cleanup.sh          ← archives + removes workspaces

Workspace isolation via jj

Each agent gets its own Jujutsu workspace — a lightweight alternative to git worktrees. Agents write files freely without stepping on each other. At merge time, all changes are combined into a single commit.

/tmp/workspaces/
  t1/   ← agent t1 works here (e.g. src/api/viral.ts)
  t2/   ← agent t2 works here (e.g. src/components/ViralCard.tsx)

No shared mutable state. No concurrent write conflicts.

Contract-based coordination

When agents need to share interfaces (e.g. t1 writes an API, t2 consumes it), they communicate through contract files:

/tmp/agent-bus/contracts/
  api-spec.md   ← t1 writes this after implementing the API
                ← t2 reads this before implementing the UI

watch-contracts.sh monitors the contracts directory. When t1 writes a contract, t2 gets a notification in its notices/ directory automatically — no polling, no shared memory.

Three-tier context architecture

Each agent receives the minimum context needed — nothing more:

Tier 1  global.md        shared by all agents (tech stack, conventions)
        plan.json        task graph, file ownership, dependencies

Tier 2  {id}/context.md  per-agent: role, files, contracts, task description

Tier 3  {id}/output.md   written by agent on completion (audit target)

DAG scheduling

Tasks declare dependencies via depends_on. spawn-agent.sh waits for upstream tasks before starting downstream ones — no manual coordination needed.

{ "id": "t2", "depends_on": ["t1"] }

Three-level heartbeat monitoring

poll-agents.sh tracks agent health passively (via tmux pane content hash) and actively (via heartbeat file):

< 2 min no heartbeat          →  soft timeout: snapshot pane, keep watching
< 5 min + pane idle           →  hard timeout: mark STALLED, log it
  30 min total elapsed        →  total timeout: mark TIMEOUT, stop

Audit + Critic Loop

After all agents complete, CC audits each output.md across four dimensions:

1. Verification — did verify_cmd pass?
2. Coverage — does every task requirement have a corresponding change?
3. File boundary — did the agent stay within its assigned files?
4. Contract consistency — does the implementation match the contract definitions?

Failures trigger exponential backoff retry (1 min → 2 min → 4 min), max 3 attempts. After 3 failures, pause and notify user.

---

Prerequisites

Run preflight.sh before first use — it checks everything and guides installation:

zsh ~/.claude/skills/multi-agent/scripts/preflight.sh

Tool	Purpose	Install
tmux	Parallel agent windows	brew install tmux
jj	Isolated workspaces	brew install jj (auto-installed by skill)
codex or claude CLI	Agent process	npm i -g @openai/codex or npm i -g @anthropic-ai/claude-code

---

Quick start

# 1. Run preflight
zsh ~/.claude/skills/multi-agent/scripts/preflight.sh

# 2. Use plan-builder skill to generate plan.json + global.md
#    (CC handles this — just describe your task)

# 3. Initialize jj workspaces
jj git init --colocate /path/to/project
jj -R /path/to/project workspace add /tmp/workspaces/t1
jj -R /path/to/project workspace add /tmp/workspaces/t2

# 4. Spawn agents
SCRIPTS=~/.claude/skills/multi-agent/scripts
PARENT_PANE=$(tmux display-message -p '#{pane_id}')
zsh "$SCRIPTS/watch-contracts.sh" "$PARENT_PANE" &
zsh "$SCRIPTS/spawn-agent.sh" t1 /tmp/workspaces/t1 "implement API layer" "$PARENT_PANE"
zsh "$SCRIPTS/spawn-agent.sh" t2 /tmp/workspaces/t2 "implement UI components" "$PARENT_PANE"

# 5. Poll until done
zsh "$SCRIPTS/poll-agents.sh" t1 t2

# 6. Merge + cleanup
T1=$(jj -R /tmp/workspaces/t1 log -r @ --no-graph -T 'change_id.short()')
T2=$(jj -R /tmp/workspaces/t2 log -r @ --no-graph -T 'change_id.short()')
jj -R /path/to/project new "$T1" "$T2" -m "feat: merge agent changes"
zsh "$SCRIPTS/cleanup.sh" /path/to/project my-plan t1 t2

---

Configuration

All behavior is controlled via config.sh — no code changes needed:

AGENT_CLI=codex                # codex | claude
AGENT_TIMEOUT_SECS=1800        # 30 min total timeout per agent
HEARTBEAT_SOFT_TIMEOUT=120     # 2 min soft timeout
HEARTBEAT_HARD_TIMEOUT=300     # 5 min hard timeout
CLAUDE_SKIP_PERMISSIONS=false  # ⚠️ set true only in trusted environments
INJECT_LANG=en                 # en | zh

---

Scripts

Script	Role
preflight.sh	Dependency check with guided installation
spawn-agent.sh	Launch one agent: generate context → register claims → open tmux window → inject task
poll-agents.sh	Monitor all agents: heartbeat tracking, timeout levels, TASK_UPDATE detection
watch-contracts.sh	Background watcher: detect contract changes, notify dependent agents via file
gen-context.py	Generate per-agent context.md from plan.json
register-claims.py	Atomic file ownership registration (fcntl-locked)
retry-agent.sh	Partial retry: clean one agent's state and re-spawn without rerunning others
cleanup.sh	Archive output → jj commit → remove workspaces → close tmux windows

---

Documentation

• English reference: references/
• 中文参考文档: references/zh/