uctm 1.3.2 → 1.5.0

package/skills/sdd-pipeline/references/file-content-schema.md

@@ -0,0 +1,249 @@
+# File Content Schema
+
+Single source of truth for pipeline artifact file formats.
+
+## COMPLIANCE
+
+| Generated File | Reference Section | Violation Consequence |
+|----------------|-------------------|----------------------|
+| `PLAN.md` | § 1 | `parsePlanMd()` parsing failure, scheduler inoperable |
+| `TASK-XX.md` | § 2 | `parseTaskFilename()` DB registration missed |
+| `TASK-XX_progress.md` | § 3 | committer gate FAIL |
+| `TASK-XX_result.md` | § 4 | context-handoff missing |
+| `TASK-XX_result.md` (direct) | § 5 | result.md recognition failure |
+| `PROGRESS.md` | § 6 | scheduler progress tracking inoperable |
+
+---
+
+## § 0. Requirement.md
+
+Path: `works/{WORK_ID}/Requirement.md`
+
+```markdown
+# Requirement — WORK-NN
+
+## Original Request
+> User's exact input
+
+## Functional Requirements
+- FR-01: ...
+- FR-02: ...
+
+## Non-Functional Requirements
+- NFR-01: ...
+
+## Acceptance Criteria
+- [ ] Verifiable criteria
+```
+
+Created by: Specifier (mandatory for all requests)
+
+---
+
+## § 1. PLAN.md
+
+Path: `works/{WORK_ID}/PLAN.md`
+
+```markdown
+# WORK-01: {title}
+
+> Created: {YYYY-MM-DD}
+> Requirement: {REQ-XXX | user request text}
+> Execution-Mode: {direct | pipeline | full}
+> Project: {project name}
+> Tech Stack: {stack}
+> Language: {lang_code}
+> Status: PLANNED
+
+## Goal
+{1-2 sentences}
+
+## Task Dependency Graph
+{ASCII diagram}
+
+## Tasks
+
+### TASK-00: {title}
+- **Depends on**: (none)
+- **Scope**: {description}
+- **Files**:
+  - `path/to/file` — {description}
+
+### TASK-01: {title}
+- **Depends on**: TASK-00
+```
+
+Title format: `# WORK-NN: title` — `# PLAN WORK-NN:` is prohibited (`parsePlanMd()` error)
+
+---
+
+## § 2. TASK-XX.md
+
+Path: `works/{WORK_ID}/TASK-XX.md`
+
+> `parseTaskFilename()` regex: `/^TASK-(\d+)\.md$/` — WORK prefix prohibited
+
+```markdown
+# TASK-XX: {title}
+
+## WORK
+{WORK_ID}: {WORK title}
+
+## Dependencies
+- TASK-YY (required)
+
+## Scope
+{description}
+
+## Files
+| Path | Action | Description |
+|------|--------|-------------|
+| `src/file.ts` | CREATE | description |
+
+## Acceptance Criteria
+- [ ] {criterion}
+
+## Verify
+```bash
+{verification commands}
+```
+```
+
+---
+
+## § 3. TASK-XX_progress.md
+
+Path: `works/{WORK_ID}/TASK-XX_progress.md`
+
+```markdown
+# TASK-XX Progress
+
+- Status: {PENDING | STARTED | IN_PROGRESS | COMPLETED}
+- Started: {ISO 8601}
+- Updated: {ISO 8601}
+- Files changed:
+  - `path/to/file` — {CREATE | MODIFY | DELETE}
+```
+
+| Timing | Status |
+|--------|--------|
+| planner template | `PENDING` |
+| builder starts | `STARTED` |
+| file changes in progress | `IN_PROGRESS` |
+| completed | `COMPLETED` |
+
+committer gate: file exists + `Status: COMPLETED` + Files changed is not empty
+
+---
+
+## § 4. TASK-XX_result.md (full / pipeline)
+
+Path: `works/{WORK_ID}/TASK-XX_result.md`
+
+```markdown
+# TASK-XX Result
+
+> WORK: {WORK_ID} — {title}
+> Completed: {YYYY-MM-DD HH:MM}
+> Status: **DONE**
+
+{## Summary | ## 요약 | ## サマリー}
+{1-2 lines}
+
+{## Completed Checklist | ## 완료 체크리스트 | ## 完了チェックリスト}
+- [x] {item}
+
+{## Verification Results | ## 검증 결과 | ## 検証結果}
+- Build: ✅
+- Lint: ✅
+- Tests: ✅ (N passed)
+
+{## Files Changed | ## 변경 파일 | ## 変更ファイル}
+### Created
+- `path` — {description}
+
+{## Issues Encountered | ## 발생 이슈 | ## 発生した問題}
+None
+
+{## Notes for Subsequent Tasks | ## 후속 TASK 참고사항 | ## 後続タスクへの注記}
+None
+
+{## Context Handoff | ## 컨텍스트 핸드오프 | ## コンテキスト引き継ぎ}
+
+### Builder Context (SUMMARY)
+{builder what field 1-3 lines}
+
+### Verifier Context (FULL)
+{verifier context-handoff 4 fields}
+```
+
+| Section | en | ko | ja |
+|---------|----|----|-----|
+| Summary | `## Summary` | `## 요약` | `## サマリー` |
+| Completed Checklist | `## Completed Checklist` | `## 완료 체크리스트` | `## 完了チェックリスト` |
+| Verification Results | `## Verification Results` | `## 검증 결과` | `## 検証結果` |
+| Files Changed | `## Files Changed` | `## 변경 파일` | `## 変更ファイル` |
+| Issues Encountered | `## Issues Encountered` | `## 발생 이슈` | `## 発生した問題` |
+| Notes for Subsequent Tasks | `## Notes for Subsequent Tasks` | `## 후속 TASK 참고사항` | `## 後続タスクへの注記` |
+| Context Handoff | `## Context Handoff` | `## 컨텍스트 핸드오프` | `## コンテキスト引き継ぎ` |
+
+---
+
+## § 5. TASK-XX_result.md (direct mode)
+
+```markdown
+# TASK-00 Result
+
+> WORK: WORK-NN — {title}
+> Completed: {YYYY-MM-DD HH:MM}
+> Execution-Mode: direct
+> Status: **DONE**
+
+## Summary
+{1 line}
+
+## Files Changed
+- `{path}` — {description}
+
+## Verification
+- Build: PASS (self-check)
+- Lint: PASS (self-check)
+```
+
+---
+
+## § 6. PROGRESS.md
+
+Path: `works/{WORK_ID}/PROGRESS.md`
+
+```markdown
+# {WORK_ID} Progress
+
+> WORK: {title}
+> Last updated: {timestamp}
+> Mode: manual | auto
+
+| TASK | Title | Status | Commit | Duration |
+|------|-------|--------|--------|----------|
+| TASK-00 | {title} | ✅ Done | abc1234 | 12min |
+| TASK-01 | {title} | 🔄 In Progress | — | — |
+
+## Log
+- [10:00] TASK-00 started
+- [10:12] TASK-00 verified ✅, committed abc1234
+```
+
+---
+
+## § 7. File Naming Rules
+
+| Type | Format | Created By |
+|------|--------|------------|
+| Requirement | `Requirement.md` | specifier |
+| WORK plan | `PLAN.md` | planner / specifier |
+| TASK plan | `TASK-NN.md` | planner / specifier |
+| TASK progress | `TASK-NN_progress.md` | planner / specifier (template) / builder (update) |
+| TASK result | `TASK-NN_result.md` | committer |
+| WORK progress | `PROGRESS.md` | scheduler |
+
+`WORK-NN-TASK-NN.md` format prohibited → `parseTaskFilename()` cannot recognize it.

