| name | subagent-handoff |
| description | Use whenever dispatching subagents in this project — implementer, spec-reviewer, or code-quality-reviewer. Wraps the upstream `superpowers:subagent-driven-development` skill with project-local prompt templates that center user goals (not just spec compliance) and require the dispatcher to verify user-observable outcomes before marking work done. |
Subagent Handoff (project-local)
Project-local override of upstream superpowers:subagent-driven-development prompt templates. Use this skill's templates instead of upstream for any subagent dispatch in this repo. Upstream process flow (implementer → spec review → code quality review → mark done) still applies — only the prompt templates change.
Rules
B1 — Every subagent prompt opens with "User goal"
Project-local templates prepend a "User goal" section that the dispatcher copies verbatim from the plan's User goal. The subagent must report whether the task as specified actually serves that goal — and stop / escalate (status BLOCKED or NEEDS_CONTEXT) if not.
B2 — Spec-reviewer also checks user goal alignment
Spec-reviewer's first question is "does the work satisfy the user goal?" Failure = ❌ regardless of spec match. Spec-reviewer reports must have a User goal alignment section before the spec-compliance section.
B3 — Dispatcher verifies user-observable outcomes before marking done
For any task whose user goal is user-observable (UI, MCP tool output, file output, gazetteer resolution), the dispatcher does NOT mark done on subagent report alone. Required: dispatcher runs an explicit verification step BEFORE marking done — DOM read, MCP call, file read, gazetteer resolution check. vitest passes and lint clean are hygiene, not user-goal verification.
B4 — Subagent reports answer three explicit questions
Implementer and reviewer reports must each answer:
- What I implemented / verified (the structural what).
- How I verified the user goal — not just "tests pass". Name the user-observable check actually performed; if none was performed, say so explicitly.
- What I assumed / where I deviated from the spec or user goal.
Dispatcher rejects reports missing any of the three and re-dispatches with the question.
B5 — Subagent prompts ALWAYS instruct rebase + branch verification
Every dispatch prompt MUST tell the subagent:
- Before starting:
git -C <worktree> fetch && git -C <worktree> rebase main so the worktree base matches current main.
- Before EVERY commit: verify
git -C <worktree> rev-parse --abbrev-ref HEAD reports worktree-agent-*, NOT main. If it reports main, the subagent has CWD-drifted — stop, abort, fix.
B6 — Prompt wording: name the SHA, not "in main"
Replace "Tasks 1-N done in main" phrasing with: "Main is at commit <sha>; rebase your worktree onto it. Commits 1-N from previous waves provide [list of artifacts]." SHA gives a concrete anchor; "in main" reads as "work on main."
B7 — Perf-sensitive diffs get a performance-reviewer pass
Any task whose diff touches src/gedcom/, src/import/, or src/api/ (including
src/api/html_site/ and src/api/archive_*) gets a read-only performance-reviewer
pass in addition to the code-quality review, BEFORE the dispatcher marks done. It
checks the two failure modes in .claude/rules/performance.md: per-row DB queries in
DB-scale loops (N+1) and long async handlers with no yield/progress. A confirmed N+1
or missing-yield finding is a re-dispatch, not a note. The query-count guard
(tests/unit/export-perf.test.ts) is the mechanical backstop; the reviewer catches
what a new untested path would miss.
How to use
When dispatching a subagent (implementer, spec-reviewer, or code-quality-reviewer):
- Use the local prompt template at
.claude/skills/subagent-handoff/<role>-prompt.md. Each is a minimal fork of the upstream template — preserves the upstream structure, adds the project-local sections.
- Copy the plan's "User goal" section verbatim into the prompt.
- After the subagent reports back, run the dispatcher verification step (B3) before marking the task done in TodoWrite.
Templates (in this directory)
implementer-prompt.md — fork of upstream implementer-prompt.mdspec-reviewer-prompt.md — fork of upstream spec-reviewer-prompt.mdcode-quality-reviewer-prompt.md — fork of upstream code-quality-reviewer-prompt.md
Each template cites the upstream template, then lists the project-local sections to prepend / append.
