multi-agent-coordination

Multi-Agent Coordination

A reusable system for running multiple Claude Code terminals on the same project safely. Extracted from production use (Etihad CRM), generalized for any stack.

When to activate

Activate this skill when the user:

• Wants to run 2+ Claude Code sessions in parallel on one repo
• Asks about multi-agent / parallel-Claude / squad workflows
• Mentions file collisions between AI sessions
• Asks for a shared task board / kanban for AI agents
• Wants a planner+developer split (architect terminal vs coder terminals)
• Asks how to do file locking, approval gates, or commit coordination across AI sessions

The five core mechanics

1. Terminal roles — each session has an explicit role: Planner (label P — reviews, never writes code) or Developer (labels T1, T2, T3, … — implements). See references/terminal-roles.md.
2. File locks — active_files.md is a shared lock registry. Append a line before editing, remove after. Timestamped so stale locks expire. See references/lock-protocol.md.
3. Shared kanban — active_tasks.md has four sections (TODO / AWAITING REVIEW / BLOCKED / DONE). Single source of truth for what each terminal is doing. See references/lock-protocol.md (kanban section).
4. Approval gate — developers never commit until the planner has reviewed the uncommitted diff and explicitly approved. See references/approval-gate.md.
5. Git workflow — pick Variant A (per-task feature branches + PR) or Variant B (direct commits to a single integration branch). See references/git-workflow-variants.md.

Scale modes

The system scales by terminal count — pick at setup time:

Mode	Terminals	Composition
Solo	1	Just task tracking, no locks needed
Pair	2	1 planner + 1 developer
Squad	3–4	1 planner + 2–3 developers
Swarm	5+	1 planner + N developers + extra rules

What this skill provides

• Setup wizard (/multi-agent-init) — interactive; asks the user every setting (mode, TTL, branch names, build/test commands, git variant) and writes a tailored config. Never assumes defaults silently.
• Terminal intros (/agent-intro) — when a fresh terminal starts, this command reads the saved config + asks which terminal number the session is, then prints a role-tailored intro that includes the lock protocol, kanban rules, commit rules, and any project-specific commands.
• Status board (/agents-status) — shows the kanban + active locks + stale-lock warnings in one view.
• Release locks (/release-locks) — clean up locks held by the current terminal (use on session exit / crash recovery).
• Templates — kanban template, lock file template, CLAUDE.md section template, role-tailored intros.

Setup wizard — fast by default (3-5 prompts)

When the user invokes /multi-agent-init, the wizard is built to feel fast. Most users finish in 3-5 prompts.

Flow

1. Preset (the only mandatory question) — Solo / Pair / Squad ⭐ / Swarm / Custom. Each preset bakes in sensible defaults (TTL 15min, Variant B, approval gate ON, Conventional Commits) so the user does NOT have to answer those individually.
2. Auto-detection — wizard reads package.json / Cargo.toml / pyproject.toml / Makefile to propose build + test commands; runs git symbolic-ref to propose integration / production branches; uses the directory name for the project name. Presents them in one confirmation step: "Use these, customize commands, customize branches, or customize everything?"
3. Swarm size — only asked if the preset was Swarm.
4. Custom mode — only asked if the preset was Custom. Walks through all 13 individual settings.
5. Final confirmation — show the fully resolved config and ask "Confirm and write?"

Presets cover ~95% of cases. Power users pick Custom for full control.

Preset defaults (NOT asked)

Setting	Solo	Pair	Squad	Swarm
has_planner	false	true	true	true
lock_ttl_minutes	n/a	15	15	15
stale_lock_policy	n/a	auto-clear	warn	warn
git_variant	B	B	B	B
approval_gate_enabled	false	true	true	true
commit_format	conventional	conventional	conventional	conventional

What the wizard writes

• .multi-agent/config.json — all final settings (committed, not gitignored — team members get the same config on clone)
• active_tasks.md — empty kanban (from templates/active_tasks.md) — gitignored
• active_files.md — empty lock registry (from templates/active_files.md) — gitignored (skipped in Solo)
• CLAUDE.md — appended with the multi-agent section between BEGIN/END markers, interpolated with the user's answers
• .gitignore — patched to exclude only active_tasks.md and active_files.md

