uctm 1.3.2 → 1.4.0

package/agents/agent-flow.md

@@ -28,7 +28,7 @@
 
 ```
 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)
 ```
@@ -41,9 +41,9 @@
 
 ```
 1. Invoke specifier → creates Requirement.md + returns planner dispatch XML
-2. [Planning approval] User review (Requirement.md)
+2. ⛔ STOP — Present Requirement.md summary and WAIT for planning approval
 3. Invoke planner (dispatch XML as prompt) → creates PLAN.md + TASK-NN + determines execution-mode
-4. [Development approval] User review (PLAN.md + TASK list)
+4. ⛔ STOP — Present PLAN.md + TASK list and WAIT for development approval
 5. Invoke builder (per-TASK dispatch XML as prompt)
 6. Invoke verifier (builder result as prompt)
 7. Invoke committer (verifier result as prompt)
@@ -55,9 +55,9 @@
 
 ```
 1. Invoke specifier → creates Requirement.md + returns planner dispatch XML
-2. [Planning approval] User review (Requirement.md)
+2. ⛔ STOP — Present Requirement.md summary and WAIT for planning approval
 3. Invoke planner → PLAN.md + TASK decomposition + execution-mode: full
-4. [Development approval] User review (PLAN.md + TASK list)
+4. ⛔ STOP — Present PLAN.md + TASK list and WAIT for development approval
 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
@@ -104,13 +104,22 @@ Resume pipeline for a WORK that already has PLAN.md + TASKs:
 
 ---
 
-## Approval Gates
+## Approval Gates (CRITICAL)
 
-| 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 |
+> **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 | What to show user |
+|------|:---------:|--------|-------------------|
+| direct | 1 | After Specifier completes | Requirement.md + PLAN.md + TASK-00.md summary |
+| pipeline/full | 2 | After Specifier → After Planner | 1st: Requirement.md summary, 2nd: PLAN.md + TASK list |
+| auto-approve | 0 | — | Skip all approval gates |
+
+**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/planner until approved
 
 ---
 
@@ -173,3 +182,55 @@ 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 (no ref-cache in) → reads files → returns task-result with <ref-cache>
+  ↓ Main Claude copies <ref-cache> into dispatch
+planner (ref-cache in) → skips file reads → 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 → ...
+```
+
+### 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** | §1,§7,§8,§9,§11 | §0,§1,§2,§3 | §1,§3 | — | full |
+| **planner** | §1,§2,§11 | §1,§2,§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** | §1,§2,§12 | — | §1,§2,§4 | Verifier section | full |
+| **committer** | §1,§2,§8,§10 | §3,§4,§5,§6,§7 | §1,§2,§4 | Committer+Retry | 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,7 +28,7 @@
 
 ```
 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로)
 ```
@@ -41,9 +41,9 @@
 
 ```
 1. specifier 호출 → Requirement.md 생성 + planner dispatch XML 반환
-2. [기획 승인] 사용자 검토 (Requirement.md)
+2. ⛔ STOP — Requirement.md 요약을 제시하고 기획 승인을 기다린다
 3. planner 호출 (dispatch XML을 prompt로) → PLAN.md + TASK-NN 생성 + execution-mode 결정
-4. [개발 승인] 사용자 검토 (PLAN.md + TASK 목록)
+4. ⛔ STOP — PLAN.md + TASK 목록을 제시하고 개발 승인을 기다린다
 5. builder 호출 (TASK별 dispatch XML을 prompt로)
 6. verifier 호출 (builder 결과를 prompt로)
 7. committer 호출 (verifier 결과를 prompt로)
