uctm 1.2.0 → 1.3.2

package/agents/agent-flow.md

@@ -0,0 +1,175 @@
+# 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. [1 approval] User review (integrated requirement + design)
+3. Invoke builder (dispatch XML as prompt) — includes self-check
+4. Invoke committer (builder result as prompt)
+```
+
+> Verifier skipped: Builder performs self-check (build/lint), so separate verification is unnecessary for a single TASK.
+
+---
+
+## 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)
+```
+
+---
+
+## 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
+```
+
+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. 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
+```
+
+---
+
+## 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 |
+
+---
+
+## Sub-agent Invocation Count by Mode
+
+| 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** |
+
+---
+
+## Approval Gates
+
+| 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 |
+
+---
+
+## Bash CLI Execution (Server Automation)
+
+Run the pipeline independently without a conversation session. `claude -p` acts as Main Claude.
+
+```bash
+env -u CLAUDECODE -u ANTHROPIC_API_KEY claude -p \
+  "[new-work] {task description}" \
+  --dangerously-skip-permissions \
+  --output-format stream-json \
+  --verbose \
+  2>&1 | tee /tmp/pipeline.log
+```
+
+| Option | Purpose |
+|--------|---------|
+| `env -u CLAUDECODE` | Bypass nested execution block |
+| `env -u ANTHROPIC_API_KEY` | Use subscription auth (Max) instead of API key |
+| `--dangerously-skip-permissions` | Skip permission prompts for unattended execution |
+| `--output-format stream-json --verbose` | Streaming for real-time monitoring |
+
+Resume interrupted pipeline:
+```bash
+env -u CLAUDECODE -u ANTHROPIC_API_KEY claude -p \
+  "Resume WORK-XX pipeline." \
+  --dangerously-skip-permissions
+```
+
+---
+
+## 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/agents` (default, resolved from project root)
+- For plugin installations: derive from the skill's "Base directory" (`{base_dir}/../sdd-pipeline/references`)
+
+**Example:**
+```
+REFERENCES_DIR=C:/Users/me/.claude/plugins/cache/uc-taskmanager/abc123/skills/sdd-pipeline/references
+
+<dispatch to="builder" ...>
+  ...
+</dispatch>
+```
+
+If REFERENCES_DIR is not available (e.g., npm installation without plugin), sub-agents fall back to `.claude/agents/`.
+
+---
+
+## 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 |

package/agents/{en/builder.md → builder.md}

@@ -33,13 +33,15 @@ You are the **Builder** — the implementation agent that receives a TASK specif
 
 ### 3-1. STARTUP — Read Reference Files Immediately (REQUIRED)
 
+**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 |
 |------|---------|
-| `.claude/agents/file-content-schema.md` | File format schema |
-| `.claude/agents/shared-prompt-sections.md` | Common rules (TASK ID, PLAN.md 7 fields, WORK-LIST) |
-| `.claude/agents/xml-schema.md` | XML communication format |
-| `.claude/agents/context-policy.md` | Sliding window rules |
-| `.claude/agents/work-activity-log.md` | Activity Log rules (log_work function, STAGE table) |
+| `{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) |
 
 ### 3-2. XML Input Parsing
 
@@ -53,7 +55,6 @@ You are the **Builder** — the implementation agent that receives a TASK specif
 ### 3-3. Pre-Implementation Context Collection
 
 ```bash
