uctm 1.3.0 → 1.4.0

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

@@ -32,44 +32,43 @@ You are the **Specifier** — the agent that transforms user requests into requi
 
 ### 3-1. STARTUP — Read Reference Files Immediately (REQUIRED)
 
-| File | Purpose |
-|------|---------|
-| `.claude/agents/file-content-schema.md` | File format schema (PLAN.md, TASK, Requirement.md formats) |
-| `.claude/agents/shared-prompt-sections.md` | Common rules (TASK ID patterns, WORK-LIST rules, log_work function) |
-| `.claude/agents/xml-schema.md` | XML communication format (dispatch / task-result structure) |
-| `.claude/agents/work-activity-log.md` | Activity Log rules (log_work function, STAGE table) |
+**Resolve REFERENCES_DIR**: Check your input for `REFERENCES_DIR=...` line. Use that absolute path. If not provided, default to `.claude/agents`.
+
+#### Reference Loading (ref-cache)
+
+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)
+
+Required reference files for this agent:
+
+| File | ref-cache key |
+|------|---------------|
+| `{REFERENCES_DIR}/file-content-schema.md` | `file-content-schema` |
+| `{REFERENCES_DIR}/shared-prompt-sections.md` | `shared-prompt-sections` |
+| `{REFERENCES_DIR}/xml-schema.md` | `xml-schema` |
+| `{REFERENCES_DIR}/work-activity-log.md` | `work-activity-log` |
 
 ### 3-2. WORK ID Determination
 
 ```bash
-WORK_FS=$(ls -d works/WORK-* 2>/dev/null | grep -oP 'WORK-\K\d+' | sort -n | tail -1)
-WORK_FS=${WORK_FS:-0}
-WORK_LIST=$(grep -oP '^WORK-\K\d+' works/WORK-LIST.md 2>/dev/null | sort -n | tail -1)
-WORK_LIST=${WORK_LIST:-0}
-WORK_MAX=$(( WORK_FS > WORK_LIST ? WORK_FS : WORK_LIST ))
-echo "WORK-$(printf "%02d" $((WORK_MAX + 1)))"
-[ "$WORK_FS" != "$WORK_LIST" ] && echo "WARNING: FS=$WORK_FS, LIST=$WORK_LIST mismatch"
+LAST_ID=$(grep -oP 'LAST_WORK_ID: WORK-\K\d+' works/WORK-LIST.md 2>/dev/null)
+LAST_ID=${LAST_ID:-0}
+NEW_ID=$(printf "%02d" $((LAST_ID + 1)))
+echo "WORK-${NEW_ID}"
 ```
 
-When IN_PROGRESS WORK exists:
-> "There is an ongoing WORK-XX. Would you like to add TASKs to it, or create a new WORK?"
+When IN_PROGRESS or DONE WORK exists:
+> "There is an ongoing WORK-XX (IN_PROGRESS) or completed WORK-XX (DONE). Would you like to add TASKs to it, or create a new WORK?"
 
 ### 3-3. Project Exploration (Discovery)
 
-```bash
-# 1. Check CLAUDE.md language setting
-grep -oP '(?<=Language:\s?)[a-z]{2}' CLAUDE.md 2>/dev/null
-
-# 2. Project information
-cat CLAUDE.md 2>/dev/null || cat README.md 2>/dev/null
+→ Project discovery commands: see `shared-prompt-sections.md` § 11
 
-# 3. Tech stack
-cat package.json 2>/dev/null | head -50
-cat pyproject.toml 2>/dev/null | head -30
-
-# 4. Structure (only when assuming Planner — skip for simple requirements)
-find . -maxdepth 3 -type f \( -name "*.md" -o -name "*.json" -o -name "*.toml" \) | grep -v node_modules | head -30
-```
+Note: Step 3 (Structure) is only needed when assuming Planner role — skip for simple requirements.
 
 ### 3-4. Requirement.md Creation
 
@@ -120,7 +119,7 @@ Requirement complexity assessment:
 5.  Create PLAN.md (Execution-Mode: direct) → file-content-schema.md § 1
 6.  Create TASK-00.md → file-content-schema.md § 2
 7.  Create TASK-00_progress.md (Status: PENDING) → file-content-schema.md § 3
-8.  Add IN_PROGRESS to WORK-LIST.md
+8.  Add IN_PROGRESS row to WORK-LIST.md + update LAST_WORK_ID
 9.  log_work PLAN "Requirement.md, PLAN.md, TASK-00.md created (assumed)"
 10. Present deliverable summary to user and request approval (integrated requirement + design review)
 11. Return dispatch XML. **Invocation is performed by Main Claude.**
@@ -128,6 +127,7 @@ Requirement complexity assessment:
 ```
 
 → dispatch XML format: see `xml-schema.md` § 1 (to="builder", task="TASK-00", execution-mode="direct")
+→ Include `<ref-cache>` with all reference files loaded (see `xml-schema.md` § 6)
 
 ### 3-7. Planner Delegation — Complex Requirements (pipeline/full)
 
@@ -140,7 +140,7 @@ Requirement complexity assessment:
 1.  mkdir works/WORK-NN/
 2.  log_work INIT "WORK-NN created — Planner delegation"
 3.  Create Requirement.md → § 3-4
-4.  Add IN_PROGRESS to WORK-LIST.md
+4.  Add IN_PROGRESS row to WORK-LIST.md + update LAST_WORK_ID
 5.  log_work REF "References: ..."
 6.  Present Requirement.md summary to user and request planning approval
 7.  Return Planner dispatch XML. **Invocation is performed by Main Claude.**
@@ -148,25 +148,17 @@ Requirement complexity assessment:
 ```
 
 → dispatch XML format: see `xml-schema.md` § 1 (to="planner", execution-mode="full")
+→ Include `<ref-cache>` with all reference files loaded (see `xml-schema.md` § 6)
 
 ### 3-8. Output Language Rule
 
 → Priority rules: see `shared-prompt-sections.md` § 1
+→ Locale detection: see `shared-prompt-sections.md` § 9
 
 Specifier-specific rules:
 - Pass resolved language via dispatch `<context><language>` field
 - Write both Requirement.md and PLAN.md in resolved language
 
-Locale detection:
-```
-1. CLAUDE.md → check "Language: xx"
-2. If not found, ask user for language
-3. If not found, auto-detect system locale
-   - Windows: powershell -c "[CultureInfo]::CurrentCulture.TwoLetterISOLanguageName"
-   - Linux/Mac: locale | grep LANG | grep -oP '[a-z]{2}' | head -1
-   - Fallback: "en"
-```
-
 ---
 
 ## 4. Constraints and Prohibitions
@@ -191,9 +183,9 @@ Locale detection:
 - Auto mode only when "proceed automatically" is explicitly stated (valid only within current WORK)
 
 ### WORK-LIST.md Rules
-→ see `.claude/agents/shared-prompt-sections.md` § 8
+→ see `{REFERENCES_DIR}/shared-prompt-sections.md` § 8
 
-- On WORK creation: add `IN_PROGRESS`
+- On WORK creation: add `IN_PROGRESS` row + update `LAST_WORK_ID` header
 
 ### Filename Rules
 - TASK filenames: `TASK-XX.md` format

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

@@ -33,12 +33,25 @@ Verifies the results of TASKs completed by the Builder, checking build, lint, te
 
 ### 3-1. STARTUP — Read Reference Files Immediately (REQUIRED)
 
-| File | Purpose |
-|------|---------|
-| `.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) |
+**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`.
+
+#### Reference Loading (ref-cache)
+
+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)
+
+Required reference files for this agent:
+
+| File | ref-cache key |
+|------|---------------|
+| `{REFERENCES_DIR}/shared-prompt-sections.md` | `shared-prompt-sections` |
+| `{REFERENCES_DIR}/xml-schema.md` | `xml-schema` |
+| `{REFERENCES_DIR}/context-policy.md` | `context-policy` |
+| `{REFERENCES_DIR}/work-activity-log.md` | `work-activity-log` |
 
 ### 3-2. XML Input Parsing
 
@@ -46,7 +59,7 @@ Verifies the results of TASKs completed by the Builder, checking build, lint, te
 
 ### 3-3. Step 0: Progress File Gate (CRITICAL)
 
-→ Gate conditions: see `file-content-schema.md` § 3 (file exists + Status=COMPLETED + Files changed)
+→ Gate conditions: see `shared-prompt-sections.md` § 12
 
 On CRITICAL failure, halt immediately. Cannot proceed to subsequent steps.
 
@@ -94,6 +107,7 @@ Only check conventions specified in CLAUDE.md or project config.
 
 → task-result XML base structure: see `xml-schema.md` § 2
 → context-handoff element: see `xml-schema.md` § 4
+→ ref-cache element: see `xml-schema.md` § 6
 
 Verifier-specific additional fields:
 
@@ -114,6 +128,12 @@ Verifier-specific additional fields:
     <suggested-fix>{suggestion}</suggested-fix>
   </failure>
 </failure-details>
+<ref-cache>
+  <!-- Include all reference files loaded during this execution (from disk or received ref-cache) -->
+  <ref key="shared-prompt-sections">{content}</ref>
+  <ref key="xml-schema">{content}</ref>
+  <!-- ... other keys loaded ... -->
+</ref-cache>
 ```
 
 ---

package/agents/{en/work-activity-log.md → work-activity-log.md}

@@ -10,19 +10,21 @@ Defines the rules for each agent to record WORK progress in the `works/{WORK_ID}
 * During work: Work items and work content
 * On task completion: The prompt message sent to other agents** Content of the prompt message received at agent startup (Required)
 
-## log_work Function
-
-```bash
-AGENT_NAME="SPECIFIER"  # Set appropriately in each agent file
-
-log_work() {
-  local WORK_ID="$1" AGENT="$2" STAGE="$3" DESC="$4"
-  mkdir -p "works/${WORK_ID}"
-  printf '[%s]_%s_%s_%s\n' \
-    "$(date '+%Y-%m-%dT%H:%M:%S')" "$AGENT" "$STAGE" "$DESC" \
-    >> "works/${WORK_ID}/work_${WORK_ID}.log"
-}
+## log_work Method
+
+**Do NOT use Bash** for activity log writes. Use the `Write` tool (or `Edit` tool to append).
+
+Format each log entry as:
 ```
+[YYYY-MM-DDTHH:MM:SS]_AGENT_STAGE_description
+```
+
+Example: to log an INIT stage, use the **Write** tool to append to `works/{WORK_ID}/work_{WORK_ID}.log`:
+```
+[2026-03-28T14:30:00]_SPECIFIER_INIT_WORK-09 created — Execution-Mode: direct
+```
+
+→ **Bash command rules: see `shared-prompt-sections.md` § 13**
 
 ---
 

package/agents/{en/xml-schema.md → xml-schema.md}

@@ -8,6 +8,14 @@ XML communication format definition for uc-taskmanager agents.
 
 ```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>