@@ -55,9 +55,9 @@
 
 ```
 1. specifier 호출 → Requirement.md 생성 + planner dispatch XML 반환
-2. [기획 승인] 사용자 검토 (Requirement.md)
+2. ⛔ STOP — Requirement.md 요약을 제시하고 기획 승인을 기다린다
 3. planner 호출 → PLAN.md + TASK 분해 + execution-mode: full 결정
-4. [개발 승인] 사용자 검토 (PLAN.md + TASK 목록)
+4. ⛔ STOP — PLAN.md + TASK 목록을 제시하고 개발 승인을 기다린다
 5. scheduler 호출 → DAG 분석 + READY TASK + builder dispatch XML 반환
 6. builder 호출 (dispatch XML을 prompt로) → 구현
 7. verifier 호출 (builder 결과를 prompt로) → 검증
@@ -104,13 +104,22 @@
 
 ---
 
-## 승인 게이트
+## 승인 게이트 (CRITICAL)
 
-| 모드 | 승인 횟수 | 시점 |
-|------|:---------:|------|
-| direct | 1회 | Specifier 완료 후 (요구사항 + 설계 통합) |
-| pipeline/full | 2회 | 기획 승인 (Requirement.md) → 개발 승인 (PLAN.md) |
-| 자동 승인 | 0회 | "자동으로 진행" 명시 시 |
+> **반드시 STOP하고 사용자의 명시적 승인을 기다린 후 다음 에이전트를 호출하라.**
+> 사용자가 "승인", "approve", "진행", "go ahead" 등으로 응답할 때까지 다음 단계로 넘어가지 마라.
+> 유일한 예외는 auto 모드 — 사용자의 원래 메시지에 "auto" 또는 "자동으로"가 포함된 경우.
+
+| 모드 | 승인 횟수 | 시점 | 사용자에게 보여줄 내용 |
+|------|:---------:|------|----------------------|
+| direct | 1회 | Specifier 완료 후 | Requirement.md + PLAN.md + TASK-00.md 요약 |
+| pipeline/full | 2회 | Specifier 후 → Planner 후 | 1차: Requirement.md 요약, 2차: PLAN.md + TASK 목록 |
+| 자동 승인 | 0회 | — | 모든 승인 게이트 생략 |
+
+**승인 요청 방법:**
+1. specifier/planner가 생성한 산출물 요약을 제시 (파일, 범위, execution-mode)
+2. "진행할까요?" 또는 동등한 질문
+3. **사용자 응답을 기다린다** — 승인 전까지 builder/planner를 호출하지 마라
 
 ---
 

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 파싱
 

package/agents/ko/committer.md

@@ -34,13 +34,24 @@ You are the **Committer** — 검증 완료된 TASK의 result report를 생성
 
 **REFERENCES_DIR 결정**: 입력에서 `REFERENCES_DIR=...` 라인 또는 `<references-dir>` XML 요소를 확인. 해당 절대 경로를 사용. 없으면 기본값 `.claude/agents` 사용.
 
-| 파일 | 목적 |
-|------|------|
-| `{REFERENCES_DIR}/file-content-schema.md` | 파일 포맷 스키마 |
-| `{REFERENCES_DIR}/shared-prompt-sections.md` | 공통 규칙 |
-| `{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 파싱
 
@@ -96,38 +107,31 @@ fi
 
 ### 3-6. Git 확인
 
-```bash
-if ! git rev-parse --is-inside-work-tree > /dev/null 2>&1; then
-  echo "WARNING: git 저장소가 없습니다. git commit을 건너뜁니다."
-  echo "결과 파일 저장 위치: works/${WORK_ID}/TASK-XX_result.md"
-  # → 7단계 (TaskCallback)로 직행
-fi
-```
+→ **Bash 명령 규칙: `shared-prompt-sections.md` § 13 참조**
 
-git이 없으면 3-7 (Git Commit) 단계를 건너뛴다. result.md, PROGRESS.md, WORK-LIST.md는 이미 저장되어 있으므로, 사용자가 나중에 `git init && git add . && git commit` 할 수 있다.
+`git rev-parse --is-inside-work-tree` 실행 (단일 명령). 실패 시 3-7 단계를 건너뛰고 7단계 (TaskCallback)로 직행. result.md, PROGRESS.md, WORK-LIST.md는 이미 저장되어 있다.
 
 ### 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
+**아래 각 명령은 별도 Bash 호출 — `&&` 또는 `;` 로 연결 금지:**
 
-# Stage WORK management files (Requirement, PLAN, TASK, progress, result)
-git add "works/${WORK_ID}/"
+1. 결과 파일 존재 확인: `Read` 도구로 `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>` (파일당 하나, 또는 공백 구분으로 한 호출에 나열)
+5. `git commit -m "{type}(TASK-XX): {title}..."` (커밋 메시지는 heredoc 사용)
 
-# Stage WORK-LIST.md (마지막 TASK이면 DONE 상태 포함)
+```
+# 예시 — 각 줄이 별도 Bash 호출:
+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 |

package/agents/ko/planner.md

@@ -38,11 +38,22 @@ WORK (일)          — 사용자 요청의 목표 단위
 
 **REFERENCES_DIR 결정**: 입력에서 `REFERENCES_DIR=...` 라인 또는 `<references-dir>` XML 요소를 확인. 해당 절대 경로를 사용. 없으면 기본값 `.claude/agents` 사용.
 
-| 파일 | 목적 |
-|------|------|
-| `{REFERENCES_DIR}/file-content-schema.md` | 파일 포맷 스키마 (PLAN.md 7개 필드, TASK 포맷) |
-| `{REFERENCES_DIR}/shared-prompt-sections.md` | 공통 규칙 (TASK ID, WORK-LIST 규칙) |
-| `{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>`를 반환 dispatch 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}/work-activity-log.md` | `work-activity-log` |
 
 ### 3-2. 프로젝트 탐색 (Discovery Process)
 
@@ -98,6 +109,8 @@ PLAN.md의 `> Execution-Mode:` 필드에 결정된 모드를 기록.
 4. 완료 보고: "{WORK-ID} 계획 생성 완료. `{WORK-ID} 파이프라인 실행해줘`로 시작하세요."
 ```
 
+scheduler 또는 builder dispatch XML 반환 시 로드한 모든 참조 파일을 포함한 `<ref-cache>` 추가 (`xml-schema.md` § 6 참조).
+
 ### 3-6. 산출물 구조
 
 → `{REFERENCES_DIR}/file-content-schema.md` § 7 참조

package/agents/ko/scheduler.md

@@ -38,13 +38,24 @@ You are the **Scheduler** — WORK 파이프라인 실행 에이전트.
 
 **REFERENCES_DIR 결정**: 입력에서 `REFERENCES_DIR=...` 라인 또는 `<references-dir>` XML 요소를 확인. 해당 절대 경로를 사용. 없으면 기본값 `.claude/agents` 사용.
 
-| 파일 | 목적 |
-|------|------|
-| `{REFERENCES_DIR}/file-content-schema.md` | 파일 포맷 스키마 |
-| `{REFERENCES_DIR}/shared-prompt-sections.md` | 공통 규칙 |
-| `{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>`를 반환 dispatch 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. WORK 식별 및 초기 로드
 
@@ -88,6 +99,7 @@ WORK 내 TASK만 처리. 다른 WORK 접근 금지.
 각 단계 시작 전 Pipeline Stage Callback 전송 (§ 3-6 참조).
 
 → dispatch XML 포맷: `xml-schema.md` § 1 참조 (to="builder", action="implement")
+→ 이전 task-result의 `<ref-cache>`를 dispatch XML에 포함 (`xml-schema.md` § 6 및 `agent-flow.md` ref-cache 체인 전파 참조)
 
 아래 dispatch XML을 생성하여 반환한다. **호출은 Main Claude가 수행한다.**
 
@@ -115,6 +127,7 @@ FAIL → builder 재시도 (최대 3회). 3회 실패 → 파이프라인 중단
 
 → dispatch XML 포맷: `xml-schema.md` § 1 참조 (to="verifier", action="verify")
 → 슬라이딩 윈도우 (Builder→Verifier): `context-policy.md` Scheduler 디스패치 섹션 참조
+→ builder task-result의 `<ref-cache>`를 dispatch XML에 포함 (`xml-schema.md` § 6 참조)
 
 아래 dispatch XML을 생성하여 반환한다. **호출은 Main Claude가 수행한다.**
 
@@ -123,6 +136,7 @@ FAIL → builder 재시도 (최대 3회). 3회 실패 → 파이프라인 중단
 → dispatch XML 포맷: `xml-schema.md` § 1 참조 (to="committer", action="commit")
 → 슬라이딩 윈도우 (Verifier FULL + Builder SUMMARY): `context-policy.md` Scheduler 디스패치 섹션 참조
 → TASK 간 의존성 전달: `context-policy.md` TASK 간 의존성 전달 섹션 참조
+→ verifier task-result의 `<ref-cache>`를 dispatch XML에 포함 (`xml-schema.md` § 6 참조)
 
 아래 dispatch XML을 생성하여 반환한다. **호출은 Main Claude가 수행한다.**
 

package/agents/ko/shared-prompt-sections.md

@@ -164,28 +164,17 @@ LAST_WORK_ID: WORK-XX
 
 ## § 10. 콜백 전송 템플릿
 
+→ **Bash 명령 규칙: § 13 참조** — 아래 각 단계는 별도 도구 호출이다.
+
 `{CallbackType}`을 실제 키 이름으로 대체 (예: `ProgressCallback`, `TaskCallback`).
 
+**1단계.** `Grep` 도구로 CLAUDE.md에서 `{CallbackType}:` 줄을 찾는다. 없으면 콜백을 건너뛴다.
+
+**2단계.** `Grep` 도구로 CLAUDE.md에서 `CallbackToken:` 줄을 찾는다 (선택).
+
+**3단계.** 단일 `curl` 명령으로 콜백 전송:
 ```bash
-CALLBACK_URL=$(grep "^{CallbackType}:" CLAUDE.md 2>/dev/null | sed 's/^{CallbackType}: //' | tr -d '\r')
-CALLBACK_TOKEN=$(grep "^CallbackToken:" CLAUDE.md 2>/dev/null | sed 's/^CallbackToken: //' | tr -d '\r')
-
-if [ -n "$CALLBACK_URL" ] && [ "$CALLBACK_URL" != "{CallbackType}:" ]; then
-  PAYLOAD=$(cat <<EOF
-{
-  "workId": "${WORK_ID}",
-  "taskId": "${TASK_ID}",
-  ... 에이전트별 필드 ...
-}
-EOF
-  )
-  AUTH_HEADER=""
-  [ -n "$CALLBACK_TOKEN" ] && AUTH_HEADER="-H \"X-Runner-Api-Key: ${CALLBACK_TOKEN}\""
-  curl -s -X POST "$CALLBACK_URL" \
-    -H "Content-Type: application/json" \
-    $AUTH_HEADER \
-    -d "$PAYLOAD" > /dev/null 2>&1
-fi
+curl -s -X POST "CALLBACK_URL" -H "Content-Type: application/json" -H "X-Runner-Api-Key: TOKEN" -d '{"workId":"WORK-01","taskId":"TASK-00",...}'
 ```
 
 에이전트별 페이로드 필드:
@@ -223,7 +212,41 @@ Gate 실패 시 → 즉시 FAIL task-result 반환. 이후 단계 진행 금지.
 
 ---
 
+## § 13. Bash 명령 규칙
+
+Bash 명령은 권한 호환성을 위해 다음 규칙을 반드시 따른다.
+
+**필수:**
+- Bash 호출 1회에 단순 명령 1개 — 복합 명령 금지 (`&&`, `||`, `;`, `|`)
+- `cd dir && command` 금지 — 이미 프로젝트 루트에서 실행 중
+- 멀티라인 스크립트 금지 — 별도 Bash 호출로 분리
+- 인자 내 서브셸 확장 금지 — 예: `printf` 안에 `$(date ...)`
+- 프로젝트 루트 기준 상대경로 사용 (예: `works/WORK-01/`) — 절대경로 금지
+- `git add file`, `git commit -m "msg"` 형식 — `git -C path` 플래그 금지
+
+**파일 작업은 Bash 대신 전용 도구 사용:**
+- 파일 읽기 → `Read` 도구 (`cat` 금지)
+- 파일 쓰기/추가 → `Write` 도구 (`echo >>`, `printf >>` 금지)
+- 파일 편집 → `Edit` 도구 (`sed -i` 금지)
+- 파일 검색 → `Grep` 도구 (`grep` 금지)
+- 파일 찾기 → `Glob` 도구 (`find` 금지)
+
+**Activity log 예시:**
+```
+잘못: printf '[%s]_%s\n' "$(date ...)" "INIT" >> work.log
+올바름: Write 도구로 로그 파일에 한 줄 추가
+```
+
+**Git 예시:**
+```
+잘못: cd /path/to/project && git add file && git commit -m "msg"
+올바름: git add file        (1회 호출)
+        git commit -m "msg"  (다음 호출)
+```
+
+---
+
 ## Version
 
 - Created: 2026-03-10
-- Updated: 2026-03-21
+- Updated: 2026-03-28