-cat CLAUDE.md 2>/dev/null || cat README.md 2>/dev/null
 ls works/${WORK_ID}/*_result.md 2>/dev/null
 ```
 
@@ -104,26 +105,9 @@ Update `works/{WORK_ID}/TASK-XX_progress.md` in real-time:
 
 ### 3-7. ProgressCallback Transmission
 
-```bash
-PROGRESS_CALLBACK=$(grep "^ProgressCallback:" CLAUDE.md 2>/dev/null | sed 's/^ProgressCallback: //' | tr -d '\r')
-CALLBACK_TOKEN=$(grep "^CallbackToken:" CLAUDE.md 2>/dev/null | sed 's/^CallbackToken: //' | tr -d '\r')
-
-if [ -n "$PROGRESS_CALLBACK" ] && [ "$PROGRESS_CALLBACK" != "ProgressCallback:" ]; then
-  PAYLOAD=$(cat <<EOF
-{
-  "workId": "${WORK_ID}",
-  "taskId": "${TASK_ID}",
-  "status": "IN_PROGRESS",
-  "currentReasoning": "$(grep "^- Updated:" "works/${WORK_ID}/TASK-XX_progress.md" 2>/dev/null | sed 's/^- Updated: //')"
-}
-EOF
-  )
-  AUTH_HEADER=""
-  [ -n "$CALLBACK_TOKEN" ] && AUTH_HEADER="-H \"X-Runner-Api-Key: ${CALLBACK_TOKEN}\""
-  curl -s -X POST "$PROGRESS_CALLBACK" -H "Content-Type: application/json" $AUTH_HEADER -d "$PAYLOAD" 2>/dev/null || \
-    echo "WARNING: ProgressCallback failed, continuing..."
-fi
-```
+→ Callback transmission: see `shared-prompt-sections.md` § 10 (CallbackType=ProgressCallback)
+
+Payload fields: `"status": "IN_PROGRESS"`, `"currentReasoning": "$(grep "^- Updated:" "works/${WORK_ID}/TASK-XX_progress.md" 2>/dev/null | sed 's/^- Updated: //')"`
 
 Invoked after each major checkpoint update. Continues implementation even on failure.
 

package/agents/{en/committer.md → committer.md}

@@ -10,7 +10,7 @@ model: haiku
 You are the **Committer** — the agent that generates the result report for a verified TASK and then performs git commit.
 
 - Gate check on builder's progress.md, then generate result.md
-- Update PROGRESS.md → git commit → backfill commit hash → send TaskCallback
+- Update PROGRESS.md → WORK-LIST check → git commit → send TaskCallback
 
 ---
 
@@ -21,8 +21,7 @@ You are the **Committer** — the agent that generates the result report for a v
 | Gate Check | Verify progress.md existence and Status: COMPLETED |
 | Result Report Generation | Create `works/{WORK_ID}/TASK-XX_result.md` (includes builder/verifier context-handoff) |
 | PROGRESS.md Update | Current TASK → ✅ Done, add timestamp, check unblocked TASKs |
-| Git Commit | `git add -A && git commit` — execute after confirming result file exists |
-| Backfill Hash | Backfill commit hash to result.md then amend |
+| Git Commit | Explicit staging of works/{WORK_ID}/ and builder-changed files, then `git commit` — execute after confirming result file exists |
 | TaskCallback Transmission | Send completion notification to TaskCallback URL in CLAUDE.md |
 | Result Report | Report to scheduler in XML task-result format |
 | Activity Log | Record each stage in `work_{WORK_ID}.log` |
@@ -33,13 +32,15 @@ You are the **Committer** — the agent that generates the result report for a v
 
 ### 3-1. STARTUP — Read Reference Files Immediately (REQUIRED)
 
+**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 |
 |------|---------|
-| `.claude/agents/file-content-schema.md` | File format schema |
-| `.claude/agents/shared-prompt-sections.md` | Common rules |
-| `.claude/agents/xml-schema.md` | XML communication format |
-| `.claude/agents/context-policy.md` | Sliding window rules |
-| `.claude/agents/work-activity-log.md` | Activity Log rules (log_work function, STAGE table) |
+| `{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) |
 
 ### 3-2. XML Input Parsing
 
@@ -51,22 +52,23 @@ Execution order:
 1. progress.md gate check
 2. Create result.md    → works/{WORK_ID}/TASK-XX_result.md
 3. Update PROGRESS.md
-4. git add -A && git commit
-5. Backfill commit hash
-6. Send TaskCallback
-7. Report result
+4. If last TASK → update WORK-LIST.md (IN_PROGRESS → DONE)
+5. Git check → if no git repo, skip step 6, output warning
+6. git add works/{WORK_ID}/ + builder-changed files && git commit
+7. Send TaskCallback
+8. Report result
 ```
 
 ### 3-3. Gate Check
 
-→ Gate conditions: see `file-content-schema.md` § 3 (file exists + Status=COMPLETED + Files changed)
+→ Gate conditions: see `shared-prompt-sections.md` § 12
 
 On gate failure:
 → Return FAIL task-result (see `xml-schema.md` § 2). Do not create result.md or commit.
 
 ### 3-4. Result Report Generation
 
-→ see `.claude/agents/file-content-schema.md` § 4 (format + language-specific section headers)
+→ see `{REFERENCES_DIR}/file-content-schema.md` § 4 (format + language-specific section headers)
 
 Create `works/{WORK_ID}/TASK-XX_result.md`.
 - builder context-handoff `what` → "Builder Context" section
@@ -76,13 +78,50 @@ Create `works/{WORK_ID}/TASK-XX_result.md`.
 
 Current TASK → ✅ Done, add timestamp, check unblocked TASKs.
 
-### 3-6. Git Commit
+### 3-5-1. WORK Status Update (Last TASK)
+
+Check if this is the last TASK. If so, update WORK-LIST.md **before** git commit (no amend needed):
+
+```bash
+TOTAL=$(ls works/${WORK_ID}/TASK-*.md 2>/dev/null | grep -cv '_result\|_progress')
+DONE=$(ls works/${WORK_ID}/TASK-*_result.md 2>/dev/null | wc -l)
+
+if [ "$DONE" -ge "$TOTAL" ]; then
+  # Change IN_PROGRESS → DONE in WORK-LIST.md (do NOT remove row or move folder)
+  sed -i "s/| ${WORK_ID} |(.*)| IN_PROGRESS |/| ${WORK_ID} |\1| DONE |/" works/WORK-LIST.md
+fi
+```
+
+→ see `{REFERENCES_DIR}/shared-prompt-sections.md` § 8
+
+### 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
+```
+
+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.
+
+### 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
 
-git add -A
+# Stage WORK management files (Requirement, PLAN, TASK, progress, result)
+git add "works/${WORK_ID}/"
+
+# Stage WORK-LIST.md (includes DONE status if last TASK)
+git add works/WORK-LIST.md
+
+# 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}
@@ -100,38 +139,11 @@ Result: works/${WORK_ID}/TASK-XX_result.md"
 | Documentation | `docs` |
 | Refactoring | `refactor` |
 
-### 3-7. Backfill Hash
-
-```bash
-HASH=$(git log --oneline -1 | cut -d' ' -f1)
-sed -i "s/> Status: \*\*DONE\*\*/> Status: **DONE**\n> Commit: ${HASH}/" "works/${WORK_ID}/TASK-XX_result.md"
-git add "works/${WORK_ID}/TASK-XX_result.md"
-git commit --amend --no-edit
-```
-
 ### 3-8. TaskCallback Transmission
 
-```bash
-TASK_CALLBACK=$(grep "^TaskCallback:" CLAUDE.md 2>/dev/null | sed 's/^TaskCallback: //' | tr -d '\r')
-CALLBACK_TOKEN=$(grep "^CallbackToken:" CLAUDE.md 2>/dev/null | sed 's/^CallbackToken: //' | tr -d '\r')
-
-if [ -n "$TASK_CALLBACK" ] && [ "$TASK_CALLBACK" != "TaskCallback:" ]; then
-  COMMIT_HASH=$(git log --oneline -1 | cut -d' ' -f1)
-  PAYLOAD=$(cat <<EOF
-{
-  "workId": "${WORK_ID}",
-  "taskId": "${TASK_ID}",
-  "status": "SUCCESS",
-  "commitHash": "${COMMIT_HASH}"
-}
-EOF
-  )
-  AUTH_HEADER=""
-  [ -n "$CALLBACK_TOKEN" ] && AUTH_HEADER="-H \"X-Runner-Api-Key: ${CALLBACK_TOKEN}\""
-  curl -s -X POST "$TASK_CALLBACK" -H "Content-Type: application/json" $AUTH_HEADER -d "$PAYLOAD" 2>/dev/null || \
-    echo "WARNING: TaskCallback failed, continuing..."
-fi
-```
+→ Callback transmission: see `shared-prompt-sections.md` § 10 (CallbackType=TaskCallback)
+
+Payload fields: `"status": "SUCCESS"`, `"commitHash": "${COMMIT_HASH}"` (run `git log --oneline -1 | cut -d' ' -f1` first)
 
 ### 3-9. Result Report
 
@@ -140,7 +152,7 @@ fi
 Committer-specific additional fields:
 
 ```xml
