subagent-dev

name	subagent-dev
description	Use when executing implementation plans with independent tasks in the current session

Subagent-Driven Development

Execute plan by dispatching a fresh implementer subagent per task, a task review (spec compliance + code quality, one reviewer, two verdicts) after each, and a broad whole-branch review at the end.

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 + task review (spec + quality) + broad final review = high quality, fast iteration

Routing gate: 先看 [[agent-routing]] — Routing Table / Orchestration Residency 命中 codex 路徑（mechanical sweep、Codex-primary change、非 view phase 的 spectra-apply）時優先走該表；本 skill 用於 Claude-primary 場景的 plan 執行。回報契約遵循 [[agent-routing]] § Subagent 回報契約。

Narration: between tool calls, narrate at most one short line — the ledger and the tool results carry the record.

Continuous execution: Do not pause to check in with 使用者 between tasks. Execute all tasks without stopping. The only reasons to stop: BLOCKED you cannot resolve, ambiguity that genuinely prevents progress, or all tasks complete.

When to Use

• Have an implementation plan（Spectra /spectra-propose 產出、docs/phases/、或 manual plan）？
• Tasks mostly independent？
• Claude-primary（非 codex 路徑）且要留在當前 session？

三者皆是 → 用本 skill。Tasks tightly coupled → 主線自己做或先拆 plan。

The Process

Setup

1. Read plan once；note global constraints（plan 的 Global Constraints 段或 spec 的專案級要求）
2. update_plan 每個 task
3. Check ledger：cat "$(git rev-parse --show-toplevel)/.spectra/sdd/progress.md"（存在 → 從第一個未標 complete 的 task 續跑，不重派已完成的）
4. 記錄目前 commit 當第一個 task 的 BASE

Pre-Flight Plan Review

Dispatch Task 1 前掃一次 plan：task 間互相矛盾、task 與 Global Constraints 矛盾、plan 明文要求但 review rubric 視為 defect 的東西（不 assert 的 test、大段 verbatim duplication）。發現 → 一次打包問 使用者（每條 finding 附 plan 原文，問哪個作準），不要執行中一條一條打斷。乾淨 → 直接開始。

Per Task Loop

1. scripts/task-brief PLAN_FILE N 產 brief 檔（印出路徑）；記錄 BASE=當前 commit
2. Dispatch implementer（./implementer-prompt.md 模板；prompt 五要素：定位一行、brief 檔路徑、跨 task interfaces、歧義裁決、report 檔路徑＋回報契約）
3. Implementer 提問 → 回答完整再讓它動工
4. Implementer 回報 status（4-status 處置見下）
5. DONE → scripts/review-package BASE HEAD 產 diff 檔 → dispatch task reviewer（./task-reviewer-prompt.md；給 brief 檔 + report 檔 + diff 檔 + 逐字 global constraints）
6. Reviewer 回 spec verdict + quality verdict：Critical / Important → dispatch fix subagent（fix 需附覆蓋該改動的 test 結果）→ 重產 review-package → re-review；Minor → 記進 ledger
7. 兩 verdict 過 → update_plan completed + ledger append 一行：Task N: complete (commits <base7>..<head7>, review clean)
8. → Next task

After All Tasks

1. Final whole-branch review：用 consumer 的 code-review agent（.codex/agents/code-review.toml），範圍 = git merge-base main HEAD..HEAD，並把 ledger 裡累積的 Minor 清單餵給它 triage（哪些 merge 前必修）
2. Final findings → dispatch 一個 fix subagent 拿完整清單（不要一 finding 一 fixer——per-finding fixer 各自重建 context + 重跑 suite，實測比全部 tasks 加起來還貴）
3. 進 /commit 流程

Model Selection

用能勝任該角色的最低檔，dispatch 時 MUST 顯式指定 model（省略 = 靜默繼承主線最貴檔）。

角色	Model	判準
Implementer（brief 內含完整 code，純轉錄＋測試）	haiku	1-2 檔、plan 已寫死 code
Implementer（prose spec、多檔整合）	sonnet	一般情況的 floor
Implementer（架構判斷、需廣泛理解 codebase）	opus	少數
Task reviewer	sonnet 起，依 diff 大小/風險升檔	小機械 diff 不需最強檔；併發/auth/RLS 類升 opus
Final whole-branch review	最強可用檔	唯一一次全域視角

Turn count beats token price：多步驟工作用最低檔常花 2-3× turns 反而總成本更高——prose 型 implementer 與 reviewer 以 sonnet 為 floor。

Handling Implementer Status

DONE: 產 review package → dispatch task reviewer。

DONE_WITH_CONCERNS: 先讀 concerns。關於 correctness / scope → review 前先處理；純觀察（「這檔案變大了」）→ 記下繼續。

NEEDS_CONTEXT: 補缺的資訊重派。

BLOCKED: 依序：(1) context 問題 → 補 context 同 model 重派；(2) 需要更多推理 → 升檔重派；(3) task 太大 → 拆小；(4) plan 本身錯 → 上報 使用者。NEVER 忽略 escalation 或不改任何條件原樣重派。

