uctm 1.3.2 → 1.5.0

package/.claude-plugin/plugin.json

@@ -0,0 +1,29 @@
+{
+  "name": "uc-taskmanager",
+  "version": "1.4.0",
+  "agents": [
+    "./agents/specifier.md",
+    "./agents/planner.md",
+    "./agents/scheduler.md",
+    "./agents/builder.md",
+    "./agents/verifier.md",
+    "./agents/committer.md"
+  ],
+  "description": "SDD WORK-PIPELINE Agent — Requirements analysis & development 6-agent full pipeline with DAG-based orchestration and sliding window context management",
+  "author": {
+    "name": "UCJung",
+    "url": "https://github.com/UCJung"
+  },
+  "homepage": "https://github.com/UCJung/uc-taskmanager-claude-agent",
+  "repository": "https://github.com/UCJung/uc-taskmanager-claude-agent",
+  "license": "GPL-3.0",
+  "keywords": [
+    "task-manager",
+    "pipeline",
+    "sub-agents",
+    "sdd",
+    "dag-orchestration",
+    "work-pipeline",
+    "automation"
+  ]
+}

package/agents/agent-flow.md

@@ -28,41 +28,37 @@
 
 ```
 1. Invoke specifier → creates Requirement.md + PLAN.md + TASK-00 + returns builder dispatch XML
-2. [1 approval] User review (integrated requirement + design)
+2. ⛔ STOP — Present summary to user and WAIT for approval (do NOT invoke builder)
 3. Invoke builder (dispatch XML as prompt) — includes self-check
-4. Invoke committer (builder result as prompt)
+4. Invoke verifier+committer (builder result as prompt) — verify then commit in one spawn
 ```
 
-> Verifier skipped: Builder performs self-check (build/lint), so separate verification is unnecessary for a single TASK.
+> Verifier+Committer combined: single spawn performs verification, then creates result.md and git commit.
 
 ---
 
 ## Pipeline Mode (Separate Planner Invocation)
 
 ```
-1. Invoke specifier → creates Requirement.md + returns planner dispatch XML
-2. [Planning approval] User review (Requirement.md)
-3. Invoke planner (dispatch XML as prompt) → creates PLAN.md + TASK-NN + determines execution-mode
-4. [Development approval] User review (PLAN.md + TASK list)
-5. Invoke builder (per-TASK dispatch XML as prompt)
-6. Invoke verifier (builder result as prompt)
-7. Invoke committer (verifier result as prompt)
+1. Invoke specifier+planner (single spawn) → creates Requirement.md + PLAN.md + TASK-NN + determines execution-mode
+2. ⛔ STOP — Present Requirement.md + PLAN.md + TASK list and WAIT for approval
+3. Invoke builder (per-TASK dispatch XML as prompt)
+4. Invoke verifier+committer (builder result as prompt) — verify then commit in one spawn
 ```
 
+> Specifier+Planner combined: specifier.md role first (Requirement.md), then planner.md role (PLAN.md + TASKs) in one spawn.
+
 ---
 
 ## Full Mode (With Scheduler)
 
 ```
-1. Invoke specifier → creates Requirement.md + returns planner dispatch XML
-2. [Planning approval] User review (Requirement.md)
-3. Invoke planner → PLAN.md + TASK decomposition + execution-mode: full
-4. [Development approval] User review (PLAN.md + TASK list)
-5. Invoke scheduler → DAG analysis + READY TASK + returns builder dispatch XML
-6. Invoke builder (dispatch XML as prompt) → implementation
-7. Invoke verifier (builder result as prompt) → verification
-8. Invoke committer (verifier result as prompt) → commit
-9. If incomplete TASKs remain, return to step 5
+1. Invoke specifier+planner (single spawn) → Requirement.md + PLAN.md + TASKs + execution-mode: full
+2. ⛔ STOP — Present Requirement.md + PLAN.md + TASK list and WAIT for approval
+3. Invoke scheduler → DAG analysis + READY TASK + returns builder dispatch XML
+4. Invoke builder (dispatch XML as prompt) → implementation
+5. Invoke verifier+committer (builder result as prompt) → verify then commit in one spawn
+6. If incomplete TASKs remain, return to step 3
 ```
 
 Parallel execution: When scheduler returns multiple READY TASKs, invoke builders concurrently.
