coordinator

# 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.8. Implementer subagents should run on Sonnet 5 (`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:** ```bash bd show <id> --json ``` If it's an epic, also fetch subtasks: ```bash bd list --parent <id> --json ``` **GitHub issue (`#<number>`):** Fetch and convert to a beads issue: ```bash 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: ```bash 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 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 + per-worktree project setup). 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: ```bash 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 ```bash 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 4). Only read that summary — ignore intermediate tool output from the subagent. The agent result includes `worktree_path` and `branch` when changes were made. **On SUCCESS:** integrate into the feature branch (sequential — do NOT run in parallel with other integrations). Try fast-path rebase first (inline — no subagent): ```bash cd <worktree_path> git rebase feature/<work-name> && \ git branch -f feature/<work-name> HEAD && \ echo "REBASE: OK" ``` After successful rebase, clean up: ```bash git worktree remove <worktree_path> --force 2>/dev/null git branch -D <branch> 2>/dev/null ``` If the rebase fails (conflict), abort and spawn the rebase subagent. Do NOT use `isolation: "worktree"` — the rebase agent enters the implementer's existing worktree: ```bash 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: <task-id> ``` **After successful integration** (either path): ```bash bd close <task-id> --reason "Implemented" --json ``` Triage the "Concerns" section: - **Bugs or broken behavior introduced by this task** — must be fixed before the PR ships. File an issue, spawn an implementer, and fix it on the feature branch. - **Low-priority, non-behavioral issues** (naming nits, future optimization ideas, minor code smells) — file as follow-up issues. - **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**. After all tasks are merged into the feature branch, run 3 specialized reviews **in parallel**. Each reviewer enters the coordinator's worktree (do NOT use `isolation: "worktree"`): **Correctness Reviewer:** ``` ROLE: Correctness Reviewer SKILL: Read and follow .claude/skills/reviewer-correctness/SKILL.md WORKTREE: <coordinator's worktree path> BASE: origin/main DIFF RANGE: origin/main...HEAD BEADS: <bd-id(s)> ``` **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 DIFF RANGE: origin/main...HEAD BEADS: <bd-id(s)> ``` **Architecture Reviewer:** ``` ROLE: Architecture Reviewer SKILL: Read and follow .claude/skills/reviewer-architecture/SKILL.md WORKTREE: <coordinator's worktree path> BASE: origin/main DIFF RANGE: origin/main...HEAD BEADS: <bd-id(s)> REFERENCE DIRS: <existing dirs to compare against — paths only, not "areas of concern"> ``` **Pass mechanical context only — route, don't narrate.** The reviewer reads the diff (`DIFF RANGE`) and the task intent (`bd show <BEADS>`, written pre-review so neutral) itself. Do **not** hand-author a summary of "what this PR implements" — composed right after your own analysis, it seeds the reviewers with your priors. If an orientation line is truly needed, pull it from a pre-existing neutral source (bd description, PR title), never your working memory. **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 a test-runner sub-agent for **epic-level acceptance tests** (if the epic defined them) using `model: "haiku"`. Pull the test commands from the **Quality Gates** table in CLAUDE.md: ``` ROLE: Test Runner SKILL: Read and follow .claude/skills/test-runner/SKILL.md WORKTREE: <coordinator's worktree path> COMMANDS: - <acceptance test commands if the epic defined them> ``` **Skip the test-runner** if the epic has no acceptance tests. **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 Run quality gates per the **Quality Gates** table in CLAUDE.md before creating the PR. Delegate to a test-runner sub-agent so verbose output doesn't pollute the coordinator's context. **Do NOT create PR if any gate fails.** Fix locally first. **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. ```bash git push -u origin feature/<work-name> gh pr create --title "<type>: <title>" --body "$(cat <<'EOF' ## Summary <1-3 bullet points explaining *why* this change exists> ## Test plan - [ ] Tests pass - [ ] <manual verification steps if any> Beads: <comma-separated list of all beads issue IDs included in this PR> Generated with Claude Code EOF )" ``` **After creating the PR, monitor CI:** ```bash gh pr checks <number> --watch ``` **If CI fails:** 1. Fetch failure logs: ```bash 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: ```bash 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): ```bash gh pr edit <number> --add-label "needs-human-review" ``` 2. Label beads issues as `in-pr`: ```bash 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 - 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 - Spawning a rebase subagent when fast-path succeeds - 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