Handling Reviewer ⚠️ Items

Reviewer 回報「⚠️ Cannot verify from diff」（要求活在未變動 code 或跨 task）→ 不 block 其他 findings，但主線自己逐條解決後才能標 task complete——你握有 plan 與跨 task context，reviewer 沒有。確認真缺 → 當 spec fail 送回 implementer 修 + re-review。

Constructing Reviewer Prompts

• NEVER pre-judge：prompt 出現「do not flag」「不用管 X」「at most Minor」= 你在替自己省 review loop。認為會是 false positive → 讓 reviewer 照報、你在 review loop 裁決
• Global constraints 逐字從 plan / spec 複製進 reviewer prompt——那是它的注意力鏡頭；process 規則（YAGNI、test hygiene）模板已內建，不用重複
• Diff 一律走 scripts/review-package BASE HEAD 檔案交付；BASE 用 dispatch implementer 前記錄的 commit，NEVER HEAD~1（多 commit task 會被靜默截斷）
• Plan-mandated finding（plan 明文要求但 rubric 視為 defect）→ 照報、由 使用者 裁決哪個作準；不得因「plan 要求的」自我豁免
• Fix dispatch 必帶 implementer 契約：重跑覆蓋該改動的 test（dispatch 內指名 test 檔，一行 fix 不用全 suite）並把結果 append 到 report 檔；fix report 缺 test 證據 → 先補齊再 re-review

Durable Progress（ledger）

Conversation memory 不會活過 compaction。實測最貴失敗：controller 失去位置後重派整段已完成的 task。

• Ledger：.spectra/sdd/progress.md（scripts/sdd-workspace 建立，自帶 self-ignoring .gitignore）
• 每個 task review 過 → 立刻 append 一行（commits 範圍 + review clean）
• Compaction / resume 後：信 ledger + git log，不信自己的記憶
• git clean -fdx 會清掉 ledger（gitignored scratch）；發生時從 git log 重建

Prompt Templates

• implementer-prompt.md — implementer dispatch
• task-reviewer-prompt.md — task reviewer dispatch（spec + quality 雙 verdict）
• Final whole-branch review — consumer 的 code-review agent

Example Workflow

[Read plan once；update_plan ×5；check ledger（無）；記 BASE]

Task 1: Add new API endpoint
[scripts/task-brief plan.md 1 → .spectra/sdd/task-1-brief.md]
[Dispatch implementer (sonnet)：定位一行 + brief 路徑 + report 路徑]

Implementer: "should this use service_role or authenticated?"
You: "先用 getSupabaseWithContext(event) 保留 request context；只有 audit、backfill、修復腳本等系統任務才直用 service_role"

Implementer: Status DONE — commits a1b2c3d, "14/14 passing, output pristine", report at .spectra/sdd/task-1-report.md

[scripts/review-package <BASE> HEAD → .spectra/sdd/review-a1b2..d4e5.diff]
[Dispatch task reviewer (sonnet)：brief + report + diff 檔 + global constraints]
Reviewer: Spec ✅；Quality Approved；Minor ×1（記 ledger）

[update_plan 1 completed；ledger append "Task 1: complete (a1b2..d4e5, review clean)"]
Task 2: ...

Red Flags

Never:

• 未經 使用者 同意在 main/master 直接開工（走 [[worktree-default]]）
• 跳過 task review，或接受缺任一 verdict（spec compliance AND quality 都要）的報告
• 帶著未修的 Critical / Important 進下一個 task
• 平行 dispatch 多個 implementer（衝突）
• 讓 subagent 讀整份 plan（用 scripts/task-brief 給它自己那份 brief）
• 把累積的前 task 摘要貼進後續 dispatch（「Tasks 1-3 完成後狀態…」）——fresh subagent 只需要：它的 task、它碰的 interfaces、global constraints
• 跳過 scene-setting 一行（subagent 要知道 task 在整體的位置）
• 忽略 subagent 提問（回答完才讓它動工）
• Spec compliance 收「close enough」
• Reviewer 找到問題後跳過 re-review
• 拿 implementer self-review 取代 task review（兩個都要）
• 在 reviewer prompt 預判 finding 嚴重度或叫它別 flag
• 不產 diff 檔就 dispatch reviewer
• 重派 ledger 已標 complete 的 task（compaction / resume 後先看 ledger + git log）

Integration

• Spectra：/spectra-propose 產 plan → 本 skill 執行（Claude-primary 場景）；spectra-apply 的 phase dispatch 分流見 [[agent-routing]]
• [[agent-routing]] § Subagent 回報契約：4-status / report-as-claims / file handoffs / model 顯式——brief 必含
• [[worktree-default]]：開工前確保隔離 worktree
• [[testing-anti-patterns]]：implementer 測試紀律
• 主線 verify：收到任何 status=DONE 仍 MUST git status --short + git diff 核實 scope = brief 宣告（report 是未驗證主張）