uctm 1.5.2 → 1.5.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "uctm",
-  "version": "1.5.2",
+  "version": "1.5.3",
   "description": "Universal Claude Task Manager — SDD-based task pipeline subagent system for Claude Code CLI",
   "type": "module",
   "bin": {
@@ -10,6 +10,7 @@
     "bin/",
     "lib/",
     "agents/",
+    "references/",
     ".agent/",
     ".claude-plugin/",
     "skills/"

package/references/agent-flow.md

@@ -0,0 +1,200 @@
+# Agent Flow — Main Claude Orchestration Guide
+
+> **All agent invocations are performed by Main Claude.**
+> Sub-agents only return results (dispatch XML or task-result XML) after completing their work.
+> Main Claude receives return values and invokes the next agent.
+
+---
+
+## Pipeline Flow
+
+```
+[] tag detected → invoke specifier
+    │
+    Check specifier return value
+    │
+    ├─ Assumed (direct) → specifier creates Requirement.md + PLAN.md + TASK-00
+    │                      → returns builder dispatch XML
+    │                      → execute § direct procedure
+    │
+    └─ Delegated (pipeline/full) → specifier creates Requirement.md only
+                                    → returns planner dispatch XML
+                                    → execute § planner-driven procedure
+```
+
+---
+
+## Direct Mode (Specifier Assumes Planner)
+
+```
+1. Invoke specifier → creates Requirement.md + PLAN.md + TASK-00 + returns builder dispatch XML
+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 verifier+committer (builder result as prompt) — verify then commit in one spawn
+```
+
+> Verifier+Committer combined: single spawn performs verification, then creates result.md and git commit.
+
+---
+
+## Pipeline Mode (Separate Planner Invocation)
+
+```
+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. For each TASK (ascending order):
+   a. Invoke builder (per-TASK dispatch XML as prompt)
+   b. Invoke verifier+committer (builder result as prompt) — verify then commit in one spawn
+   c. If incomplete TASKs remain, continue to next TASK
+```
+
+> Specifier+Planner combined: specifier.md role first (Requirement.md), then planner.md role (PLAN.md + TASKs) in one spawn.
+> Each TASK must complete the full builder → verifier+committer cycle before the next TASK starts.
+
+---
+
+## Full Mode (With Scheduler)
+
+```
+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.
+
+---
+
+## Resuming Existing WORK
+
+Resume pipeline for a WORK that already has PLAN.md + TASKs:
+
+```
+1. Read last line of works/{WORK_ID}/work_{WORK_ID}.log to determine current state
+   Key rule: *_START = interrupted (redo that step), *_DONE = completed (move to next)
+
+   - COMMITTER_DONE — TASK-NN  → TASK-NN completed, resume from next TASK
+   - COMMITTER_START — TASK-NN → interrupted, redo verifier+committer for TASK-NN
+   - VERIFIER_DONE — TASK-NN   → verified, resume with committer for TASK-NN
+   - VERIFIER_START — TASK-NN  → interrupted, redo verifier+committer for TASK-NN
+   - BUILDER_DONE — TASK-NN    → built, resume with verifier+committer for TASK-NN
+   - BUILDER_START — TASK-NN   → interrupted, redo builder for TASK-NN
+   - PLANNER_DONE              → planning done, start first TASK
+   - PLANNER_START             → interrupted, redo specifier+planner
+   - SPECIFIER_DONE            → specifier done, redo planner
+   - SPECIFIER_START           → interrupted, redo specifier+planner
+   - No log file               → start from scratch
+
+2. For each remaining TASK:
+   a. Invoke builder → implementation
+   b. Invoke verifier+committer → verify then commit in one spawn
+```
+
+---
+
+## Combined Agent Invocation
+
+### Specifier+Planner (single spawn)
+
+- Model: opus
+- Prompt: "Role 1 — Specifier (specifier.md): create Requirement.md. Role 2 — Planner (planner.md): create PLAN.md + TASKs. Execute sequentially. Each role sends its own START/DONE callback + activity log."
+- Returns: Requirement.md + PLAN.md + TASK files + execution-mode
+
+### Verifier+Committer (single spawn)
+
+- Model: haiku
+- Prompt: "Role 1 — Verifier (verifier.md): verify build/lint/test. Role 2 — Committer (committer.md): create result.md + git commit. If verification FAILS, skip Role 2. Each role sends its own START/DONE callback + activity log."
+- On PASS: verification result + commit hash
+- On FAIL: verification failure only (no commit)
+
+---
+
+## Agent Role Summary
+
+| 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 Spawn Count by Mode
+
+| Mode | Spec+Plan | Scheduler | Builder | Veri+Commit | Total |
+|------|:---------:|:---------:|:-------:|:-----------:|:-----:|
+| direct | 1 (assumed) | — | 1 | 1 | **3** |
+| pipeline (N TASKs) | 1 (combined) | — | N | N | **1 + 2N** |
+| full (N TASKs) | 1 (combined) | 1 | N | N | **2 + 2N** |
+
+**Before vs After (6 TASKs):**
+
+| | Before | After | Reduction |
+|---|:---:|:---:|:---:|
+| Spawns | 2 + 3×6 = 20 | 2 + 2×6 = 14 | **-30%** |
+
+---
+
+## 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 | 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
+
+---
+
+## References Directory Passing (REQUIRED)
+
+Main Claude MUST pass the references directory path to every sub-agent invocation.
+This allows sub-agents to locate their reference files regardless of installation method (npm or plugin).
+
+**How to pass:**
+- Prepend `REFERENCES_DIR={absolute_path}` at the top of the prompt for every Task tool call
+- For npm installations: use `.claude/references` (default, resolved from project root)
+- For plugin installations: derive from the skill's "Base directory" (`{base_dir}/../../references`)
+
+**Example:**
+```
+REFERENCES_DIR=C:/Users/me/.claude/plugins/cache/uc-taskmanager/abc123/references
+
+<dispatch to="builder" ...>
+  ...
+</dispatch>
+```
+
+If REFERENCES_DIR is not available (e.g., npm installation without plugin), sub-agents fall back to `.claude/references/`.
+
+---
+
+## Context Handoff (Sliding Window)
+
+| Distance | Level | Content |
+|----------|-------|---------|
+| Previous | FULL | what + why + caution + incomplete |
+| 2 steps back | SUMMARY | what 1-2 lines |
+| 3+ steps | DROP | Not passed |
+
+---
+
+## Reference Loading
+
+Each sub-agent reads its own reference files from `{REFERENCES_DIR}/` at startup. Main Claude does NOT read reference files — only `agent-flow.md`.

package/references/context-policy.md

@@ -0,0 +1,93 @@
+# Context Handoff Policy
+
+Sliding window context transfer rules between agents.
+
+## Sliding Window
+
+| Step Distance | Detail Level | Rule |
+|---------------|-------------|------|
+| Immediate (1 step) | `FULL` | All 4 fields transmitted |
+| 2 steps back | `SUMMARY` | `what` field only, 1-3 lines |
+| 3+ steps back | `DROP` | Omitted |
+
+## Context-Handoff 4 Fields
+
+| Field | FULL | SUMMARY | Content |
+|-------|:----:|:-------:|---------|
+| `what` | ✅ | ✅ | Summary of changes/verification (2-5 lines) |
+| `why` | ✅ | ❌ | Decision rationale (2-4 lines) |
+| `caution` | ✅ | ❌ | Caveats, conditional completion (1-3 lines) |
+| `incomplete` | ✅ | ❌ | Incomplete items (1-2 lines, "None" if empty) |
+
+## Pipeline Stage Input/Output
+
+### Builder
+
+Input: TASK spec + dependent TASK result.md context-handoff (sliding window)
+
+Output:
+```xml
+<task-result status="PASS|FAIL">
+  <context-handoff from="builder" detail-level="FULL">
+    <what>Changes made</what><why>Rationale</why><caution>Caveats</caution><incomplete>Incomplete items</incomplete>
+  </context-handoff>
+</task-result>
+```
+
+### Verifier
+
+Input: TASK spec + Builder context-handoff (FULL)
+
+Output:
+```xml
+<task-result status="PASS|FAIL">
+  <context-handoff from="verifier" detail-level="FULL">
+    <what>Verification results</what><why>Judgment rationale</why><caution>Manual checks needed</caution><incomplete>Items that could not be verified</incomplete>
+  </context-handoff>
+</task-result>
+```
+
+### Committer
+
+Input: Verifier context-handoff (FULL) + Builder context-handoff (SUMMARY)
+
+Processing:
+1. Verify builder completed successfully (check context-handoff status)
+2. Write result.md + git commit
+
+Output: → `{REFERENCES_DIR}/file-content-schema.md` § 4 reference
+
+## Inter-TASK Dependency Transfer
+
+- Immediate dependent TASK: context-handoff **FULL** (all 4 fields)
+- 2 steps back: **SUMMARY** (what only)
+- 3+ steps back: **DROP**
+
+## Scheduler Dispatch
+
+```xml
+<!-- Verifier: Builder FULL -->
+<dispatch to="verifier">
+  <context-handoff from="builder" detail-level="FULL">...</context-handoff>
+</dispatch>
+
+<!-- Committer: Verifier FULL + Builder SUMMARY -->
+<dispatch to="committer">
+  <context-handoff from="verifier" detail-level="FULL">...</context-handoff>
+  <context-handoff from="builder" detail-level="SUMMARY"><what>...</what></context-handoff>
+</dispatch>
+
+<!-- Next TASK Builder: dependency distance applied -->
+<dispatch to="builder" task="TASK-YY">
+  <previous-results>
+    <context-handoff from="prev-task" task="TASK-XX" detail-level="FULL">...</context-handoff>
+    <context-handoff from="prev-prev-task" task="TASK-WW" detail-level="SUMMARY"><what>...</what></context-handoff>
+  </previous-results>
+</dispatch>
+```
+
+## Committer Retry
+
+1. Failure cause: verification FAIL / No files changed
+2. Re-dispatch to builder
+3. Maximum 2 retries (3 attempts total). 3 failures → TASK FAILED, pipeline halted

package/references/file-content-schema.md

@@ -0,0 +1,198 @@
+# 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_result.md` | § 3 | context-handoff missing |
+| `TASK-XX_result.md` (direct) | § 4 | result.md recognition failure |
+
+---
+
+## § 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_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` | `## 컨텍스트 핸드오프` | `## コンテキスト引き継ぎ` |
+
+---
+
+## § 4. 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)
+```
+
+---
+
+## § 5. 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 result | `TASK-NN_result.md` | committer |
+| Activity log | `work_WORK-NN.log` | all agents (append) |
+
+`WORK-NN-TASK-NN.md` format prohibited → `parseTaskFilename()` cannot recognize it.

package/references/ref-cache-protocol.md

@@ -0,0 +1,31 @@
+# ref-cache Protocol
+
+## Overview
+
+ref-cache is a mechanism to avoid redundant file reads across sub-agent invocations within a pipeline.
+Reference files are passed between agents via `<ref-cache>` XML elements instead of being re-read from disk each time.
+
+## Protocol (4 Steps)
+
+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)
+
+## ref-cache XML Format
+
+See `xml-schema.md` § 4 for the full schema.
+
+```xml
+<ref-cache>
+  <ref key="file-content-schema">...content...</ref>
+  <ref key="shared-prompt-sections">...content...</ref>
+  <!-- one <ref> per loaded reference file -->
+</ref-cache>
+```
+
+## Chain Propagation
+
+See `agent-flow.md` § ref-cache Chain Propagation for how ref-cache flows between agents in the pipeline.

package/references/shared-prompt-sections.md

@@ -0,0 +1,312 @@
+# 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
+  ├─ TASK-00.md               # No WORK prefix
+  ├─ 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), read last line of works/WORK-NN/work_WORK-NN.log
+#   - No log file → not started
+#   - Last line contains "COMMITTER_DONE" with last TASK number → check if more TASKs remain
+# First WORK that is not fully completed is the active WORK
+
+# List all WORKs
+# Use Glob tool: pattern "works/WORK-*/"
+
+# WORK/TASK status from activity log (last line)
+# Read last line of works/${WORK_ID}/work_${WORK_ID}.log
+#   Format: [timestamp] EVENT — description
+#
+#   Key rule: *_START without matching *_DONE = interrupted, must REDO that step
+#
+#   COMMITTER_DONE — TASK-NN → TASK-NN completed, next TASK is TASK-(NN+1)
+#   COMMITTER_START — TASK-NN → committer interrupted, redo verifier+committer for TASK-NN
+#   VERIFIER_DONE — TASK-NN  → TASK-NN verified, needs committer
+#   VERIFIER_START — TASK-NN → verifier interrupted, redo verifier+committer for TASK-NN
+#   BUILDER_DONE — TASK-NN   → TASK-NN builder done, needs verifier+committer
+#   BUILDER_START — TASK-NN  → builder interrupted, redo builder for TASK-NN
+#   PLANNER_DONE             → planning done, start first TASK
+#   PLANNER_START            → planner interrupted, redo specifier+planner
+#   SPECIFIER_DONE           → specifier done, needs planner
+#   SPECIFIER_START          → specifier interrupted, redo specifier+planner
+#   No log file              → start from scratch
+```
+
+---
+
+## § 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. Use Grep tool: pattern "Language:\s*[a-z]{2}" path="CLAUDE.md" → extract language code
+2. If not found, ask user for language
+3. If not found, auto-detect system locale via Bash:
+   - Windows: powershell -c "[CultureInfo]::CurrentCulture.TwoLetterISOLanguageName"
+   - Linux/Mac: locale | grep LANG
+   - Fallback: "en"
+```
+
+---
+
+## § 10. Callback & Activity Log
+
+### 10-1. Callback (CE7)
+
+Each agent sends START/DONE/FAILED events to the server via CE7 API.
+
+**Activation condition:** Only when `CALLBACK_URL` is available. Check in order:
+1. Dispatch XML `<callback-url>` element (passed from Main Claude)
+2. Prompt text containing `CALLBACK_URL=...` line
+3. If neither found → **skip all callbacks**
+
+**How to resolve CALLBACK_URL and CALLBACK_TOKEN:**
+
+The runner injects callback info directly into the prompt:
+```
+POST {CALLBACK_URL}
+Authorization: Bearer {CALLBACK_TOKEN}
+```
+The first agent (specifier) extracts these and passes them via dispatch XML to subsequent agents.
+
+**When to send:**
+- **START**: At the very beginning of agent execution (after STARTUP)
+- **DONE**: At the very end, before returning task-result XML
+- **FAILED**: On unrecoverable failure, before returning FAIL task-result
+
+**How to send** (single curl command):
+```bash
+curl -s --connect-timeout 3 --max-time 5 -X POST "$CALLBACK_URL" \
+  -H "Authorization: Bearer $CALLBACK_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"stage":"BUILDER","event":"START","workId":"WORK-09","taskId":"TASK-01"}' \
+  2>/dev/null || true
+```
+
+- `--connect-timeout 3`: 연결 대기 최대 3초
+- `--max-time 5`: 전체 요청 최대 5초
+- `|| true`: 실패해도 agent 실행 계속
+
+**Include docs (actual file content, not references):**
+- specifier DONE: `"docs": {"requirementContent": "<Requirement.md content>"}`
+- planner DONE: `"docs": {"planContent": "<PLAN.md content>"}`
+- builder START: `"docs": {"taskContent": "<TASK-NN.md content>"}`
+- committer DONE: `"docs": {"resultContent": "<TASK-NN_result.md content>"}`
+
+**Token usage** (DONE event only, optional):
+```json
+{"inputTokens": 1234, "outputTokens": 567, "cacheCreationTokens": 890, "cacheReadTokens": 456}
+```
+
+Callback failure must NOT block agent execution. Always continue.
+
+### 10-2. Activity Log
+
+Each agent records start/end to `works/{WORK_ID}/work_{WORK_ID}.log`.
+
+**All WORKs** — no CALLBACK_URL condition.
+
+**Timestamp:** Run `date -u +"%Y-%m-%dT%H:%M:%SZ"` via Bash tool to get the real UTC time. Do NOT use dummy/placeholder timestamps.
+
+**Format:**
+```
+[2026-03-30T14:30:00Z] AGENT_EVENT — description
+```
+
+**How to write:** Use Bash `echo "[timestamp] EVENT — description" >> works/{WORK_ID}/work_{WORK_ID}.log`
+
+**Required entries per agent (START and DONE only):**
+```
+[{timestamp}] SPECIFIER_START — WORK-NN specifier started
+[{timestamp}] SPECIFIER_DONE — WORK-NN specifier completed
+[{timestamp}] BUILDER_START — TASK-NN implement
+[{timestamp}] BUILDER_DONE — TASK-NN complete
+[{timestamp}] VERIFIER_START — TASK-NN verification
+[{timestamp}] VERIFIER_DONE — TASK-NN verified
+[{timestamp}] COMMITTER_START — TASK-NN commit
+[{timestamp}] COMMITTER_DONE — TASK-NN committed
+```
+
+Do NOT write INIT, REF, PLAN, DISPATCH or other intermediate entries. Only START and DONE per agent role.
+
+---
+
+## § 11. Project Discovery
+
+```
+# 1. Check CLAUDE.md language setting
+Use Grep tool: pattern "Language:\s*[a-z]{2}" path="CLAUDE.md"
+
+# 2. Tech stack (read first 50/30/20/10 lines if file exists)
+Use Read tool: "package.json" (limit=50)
+Use Read tool: "pyproject.toml" (limit=30)
+Use Read tool: "Cargo.toml" (limit=20)
+Use Read tool: "go.mod" (limit=10)
+
+# 3. Structure (when needed)
+Use Glob tool: pattern "**/*.{md,json,toml}" (exclude node_modules)
+```
+
+---
+
+## § 12. Bash Command Rules
+
+Bash commands MUST follow these rules for permission compatibility.
+
+**MANDATORY:**
+- One simple command per Bash call — NO compound commands (`&&`, `||`, `;`, `|`)
+- NO `cd` — Bash tool cwd is always the project root. Never use `cd dir &&`, `cd dir ;`, or `cd dir` in any form. Use relative paths from 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/references/work-activity-log.md

@@ -0,0 +1,26 @@
+# Work Activity Log
+
+Records agent start/end events in `works/{WORK_ID}/work_{WORK_ID}.log`.
+
+## Rules
+
+1. **Timestamp**: Run `date -u +"%Y-%m-%dT%H:%M:%SZ"` via Bash to get real UTC time. Never use dummy values.
+2. **Write method**: Use `Edit` tool to append. Do NOT use Bash for log writes.
+3. **Entries**: Only START and DONE per agent role. No intermediate stages.
+
+## Format
+
+```
+[YYYY-MM-DDTHH:MM:SSZ] AGENT_EVENT — description
+```
+
+## Required Entries
+
+| Agent | START | DONE |
+|-------|-------|------|
+| specifier | `SPECIFIER_START — WORK-NN specifier started` | `SPECIFIER_DONE — WORK-NN specifier completed` |
+| planner | `PLANNER_START — WORK-NN planner started` | `PLANNER_DONE — WORK-NN planner completed` |
+| scheduler | `SCHEDULER_START — WORK-NN scheduler started` | `SCHEDULER_DONE — WORK-NN scheduler completed` |
+| builder | `BUILDER_START — TASK-NN implement` | `BUILDER_DONE — TASK-NN complete` |
+| verifier | `VERIFIER_START — TASK-NN verification` | `VERIFIER_DONE — TASK-NN verified` |
+| committer | `COMMITTER_START — TASK-NN commit` | `COMMITTER_DONE — TASK-NN committed` |

package/references/xml-schema.md

@@ -0,0 +1,120 @@
+# 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. 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 |
+
+---
+
+## 4. 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.