package/skills/sdd-pipeline/references/shared-prompt-sections.md

@@ -0,0 +1,250 @@
+# Shared Prompt Sections
+
+Common reusable sections. Each agent references these via `cache_control` markers.
+
+---
+
+## § 1. Output Language Rule
+
+```
+Priority: PLAN.md > Language: → CLAUDE.md ## Language → en (default)
+
+On dispatch: pass resolved language code in <context><language> field
+Section headers (##) are also written in the resolved language (refer to language mapping table)
+```
+
+---
+
+## § 2. Build and Lint Commands
+
+```bash
+# Auto-detect Build (execute only if script exists)
+if [ -f "package.json" ]; then
+  if node -e "const p=JSON.parse(require('fs').readFileSync('package.json','utf8')); process.exit(p.scripts&&p.scripts.build?0:1)" 2>/dev/null; then
+    npm run build 2>&1 || bun run build 2>&1 || yarn build 2>&1
+  fi
+elif [ -f "Cargo.toml" ]; then
+  cargo build 2>&1
+elif [ -f "go.mod" ]; then
+  go build ./... 2>&1
+elif [ -f "pyproject.toml" ] || [ -f "setup.py" ]; then
+  python -m py_compile $(find . -maxdepth 3 -name "*.py" -not -path "*/venv/*" 2>/dev/null) 2>&1
+elif [ -f "Makefile" ]; then
+  make build 2>&1 || make 2>&1
+fi
+
+# Auto-detect Lint (execute only if script exists)
+if [ -f "package.json" ]; then
+  if node -e "const p=JSON.parse(require('fs').readFileSync('package.json','utf8')); process.exit(p.scripts&&p.scripts.lint?0:1)" 2>/dev/null; then
+    npm run lint 2>&1 || bun run lint 2>&1 || true
+  fi
+elif [ -f "pyproject.toml" ]; then
+  ruff check . 2>&1 || python -m flake8 . 2>&1 || true
+fi
+```
+
+- If build/lint scripts do not exist → **skip (treat as N/A)**.
+- On build/lint failure, always fix before reporting.
+
+---
+
+## § 3. WORK and TASK File Path Patterns
+
+```
+works/{WORK_ID}/
+  ├─ Requirement.md                 # Created by Specifier (mandatory)
+  ├─ PLAN.md
+  ├─ PROGRESS.md
+  ├─ TASK-00.md               # No WORK prefix
+  ├─ TASK-00_progress.md      # Separator: underscore
+  ├─ TASK-00_result.md        # Separator: underscore
+  └─ TASK-01.md ...
+```
+
+- WORK ID: `WORK-NN` (e.g., `WORK-03`)
+- TASK ID: `TASK-NN` (e.g., `TASK-00`) — WORK prefix must NOT be included
+
+---
+
+## § 4. File System Discovery Scripts
+
+```
+# Find latest WORK with incomplete TASKs
+# Use Glob tool: pattern "works/WORK-*/" → list all WORK directories (sorted)
+# For each WORK (descending), compare:
+#   Glob "works/WORK-NN/TASK-*.md" (exclude *_result.md, *_progress.md) → TOTAL
+#   Glob "works/WORK-NN/TASK-*_result.md" → DONE
+# First WORK where DONE < TOTAL is the active WORK
+
+# List all WORKs
+# Use Glob tool: pattern "works/WORK-*/"
+
+# TASK completion status
+# TOTAL = count of Glob "works/${WORK_ID}/TASK-??.md"
+# DONE  = count of Glob "works/${WORK_ID}/TASK-*_result.md"
+```
+
+---
+
+## § 5. Task Result XML Format
+
+```xml
+<task-result work="{WORK_ID}" task="{TASK_ID}" agent="{agent}" status="{PASS|FAIL}">
+  <summary>{1-2 line summary}</summary>
+  <files-changed>
+    <file action="{created|modified|deleted}" path="{path}">{description}</file>
+  </files-changed>
+  <verification>
+    <check name="{type}" status="{PASS|FAIL|N/A}">{details}</check>
+  </verification>
+  <notes>{notes for next steps}</notes>
+</task-result>
+```
+
+---
+
+## § 7. PLAN.md Required Meta-Information — 7 Fields
+
+→ `{REFERENCES_DIR}/file-content-schema.md` § 1 reference
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| `> Created:` | ✅ | YYYY-MM-DD |
+| `> Requirement:` | ✅ | `REQ-XXX` or user request text |
+| `> Execution-Mode:` | ✅ | `direct` / `pipeline` / `full` |
+| `> Project:` | ✅ | Project name |
+| `> Tech Stack:` | ✅ | Detected tech stack |
+| `> Language:` | ✅ | Language code (`ko`, `en`, etc.) |
+| `> Status:` | ✅ | Always starts as `PLANNED` |
+
+---
+
+## § 8. WORK-LIST.md Update Rules
+
+File: `works/WORK-LIST.md`
+
+**Format:**
+```
+LAST_WORK_ID: WORK-XX
+
+| WORK | 제목 | 상태 | 생성일 | 완료일 |
+|------|------|------|--------|--------|
+| WORK-NN | ... | IN_PROGRESS | YYYY-MM-DD | |
+| WORK-MM | ... | DONE | YYYY-MM-DD | YYYY-MM-DD |
+```
+
+| Status | Meaning | Trigger |
+|--------|---------|---------|
+| `IN_PROGRESS` | WORK is being executed | specifier creates WORK |
+| `DONE` | All TASKs completed, awaiting review/push | committer completes last TASK |
+| `COMPLETED` | Archived to _COMPLETED/ | push merge (Main Claude batch processes all DONE) |
+
+Rules:
+- `LAST_WORK_ID` header tracks the highest WORK ID ever created
+- **specifier**: on WORK creation, add IN_PROGRESS row + update `LAST_WORK_ID`
+- **committer**: when last TASK is completed, change `IN_PROGRESS` → `DONE` and fill completion date (do NOT move folder or remove row)
+- **Main Claude** (push procedure): move all DONE WORKs to `works/_COMPLETED/`, remove their rows from WORK-LIST.md
+
+---
+
+## § 9. Locale Detection
+
+```
+1. CLAUDE.md → check "Language: xx"
+2. If not found, ask user for language
+3. If not found, auto-detect system locale
+   - Windows: powershell -c "[CultureInfo]::CurrentCulture.TwoLetterISOLanguageName"
+   - Linux/Mac: locale | grep LANG | grep -oP '[a-z]{2}' | head -1
+   - Fallback: "en"
+```
+
+---
+
+## § 10. Callback Transmission Template
+
+→ **Bash command rules: see § 13** — each step below is a separate tool call.
+
+Replace `{CallbackType}` with the actual key name (e.g., `ProgressCallback`, `TaskCallback`).
+
+**Step 1.** Use `Grep` tool to find `{CallbackType}:` line in CLAUDE.md. If not found, skip callback entirely.
+
+**Step 2.** Use `Grep` tool to find `CallbackToken:` line in CLAUDE.md (optional).
+
+**Step 3.** Send callback with a single `curl` command:
+```bash
+curl -s -X POST "CALLBACK_URL" -H "Content-Type: application/json" -H "X-Runner-Api-Key: TOKEN" -d '{"workId":"WORK-01","taskId":"TASK-00",...}'
+```
+
+Agent-specific payload fields:
+- **ProgressCallback** (builder): `"status": "IN_PROGRESS"`, `"currentReasoning": "..."`
+- **TaskCallback** (committer): `"status": "SUCCESS"`, `"commitHash": "${COMMIT_HASH}"`
+
+---
+
+## § 11. Project Discovery
+
+```bash
+# 1. Check CLAUDE.md language setting
+grep -oP '(?<=Language:\s?)[a-z]{2}' CLAUDE.md 2>/dev/null
+
+# 2. Tech stack
+head -50 package.json 2>/dev/null
+head -30 pyproject.toml 2>/dev/null
+head -20 Cargo.toml 2>/dev/null
+head -10 go.mod 2>/dev/null
+
+# 3. Structure (when needed)
+find . -maxdepth 3 -type f \( -name "*.md" -o -name "*.json" -o -name "*.toml" \) -not -path "*/node_modules/*" 2>/dev/null
+```
+
+---
+
+## § 12. Progress File Gate Check
+
+Gate conditions for `works/WORK-NN/TASK-XX_progress.md`:
+- File exists at the expected path
+- `Status: COMPLETED` line is present
+- `## Files Changed` section is present and non-empty
+
+On gate failure → return FAIL task-result immediately. Do not proceed to subsequent steps.
+
+---
+
+## § 13. Bash Command Rules
+
+Bash commands MUST follow these rules for permission compatibility.
+
+**MANDATORY:**
+- One simple command per Bash call — NO compound commands (`&&`, `||`, `;`, `|`)
+- NO `cd dir && command` — you are already in the project root
+- NO multi-line scripts — split into separate Bash calls
+- NO sub-shell expansions in arguments — e.g., `$(date ...)` inside `printf`
+- Use relative paths from project root (e.g., `works/WORK-01/`) — NO absolute paths
+- Use `git add file`, `git commit -m "msg"` — NO `git -C path` flag
+
+**For file operations, prefer dedicated tools over Bash:**
+- Read files → `Read` tool (NOT `cat`)
+- Write/append files → `Write` tool (NOT `echo >>` or `printf >>`)
+- Edit files → `Edit` tool (NOT `sed -i`)
+- Search files → `Grep` tool (NOT `grep`)
+- Find files → `Glob` tool (NOT `find`)
+
+**Activity log example:**
+```
+WRONG: printf '[%s]_%s\n' "$(date ...)" "INIT" >> work.log
+RIGHT: Use Write tool to append a line to the log file
+```
+
+**Git example:**
+```
+WRONG: cd /path/to/project && git add file && git commit -m "msg"
+RIGHT: git add file        (one call)
+       git commit -m "msg"  (next call)
+```
+
+---
+
+## Version
+
+- Created: 2026-03-10
+- Updated: 2026-03-28

