Menu
Use when executing implementation plans with independent tasks in the current session
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Use when completing tasks, implementing major features, or before merging to verify work meets requirements
You MUST use this before any creative work - creating features, building components, adding functionality, or modifying behavior. Explores user intent, requirements and design before implementation.
Use when you have a spec or requirements for a multi-step task, before touching code
Use after implementation is verified and before merge — consolidates multiple spec iterations into a single final-state report, marks related specs, and records key lessons
Use when you want to evolve your own capabilities — create new tools to avoid repeating patterns, add hooks to improve your own behavior, build skills to accumulate domain knowledge, or override built-in tools to adapt to project needs. This is your self-iteration interface.
Use when encountering any bug, test failure, or unexpected behavior, before proposing fixes
| name | compose:subagent |
| hidden | true |
| description | Use when executing implementation plans with independent tasks in the current session |
Execute plan by dispatching fresh subagent per task, with two-stage review after each: spec compliance review first, then code quality review.
Why subagents: You delegate tasks to specialized agents with isolated context. By precisely crafting their instructions and context, you ensure they stay focused and succeed at their task. They should never inherit your session's context or history — you construct exactly what they need. This also preserves your own context for coordination work.
Core principle: Fresh subagent per task + two-stage review (spec then quality) = high quality, fast iteration
Continuous execution: Do not pause to check in with your human partner between tasks. Execute all tasks from the plan without stopping. The only reasons to stop are: BLOCKED status you cannot resolve, ambiguity that genuinely prevents progress, or all tasks complete. "Should I continue?" prompts and progress summaries waste their time — they asked you to execute the plan, so execute it. When you must stop for ambiguity or a blocker, use compose:ask to present the situation with structured options. If no user is available, resolve it with your best judgment and continue.
vs. Executing Plans (parallel session):
Setup: Read plan → extract all tasks with full text → note context → create a task per plan task (task create)
Per Task:
--task <TID>, auto-starts), inject covered spec as Intent, dispatch (./implementer-prompt.md)./code-quality-reviewer-prompt.md)task done <TID>More tasks remain? — Yes → next task (dispatch implementer)
Finish: Dispatch final code reviewer for entire implementation → compose:merge
This is how each task's spec-compliance review works. It replaces a single prose review with intent-grounded implementation and a two-phase, evidence-gated verdict.
Working directory (only if isolated). Subagents run with fresh context and start
in the repo root. If compose:worktree set up an isolated worktree, the work does NOT
live there — tell every subagent to cd into the worktree first (fill the
implementer's Work from: line, and add the cd note the reviewer prompts describe).
Otherwise there's nothing to do: the current checkout is correct and you can leave
those lines out. When a worktree IS in use and you forget, a reviewer's git diff and
tests run against the wrong checkout and the verdict is meaningless.
1. Create and bind a task before dispatching. Before the implementer runs, create
a work-item with the task tool (task create "<plan task summary>") and capture its
TID. Dispatch the implementer bound to that task by passing --task <TID> on the actor
call (actor run general "<desc>" "<prompt>" --task T3). Binding auto-starts the task
to in_progress with the subagent as owner, and lets the postStop hook validate the
task's progress. Do NOT mark the task done here — completion is gated on review (step 4).
2. Inject intent before dispatching the implementer. Read the task's Covers:
field, pull the verbatim text of those [Sn] spec sections, and paste it into the
implementer prompt's ## Intent (from spec) block (see ./implementer-prompt.md).
The implementer never reads the spec itself — you hand it exactly the sections its
task covers, with the scope boundary intact.
3. Run the spec reviewer in two phases (see ./spec-reviewer-prompt.md).
If an isolated worktree is in use, add the cd <worktree> instruction to each
dispatch (see the working-directory note above):
git diff ONLY. Do NOT
include the implementer's report — its claims anchor the reviewer toward confirming
what was reported and away from spotting silent omissions. Phase 1 returns a
structured per-claim verdict.4. Gate on the verdict. The task is complete ONLY when the final verdict is
Status: pass AND every in-scope claim is status: pass with evidence. Any
fail or unverifiable in-scope claim → re-dispatch the implementer with the
specific failing claims, then re-review. Loop until the gate passes. Then run the
code quality review (spec compliance always precedes quality), and once that also
passes, mark the bound task done with task done <TID>.
A structured pass without verifiable evidence (test name, command output, or
file:line) does not satisfy the gate — treat it as fail. Prose is not evidence.
Before dispatching Task 1, scan the entire plan once for conflicts:
Present everything you find to your human partner as one batched question — each finding beside the plan text that mandates it, asking which governs — before execution begins. Do not interrupt mid-plan with one finding at a time. If the scan is clean, proceed without comment.
Use compose:ask for the batched question. If no user is available, resolve
contradictions conservatively (strictest interpretation) and continue.
Use the least powerful model that can handle each role to conserve cost and increase speed.
Mechanical implementation tasks (isolated functions, clear specs, 1-2 files): use a fast, cheap model. Most implementation tasks are mechanical when the plan is well-specified.
Integration and judgment tasks (multi-file coordination, pattern matching, debugging): use a standard model.
Architecture, design, and review tasks: use the most capable available model.
Task complexity signals:
Reviewer tier: Dispatch the spec reviewer at a model tier at least as capable as the implementer's. A reviewer weaker than the implementer shares its blind spots and rubber-stamps the same misreadings; the adversarial value of review comes from the reviewer interpreting the spec independently, which a weaker model cannot reliably do.
Implementer subagents report one of four statuses. Handle each appropriately:
DONE: Proceed to spec compliance review.
DONE_WITH_CONCERNS: The implementer completed the work but flagged doubts. Read the concerns before proceeding. If the concerns are about correctness or scope, address them before review. If they're observations (e.g., "this file is getting large"), note them and proceed to review.
NEEDS_CONTEXT: The implementer needs information that wasn't provided. Provide the missing context and re-dispatch.
BLOCKED: The implementer cannot complete the task. Assess the blocker:
Never ignore an escalation or force the same model to retry without changes. If the implementer said it's stuck, something needs to change.
./implementer-prompt.md - Dispatch implementer subagent./spec-reviewer-prompt.md - Dispatch spec compliance reviewer (two-phase, evidence-gated verdict)./code-quality-reviewer-prompt.md - Dispatch code quality reviewer subagentYou: I'm using Subagent-Driven Development to execute this plan.
[Read plan file once: plans/feature-plan.md]
[Extract all 5 tasks with full text and context]
[Create a task per plan task with `task create`, capturing each TID]
Task 1: Hook installation script
[Get Task 1 text and context (already extracted)]
[Dispatch implementation subagent with full task text + context, bound to its task: actor run general "..." "..." --task T1 — binding auto-starts T1 to in_progress]
Implementer: "Before I begin - should the hook be installed at user or system level?"
You: "User level (~/.config/compose/hooks/)"
Implementer: "Got it. Implementing now..."
[Later] Implementer:
- Implemented install-hook command
- Added tests, 5/5 passing
- Self-review: Found I missed --force flag, added it
- Committed
[Inject covered spec [Sn] sections as Intent; implementer builds]
[Dispatch spec reviewer phase 1: spec sections + diff only, no report]
Spec reviewer (phase 1):
Status: pass
Claims: [S1 · "install at user level"] in-scope · pass — evidence: test "installs to ~/.config" 5/5
[Phase 1 all-pass → skip phase 2; gate passes]
[Dispatch code quality reviewer]
Code reviewer: Strengths: Good test coverage, clean. Issues: None. Approved.
[Gate passed → mark Task 1 done: task done T1]
Task 2: Recovery modes
[Get Task 2 text and context (already extracted)]
[Dispatch implementation subagent with full task text + context]
Implementer: [No questions, proceeds]
Implementer:
- Added verify/repair modes
- 8/8 tests passing
- Self-review: All good
- Committed
[Dispatch spec reviewer phase 1: spec sections + diff only, no report]
Spec reviewer (phase 1):
Status: fail
Claims:
- [S4 · "report every 100 items"] in-scope · fail — evidence: no progress code in diff (omission)
- [S4 · "verify/repair modes"] in-scope · pass — evidence: test "repairs index" 8/8
Extra work: --json flag (no covered claim requires it)
[Phase 1 flagged items → dispatch phase 2 with report]
Spec reviewer (phase 2): report gives no justification for --json; progress still missing — Status: fail
[Gate blocks: in-scope fail]
[Implementer fixes: removed --json, added progress reporting]
[Re-dispatch phase 1]
Spec reviewer (phase 1): Status: pass — all in-scope claims pass with evidence
[Gate passes]
[Dispatch code quality reviewer]
Code reviewer: Strengths: Solid. Issues (Important): Magic number (100)
[Implementer fixes]
Implementer: Extracted PROGRESS_INTERVAL constant
[Code reviewer reviews again]
Code reviewer: ✅ Approved
[Gate passed → mark Task 2 done: task done T2]
...
[After all tasks]
[Dispatch final code-reviewer]
Final reviewer: All requirements met, ready to merge
Done!
vs. Manual execution:
vs. Executing Plans:
Efficiency gains:
Quality gates:
Cost:
Never:
status: pass that has no verifiable evidence (test/exec/file:line)fail or unverifiableIf subagent asks questions:
If reviewer finds issues:
If subagent fails task:
Required workflow skills:
Subagents should use:
Important: Passing skills to subagents
Compose skills do NOT appear in subagents' available_skills list. When a subagent needs to use a skill, pass the relevant <compose_skills> block (or subset) directly in the subagent's prompt. Include this note alongside the block: "The skills listed in <compose_skills> are NOT in your available_skills — this is by design. You can invoke them by name using the skill tool, or read the SKILL.md at the location path."
Alternative workflow: