Execution Orchestrator¶
Execute plans using parallel worker swarms with quality gates and native task-list tracking.
MCP Tools¶
Context7 (documentation):
- Research implementation patterns
- Verify API usage
CLI Tools¶
gh (GitHub CLI):
- Use
gh pr createfor creating pull requests - Use
gh pr viewto check PR status - Use
gh issue listfor issue tracking
Execution Workflow¶
- Discover — Find available work via
TaskList(unblocked, not-yet-started tasks) - Claim — Mark the task in progress via
TaskUpdate(status: in_progress) - Analyze — Check the task's
blockedBydependencies to confirm it is actually unblocked - Execute — Launch parallel workers for independent tasks
- Gate — Run quality gates before marking tasks complete
- Close — Mark complete via
TaskUpdate(status: completed), and in this repo flip the task's line inTASKS.mdto[x]with the commit hash ([~]while in progress) in the same commit as the work or its docs - Push — Push to remote (MANDATORY)
Context Efficiency¶
- Workers inherit session context - CLAUDE.md and rules are loaded, but workers use focused instructions
- Narrow scope - Each worker focuses on one task, sized to roughly 200-400 changed LOC or 15-45 minutes of focused work (review effectiveness collapses beyond ~400 LOC — SmartBear/Cisco)
- Guided behavior - Agent instructions define scope, permissionMode controls access
- Right-sized models - see Worker Types below for the tiering pointer
Worker Types¶
| Worker | Primary Use |
|---|---|
worker-explorer |
Fast codebase search, web research, dependency mapping |
worker-builder |
Implementation, testing, refactoring |
worker-reviewer |
Code review, security audit, quality assessment |
worker-research |
Deep multi-source investigation, technology evaluation |
worker-architect |
Complex design decisions, ADRs, system architecture |
Model tiers are pinned in each agent's frontmatter (.claude/agents/) — that is the single source of truth.
Worker Focus Modes¶
Orchestrators specialize workers by specifying a focus mode in the prompt.
worker-builder focus modes:
implementation(default): Write code per specificationtesting: Write tests, cover happy path and edge cases, ensure deterministicrefactoring: Extract patterns, simplify conditionals, apply SOLID/DRY. Follow Two Hats Rule (see code-quality.md)
worker-reviewer focus modes:
quality(default): Code review checklist — naming, style, tests, patternssecurity: OWASP Top 10 scan, hardcoded secrets, auth/authz flows, input validation. Reference CWE IDs. See security.mdperformance: N+1 queries, blocking I/O, allocations, pagination, caching. See code-quality.md
Quality Gates¶
Run quality gates per code-quality.md — all must pass. No exceptions.
Coordination Protocol¶
- Orchestrator decomposes work into tasks via
TaskCreate, with acceptance criteria andblockedBydependencies — each unit shaped to merge tomainindependently (trunk-based, per core-directives) - Orchestrator claims a task on behalf of a worker:
TaskUpdate(status: in_progress) - Workers execute their assigned task following AGENTS.md "Landing the Plane" workflow — workers do NOT touch the task list themselves
- Workers report completion (and any follow-up work discovered) back to the orchestrator
- Orchestrator integrates, verifies, and updates the task list based on worker reports
Worker Completion Requirements¶
Workers do not have direct access to the native task list — the orchestrator owns it. Which completion mode a worker follows depends on its isolation frontmatter; see AGENTS.md "Landing the Plane" for the canonical two-mode protocol (Mode A: isolated worktree workers commit-and-report; Mode B: non-isolated agents push directly).
worker-builder runs isolated (isolation: worktree) — every other worker in this table does not. For an isolated worker's completed task, the orchestrator:
- Merges the worker's worktree branch into the integration branch (
mainin this repo) withgit merge --ff-only - Re-runs quality gates on the merged result — a worker's local gate pass does not substitute for the orchestrator's own verification
- Pushes to remote only after the user approves the push (see Core Directives "Constraints") — then watches CI for that SHA
- Cleans up the worker's worktree
- Marks the task completed via
TaskUpdate, and files any follow-up work the worker reported viaTaskCreate
In this repo the orchestrator integrates on main (CI deploys from main); a PR is opened only when the user asks for one, and then never with another unit's branch as its base.
Checkpointing¶
For long-running tasks, the orchestrator records progress on the task via TaskUpdate (metadata/comments), e.g.:
- "Completed step 1: schema migration"
- "Completed step 2: API endpoints"
- "In progress: integration tests"
Error Handling¶
If a worker fails:
- Orchestrator marks the task blocked via
TaskUpdate(status: blocked), with a comment: "Blocked: [safe error description without secrets]" - Orchestrator creates a new blocker task via
TaskCreatedescribing the fix needed - Orchestrator sets the original task's
blockedByto reference the new blocker task
Recovery¶
For a maxTurns ceiling hit, a lost orchestrator session, or a rejected fast-forward merge, see AGENTS.md "Landing the Plane" → Mode A → Recovery for the three canonical recovery procedures.
Rollback¶
If quality gates fail: stash changes, mark the task as blocked via TaskUpdate, add a comment with the reason.
Performance Tips¶
- Launch multiple explorers for broad searches
- Use worker-architect for decisions, worker-builder for execution
- Parallelize independent tasks (max 8 concurrent workers)
- For large dispatch batches, declare a token/wave ceiling up front — see
swarm-coordination's Budget & Waves section - Keep worker prompts under 500 tokens for fast startup
Constraints¶
- NO closing tasks without passing quality gates
- NO leaving work uncommitted locally
- NO exceeding 8 parallel workers
- NO skipping git push step
- NO exposing secrets in error messages or comments
- ALWAYS update task status in real-time via
TaskUpdate, and keepTASKS.mdin step (this repo's durable task record) - ALWAYS add comments for blocked work
- ALWAYS verify
git statusshows up to date - ALWAYS validate inputs before executing commands
Definition of Done¶
- [ ] Code implemented per specification
- [ ] Tests written and passing
- [ ] Linter passes
- [ ] Types check
- [ ] Build succeeds
- [ ] Task marked completed with reason
- [ ] Changes pushed to remote
- [ ]
git statusshows up to date with origin
Related Skills¶
swarm-coordination, testing
Handoff¶
- To
/swarm-review: After implementation complete, create PR - To
/qa-engineer: For acceptance testing - To
/swarm-plan: When scope changes discovered