@@ -75,42 +71,102 @@ Resume pipeline for a WORK that already has PLAN.md + TASKs:
 
 ```
 1. Invoke scheduler → check READY TASKs + return builder dispatch XML
-2. Execute builder → verifier → committer in sequence
-3. If incomplete TASKs remain, return to step 1
+2. Invoke builder → implementation
+3. Invoke verifier+committer → verify then commit in one spawn
+4. If incomplete TASKs remain, return to step 1
 ```
 
 ---
 
+## Combined Agent Invocation
+
+### Specifier+Planner (single spawn)
+
+When invoking specifier in pipeline/full mode, include both agent definitions:
+
+```
+Prompt to agent:
+  "You will perform two roles in sequence.
+
+   Role 1 — Specifier: Read specifier.md and create Requirement.md.
+   Role 2 — Planner: Read planner.md and create PLAN.md + TASK files.
+
+   Execute Role 1 first, then Role 2. Return the combined result."
+```
+
+- Use specifier's model (opus) for the spawn
+- Agent reads both specifier.md and planner.md from REFERENCES_DIR
+- Returns: Requirement.md + PLAN.md + TASK files + execution-mode
+
+### Verifier+Committer (single spawn)
+
+When invoking verification after builder completes:
+
+```
+Prompt to agent:
+  "You will perform two roles in sequence.
+
+   Role 1 — Verifier: Read verifier.md and verify build/lint/test.
+   Role 2 — Committer: Read committer.md and create result.md + git commit.
+
+   Execute Role 1 first. If verification PASSES, execute Role 2.
+   If verification FAILS, skip Role 2 and return FAIL result."
+```
+
+- Use verifier's model (haiku) for the spawn
+- Agent reads both verifier.md and committer.md from REFERENCES_DIR
+- On PASS: returns verification result + commit hash
+- On FAIL: returns verification failure only (no commit)
+
+---
+
 ## Agent Role Summary
 
-| Agent | Return Value | Invoked By |
-|-------|-------------|------------|
-| specifier | Requirement.md + (when assumed) PLAN.md/TASK + dispatch XML | Main Claude |
-| planner | PLAN.md/TASK files created + execution-mode | Main Claude |
-| scheduler | READY TASK + dispatch XML | Main Claude |
-| builder | task-result XML (including context-handoff) | Main Claude |
-| verifier | task-result XML | Main Claude |
-| committer | task-result XML + commit hash | Main Claude |
+| Agent | Role | Model | Combined With |
+|-------|------|-------|---------------|
+| specifier | Requirement analysis | opus | + planner (pipeline/full) |
+| planner | PLAN + TASK decomposition | opus | combined into specifier spawn |
+| scheduler | DAG management + dispatch | haiku | standalone |
+| builder | Code implementation | sonnet | standalone |
+| verifier | Build/lint/test verification | haiku | + committer |
+| committer | Result report + git commit | haiku | combined into verifier spawn |
 
 ---
 
-## Sub-agent Invocation Count by Mode
+## Sub-agent Spawn Count by Mode
+
+| Mode | Spec+Plan | Scheduler | Builder | Veri+Commit | Total |
+|------|:---------:|:---------:|:-------:|:-----------:|:-----:|
+| direct | 1 (assumed) | — | 1 | 1 | **3** |
+| pipeline | 1 (combined) | — | 1 | 1 | **3** |
+| full (N TASKs) | 1 (combined) | 1 | N | N | **2 + 2N** |
 
-| Mode | Specifier | Planner | Scheduler | Builder | Verifier | Committer | Total |
-|------|:---------:|:-------:|:---------:|:-------:|:--------:|:---------:|:-----:|
-| direct | O (assumed) | X | X | O | X | O | **3** |
-| pipeline | O | O | X | O | O | O | **5** |
-| full | O | O | O | O | O | O | **6** |
+**Before vs After (6 TASKs):**
+
+| | Before | After | Reduction |
+|---|:---:|:---:|:---:|
+| Spawns | 2 + 3×6 = 20 | 2 + 2×6 = 14 | **-30%** |
 
 ---
 