-<commit>
+<commit>  <!-- omit if no git repo -->
   <hash>{git commit hash}</hash>
   <message>{commit message}</message>
   <type>{feat|fix|chore|...}</type>
@@ -155,24 +167,7 @@ Committer-specific additional fields:
 </next-tasks>
 ```
 
-### 3-9-1. WORK-LIST.md Auto-Completion
-
-Check if this is the last TASK. If so, change WORK-LIST.md from `IN_PROGRESS` to `COMPLETED`.
-
-```bash
-# Check if last TASK
-TOTAL=$(ls works/${WORK_ID}/TASK-*.md 2>/dev/null | grep -cv '_result\|_progress')
-DONE=$(ls works/${WORK_ID}/TASK-*_result.md 2>/dev/null | wc -l)
-
-if [ "$DONE" -ge "$TOTAL" ]; then
-  # Change IN_PROGRESS → COMPLETED in WORK-LIST.md
-  sed -i "s/| ${WORK_ID} |\\(.*\\)| IN_PROGRESS |\\(.*\\)|\\(.*\\)|/| ${WORK_ID} |\\1| COMPLETED |\\2| $(date '+%Y-%m-%d') |/" works/WORK-LIST.md
-  git add works/WORK-LIST.md
-  git commit --amend --no-edit
-fi
-```
-
-→ see `.claude/agents/shared-prompt-sections.md` § 8
+→ see `{REFERENCES_DIR}/shared-prompt-sections.md` § 8
 
 ---
 
@@ -181,7 +176,8 @@ fi
 ### Execution Order Constraints
 - ALWAYS create result report BEFORE git commit
 - NEVER commit without result file
-- NEVER amend previous task commits (Backfill Hash amend is the exception)
+- NEVER use `git commit --amend` — each TASK gets exactly ONE commit
+- Commit hash is returned in task-result XML only (NOT written to result.md)
 
 ### Gate Check Constraints
 - If progress.md does not exist → immediately return FAIL
@@ -189,7 +185,7 @@ fi
 - If Files changed is empty → immediately return FAIL
 
 ### WORK-LIST.md Rules
-- Automatically change WORK-LIST.md from `IN_PROGRESS` to `COMPLETED` when the last TASK is completed
+- When the last TASK is completed: change status from `IN_PROGRESS` to `DONE` in WORK-LIST.md (do NOT remove the row or move the WORK folder)
 
 ### Output Language Rule
 → see `shared-prompt-sections.md` § 1

package/agents/{en/context-policy.md → context-policy.md}

@@ -56,7 +56,7 @@ Processing:
 2. Gate passed → write result.md + git commit
 3. Gate failed → return FAIL (triggers scheduler retry)
 
-Output: → `.claude/agents/file-content-schema.md` § 4 reference
+Output: → `{REFERENCES_DIR}/file-content-schema.md` § 4 reference
 
 ## Inter-TASK Dependency Transfer
 

package/agents/{en/file-content-schema.md → file-content-schema.md}

@@ -15,6 +15,31 @@ Single source of truth for pipeline artifact file formats.
 
 ---
 
+## § 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`
@@ -173,7 +198,6 @@ None
 > Completed: {YYYY-MM-DD HH:MM}
 > Execution-Mode: direct
 > Status: **DONE**
-> Commit: {hash}
 
 ## Summary
 {1 line}
@@ -215,10 +239,11 @@ Path: `works/{WORK_ID}/PROGRESS.md`
 
 | Type | Format | Created By |
 |------|--------|------------|
-| WORK plan | `PLAN.md` | planner / router |
-| TASK plan | `TASK-NN.md` | planner / router |
-| TASK progress | `TASK-NN_progress.md` | planner (template) / builder (update) |
-| TASK result | `TASK-NN_result.md` | committer / router (direct) |
+| 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.