@@ -46,6 +54,13 @@ XML communication format definition for uc-taskmanager agents.
     <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>
 ```
 
@@ -106,3 +121,39 @@ Invariants (regardless of mode):
 | `TASK-XX_result.md` | Committer | Committer |
 | COMMITTER DONE callback | Committer | Committer |
 | `WORK-LIST.md` IN_PROGRESS | Specifier | Specifier |
+
+---
+
+## 6. ref-cache Element Definition
+
+`<ref-cache>` is an optional container element that carries pre-loaded reference file contents within dispatch and task-result XML. When present, receiving agents MUST use these contents instead of reading files from disk.
+
+### Structure
+
+```xml
+<ref-cache>
+  <ref key="{filename-without-extension}">{full file content}</ref>
+  ...
+</ref-cache>
+```
+
+| Element | Required | Description |
+|---------|----------|-------------|
+| `<ref-cache>` | Optional | Container for cached reference files. Omit entirely if no cache is available. |
+| `<ref key="...">` | — | Individual reference file. `key` is the filename without extension (e.g., `shared-prompt-sections`). |
+
+### Recognized Keys
+
+| Key | Corresponding File |
+|-----|--------------------|
+| `shared-prompt-sections` | `{REFERENCES_DIR}/shared-prompt-sections.md` |
+| `file-content-schema` | `{REFERENCES_DIR}/file-content-schema.md` |
+| `xml-schema` | `{REFERENCES_DIR}/xml-schema.md` |
+| `context-policy` | `{REFERENCES_DIR}/context-policy.md` |
+| `work-activity-log` | `{REFERENCES_DIR}/work-activity-log.md` |
+
+### Backward Compatibility
+
+- Dispatch or task-result XML without `<ref-cache>` is fully valid — agents fall back to reading files from `REFERENCES_DIR`.
+- Agents that do not yet support ref-cache simply ignore the element and read files normally.
+- Partial ref-cache (only some keys present) is allowed — missing keys are read from disk.

package/bin/cli.mjs

@@ -1,4 +1,4 @@
-#!/usr/bin/env node
+#!/usr/bin/env node
 
 import { createInterface } from 'node:readline';
 import { VERSION, SUPPORTED_LANGS } from '../lib/constants.mjs';
@@ -100,7 +100,7 @@ async function main() {
       lang = await promptLang();
     }
     const { init } = await import('../lib/init.mjs');
-    init(isGlobal, lang);
+    await init(isGlobal, lang);
     return;
   }
 

package/lib/constants.mjs

@@ -25,6 +25,9 @@ export const AGENT_FILES = [
 ];
 
 export function getAgentsSrcDir(lang) {
+  if (lang === 'en') {
+    return join(__dirname, '..', 'agents');
+  }
   return join(__dirname, '..', 'agents', lang);
 }
 
@@ -59,3 +62,66 @@ Examples: \`[new-feature]\`, \`[bugfix]\`, \`[enhancement]\`, \`[new-work]\`, et
 export function getClaudeMdSection(lang) {
   return lang === 'ko' ? CLAUDE_MD_SECTION_KO : CLAUDE_MD_SECTION_EN;
 }
+
+/**
+ * Bash permissions required by uc-taskmanager agents.
+ * Merged into .claude/settings.local.json during init.
+ *
+ * Categories:
+ *   - File discovery: ls, cat, basename, find, wc, sort, tail, head
+ *   - Pattern matching: grep, sed, cut, tr
+ *   - Formatting: printf, echo
+ *   - Build/Lint: node, npm, bun, yarn, cargo, go, python, ruff, make
+ *   - Git: git add, git commit, git log, git rev-parse
+ *   - Network: curl (callback)
+ */
+export const REQUIRED_PERMISSIONS = [
+  // File read/write tools (project-root scoped)
+  'Read(/**)',
+  'Edit(/**)',
+  'Write(/**)',
+  'Read(**)',
+  'Edit(**)',
+  'Write(**)',
+
+  // File discovery & text utilities
+  'Bash(ls:*)',
+  'Bash(cat:*)',
+  'Bash(mkdir:*)',
+  'Bash(basename:*)',
+  'Bash(find:*)',
+  'Bash(wc:*)',
+  'Bash(sort:*)',
+  'Bash(tail:*)',
+  'Bash(head:*)',
+  'Bash(echo:*)',
+  'Bash(printf:*)',
+
+  // Pattern matching & text processing
+  'Bash(grep:*)',
+  'Bash(sed:*)',
+  'Bash(cut:*)',
+  'Bash(tr:*)',
+
+  // Build & Lint (auto-detect per project type)
+  'Bash(node:*)',
+  'Bash(npm run:*)',
+  'Bash(npm test:*)',
+  'Bash(bun run:*)',
+  'Bash(yarn:*)',
+  'Bash(cargo:*)',
+  'Bash(go build:*)',
+  'Bash(go test:*)',
+  'Bash(python:*)',
+  'Bash(ruff:*)',
+  'Bash(make:*)',
+
+  // Git operations (committer)
+  'Bash(git add:*)',
+  'Bash(git commit:*)',
+  'Bash(git log:*)',
+  'Bash(git rev-parse:*)',
+
+  // Network (callback transmission)
+  'Bash(curl:*)',
+];

package/lib/init.mjs

@@ -2,12 +2,15 @@ import { existsSync, mkdirSync, copyFileSync, readFileSync, writeFileSync } from
 import { join, dirname } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { homedir } from 'node:os';
-import { AGENT_FILES, getAgentsSrcDir, getClaudeMdSection } from './constants.mjs';
+import { AGENT_FILES, getAgentsSrcDir, getClaudeMdSection, REQUIRED_PERMISSIONS } from './constants.mjs';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 
+import { createInterface } from 'node:readline';
+
 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);
@@ -56,7 +59,54 @@ function updateClaudeMd(projectDir, lang) {
   return true;
 }
 
-export function init(isGlobal, lang) {
+function mergePermissions(projectDir) {
+  const settingsPath = join(projectDir, '.claude', 'settings.local.json');
+  let settings = {};
+
+  if (existsSync(settingsPath)) {
+    try {
+      settings = JSON.parse(readFileSync(settingsPath, 'utf8'));
+    } catch {
+      settings = {};
+    }
+  }
+
+  if (!settings.permissions) settings.permissions = {};
+  if (!Array.isArray(settings.permissions.allow)) settings.permissions.allow = [];
+
+  const existing = new Set(settings.permissions.allow);
+  let added = 0;
+
+  for (const perm of REQUIRED_PERMISSIONS) {
+    if (!existing.has(perm)) {
+      settings.permissions.allow.push(perm);
+      added++;
+    }
+  }
+
+  if (added > 0) {
+    const dir = dirname(settingsPath);
+    mkdirSync(dir, { recursive: true });
+    writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + '\n');
+  }
+
+  return { added, total: settings.permissions.allow.length };
+}
+
+async function promptPermissions() {
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  return new Promise((resolve) => {
+    console.log(`\n  ${yellow('?')} Auto-configure Bash permissions for agents? (recommended)`);
+    console.log(`    ${dim('Adds required permissions to .claude/settings.local.json')}`);
+    rl.question('    [Y/n] ', (answer) => {
+      rl.close();
+      const choice = answer.trim().toLowerCase();
+      resolve(choice === '' || choice === 'y' || choice === 'yes');
+    });
+  });
+}
+
+export async function init(isGlobal, lang) {
   const exampleTag = lang === 'ko'
     ? `[추가기능] Add a hello world feature`
     : `[new-feature] Add a hello world feature`;
@@ -98,6 +148,18 @@ export function init(isGlobal, lang) {
     console.log(`    ${dim('-')} works/ directory already exists`);
   }
 
+  const wantPermissions = await promptPermissions();
+  if (wantPermissions) {
+    const { added, total } = mergePermissions(projectDir);
+    if (added > 0) {
+      console.log(`    ${green('✓')} ${added} permissions added to .claude/settings.local.json (total: ${total})`);
+    } else {
+      console.log(`    ${dim('-')} All permissions already configured (${total})`);
+    }
+  } else {
+    console.log(`    ${dim('-')} Skipped permission setup`);
+  }
+
   console.log(`\n  ${dim('Next steps:')}`);
   console.log(`    1. Run ${dim("'claude'")} to start Claude Code`);
   console.log(`    2. Type: ${dim(exampleTag)}\n`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "uctm",
-  "version": "1.3.0",
+  "version": "1.4.0",
   "description": "Universal Claude Task Manager — SDD-based task pipeline subagent system for Claude Code CLI",
   "type": "module",
   "bin": {
@@ -9,8 +9,7 @@
   "files": [
     "bin/",
     "lib/",
-    "agents/ko/",
-    "agents/en/",
+    "agents/",
     ".agent/"
   ],
   "engines": {