-## Approval Gates
+## Approval Gates (CRITICAL)
+
+> **MUST STOP and wait for explicit user approval before invoking the next agent.**
+> Do NOT proceed until the user says "approve", "승인", "proceed", "go ahead", or equivalent.
+> The only exception is auto mode — when the user's original message contains "auto" or "자동으로".
 
-| Mode | Approvals | Timing |
-|------|:---------:|--------|
-| direct | 1 | After Specifier completes (integrated requirement + design) |
-| pipeline/full | 2 | Planning approval (Requirement.md) → Development approval (PLAN.md) |
-| auto-approve | 0 | When "proceed automatically" is explicitly stated |
+| Mode | Approvals | Timing | What to show user |
+|------|:---------:|--------|-------------------|
+| direct | 1 | After Specifier completes | Requirement.md + PLAN.md + TASK-00.md summary |
+| pipeline/full | 1 | After Specifier+Planner completes | Requirement.md + PLAN.md + TASK list |
+| auto-approve | 0 | — | Skip all approval gates |
+
+> Note: pipeline/full now has **1 approval** (not 2), since specifier and planner run in one spawn.
+
+**How to request approval:**
+1. Present a summary of what the specifier+planner created (files, scope, execution-mode)
+2. Ask: "Proceed?" or equivalent
+3. **WAIT for user response** — do NOT invoke builder until approved
 
 ---
 
@@ -173,3 +229,51 @@ If REFERENCES_DIR is not available (e.g., npm installation without plugin), sub-
 | Previous | FULL | what + why + caution + incomplete |
 | 2 steps back | SUMMARY | what 1-2 lines |
 | 3+ steps | DROP | Not passed |
+
+---
+
+## ref-cache Chain Propagation
+
+`<ref-cache>` carries pre-loaded reference file contents through the pipeline, eliminating redundant disk reads in each sub-agent.
+
+### Rules
+
+1. **First agent (typically specifier)** — no ref-cache available on dispatch. Reads reference files from `REFERENCES_DIR` normally.
+
+2. **Agent returns task-result** — if the agent supports ref-cache, it includes `<ref-cache>` in its task-result XML containing all reference files it loaded.
+
+3. **Main Claude propagates ref-cache** — when dispatching the next agent, copy the `<ref-cache>` block from the previous task-result into the new dispatch XML unchanged.
+
+4. **Receiving agent skips file reads** — when `<ref-cache>` is present in the dispatch XML, the agent reads reference content from `<ref>` elements instead of reading files from disk.
+
+5. **Missing ref-cache** — if a task-result does not contain `<ref-cache>` (agent does not support it yet), omit `<ref-cache>` from the next dispatch. The receiving agent falls back to reading files from disk.
+
+### Flow Example
+
+```
+specifier+planner (no ref-cache in) → reads files → returns task-result with <ref-cache>
+  ↓ Main Claude copies <ref-cache> into dispatch
+builder (ref-cache in) → skips file reads → returns task-result with <ref-cache>
+  ↓ Main Claude copies <ref-cache> into dispatch
+verifier+committer (ref-cache in) → skips file reads → commit
+```
+
+### Phase 2: Selective Section Delivery
+
+Instead of passing full reference files, Main Claude extracts only the sections each agent needs. This reduces dispatch token size by 50-70%.
+
+**Main Claude reads reference files once at pipeline start**, then delivers condensed `<ref-cache>` per agent using this mapping:
+
+| Agent | shared-prompt-sections | file-content-schema | xml-schema | context-policy | work-activity-log |
+|-------|:---:|:---:|:---:|:---:|:---:|
+| **specifier+planner** | §1,§2,§7,§8,§9,§11 | §0,§1,§2,§3 | §1,§3 | — | full |
+| **scheduler** | §4,§8,§10 | §1,§6 | §1,§3,§4,§5 | full | full |
+| **builder** | §1,§2,§10,§12 | §2,§3 | §1,§2,§4 | Builder section | full |
+| **verifier+committer** | §1,§2,§8,§10,§12 | §3,§4,§5,§6,§7 | §1,§2,§4 | Verifier+Committer | full |
+
+**Delivery format**: Condense each `<ref key="">` to contain only the needed sections, not the full file. Use one-line summaries for simple rules, keep full content only for templates and code blocks.
+
+### Constraints
+
+- **ref-cache does not replace REFERENCES_DIR** — always pass `REFERENCES_DIR` (or `<references-dir>`) in every dispatch regardless of ref-cache presence, for backward compatibility.
+- **Agents may still read files** — if ref-cache content is insufficient, agents fall back to reading from disk.

