uctm 1.5.1 → 1.5.2

package/skills/sdd-pipeline/references/agent-flow.md

@@ -1,279 +0,0 @@
-# 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. Invoke builder (per-TASK dispatch XML as prompt)
-4. Invoke verifier+committer (builder result as prompt) — verify then commit in one spawn
-```
-
-> Specifier+Planner combined: specifier.md role first (Requirement.md), then planner.md role (PLAN.md + TASKs) in one spawn.
-
----
-
-## Full Mode (With Scheduler)
-
-```
-1. Invoke specifier+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. Invoke scheduler → check READY TASKs + return builder dispatch XML
-2. Invoke builder → implementation
-3. Invoke verifier+committer → verify then commit in one spawn
-4. If incomplete TASKs remain, return to step 1
-```
-
----
-
-## Combined Agent Invocation
-
-### Specifier+Planner (single spawn)
-
-When invoking specifier in pipeline/full mode, include both agent definitions:
-
-```
-Prompt to agent:
-  "You will perform two roles in sequence.
-
-   Role 1 — Specifier: Read specifier.md and create Requirement.md.
-   Role 2 — Planner: Read planner.md and create PLAN.md + TASK files.
-
-   Execute Role 1 first, then Role 2. Return the combined result."
-```
-
-- Use specifier's model (opus) for the spawn
-- Agent reads both specifier.md and planner.md from REFERENCES_DIR
-- Returns: Requirement.md + PLAN.md + TASK files + execution-mode
-
-### Verifier+Committer (single spawn)
-
-When invoking verification after builder completes:
-
-```
-Prompt to agent:
-  "You will perform two roles in sequence.
-
-   Role 1 — Verifier: Read verifier.md and verify build/lint/test.
-   Role 2 — Committer: Read committer.md and create result.md + git commit.
-
-   Execute Role 1 first. If verification PASSES, execute Role 2.
-   If verification FAILS, skip Role 2 and return FAIL result."
-```
-
-- Use verifier's model (haiku) for the spawn
-- Agent reads both verifier.md and committer.md from REFERENCES_DIR
-- On PASS: returns verification result + commit hash
-- On FAIL: returns verification failure only (no commit)
-
----
-
-## Agent Role Summary
-
-| Agent | 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 | 1 (combined) | — | 1 | 1 | **3** |
-| 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
-
----
-
-## 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 |
-
----
-
-## ref-cache Chain Propagation
-
-`<ref-cache>` carries pre-loaded reference file contents through the pipeline, eliminating redundant disk reads in each sub-agent.
-
-### Rules
-
-1. **First agent (typically specifier)** — no ref-cache available on dispatch. Reads reference files from `REFERENCES_DIR` normally.
-
-2. **Agent returns task-result** — if the agent supports ref-cache, it includes `<ref-cache>` in its task-result XML containing all reference files it loaded.
-
-3. **Main Claude propagates ref-cache** — when dispatching the next agent, copy the `<ref-cache>` block from the previous task-result into the new dispatch XML unchanged.
-
-4. **Receiving agent skips file reads** — when `<ref-cache>` is present in the dispatch XML, the agent reads reference content from `<ref>` elements instead of reading files from disk.
-
-5. **Missing ref-cache** — if a task-result does not contain `<ref-cache>` (agent does not support it yet), omit `<ref-cache>` from the next dispatch. The receiving agent falls back to reading files from disk.
-
-### Flow Example
-
-```
-specifier+planner (no ref-cache in) → reads files → returns task-result with <ref-cache>
-  ↓ Main Claude copies <ref-cache> into dispatch
-builder (ref-cache in) → skips file reads → returns task-result with <ref-cache>
-  ↓ Main Claude copies <ref-cache> into dispatch
-verifier+committer (ref-cache in) → skips file reads → commit
-```
-
-### Phase 2: Selective Section Delivery
-
-Instead of passing full reference files, Main Claude extracts only the sections each agent needs. This reduces dispatch token size by 50-70%.
-
-**Main Claude reads reference files once at pipeline start**, then delivers condensed `<ref-cache>` per agent using this mapping:
-
-| Agent | shared-prompt-sections | file-content-schema | xml-schema | context-policy | work-activity-log |
-|-------|:---:|:---:|:---:|:---:|:---:|
-| **specifier+planner** | §1,§2,§7,§8,§9,§11 | §0,§1,§2,§3 | §1,§3 | — | full |
-| **scheduler** | §4,§8,§10 | §1,§6 | §1,§3,§4,§5 | full | full |
-| **builder** | §1,§2,§10,§12 | §2,§3 | §1,§2,§4 | Builder section | full |
-| **verifier+committer** | §1,§2,§8,§10,§12 | §3,§4,§5,§6,§7 | §1,§2,§4 | Verifier+Committer | full |
-
-**Delivery format**: Condense each `<ref key="">` to contain only the needed sections, not the full file. Use one-line summaries for simple rules, keep full content only for templates and code blocks.
-
-### Constraints
-
-- **ref-cache does not replace REFERENCES_DIR** — always pass `REFERENCES_DIR` (or `<references-dir>`) in every dispatch regardless of ref-cache presence, for backward compatibility.
-- **Agents may still read files** — if ref-cache content is insufficient, agents fall back to reading from disk.

package/skills/sdd-pipeline/references/context-policy.md

@@ -1,94 +0,0 @@
-# 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) + progress.md (gate)
-
-Processing:
-1. progress.md gate: exists + Status=COMPLETED + Files changed is not empty
-2. Gate passed → write result.md + git commit
-3. Gate failed → return FAIL (triggers scheduler retry)
-
-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: progress.md not found / Status≠COMPLETED / No files changed
-2. Re-dispatch to builder including existing progress.md
-3. Maximum 2 retries (3 attempts total). 3 failures → TASK FAILED, pipeline halted

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

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