agent-swarm
Enforcement system for phase-gated, multi-agent workflows in Claude Code. Routes all tool calls through a central MCP router, enforces per-phase tool restrictions, and spawns specialized subagents under a role-based permission model.
Installation
claude plugin install agent-swarm
Registers a mcp-router MCP server and installs PreToolUse, SessionStart, SessionEnd, and PreCompact hooks.
Requirements: Python 3.11+, git, gh CLI (for PR workflows)
Workflows
Four workflow definitions live in config/workflows/*.yaml. Each defines phases, tool restrictions per phase, eligible agent roles, checkpoint gates, and transition rules.
/iterate — TDD Loop
Well-scoped task with test-driven implementation and adversarial review gates.
test_writing → implement → test ─── pass + confident ──→ review → complete
↑ ├── adversary fails ──→ implement
└──────────────┴── weak suite ───────→ test_writing
| Phase | What happens | Can write code? |
|---|
test_writing | Write tests first, cover edge cases | Yes |
implement | Write minimal code to pass tests | Yes |
test | Run tests, adversary evaluates suite quality | No |
review | Verify conventions, commit if clean | No |
complete | Terminal | — |
Gate logic: Tests pass + high confidence → review. Adversary-written tests fail → implement. Tests pass but weak suite → test_writing. Review clean → complete. Review issues → implement.
Invoke: /iterate
/develop — Full SDLC Simulation
Significant features requiring team simulation: requirements, research, design, TDD implementation, adversarial review, and PM acceptance.
intake → research → design ─(checkpoint)→ branch
→ test_writing → implement → test ─(checkpoint)→ review ─(checkpoint)→ merge
→ acceptance ─(checkpoint)→ complete
| Phase | Eligible agents | Can write code? |
|---|
intake | PM | No |
research | Researcher | No |
design | Architect | No (checkpoint) |
branch | Git-agent | No |
test_writing | Implementer | Yes |
implement | Implementer | Yes |
test | Implementer, Debugger | No (checkpoint) |
review | Reviewer | No (checkpoint) |
merge | Git-agent | No |
acceptance | PM | No (checkpoint) |
complete | — | — |
Checkpoints at design, test, review, and acceptance block advancement until the responsible agent passes them. Max 8 concurrent agents, 3 agent respawns. Integrates with GitHub issues for feature tickets, subtasks, and followups.
Invoke: /develop
/experiment — Autonomous Experiment Loop
Research experiments with eval gates, journal memory, and iteration limits.
read → plan → work → eval ─── pass ──→ journal → decide ─── done
↑ └── fail ──→ work └── iterate → plan
| Phase | What happens | Can write code? |
|---|
read | Read goal.yaml, understand experiment | No |
plan | Design next iteration, research if needed | No |
work | Implement the experiment (eval files protected) | Yes |
eval | Run eval suite (eval files protected) | No |
journal | Record results to journal/ | Journal only |
decide | Continue iterating or stop | No |
done | Terminal | — |
Max 10 iterations, 4 concurrent agents. Eval files are write-protected during both work and eval phases to prevent gaming.
Invoke: /experiment
Orchestrate — Parallel Task Dispatch
Breaks a feature into independent subtasks, dispatches subagents (each running their own workflow), and manages PRs per task group.
| Phase | What happens |
|---|
intake | Gather missing info (skipped if input is complete) |
design | Plan architecture, document decisions |
orchestrate | Build task queue, dispatch subagents, poll for completion |
Each group in the task queue maps to a PR. Stop condition: queue empty + no agents in flight + no unaddressed PR comments + clean working tree + all groups have PRs.
Invoke: /orchestrate
Skills
Skills are invocable via /skill_name. They provide workflow entry points, utilities, and reference documentation.
Workflow Skills
| Skill | Invoke | Purpose |
|---|
iterate | /iterate | TDD loop with phase gates |
develop | /develop | Full SDLC team simulation |
experiment | /experiment | Autonomous experiment with eval gates |
orchestrate | /orchestrate | Task queue dispatch with parallel subagents |
implement | /implement | General implementation (default workflow, no TDD) |
debug | /debug | Systematic debugging: triage → reproduce → hypothesize → prove → fix → verify |
teams-develop | /teams-develop | Full PR lifecycle using native Claude Code teams |
agent-teams-workflow | /agent-teams-workflow | Coordinate agent teams from a design doc or plan |
Orchestration Skills