package/agents/builder.md

@@ -35,13 +35,24 @@ You are the **Builder** — the implementation agent that receives a TASK specif
 
 **Resolve REFERENCES_DIR**: Check your input for `REFERENCES_DIR=...` line or `<references-dir>` XML element. Use that absolute path. If not provided, default to `.claude/agents`.
 
-| File | Purpose |
-|------|---------|
-| `{REFERENCES_DIR}/file-content-schema.md` | File format schema |
-| `{REFERENCES_DIR}/shared-prompt-sections.md` | Common rules (TASK ID, PLAN.md 7 fields, WORK-LIST) |
-| `{REFERENCES_DIR}/xml-schema.md` | XML communication format |
-| `{REFERENCES_DIR}/context-policy.md` | Sliding window rules |
-| `{REFERENCES_DIR}/work-activity-log.md` | Activity Log rules (log_work function, STAGE table) |
+#### Reference Loading (ref-cache)
+
+1. Check if `<ref-cache>` exists in the received dispatch XML
+2. For each required reference file:
+   - If present in ref-cache → **SKIP file read**, use cached content
+   - If absent from ref-cache → Read from `{REFERENCES_DIR}/{filename}.md` and add to ref-cache
+3. On task completion, include the merged `<ref-cache>` in the returned task-result XML
+4. **Backward compatibility**: If dispatch contains no `<ref-cache>`, read all reference files normally (existing behavior)
+
+Required reference files for this agent:
+
+| File | ref-cache key |
+|------|---------------|
+| `{REFERENCES_DIR}/file-content-schema.md` | `file-content-schema` |
+| `{REFERENCES_DIR}/shared-prompt-sections.md` | `shared-prompt-sections` |
+| `{REFERENCES_DIR}/xml-schema.md` | `xml-schema` |
+| `{REFERENCES_DIR}/context-policy.md` | `context-policy` |
+| `{REFERENCES_DIR}/work-activity-log.md` | `work-activity-log` |
 
 ### 3-2. XML Input Parsing
 
@@ -115,6 +126,7 @@ Invoked after each major checkpoint update. Continues implementation even on fai
 
 → task-result XML base structure: see `xml-schema.md` § 2
 → context-handoff element: see `xml-schema.md` § 4
+→ ref-cache element: see `xml-schema.md` § 6
 
 Builder-specific additional fields:
 
@@ -124,6 +136,12 @@ Builder-specific additional fields:
   <check name="lint" status="PASS" />
 </self-check>
 <notes>{items for verifier to check}</notes>
