coordinator

name	coordinator
description	Single entry point for all implementation work. Triages tasks, manages beads issues, delegates to implementer skill, runs reviewers, creates PRs.

Coordinator

You are the single entry point for all implementation work. You triage incoming work, manage the beads lifecycle, and orchestrate subagents via branch/PR workflow.

Model guidance: The coordinator should run on Opus 4.6. Implementer subagents should run on Sonnet 4.6 (model: "sonnet").

IMPORTANT: The main branch is protected. All changes MUST go through a feature branch and PR. Direct commits to main are not allowed.

Phase 1: Triage

1. Parse Input

The input is a beads ID, a GitHub issue reference (#<number>), or an ad-hoc description. When the input could plausibly be a beads ID, try bd show <input> --json first; if it returns an issue, treat it as one. Otherwise fall through.

Beads ID:

bd show <id> --json

If it's an epic, also fetch subtasks:

bd list --parent <id> --json

GitHub issue (#<number>): Fetch and convert to a beads issue:

gh issue view <number> --json title,body,labels,number
bd create "<title>" -d "GitHub: #<number> — <description>" -t <type> -p <priority> --json

Map GitHub labels to beads types. Priority 1 for bugs, 2 for features/tasks.

Ad-hoc description: Create a beads issue:

bd create "<description>" -t <task|bug|feature> -p 2 --json

2. Check for Existing Branch

If the issue is a fix for code on an existing feature branch (e.g., CI failure on an open PR, discovered-from dependency on an issue labeled in-pr, or the code to fix doesn't exist on main), use that branch as the base in Branch Mode instead of origin/main. Commit directly to it — do not create a new branch or PR.

---

Branch Mode

You're in your worktree from /work — pwd is its path. Implementer subagents spawn with isolation: "worktree" (the WorktreeCreate hook handles branch + node_modules symlink + .env.local copy). Rebase, reviewer, and test-runner subagents enter your existing worktree via a WORKTREE field — do NOT use isolation: "worktree" for those.

1. Conflict Avoidance

Before parallelizing tasks, analyze file overlap:

Tasks conflict if they likely touch the same files:

• Same component/module
• Same API route
• Same database table/repository
• Shared utilities they might both modify

Task A: Add user profile page (src/app/profile/*)
Task B: Fix login bug (src/app/login/*)
-> SAFE to parallelize (different directories)

Task A: Add validation to UserForm
Task B: Add new field to UserForm
-> NOT SAFE (same component)

When in doubt, add a dependency:

bd dep add <later-task-id> <earlier-task-id> --json

2. Implement Tasks

Follow the dependency graph from beads. Spawn all currently-unblocked tasks in parallel. When a task completes, check if any blocked tasks are now unblocked and spawn those.

For each task:

a. Claim

bd update <task-id> --set-labels wip --json

b. Spawn Implementer Subagent

Use the Agent tool with isolation: "worktree" and model: "sonnet":

ROLE: Implementer
SKILL: Read and follow .claude/skills/implementer/SKILL.md

TASK: <task-id>
Read the task description: bd show <task-id> --json

c. Handle Result

The implementer's final output is a structured summary (Phase 6). Only read that summary — ignore intermediate tool output from the subagent. The Agent tool's result metadata exposes worktree_path and branch for integration.

On implementer FAILURE or STALL (timeout, crash, incomplete summary): don't silently drop the work. Choose one — retry with continuation, finish the task inline, or ask the user how to proceed.

On SUCCESS: integrate into the feature branch (sequential — do NOT run in parallel with other integrations).

Try fast-path rebase first (inline — no subagent):

cd <worktree_path>
git rebase feature/<work-name> && \
  git branch -f feature/<work-name> HEAD && \
  git worktree remove <worktree_path> --force 2>/dev/null && \
  git branch -D <branch> 2>/dev/null && \
  echo "REBASE: OK"

If the rebase command fails (conflict), abort and fall back to a rebase subagent (no isolation: "worktree" — it enters the implementer's existing worktree):

git rebase --abort

ROLE: Rebase Agent (Conflict Resolution)
SKILL: Read and follow .claude/skills/rebase/SKILL.md

SOURCE: <branch>
TARGET: feature/<work-name>
WORKTREE: <worktree_path>
CLEANUP: true
BEADS_IDS: <comma-separated task IDs whose changes are on the source branch>

After successful integration (either path):

bd close <task-id> --reason "Implemented" --json

Triage the "Concerns" section. Filing follow-ups mid-implementation is fine — the gate is before reviewers (or before the PR if reviewers were skipped):

• Issues this PR's diff is the proximate cause of — must be fixed in this PR or have explicit user approval to defer. Surface the list and ask; don't assume.
• Pre-existing issues this work surfaced — file as follow-ups; no approval needed.
• Anything ambiguous — ask the user whether to fix now or defer.

On rebase subagent FAILURE:

• Spawn a new implementer in a fresh worktree to resolve the conflict
• If blocked: note the blocker, move to next task
• Do NOT close the task

3. Pre-PR Review

Reviews are optional for small, isolated changes (single-file fixes, typo corrections, config tweaks). For anything of any complexity — multi-file changes, new features, behavioral changes, refactors — reviews are required. The same condition gates the /simplify pass in 3a — skip both together for trivial changes.

3a. Cleanup pass (/simplify)

After all tasks are merged into the feature branch, invoke the Claude Code built-in /simplify skill via the Skill tool (skill: "simplify"). It spawns 3 parallel agents (reuse / quality / efficiency) over the changed files and auto-commits cleanup fixes directly to the feature branch.

/simplify is bundled with Claude Code — there is no repo-local SKILL.md for it. Do not try to read it from .claude/skills/.

Rationale: running the cleanup pass before the specialized reviewers means they assess post-cleanup code instead of wasting cycles on cruft /simplify already removed. Auto-fix is safe here — the 3 specialized reviewers in 3b inspect the post-cleanup diff, and the user inspects the final PR diff before merge.

3b. Specialized reviews

After /simplify has committed its cleanup, run 3 specialized reviews in parallel using the Task tool. Each reviewer enters the coordinator's existing worktree (do NOT create a new worktree):

Correctness Reviewer:

ROLE: Correctness Reviewer
SKILL: Read and follow .claude/skills/reviewer-correctness/SKILL.md

WORKTREE: <coordinator's worktree path>
BASE: origin/main
SUMMARY: <what this PR implements>

Test Quality Reviewer:

ROLE: Test Quality Reviewer
SKILL: Read and follow .claude/skills/reviewer-tests/SKILL.md

WORKTREE: <coordinator's worktree path>
BASE: origin/main
SUMMARY: <what this PR implements>

Architecture Reviewer:

ROLE: Architecture Reviewer
SKILL: Read and follow .claude/skills/reviewer-architecture/SKILL.md

WORKTREE: <coordinator's worktree path>
BASE: origin/main
SUMMARY: <what this PR implements>
REFERENCE DIRS: <key directories in the existing codebase to compare against>

Handle review results:

• Trivial issues (typos, minor naming): fix directly, commit
• Non-trivial issues (bugs, missing tests, duplication): file a beads issue, spawn implementer, close when fixed

After all issues resolved, run quality gates via a test-runner sub-agent. Run unit/integration tests and any epic-level e2e acceptance tests here. lefthook enforces the fast gates locally (lint + typecheck on pre-commit, npm test on pre-push), but the coordinator still owns running the full gate — including integration and epic-level e2e acceptance tests, which lefthook deliberately leaves to CI — before the PR. Use the Task tool with subagent_type: "Bash" and model: "haiku":

ROLE: Test Runner
SKILL: Read and follow .claude/skills/test-runner/SKILL.md

WORKTREE: <coordinator's worktree path>
COMMANDS:
- npm test
- npm run lint
- npx tsc --noEmit
- <integration tests if the change touches the sandbox/server boundary — npm run test:integration:sandbox>
- <e2e acceptance test commands if the epic defined them — e.g., npm run test:e2e -- e2e/specific-test.spec.ts>

If the epic has e2e acceptance tests, run them here targeting the specific spec files under e2e/ (not the full e2e suite). This is the gate that verifies the feature works end-to-end before creating the PR.

Skip the test-runner entirely only for genuinely gate-free changes (pure docs/config). Do NOT create PR if the test-runner reports FAIL. Fix locally first (spawn implementer if non-trivial).

4. Create PR, Monitor CI, and Hand Off

PR description guidelines:

• The summary should explain why the change exists, not restate the diff. Reviewers can read the code.
• Only call out specific changes if they are notable, unusual, or would surprise a reviewer.
• Add additional sections (e.g., "Manual steps required") only when relevant.

git push -u origin feature/<work-name>

gh pr create --title "<type>: <title>" --body "$(cat <<'EOF'
## Summary
<1-3 bullet points>

## Changes
<list of significant changes>

## Test plan
- [ ] Tests pass
- [ ] <manual verification steps if any>

Beads: <comma-separated list of all beads issue IDs included in this PR>

<if any beads issue description contains "GitHub: #<number>", add a line: "Closes #<number>" for each>

Generated with Claude Code
EOF
)"

After creating the PR, monitor CI:

gh pr checks <number> --watch

If CI fails:

1. Fetch failure logs:

   gh run view <run-id> --log-failed
   

2. Trivial fix (single-line, obvious test typo): fix inline, commit, push.
3. Non-trivial fix: spawn an implementer in the coordinator's worktree to fix the failures, then push:

   git push
   

4. Re-run gh pr checks <number> --watch and repeat until CI passes.

After CI passes:

1. If user indicated review needed (e.g., "review this", "flag for review", or high-risk changes like auth/infra/migrations):

   gh pr edit <number> --add-label "needs-human-review"
   

   This blocks merge until a human approves the PR on GitHub.
2. Label beads issues as in-pr:

   bd update <id> --set-labels in-pr --json
   

3. Report: "PR #X opened. CI passing. /merge will handle merging."

Do NOT merge. The /merge agent handles all merging.

Do NOT clean up worktrees or branches. The /merge agent does this after successful merge, since worktrees may be needed for rebases.

---

Anti-Patterns

• Committing directly to main (branch is protected — all changes require a PR)
• Creating a new branch/PR for a fix that belongs on an existing feature branch
• Starting dependent task before blocker is closed
• Parallelizing tasks that touch the same files (use Conflict Avoidance section above)
• Running task integrations in parallel (must be sequential for linear history)
• Creating PR before running specialized reviews
• Skipping /simplify before reviewers — they should see post-cleanup code (only skip when the whole review gate is skipped for a trivial change)
• Creating PR with failing tests
• Shipping known bugs as follow-up issues — bugs introduced by the current work must be fixed before the PR ships
• Filing introduced bugs (or nits) as follow-ups without explicit user approval to defer
• Silently dropping a stalled or failed implementer's work and moving on
• Spawning a rebase subagent when there are no conflicts (use inline fast-path first)
• Fixing non-trivial review issues inline — file issues and spawn implementers instead
• Running quality gates directly in coordinator context — always delegate to test-runner sub-agents
• Merging PRs (that's /merge's job)
• Handing off to /merge before CI passes — coordinator owns CI failures and must fix them
• Cleaning up worktrees before merge (that's /merge's job)
• Manually creating worktrees with git worktree add for subagents — use isolation: "worktree" so the WorktreeCreate hook handles setup
• Using isolation: "worktree" for rebase/reviewer/test-runner agents — they enter the coordinator's existing worktree

---

Hooks — What's Automatic vs Manual

lefthook git hooks run quality gates automatically (see lefthook.yml). Do NOT duplicate these in test-runner prompts.

Pre-commit hooks (automatic at commit time) — never run manually:

• npx eslint (lint, staged *.ts/*.tsx)
• npx tsc --noEmit (typecheck)
• gitleaks secret scan
• bd hooks run pre-commit (beads sync)

Pre-push hooks (automatic at push time) — do not put in the coordinator test-runner:

• npm test (full Jest suite)
• bd hooks run pre-push (beads sync)

Integration / e2e tests (NOT in hooks) — run in the coordinator test-runner when relevant:

• npm run test:integration:sandbox — changes touching the Python sandbox / server boundary
• npm run test:e2e -- e2e/<spec> — epic-defined acceptance tests, targeting specific spec files (not the full e2e suite)

Note: implementer subagents still run npm test in Phase 3 for TDD feedback before committing. The pre-push hook re-running it is an accepted safety net, not wasteful duplication.