Then the wizard outputs N ready-to-paste intro blocks — one per terminal — tailored from templates/intros/. The user opens N terminals and pastes the matching intro into each.

Planner intro flow (after setup)

Once /multi-agent-init finishes, the Planner terminal (the one that ran setup) outputs:

✅ Setup complete. Open N more Claude Code terminals in this project.
Then paste the following into each:

━━━ TERMINAL 1 (Developer A) ━━━
<contents of templates/intros/developer-intro.md, interpolated with config>

━━━ TERMINAL 2 (Developer B) ━━━
<same, with terminal number 2>

…

This way the user does not have to explain anything — every terminal gets onboarded automatically.

Lock protocol (one-paragraph version)

Before editing any file: read active_files.md. If the target path is listed by another terminal, wait 30s and recheck. If not listed, append - <path> → T<N> @ <ISO-timestamp> (developers — use P for the planner). Edit. Remove the line immediately when done. Locks older than the configured TTL are stale — any terminal may warn or auto-clear them per project policy. Full details and edge cases: references/lock-protocol.md.

Approval gate (one-paragraph version)

Developers must not run git add / git commit / git push / gh pr create until the planner has reviewed the uncommitted diff and the user has relayed an explicit "approved" message. Developers signal readiness by moving the task to AWAITING REVIEW in active_tasks.md and saying so in chat. Planner verifies via git diff + typecheck + test + manual run, then approves or blocks. Exception: pure-docs / planning-file commits and explicit user-authorized hotfixes. Full flow: references/approval-gate.md.

Git workflows (when to pick which)

• Variant A (feature branches + PR per task) — better for teams that already use code review tooling, want per-task isolation, and don't mind cross-branch dependency overhead.
• Variant B (direct commits to integration branch) — better for solo users + AI assistants where the planner approval gate already plays the role of code review. Simpler, no cross-branch dependency chaos. Recommended default.

Details, hotfix flows, and the rationale for Variant B: references/git-workflow-variants.md.

Troubleshooting common issues

Stale locks after a crash, two terminals colliding on a task, planner unable to spawn sub-agents, conflicts during git pull --rebase, and what to do when CI goes red mid-coordination — all covered in references/troubleshooting.md.

Files

Path	Purpose
references/terminal-roles.md	What each role does and what it MAY NOT do
references/lock-protocol.md	Full lock + kanban protocol with edge cases
references/approval-gate.md	Pre-commit review flow and exceptions
references/git-workflow-variants.md	Variant A vs B, hotfix flow, release flow
references/troubleshooting.md	Common breakage and recovery recipes
templates/active_tasks.md	Empty kanban template
templates/active_files.md	Empty lock-registry template
templates/CLAUDE-section.md	Block to append to project CLAUDE.md
templates/intros/planner-intro.md	Intro the planner terminal reads on session start
templates/intros/developer-intro.md	Intro a developer terminal reads on session start
templates/intros/solo-intro.md	Intro for the lite single-terminal mode

Where things live (global vs per-project)

• Skill itself — installed once per machine at ~/.claude/plugins/multi-agent-coordination/. Available in every project automatically. Re-installing is only needed on new machines.
• Per-project config — .multi-agent/config.json at the project root. Committed to git so collaborators cloning the repo get the same multi-agent settings without re-running the wizard.
• CLAUDE.md block — appended to the project's CLAUDE.md between BEGIN/END markers. Committed. Auto-loaded by every Claude Code session in that project, so terminals know the rules without explicit /agent-intro.
• Live state — active_tasks.md, active_files.md at the project root. Gitignored. These represent in-flight kanban + lock state, not durable config.

This means: once a user installs the skill and runs /multi-agent-init in a project, that project is permanently configured. Every new terminal session loads CLAUDE.md + reads config.json automatically. No re-install per project.

Important guardrails

• Never assume settings the user did not pick or default into via a preset. Presets bake in defaults transparently; Custom mode asks every question.
• Never commit on the user's behalf without their relay. The approval gate exists because automated commits cause more cleanup than they save.
• Locks are honor-system. This is a coordination protocol, not OS-level locking. It works because all participants follow it — if a terminal ignores the protocol, no enforcement.
• Do not edit active_files.md / active_tasks.md while another terminal holds a lock on them implicitly — these files are written by every terminal; treat appends as atomic single-line writes and re-read before every operation.