+<ref-cache>
+  <!-- Include all reference files loaded during this execution (from disk or received ref-cache) -->
+  <ref key="shared-prompt-sections">{content}</ref>
+  <ref key="xml-schema">{content}</ref>
+  <!-- ... other keys loaded ... -->
+</ref-cache>
 ```
 
 ### 3-9. Retry Protocol

package/agents/committer.md

@@ -34,13 +34,24 @@ You are the **Committer** — the agent that generates the result report for a v
 
 **Resolve REFERENCES_DIR**: Check your input for `REFERENCES_DIR=...` line or `<references-dir>` XML element. Use that absolute path. If not provided, default to `.claude/agents`.
 
-| File | Purpose |
-|------|---------|
-| `{REFERENCES_DIR}/file-content-schema.md` | File format schema |
-| `{REFERENCES_DIR}/shared-prompt-sections.md` | Common rules |
-| `{REFERENCES_DIR}/xml-schema.md` | XML communication format |
-| `{REFERENCES_DIR}/context-policy.md` | Sliding window rules |
-| `{REFERENCES_DIR}/work-activity-log.md` | Activity Log rules (log_work function, STAGE table) |
+#### Reference Loading (ref-cache)
+
+1. Check if `<ref-cache>` exists in the received dispatch XML
+2. For each required reference file:
+   - If present in ref-cache → **SKIP file read**, use cached content
+   - If absent from ref-cache → Read from `{REFERENCES_DIR}/{filename}.md` and add to ref-cache
+3. On task completion, include the merged `<ref-cache>` in the returned task-result XML
+4. **Backward compatibility**: If dispatch contains no `<ref-cache>`, read all reference files normally (existing behavior)
+
+Required reference files for this agent:
+
+| File | ref-cache key |
+|------|---------------|
+| `{REFERENCES_DIR}/file-content-schema.md` | `file-content-schema` |
+| `{REFERENCES_DIR}/shared-prompt-sections.md` | `shared-prompt-sections` |
+| `{REFERENCES_DIR}/xml-schema.md` | `xml-schema` |
+| `{REFERENCES_DIR}/context-policy.md` | `context-policy` |
+| `{REFERENCES_DIR}/work-activity-log.md` | `work-activity-log` |
 
 ### 3-2. XML Input Parsing
 
@@ -96,38 +107,31 @@ fi
 
 ### 3-6. Git Check
 
-```bash
-if ! git rev-parse --is-inside-work-tree > /dev/null 2>&1; then
-  echo "WARNING: No git repository found. Skipping git commit."
-  echo "Result file saved at: works/${WORK_ID}/TASK-XX_result.md"
-  # → Jump directly to step 7 (TaskCallback)
-fi
-```
+→ **Bash command rules: see `shared-prompt-sections.md` § 13**
 
-If git is not available, skip step 3-7 (Git Commit). The result.md, PROGRESS.md, and WORK-LIST.md are already saved — the user can `git init && git add . && git commit` later.
+Run `git rev-parse --is-inside-work-tree` (single command). If it fails, skip steps 3-7 and jump to step 7 (TaskCallback). The result.md, PROGRESS.md, and WORK-LIST.md are already saved.
 
 ### 3-7. Git Commit
 
-```bash
-RESULT_FILE="works/${WORK_ID}/TASK-XX_result.md"
-[ ! -f "$RESULT_FILE" ] && echo "ABORT: result file not found" && exit 1
+**Each command below is a separate Bash call — do NOT chain with `&&` or `;`:**
 
-# Stage WORK management files (Requirement, PLAN, TASK, progress, result)
-git add "works/${WORK_ID}/"
+1. Verify result file exists: use `Read` tool on `works/{WORK_ID}/TASK-XX_result.md`
+2. `git add works/{WORK_ID}/`
+3. `git add works/WORK-LIST.md`
+4. `git add <builder-changed-file-1>` (one `git add` per file, or space-separated in one call)
+5. `git commit -m "{type}(TASK-XX): {title}..."` (commit message via heredoc)
 
-# Stage WORK-LIST.md (includes DONE status if last TASK)
+```
+# Example — each line is a SEPARATE Bash call:
+git add works/WORK-01/
 git add works/WORK-LIST.md
+git add src/app.js
+git commit -m "feat(TASK-00): Add authentication module
 
-# Stage builder-changed files from progress.md
-# (parse Files changed section and add each file)
-git add <builder-changed-files>
-
-git commit -m "{type}(TASK-XX): {title}
-
-- {change 1}
-- {change 2}
+- Created auth middleware
+- Added JWT token validation
 
-Result: works/${WORK_ID}/TASK-XX_result.md"
+Result: works/WORK-01/TASK-00_result.md"
 ```
 
 | Content | Type |
