Subagent Dev

---
name: subagent-dev
description: Use when executing implementation plans with independent tasks in the current session. NOT for 單一線性任務或 3 個 tool call 內做得完的事（主線自己做，per agent-routing § 派不派），NOT for 建立隔離工作環境本身（走 /wt）。
permission_tier: read-only
---
<!-- 🔒 LOCKED — managed by clade · auto-generated by sync-to-cursor; edit source in .claude/ then re-run sync -->

# 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 命中 pi 路徑（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（非 pi 路徑）且要留在當前 session？

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

## The Process

### Setup

1. Read plan once；note global constraints（plan 的 Global Constraints 段或 spec 的專案級要求）
2. `TaskCreate` 每個 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 過 → `TaskUpdate` 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（`.cursor/agents/code-review.md`），範圍 = `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

`Agent(model: haiku|sonnet)` 會被 PreToolUse 機械 gate 立即攔下（**不分 `subagent_type`**，per
[[agent-routing]] § Claude 委派的 model 檔位）。所以本表**不出現 `haiku` 與 `sonnet`**——implementer
的兩個檔位改由 Pi 承接，那是同級工作換 runtime，不是降檔。

| 角色 | 檔位 | 判準 |
| --- | --- | --- |
| Implementer（brief 內含完整 code，純轉錄＋測試） | Pi `--model gemini --effort low` | 1-2 檔、plan 已寫死 code。原判 `haiku` 的 delegate-sub 轉派 |
| Implementer（prose spec、多檔整合） | Pi `--model gemini --effort high` | 一般情況的 floor。原判 `sonnet` 的 delegate-sub 轉派 |
| Implementer（架構判斷、需廣泛理解 codebase） | Claude `opus` | 少數。Opus 不在機械 gate 範圍 |
| Task reviewer | Claude，**省略 `model`**（繼承主線）；併發／auth／RLS 類顯式 `opus` | 輸出本身是 gate = [[agent-routing]] § NEVER 降檔的形狀。省略與 Opus 都不在機械 gate 範圍 |
| Final whole-branch review | 最強可用檔 | 唯一一次全域視角 |

**Implementer 走 Pi 的兩項前置**（[[agent-routing]] § `subagent_type` 是 `general-purpose` 或 `Explore` 時
的 (b) 機械改寫）：改動有硬 gate（typecheck／test／lint 的 exit code）接住，且可一鍵 `git checkout` 還原。
本 skill 的 task-brief ＋ task reviewer 流程恰好提供這兩項。兩項缺一 → 照原判派 Claude `sonnet`，
並在 dispatch 前依機械 gate 的 receipt 流程結案。

**每一個** Pi dispatch 都 MUST 帶 `--route claude-delegate-sub --tier-basis delegate-sub`。
gemini 回 exit 2 → 升 `--model astra` 重派一次（原 `low` 保留，其餘 effort 改 `medium`）；再 fail 才回 Claude `sonnet`（走
`delegate-escalation-failed` fallback receipt）。exit 3／4 照 [[agent-routing]] 的 watch-protocol
與 § 配額耗盡時的 fallback 紀律走，**NEVER** 記入品質判斷。

**Turn count beats token price**：多步驟工作用最低檔常花 2-3× turns 反而總成本更高——prose 型
implementer 的 floor 是 `--effort high`，不是 `low`。

## 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-prompt.md) — implementer dispatch
- [task-reviewer-prompt.md](task-reviewer-prompt.md) — task reviewer dispatch（spec + quality 雙 verdict）
- Final whole-branch review — consumer 的 `code-review` agent

## Example Workflow

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

Task 1: Add new API endpoint
[scripts/task-brief plan.md 1 → .spectra/sdd/task-1-brief.md]
[Dispatch implementer：Pi --model gemini --effort high --route claude-delegate-sub --tier-basis delegate-sub；定位一行 + 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：Claude，省略 model；brief + report + diff 檔 + global constraints]
Reviewer: Spec ✅；Quality Approved；Minor ×1（記 ledger）

[TaskUpdate 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 是未驗證主張）