uctm 1.5.1 → 1.5.3

package/lib/init.mjs

@@ -2,7 +2,7 @@ import { existsSync, mkdirSync, copyFileSync, readFileSync, writeFileSync, readd
 import { join, dirname } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { homedir } from 'node:os';
-import { AGENT_FILES, getAgentsSrcDir, REQUIRED_PERMISSIONS } from './constants.mjs';
+import { AGENT_FILES, REFERENCE_FILES, getAgentsSrcDir, getReferencesSrcDir, REQUIRED_PERMISSIONS } from './constants.mjs';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 
@@ -12,8 +12,8 @@ const green = (s) => `\x1b[32m${s}\x1b[0m`;
 const dim = (s) => `\x1b[2m${s}\x1b[0m`;
 const yellow = (s) => `\x1b[33m${s}\x1b[0m`;
 
-function copyAgents(destDir, lang) {
-  const srcDir = getAgentsSrcDir(lang);
+function copyAgents(destDir) {
+  const srcDir = getAgentsSrcDir();
   mkdirSync(destDir, { recursive: true });
   let count = 0;
   for (const file of AGENT_FILES) {
@@ -25,6 +25,19 @@ function copyAgents(destDir, lang) {
   return count;
 }
 
+function copyReferences(destDir) {
+  const srcDir = getReferencesSrcDir();
+  mkdirSync(destDir, { recursive: true });
+  let count = 0;
+  for (const file of REFERENCE_FILES) {
+    const src = join(srcDir, file);
+    if (!existsSync(src)) continue;
+    copyFileSync(src, join(destDir, file));
+    count++;
+  }
+  return count;
+}
+
 function copyDirRecursive(src, dest) {
   mkdirSync(dest, { recursive: true });
   let count = 0;
@@ -126,17 +139,16 @@ async function promptPermissions() {
   });
 }
 
-export async function init(isGlobal, lang) {
-  const exampleTag = lang === 'ko'
-    ? `[추가기능] Add a hello world feature`
-    : `[new-feature] Add a hello world feature`;
+export async function init(isGlobal) {
+  const exampleTag = `[new-feature] Add a hello world feature`;
 
   if (isGlobal) {
     const globalClaudeDir = join(homedir(), '.claude');
-    const globalDir = join(globalClaudeDir, 'agents');
-    const count = copyAgents(globalDir, lang);
-    console.log(`\n  Installing to ${dim('~/.claude/agents/')} (${lang}) ...`);
-    console.log(`    ${green('✓')} ${count} agent files copied`);
+    const agentCount = copyAgents(join(globalClaudeDir, 'agents'));
+    const refCount = copyReferences(join(globalClaudeDir, 'references'));
+    console.log(`\n  Installing to ${dim('~/.claude/')} ...`);
+    console.log(`    ${green('✓')} ${agentCount} agent files copied to agents/`);
+    console.log(`    ${green('✓')} ${refCount} reference files copied to references/`);
     const globalResCount = copyPluginResources(globalClaudeDir);
     if (globalResCount > 0) {
       console.log(`    ${green('✓')} ${globalResCount} plugin resource files copied`);
@@ -148,14 +160,15 @@ export async function init(isGlobal, lang) {
   }
 
   const projectDir = process.cwd();
-  const destDir = join(projectDir, '.claude', 'agents');
+  const claudeDir = join(projectDir, '.claude');
 
-  console.log(`\n  Installing to ${dim('.claude/agents/')} (${lang}) ...`);
+  console.log(`\n  Installing to ${dim('.claude/')} ...`);
 
-  const count = copyAgents(destDir, lang);
-  console.log(`    ${green('✓')} ${count} agent files copied`);
+  const agentCount = copyAgents(join(claudeDir, 'agents'));
+  console.log(`    ${green('✓')} ${agentCount} agent files copied to agents/`);
+  const refCount = copyReferences(join(claudeDir, 'references'));
+  console.log(`    ${green('✓')} ${refCount} reference files copied to references/`);
 
-  const claudeDir = join(projectDir, '.claude');
   const resCount = copyPluginResources(claudeDir);
   if (resCount > 0) {
     console.log(`    ${green('✓')} ${resCount} plugin resource files copied (.claude-plugin, skills)`);

package/lib/update.mjs

@@ -2,41 +2,47 @@ import { existsSync, copyFileSync, mkdirSync } from 'node:fs';
 import { join, dirname } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { homedir } from 'node:os';
-import { AGENT_FILES, getAgentsSrcDir } from './constants.mjs';
+import { AGENT_FILES, REFERENCE_FILES, getAgentsSrcDir, getReferencesSrcDir } from './constants.mjs';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 
 const green = (s) => `\x1b[32m${s}\x1b[0m`;
 const dim = (s) => `\x1b[2m${s}\x1b[0m`;
-const red = (s) => `\x1b[31m${s}\x1b[0m`;
 
-export function update(isGlobal, lang) {
-  if (!lang) {
-    console.error(`\n  ${red('Error:')} --lang is required for update.`);
-    console.error(`  Usage: uctm update --lang ko|en ${isGlobal ? '--global' : ''}\n`);
-    process.exit(1);
-  }
-
-  const srcDir = getAgentsSrcDir(lang);
-  const destDir = isGlobal
-    ? join(homedir(), '.claude', 'agents')
-    : join(process.cwd(), '.claude', 'agents');
+export function update(isGlobal) {
+  const baseDir = isGlobal
+    ? join(homedir(), '.claude')
+    : join(process.cwd(), '.claude');
+  const agentDestDir = join(baseDir, 'agents');
+  const refDestDir = join(baseDir, 'references');
 
-  if (!existsSync(destDir)) {
-    console.error(`\n  Error: ${destDir} not found. Run ${dim("'uctm init'")} first.\n`);
+  if (!existsSync(agentDestDir)) {
+    console.error(`\n  Error: ${agentDestDir} not found. Run ${dim("'uctm init'")} first.\n`);
     process.exit(1);
   }
 
-  let count = 0;
+  const agentSrcDir = getAgentsSrcDir();
+  let agentCount = 0;
   for (const file of AGENT_FILES) {
-    const src = join(srcDir, file);
+    const src = join(agentSrcDir, file);
+    if (!existsSync(src)) continue;
+    copyFileSync(src, join(agentDestDir, file));
+    agentCount++;
+  }
+
+  mkdirSync(refDestDir, { recursive: true });
+  const refSrcDir = getReferencesSrcDir();
+  let refCount = 0;
+  for (const file of REFERENCE_FILES) {
+    const src = join(refSrcDir, file);
     if (!existsSync(src)) continue;
-    copyFileSync(src, join(destDir, file));
-    count++;
+    copyFileSync(src, join(refDestDir, file));
+    refCount++;
   }
 
-  const label = isGlobal ? '~/.claude/agents/' : '.claude/agents/';
-  console.log(`\n  Updating ${dim(label)} (${lang}) ...`);
-  console.log(`    ${green('✓')} ${count} agent files updated`);
+  const label = isGlobal ? '~/.claude/' : '.claude/';
+  console.log(`\n  Updating ${dim(label)} ...`);
+  console.log(`    ${green('✓')} ${agentCount} agent files updated`);
+  console.log(`    ${green('✓')} ${refCount} reference files updated`);
   console.log(`    ${dim('-')} CLAUDE.md, router_rule_config.json untouched\n`);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "uctm",
-  "version": "1.5.1",
+  "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/{agents → references}/context-policy.md

@@ -49,12 +49,11 @@ Output:
 
 ### Committer
 
-Input: Verifier context-handoff (FULL) + Builder context-handoff (SUMMARY) + progress.md (gate)
+Input: Verifier context-handoff (FULL) + Builder context-handoff (SUMMARY)
 
 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)
+1. Verify builder completed successfully (check context-handoff status)
+2. Write result.md + git commit
 
 Output: → `{REFERENCES_DIR}/file-content-schema.md` § 4 reference
 
@@ -89,6 +88,6 @@ Output: → `{REFERENCES_DIR}/file-content-schema.md` § 4 reference
 
 ## Committer Retry
 
-1. Failure cause: progress.md not found / Status≠COMPLETED / No files changed
-2. Re-dispatch to builder including existing progress.md
+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/{skills/sdd-pipeline/references → references}/file-content-schema.md

@@ -8,10 +8,8 @@ Single source of truth for pipeline artifact file formats.
 |----------------|-------------------|----------------------|
 | `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 |
+| `TASK-XX_result.md` | § 3 | context-handoff missing |
+| `TASK-XX_result.md` (direct) | § 4 | result.md recognition failure |
 
 ---
 
@@ -111,32 +109,7 @@ Path: `works/{WORK_ID}/TASK-XX.md`
 
 ---
 
-## § 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)
+## § 3. TASK-XX_result.md (full / pipeline)
 
 Path: `works/{WORK_ID}/TASK-XX_result.md`
 
@@ -189,7 +162,7 @@ None
 
 ---
 
-## § 5. TASK-XX_result.md (direct mode)
+## § 4. TASK-XX_result.md (direct mode)
 
 ```markdown
 # TASK-00 Result
@@ -212,38 +185,14 @@ None
 
 ---
 
-## § 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
+## § 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 progress | `TASK-NN_progress.md` | planner / specifier (template) / builder (update) |
 | TASK result | `TASK-NN_result.md` | committer |
-| WORK progress | `PROGRESS.md` | scheduler |
+| 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.