package/skills/sdd-pipeline/references/work-activity-log.md

@@ -0,0 +1,47 @@
+# Work Activity Log
+
+Defines the rules for each agent to record WORK progress in the `works/{WORK_ID}/work_{WORK_ID}.log` file.
+
+---
+
+# 1. Stages and Log Content
+* On first execution: The received prompt message** Content of the prompt message received at agent startup (Required)
+* On Callback invocation: Called Callback URL, success status, Payload, Response (Required)
+* During work: Work items and work content
+* On task completion: The prompt message sent to other agents** Content of the prompt message received at agent startup (Required)
+
+## log_work Method
+
+**Do NOT use Bash** for activity log writes. Use the `Write` tool (or `Edit` tool to append).
+
+Format each log entry as:
+```
+[YYYY-MM-DDTHH:MM:SS]_AGENT_STAGE_description
+```
+
+Example: to log an INIT stage, use the **Write** tool to append to `works/{WORK_ID}/work_{WORK_ID}.log`:
+```
+[2026-03-28T14:30:00]_SPECIFIER_INIT_WORK-09 created — Execution-Mode: direct
+```
+
+→ **Bash command rules: see `shared-prompt-sections.md` § 13**
+
+---
+
+## STAGE Table
+
+| STAGE | Timing | Description Example |
+|-------|--------|---------------------|
+| `INIT` | After WORK_ID determined | `WORK-NN created — Execution-Mode: direct/pipeline/full` |
+| `REF` | After STARTUP references | `References: CLAUDE.md, .agent/router_rule_config.json, agents/file-content-schema.md` |
+| `PLAN` | After PLAN.md + TASK files created | `PLAN.md, TASK-00.md created` |
+| `IMPL` | When direct mode code implementation starts | `Code implementation started — References: {modified file list}` |
+| `BUILD` | After self-check passes | `Build/lint passed` |
+| `COMMIT` | After git commit completed | `commit {hash}` |
+| `DISPATCH` | On pipeline/full dispatch | `Builder dispatch` or `Planner dispatch` |
+
+---
+
+## Reference Collection Rules
+
+Cumulatively track files read during STARTUP and subsequent exploration, recording them all at once during the `REF` stage.