@@ -148,6 +152,7 @@ Payload fields: `"status": "SUCCESS"`, `"commitHash": "${COMMIT_HASH}"` (run `gi
 ### 3-9. Result Report
 
 → task-result XML base structure: see `xml-schema.md` § 2
+→ ref-cache element: see `xml-schema.md` § 6
 
 Committer-specific additional fields:
 
@@ -165,6 +170,12 @@ Committer-specific additional fields:
 <next-tasks>
   <task id="TASK-YY" status="READY">{title}</task>
 </next-tasks>
+<ref-cache>
+  <!-- Include all reference files loaded during this execution (from disk or received ref-cache) -->
+  <ref key="shared-prompt-sections">{content}</ref>
+  <ref key="xml-schema">{content}</ref>
+  <!-- ... other keys loaded ... -->
+</ref-cache>
 ```
 
 → see `{REFERENCES_DIR}/shared-prompt-sections.md` § 8

package/agents/ko/agent-flow.md

@@ -28,41 +28,37 @@
 
 ```
 1. specifier 호출 → Requirement.md + PLAN.md + TASK-00 생성 + builder dispatch XML 반환
-2. [승인 1회] 사용자 검토 (요구사항 + 설계 통합)
+2. ⛔ STOP — 산출물 요약을 사용자에게 제시하고 승인을 기다린다 (builder 호출 금지)
 3. builder 호출 (dispatch XML을 prompt로) — self-check 포함
-4. committer 호출 (builder 결과를 prompt로)
+4. verifier+committer 호출 (builder 결과를 prompt로) — 단일 spawn에서 검증 후 커밋
 ```
 
-> Verifier 생략: Builder가 self-check(build/lint)를 수행하므로 단일 TASK에서 별도 검증 불필요.
+> Verifier+Committer 통합: 단일 spawn에서 검증 수행 후 result.md 생성 + git commit.
 
 ---
 
 ## pipeline 모드 (Planner 별도 호출)
 
 ```
-1. specifier 호출 → Requirement.md 생성 + planner dispatch XML 반환
-2. [기획 승인] 사용자 검토 (Requirement.md)
-3. planner 호출 (dispatch XML을 prompt로) → PLAN.md + TASK-NN 생성 + execution-mode 결정
-4. [개발 승인] 사용자 검토 (PLAN.md + TASK 목록)
-5. builder 호출 (TASK별 dispatch XML을 prompt로)
-6. verifier 호출 (builder 결과를 prompt로)
-7. committer 호출 (verifier 결과를 prompt로)
+1. specifier+planner 호출 (단일 spawn) → Requirement.md + PLAN.md + TASK-NN 생성 + execution-mode 결정
+2. ⛔ STOP — Requirement.md + PLAN.md + TASK 목록을 제시하고 승인을 기다린다
+3. builder 호출 (TASK별 dispatch XML을 prompt로)
+4. verifier+committer 호출 (builder 결과를 prompt로) — 단일 spawn에서 검증 후 커밋
 ```
 
+> Specifier+Planner 통합: specifier.md 역할 (Requirement.md) 수행 후 planner.md 역할 (PLAN.md + TASKs) 순차 수행.
+
 ---
 
 ## full 모드 (Scheduler 포함)
 
 ```
-1. specifier 호출 → Requirement.md 생성 + planner dispatch XML 반환
-2. [기획 승인] 사용자 검토 (Requirement.md)
-3. planner 호출 → PLAN.md + TASK 분해 + execution-mode: full 결정
-4. [개발 승인] 사용자 검토 (PLAN.md + TASK 목록)
-5. scheduler 호출 → DAG 분석 + READY TASK + builder dispatch XML 반환
-6. builder 호출 (dispatch XML을 prompt로) → 구현
-7. verifier 호출 (builder 결과를 prompt로) → 검증
-8. committer 호출 (verifier 결과를 prompt로) → commit
-9. 미완료 TASK 있으면 5번으로 돌아감
+1. specifier+planner 호출 (단일 spawn) → Requirement.md + PLAN.md + TASK 분해 + execution-mode: full
+2. ⛔ STOP — Requirement.md + PLAN.md + TASK 목록을 제시하고 승인을 기다린다
+3. scheduler 호출 → DAG 분석 + READY TASK + builder dispatch XML 반환
+4. builder 호출 (dispatch XML을 prompt로) → 구현
+5. verifier+committer 호출 (builder 결과를 prompt로) → 단일 spawn에서 검증 후 커밋
+6. 미완료 TASK 있으면 3번으로 돌아감
 ```
 
 병렬 실행: scheduler가 복수의 READY TASK를 반환하면 builder를 동시에 호출한다.
@@ -75,42 +71,102 @@
 
 ```
 1. scheduler 호출 → READY TASK 확인 + builder dispatch XML 반환
-2. builder → verifier → committer 순서대로 실행
-3. 미완료 TASK 있으면 1번으로 돌아감
+2. builder 호출 → 구현
+3. verifier+committer 호출 → 단일 spawn에서 검증 후 커밋
+4. 미완료 TASK 있으면 1번으로 돌아감
 ```
 
 ---
 
+## 통합 에이전트 호출
+
+### Specifier+Planner (단일 spawn)
+
+pipeline/full 모드에서 specifier 호출 시 양쪽 에이전트 정의를 포함:
+
+```
+에이전트에 전달할 프롬프트:
+  "두 가지 역할을 순서대로 수행하라.
+
+   역할 1 — Specifier: specifier.md를 읽고 Requirement.md를 생성하라.
+   역할 2 — Planner: planner.md를 읽고 PLAN.md + TASK 파일을 생성하라.
+
+   역할 1을 먼저 수행한 후 역할 2를 수행하라. 통합 결과를 반환하라."
+```
+
+- specifier의 모델(opus)로 spawn
+- REFERENCES_DIR에서 specifier.md와 planner.md 양쪽 참조
+- 반환: Requirement.md + PLAN.md + TASK 파일 + execution-mode
+
+### Verifier+Committer (단일 spawn)
+
+builder 완료 후 검증 호출 시:
+
+```
+에이전트에 전달할 프롬프트:
+  "두 가지 역할을 순서대로 수행하라.
+
+   역할 1 — Verifier: verifier.md를 읽고 build/lint/test를 검증하라.
+   역할 2 — Committer: committer.md를 읽고 result.md를 생성하고 git commit하라.
+
+   역할 1을 먼저 수행하라. 검증 통과 시 역할 2를 수행하라.
+   검증 실패 시 역할 2를 건너뛰고 FAIL 결과만 반환하라."
+```
+
+- verifier의 모델(haiku)로 spawn
+- REFERENCES_DIR에서 verifier.md와 committer.md 양쪽 참조
+- 통과 시: 검증 결과 + commit hash 반환
+- 실패 시: 검증 실패만 반환 (커밋 없음)
+
+---
+
 ## 에이전트 역할 요약
 
-| 에이전트 | 반환값 | 호출 주체 |
-|---------|-------|---------|
-| specifier | Requirement.md + (겸임 시) PLAN.md/TASK + dispatch XML | Main Claude |
-| planner | PLAN.md/TASK 파일 생성 완료 + execution-mode | Main Claude |
-| scheduler | READY TASK + dispatch XML | Main Claude |
-| builder | task-result XML (context-handoff 포함) | Main Claude |
-| verifier | task-result XML | Main Claude |
-| committer | task-result XML + commit hash | Main Claude |
+| 에이전트 | 역할 | 모델 | 통합 대상 |
+|---------|------|------|----------|
+| specifier | 요구사항 분석 | opus | + planner (pipeline/full) |
+| planner | PLAN + TASK 분해 | opus | specifier spawn에 통합 |
+| scheduler | DAG 관리 + dispatch | haiku | 단독 |
+| builder | 코드 구현 | sonnet | 단독 |
+| verifier | build/lint/test 검증 | haiku | + committer |
+| committer | 결과 보고 + git commit | haiku | verifier spawn에 통합 |
 
 ---
 
-## 모드별 서브에이전트 호출 횟수
+## 모드별 서브에이전트 Spawn 횟수
+
+| 모드 | Spec+Plan | Scheduler | Builder | Veri+Commit | 합계 |
+|------|:---------:|:---------:|:-------:|:-----------:|:----:|
+| direct | 1 (겸임) | — | 1 | 1 | **3** |
+| pipeline | 1 (통합) | — | 1 | 1 | **3** |
+| full (N TASK) | 1 (통합) | 1 | N | N | **2 + 2N** |
+
+**Before vs After (6 TASK 기준):**
 
-| 모드 | Specifier | Planner | Scheduler | Builder | Verifier | Committer | 합계 |
-|------|:---------:|:-------:|:---------:|:-------:|:--------:|:---------:|:----:|
-| direct | O (겸임) | X | X | O | X | O | **3회** |
-| pipeline | O | O | X | O | O | O | **5회** |
-| full | O | O | O | O | O | O | **6회** |
+| | Before | After | 감소율 |
+|---|:---:|:---:|:---:|
+| Spawn 횟수 | 2 + 3×6 = 20 | 2 + 2×6 = 14 | **-30%** |
 
 ---
 
-## 승인 게이트
+## 승인 게이트 (CRITICAL)
+
+> **반드시 STOP하고 사용자의 명시적 승인을 기다린 후 다음 에이전트를 호출하라.**
+> 사용자가 "승인", "approve", "진행", "go ahead" 등으로 응답할 때까지 다음 단계로 넘어가지 마라.
+> 유일한 예외는 auto 모드 — 사용자의 원래 메시지에 "auto" 또는 "자동으로"가 포함된 경우.
+
+| 모드 | 승인 횟수 | 시점 | 사용자에게 보여줄 내용 |
+|------|:---------:|------|----------------------|
+| direct | 1회 | Specifier 완료 후 | Requirement.md + PLAN.md + TASK-00.md 요약 |
+| pipeline/full | 1회 | Specifier+Planner 완료 후 | Requirement.md + PLAN.md + TASK 목록 |
+| 자동 승인 | 0회 | — | 모든 승인 게이트 생략 |
+
+> 참고: pipeline/full 승인이 **2회에서 1회**로 줄었다 (specifier+planner가 단일 spawn이므로).
 
-| 모드 | 승인 횟수 | 시점 |
-|------|:---------:|------|
-| direct | 1회 | Specifier 완료 후 (요구사항 + 설계 통합) |
-| pipeline/full | 2회 | 기획 승인 (Requirement.md) → 개발 승인 (PLAN.md) |
-| 자동 승인 | 0회 | "자동으로 진행" 명시 시 |
+**승인 요청 방법:**
+1. specifier+planner가 생성한 산출물 요약을 제시 (파일, 범위, execution-mode)
+2. "진행할까요?" 또는 동등한 질문
+3. **사용자 응답을 기다린다** — 승인 전까지 builder를 호출하지 마라
 
 ---
 

package/agents/ko/builder.md

@@ -35,13 +35,24 @@ You are the **Builder** — TASK 명세를 받아 실제 코드를 구현하고
 
 **REFERENCES_DIR 결정**: 입력에서 `REFERENCES_DIR=...` 라인 또는 `<references-dir>` XML 요소를 확인. 해당 절대 경로를 사용. 없으면 기본값 `.claude/agents` 사용.
 
-| 파일 | 목적 |
-|------|------|
-| `{REFERENCES_DIR}/file-content-schema.md` | 파일 포맷 스키마 |
-| `{REFERENCES_DIR}/shared-prompt-sections.md` | 공통 규칙 (TASK ID, PLAN.md 7개 필드, WORK-LIST) |
-| `{REFERENCES_DIR}/xml-schema.md` | XML 통신 포맷 |
-| `{REFERENCES_DIR}/context-policy.md` | 슬라이딩 윈도우 규칙 |
-| `{REFERENCES_DIR}/work-activity-log.md` | Activity Log 규칙 (log_work 함수, STAGE 테이블) |
+#### Reference Loading (ref-cache)
+
+1. 수신한 dispatch XML에 `<ref-cache>`가 있는지 확인한다
+2. 필요한 참조 파일별로:
+   - ref-cache에 있으면 → **파일 읽기 SKIP**, 캐시된 내용 사용
+   - ref-cache에 없으면 → `{REFERENCES_DIR}/{filename}.md`에서 읽고 ref-cache에 추가
+3. 작업 완료 시 병합된 `<ref-cache>`를 반환 task-result XML에 포함한다
+4. **하위 호환성**: dispatch에 `<ref-cache>`가 없으면 기존 방식대로 모든 참조 파일을 읽는다 (기존 동작 유지)
+
+이 에이전트의 필수 참조 파일:
+
+| 파일 | ref-cache key |
+|------|---------------|
+| `{REFERENCES_DIR}/file-content-schema.md` | `file-content-schema` |
+| `{REFERENCES_DIR}/shared-prompt-sections.md` | `shared-prompt-sections` |
+| `{REFERENCES_DIR}/xml-schema.md` | `xml-schema` |
+| `{REFERENCES_DIR}/context-policy.md` | `context-policy` |
+| `{REFERENCES_DIR}/work-activity-log.md` | `work-activity-log` |
 
 ### 3-2. XML Input 파싱