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.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:** ```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 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 + frontend/node_modules symlink). Rebase, reviewer, and test-runner subagents enter your existing worktree via a `WORKTREE` field — do NOT use `isolation: "worktree"` for those. ### 1. 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 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): ```bash 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): ```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: <comma-separated task IDs whose changes are on the source branch> ``` **After successful integration** (either path): ```bash 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 ### 2. 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 2a — skip both together for trivial changes. #### 2a. 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 2b inspect the post-cleanup diff, and the user inspects the final PR diff before merge. #### 2b. 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 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 quality gates via a test-runner sub-agent. **Run integration tests and any epic-level e2e acceptance tests here** — unit tests and contract coverage are handled by pre-push hooks when pushing in Phase 4. 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: - <integration test commands matching changed code — see Hooks section below> - <e2e acceptance test commands if the epic defined them — e.g., make test-e2e -- e2e/specific-test.spec.ts> ``` If the epic has e2e acceptance tests, run them here targeting the specific test files (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** if no integration tests or acceptance tests are needed (e.g., frontend-only changes with no store layer involvement and no e2e acceptance tests). **Do NOT create PR if the test-runner reports FAIL.** Fix locally first (spawn implementer if non-trivial). ### 3. Create PR, Monitor CI, and Hand Off ```bash 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> <if any beads issue description contains "GitHub: #<number>", add a line: "Closes #<number>" for each> 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" ``` This blocks merge until a human approves the PR on GitHub. 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. --- ## GitHub Authentication If `git push` or `gh` commands fail with 401/403, refresh the GitHub App token: ```bash WORKSPACE_DIR=/workspaces/eval /workspaces/eval/.devcontainer/refresh-github-app-token.sh export GH_TOKEN=$(cat /workspaces/eval/.gh-app-token) ``` ## 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 - 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 - 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) - Running integrations in parallel (must be sequential for linear history) - 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 - 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. Do NOT duplicate these in test-runner prompts. **Pre-commit hooks (automatic at commit time) — never run manually:** - `make lint-api`, `make lint-executor`, `make lint-frontend` - `make typecheck-frontend` - `make check-api-imports` **Pre-push hooks (automatic at push time) — never run in coordinator test-runner:** - `make test-api`, `make test-executor`, `make test-frontend` - `make check-contract-coverage` **Integration tests (NOT in hooks) — run in coordinator test-runner when relevant:** - `make test-integration-store` — store/DB changes - `make test-integration-realtime` — realtime/Centrifugo changes - `make test-integration-api` — API handler changes - `make test-integration-contract` — API contract changes **E2e acceptance tests (NOT in hooks) — run in coordinator test-runner when epic defines them:** - `make test-e2e -- e2e/specific-test.spec.ts` — target specific acceptance test files, not the full suite Note: implementer subagents DO run unit tests (`make test-api`, etc.) for TDD feedback before committing. Pre-push hooks re-running them is an accepted safety net, not wasteful duplication.