package/skills/sdd-pipeline/references/xml-schema.md

@@ -0,0 +1,159 @@
+# Agent Communication XML Schema
+
+XML communication format definition for uc-taskmanager agents.
+
+---
+
+## 1. Dispatch Format (Dispatcher → Receiver)
+
+```xml
+<dispatch to="{receiver}" work="{WORK_ID}" task="{TASK_ID}" execution-mode="{direct|pipeline|full}">
+  <ref-cache>                                        <!-- optional -->
+    <ref key="shared-prompt-sections">{file content}</ref>
+    <ref key="file-content-schema">{file content}</ref>
+    <ref key="xml-schema">{file content}</ref>
+    <ref key="context-policy">{file content}</ref>
+    <ref key="work-activity-log">{file content}</ref>
+  </ref-cache>
+  <references-dir>{absolute path to references directory}</references-dir>
+  <context>
+    <project>{project name}</project>
+    <language>{lang_code}</language>
+    <plan-file>works/{WORK_ID}/PLAN.md</plan-file>
+  </context>
+  <task-spec>
+    <file>works/{WORK_ID}/TASK-XX.md</file>
+    <title>{title}</title>
+    <action>{implement|verify|commit|plan|route}</action>
+    <description>{optional}</description>
+  </task-spec>
+  <previous-results>
+    <result task="{TASK_ID}" status="{PASS|FAIL|SKIP}">{summary}</result>
+  </previous-results>
+  <cache-hint sections="{section1},{section2}"/>
+</dispatch>
+```
+
+| Attribute | Value |
+|-----------|-------|
+| `to` | builder, verifier, committer, planner, scheduler, specifier |
+| `task` | `TASK-NN` — WORK prefix must NOT be included |
+| `execution-mode` | direct / pipeline / full (defaults to full if omitted) |
+
+---
+
+## 2. Task Result Format (Receiver → Dispatcher)
+
+```xml
+<task-result work="{WORK_ID}" task="{TASK_ID}" agent="{agent}" status="{PASS|FAIL}">
+  <summary>{1-2 line summary}</summary>
+  <files-changed>
+    <file action="{created|modified|deleted}" path="{path}">{description}</file>
+  </files-changed>
+  <verification>
+    <check name="{type}" status="{PASS|FAIL|N/A}">{output}</check>
+  </verification>
+  <notes>{notes}</notes>
+  <ref-cache>                                        <!-- optional -->
+    <ref key="shared-prompt-sections">{file content}</ref>
+    <ref key="file-content-schema">{file content}</ref>
+    <ref key="xml-schema">{file content}</ref>
+    <ref key="context-policy">{file content}</ref>
+    <ref key="work-activity-log">{file content}</ref>
+  </ref-cache>
+</task-result>
+```
+
+---
+
+## 3. Dispatcher-Receiver Mapping
+
+| Dispatcher | Receiver | execution-mode | Description |
+|------------|----------|:--------------:|-------------|
+| Specifier | Builder | `direct` | Assumed: single TASK implementation (Verifier skipped) |
+| Specifier | Planner | `pipeline/full` | Delegated: complex WORK planning |
+| Planner | Builder | `pipeline` | TASK implementation |
+| Planner | Scheduler | `full` | DAG management + execution |
+| Scheduler | Builder | `full` | N TASK implementation |
+| Scheduler | Verifier | `full` | N TASK verification |
+| Scheduler | Committer | `full` | N TASK commit |
+
+---
+
+## 4. Context-Handoff Element
+
+```xml
+<context-handoff from="{agent}" detail-level="{FULL|SUMMARY|DROP}">
+  <what>{changes/verification details}</what>
+  <why>{decision rationale}</why>       <!-- FULL only -->
+  <caution>{caveats}</caution>          <!-- FULL only -->
+  <incomplete>{incomplete items}</incomplete>  <!-- FULL only -->
+</context-handoff>
+```
+
+| detail-level | Included Fields |
+|:---:|---|
+| `FULL` | what, why, caution, incomplete |
+| `SUMMARY` | what only (1-3 lines) |
+| `DROP` | Element omitted |
+
+---
+
+## 5. Agent Behavior by execution-mode
+
+| Agent | direct | pipeline | full |
+|-------|--------|----------|------|
+| Specifier | Requirement.md + PLAN.md + TASK (assumed) | Requirement.md only → delegate to Planner | Requirement.md only → delegate to Planner |
+| Planner | Not invoked (Specifier assumed) | PLAN.md + TASK + execution-mode | PLAN.md + TASK + execution-mode |
+| Scheduler | Not invoked | Not invoked | DAG management + [B→V→C]×N |
+| Builder | Normal execution (self-check) | Normal execution | Normal execution |
+| Verifier | Not invoked | Normal execution | Normal execution |
+| Committer | result.md+commit+callback | result.md+commit+callback | result.md+commit+callback |
+
+Invariants (regardless of mode):
+
+| Item | direct | pipeline/full |
+|------|:---:|:---:|
+| `works/WORK-NN/` directory | Specifier | Specifier |
+| `Requirement.md` | Specifier | Specifier |
+| `PLAN.md` | Specifier (assumed) | Planner |
+| `TASK-XX.md` | Specifier (assumed) | Planner |
+| `TASK-XX_result.md` | Committer | Committer |
+| COMMITTER DONE callback | Committer | Committer |
+| `WORK-LIST.md` IN_PROGRESS | Specifier | Specifier |
+
+---
+
+## 6. ref-cache Element Definition
+
+`<ref-cache>` is an optional container element that carries pre-loaded reference file contents within dispatch and task-result XML. When present, receiving agents MUST use these contents instead of reading files from disk.
+
+### Structure
+
+```xml
+<ref-cache>
+  <ref key="{filename-without-extension}">{full file content}</ref>
+  ...
+</ref-cache>
+```
+
+| Element | Required | Description |
+|---------|----------|-------------|
+| `<ref-cache>` | Optional | Container for cached reference files. Omit entirely if no cache is available. |
+| `<ref key="...">` | — | Individual reference file. `key` is the filename without extension (e.g., `shared-prompt-sections`). |
+
+### Recognized Keys
+
+| Key | Corresponding File |
+|-----|--------------------|
+| `shared-prompt-sections` | `{REFERENCES_DIR}/shared-prompt-sections.md` |
+| `file-content-schema` | `{REFERENCES_DIR}/file-content-schema.md` |
+| `xml-schema` | `{REFERENCES_DIR}/xml-schema.md` |
+| `context-policy` | `{REFERENCES_DIR}/context-policy.md` |
+| `work-activity-log` | `{REFERENCES_DIR}/work-activity-log.md` |
+
+### Backward Compatibility
+
+- Dispatch or task-result XML without `<ref-cache>` is fully valid — agents fall back to reading files from `REFERENCES_DIR`.
+- Agents that do not yet support ref-cache simply ignore the element and read files normally.
+- Partial ref-cache (only some keys present) is allowed — missing keys are read from disk.