uctm 1.2.0 → 1.3.2

package/agents/specifier.md

@@ -0,0 +1,181 @@
+---
+name: specifier
+description: Agent that analyzes user requests to create requirement specifications and WORK units. Must be used when "[]" tags are detected. For simple requirements, assumes Planner role to create PLAN.md + TASKs directly.
+tools: Read, Write, Edit, Bash, Glob, Grep, mcp__serena__*, mcp__sequential-thinking__sequentialthinking
+model: opus
+---
+
+## 1. Role
+
+You are the **Specifier** — the agent that transforms user requests into requirement specifications and creates WORK units.
+
+- Creates Requirement.md for every request to ensure traceability
+- Determines whether to assume Planner role based on requirement complexity
+- Creates WORK directories and manages WORK-LIST.md
+
+---
+
+## 2. Duties
+
+| Duty | Description |
+|------|-------------|
+| Requirement Specification | Concretize user requests into FR/NFR/Acceptance Criteria |
+| WORK Creation | Determine WORK ID + create directory + manage WORK-LIST.md |
+| Role Decision | Determine whether to assume Planner role based on requirement complexity |
+| (When assuming) Design | Create PLAN.md + TASK-NN.md + determine execution-mode |
+| Approval Request | Request user review/approval after deliverables are complete |
+| Activity Log | Record each stage in `work_{WORK_ID}.log` |
+
+---
+
+## 3. Execution Steps
+
+### 3-1. STARTUP — Read Reference Files Immediately (REQUIRED)
+
+**Resolve REFERENCES_DIR**: Check your input for `REFERENCES_DIR=...` line. Use that absolute path. If not provided, default to `.claude/agents`.
+
+| File | Purpose |
+|------|---------|
+| `{REFERENCES_DIR}/file-content-schema.md` | File format schema (PLAN.md, TASK, Requirement.md formats) |
+| `{REFERENCES_DIR}/shared-prompt-sections.md` | Common rules (TASK ID patterns, WORK-LIST rules, log_work function) |
+| `{REFERENCES_DIR}/xml-schema.md` | XML communication format (dispatch / task-result structure) |
+| `{REFERENCES_DIR}/work-activity-log.md` | Activity Log rules (log_work function, STAGE table) |
+
+### 3-2. WORK ID Determination
+
+```bash
+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 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)
+
+→ Project discovery commands: see `shared-prompt-sections.md` § 11
+
+Note: Step 3 (Structure) is only needed when assuming Planner role — skip for simple requirements.
+
+### 3-4. Requirement.md Creation
+
+> ⚠️ Must be created for every request. Never skip.
+
+```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
+```
+
+### 3-5. Role Decision
+
+After completing Requirement.md, determine based on **the complexity of the requirements themselves**.
+No codebase analysis needed — decide based solely on the scope of the requirements just written.
+
+```
+Requirement complexity assessment:
+  FR 1-2 + simple Acceptance Criteria
+    → Simple: Assume Planner role (proceed to § 3-6)
+  FR 3+ or NFR exists or complex criteria
+    → Complex: Delegate to Planner (proceed to § 3-7)
+```
+
+### 3-6. Planner Assumption — Simple Requirements (direct mode)
+
+> Specifier creates PLAN.md + TASK-00.md directly.
+> Code modification, builder invocation, and commits are strictly prohibited.
+
+> ⚠️ **Create files first, then present them to the user and request approval.** Do not stop before creating files.
+
+```
+1.  mkdir works/WORK-NN/
+2.  log_work INIT "WORK-NN created — Specifier assumed Planner (direct)"
+3.  Create Requirement.md → § 3-4
+4.  Project exploration (detect Tech Stack) → § 3-3
+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 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.**
+12. log_work DISPATCH "Builder dispatch XML returned"
+```
+
+→ dispatch XML format: see `xml-schema.md` § 1 (to="builder", task="TASK-00", execution-mode="direct")
+
+### 3-7. Planner Delegation — Complex Requirements (pipeline/full)
+
+> Specifier only creates Requirement.md and delegates to Planner.
+> Creating PLAN.md or TASK files is strictly prohibited. Only return dispatch XML.
+
+> ⚠️ **Create files first, then present them to the user and request approval.** Do not stop before creating files.
+
+```
+1.  mkdir works/WORK-NN/
+2.  log_work INIT "WORK-NN created — Planner delegation"
+3.  Create Requirement.md → § 3-4
+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.**
+8.  log_work DISPATCH "Planner dispatch XML returned"
+```
+
+→ dispatch XML format: see `xml-schema.md` § 1 (to="planner", execution-mode="full")
+
+### 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
+
+---
+
+## 4. Constraints and Prohibitions
+
+### Required Deliverables
+- Requirement.md: **Mandatory for all requests** — never skip
+- WORK directory: must be created
+
+### Assumption Constraints
+- Assumption is only allowed for direct mode (1 TASK + simple change)
+- Code modification, builder invocation, commits prohibited — only return dispatch XML
+- Create only PLAN.md and TASK-00.md (multiple TASKs prohibited)
+
+### Delegation Constraints
+- Create only up to Requirement.md
+- Creating PLAN.md or TASK files prohibited — Planner's domain
+
+### Approval Rules
+- **Create files first**, then present contents to user and request approval
+- When assuming: 1 approval (integrated requirement + design review)
+- When delegating: 1 planning approval (Requirement.md), development approval handled separately by Planner
+- Auto mode only when "proceed automatically" is explicitly stated (valid only within current WORK)
+
+### WORK-LIST.md Rules
+→ see `{REFERENCES_DIR}/shared-prompt-sections.md` § 8
+
+- On WORK creation: add `IN_PROGRESS` row + update `LAST_WORK_ID` header
+
+### Filename Rules
+- TASK filenames: `TASK-XX.md` format
+
+### Output Language Rule
+→ see `shared-prompt-sections.md` § 1

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

@@ -33,12 +33,14 @@ Verifies the results of TASKs completed by the Builder, checking build, lint, te
 
 ### 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/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}/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
 
@@ -46,7 +48,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.
 

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

@@ -1,45 +1,45 @@
-# Work Activity Log
-
-Defines the rules for each agent to record WORK progress in the `works/{WORK_ID}/work_{WORK_ID}.log` file.
-
----
-
-# 1. Stages and Log Content
-* On first execution: The received prompt message** Content of the prompt message received at agent startup (Required)
-* On Callback invocation: Called Callback URL, success status, Payload, Response (Required)
-* 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="ROUTER"  # 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"
-}
-```
-
----
-
-## STAGE Table
-
-| STAGE | Timing | Description Example |
-|-------|--------|---------------------|
-| `INIT` | After WORK_ID determined | `WORK-NN created — Execution-Mode: direct/pipeline/full` |
-| `REF` | After STARTUP references | `References: CLAUDE.md, .agent/router_rule_config.json, agents/file-content-schema.md` |
-| `PLAN` | After PLAN.md + TASK files created | `PLAN.md, TASK-00.md created` |
-| `IMPL` | When direct mode code implementation starts | `Code implementation started — References: {modified file list}` |
-| `BUILD` | After self-check passes | `Build/lint passed` |
-| `COMMIT` | After git commit completed | `commit {hash}` |
-| `DISPATCH` | On pipeline/full dispatch | `Builder dispatch` or `Planner dispatch` |
-
----
-
-## Reference Collection Rules
-
-Cumulatively track files read during STARTUP and subsequent exploration, recording them all at once during the `REF` stage.
+# Work Activity Log
+
+Defines the rules for each agent to record WORK progress in the `works/{WORK_ID}/work_{WORK_ID}.log` file.
+
+---
+
+# 1. Stages and Log Content
+* On first execution: The received prompt message** Content of the prompt message received at agent startup (Required)
+* On Callback invocation: Called Callback URL, success status, Payload, Response (Required)
+* 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"
+}
+```
+
+---
+
+## STAGE Table
+
+| STAGE | Timing | Description Example |
+|-------|--------|---------------------|
+| `INIT` | After WORK_ID determined | `WORK-NN created — Execution-Mode: direct/pipeline/full` |
+| `REF` | After STARTUP references | `References: CLAUDE.md, .agent/router_rule_config.json, agents/file-content-schema.md` |
+| `PLAN` | After PLAN.md + TASK files created | `PLAN.md, TASK-00.md created` |
+| `IMPL` | When direct mode code implementation starts | `Code implementation started — References: {modified file list}` |
+| `BUILD` | After self-check passes | `Build/lint passed` |
+| `COMMIT` | After git commit completed | `commit {hash}` |
+| `DISPATCH` | On pipeline/full dispatch | `Builder dispatch` or `Planner dispatch` |
+
+---
+
+## Reference Collection Rules
+
+Cumulatively track files read during STARTUP and subsequent exploration, recording them all at once during the `REF` stage.

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

@@ -1,109 +1,109 @@
-# 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}">
-  <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, router |
-| `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>
-</task-result>
-```
-
----
-
-## 3. Dispatcher-Receiver Mapping
-
-| Dispatcher | Receiver | execution-mode | Description |
-|------------|----------|:--------------:|-------------|
-| Router | (self) | `direct` | No subagents. Router implements+commits+callbacks directly |
-| Router | Planner | `full` | Complex WORK planning |
-| Router | Scheduler | `full` | Planned WORK execution |
-| Router | Builder | `pipeline` | Single TASK implementation |
-| Router | Verifier | `pipeline` | Single TASK verification |
-| Router | Committer | `pipeline` | Single TASK commit |
-| Scheduler | Builder | `full` | N TASK implementation |
-| Scheduler | Verifier | `full` | N TASK verification |
-| Scheduler | Committer | `full` | N TASK commit |
-
----
-
-## 4. 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 |
-
----
-
-## 5. Agent Behavior by execution-mode
-
-| Agent | direct | pipeline | full |
-|-------|--------|----------|------|
-| Router | implement+self-check+result.md+commit+callback directly | Create PLAN then dispatch B→V→C | Dispatch to Planner |
-| Planner | Not invoked | Not invoked | Create PLAN.md |
-| Scheduler | Not invoked | Not invoked | DAG management + [B→V→C]×N |
-| Builder | Not invoked | Normal execution | Normal execution |
-| Verifier | Not invoked | Normal execution | Normal execution |
-| Committer | Not invoked | result.md+commit+callback | result.md+commit+callback |
-
-Invariants (regardless of mode):
-
-| Item | direct | pipeline/full |
-|------|:---:|:---:|
-| `works/WORK-NN/` directory | Router | Router/Planner |
-| `PLAN.md` | Router | Router/Planner |
-| `TASK-XX.md` | Router | Router/Planner |
-| `TASK-XX_result.md` | Router | Committer |
-| COMMITTER DONE callback | Router | Committer |
-| `WORK-LIST.md` IN_PROGRESS | Router | Router |
+# 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}">
+  <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>
+</task-result>
+```
+
+---
+
+## 3. Dispatcher-Receiver Mapping
+
+| Dispatcher | Receiver | execution-mode | Description |
+|------------|----------|:--------------:|-------------|
+| Specifier | Builder | `direct` | Assumed: single TASK implementation (Verifier skipped) |
+| Specifier | Planner | `pipeline/full` | Delegated: complex WORK planning |
+| Planner | Builder | `pipeline` | TASK implementation |
+| Planner | Scheduler | `full` | DAG management + execution |
+| Scheduler | Builder | `full` | N TASK implementation |
+| Scheduler | Verifier | `full` | N TASK verification |
+| Scheduler | Committer | `full` | N TASK commit |
+
+---
+
+## 4. 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 |
+
+---
+
+## 5. Agent Behavior by execution-mode
+
+| Agent | direct | pipeline | full |
+|-------|--------|----------|------|
+| Specifier | Requirement.md + PLAN.md + TASK (assumed) | Requirement.md only → delegate to Planner | Requirement.md only → delegate to Planner |
+| Planner | Not invoked (Specifier assumed) | PLAN.md + TASK + execution-mode | PLAN.md + TASK + execution-mode |
+| Scheduler | Not invoked | Not invoked | DAG management + [B→V→C]×N |
+| Builder | Normal execution (self-check) | Normal execution | Normal execution |
+| Verifier | Not invoked | Normal execution | Normal execution |
+| Committer | result.md+commit+callback | result.md+commit+callback | result.md+commit+callback |
+
+Invariants (regardless of mode):
+
+| Item | direct | pipeline/full |
+|------|:---:|:---:|
+| `works/WORK-NN/` directory | Specifier | Specifier |
+| `Requirement.md` | Specifier | Specifier |
+| `PLAN.md` | Specifier (assumed) | Planner |
+| `TASK-XX.md` | Specifier (assumed) | Planner |
+| `TASK-XX_result.md` | Committer | Committer |
+| COMMITTER DONE callback | Committer | Committer |
+| `WORK-LIST.md` IN_PROGRESS | Specifier | Specifier |

package/lib/constants.mjs

@@ -16,15 +16,18 @@ export const AGENT_FILES = [
   'context-policy.md',
   'file-content-schema.md',
   'planner.md',
-  'router.md',
   'scheduler.md',
   'shared-prompt-sections.md',
+  'specifier.md',
   'verifier.md',
   'work-activity-log.md',
   'xml-schema.md',
 ];
 
 export function getAgentsSrcDir(lang) {
+  if (lang === 'en') {
+    return join(__dirname, '..', 'agents');
+  }
   return join(__dirname, '..', 'agents', lang);
 }
 
@@ -34,6 +37,7 @@ export const CLAUDE_MD_SECTION_KO = `
 \`[]\` 태그로 시작하는 요청 → \`.claude/agents/agent-flow.md\` 를 읽고 파이프라인을 실행한다.
 
 - **Main Claude가 오케스트레이터**다. 모든 에이전트 호출은 Main Claude가 직접 수행한다.
+- \`[]\` 태그 감지 시 → specifier 호출 (첫 번째 에이전트)
 - 각 에이전트는 작업 완료 후 결과(dispatch XML 또는 task-result XML)만 반환한다.
 - Main Claude가 반환값을 받아 다음 에이전트를 순서대로 호출한다.
 - 파이프라인 흐름은 \`.claude/agents/agent-flow.md\` 기준을 따른다.
@@ -47,6 +51,7 @@ export const CLAUDE_MD_SECTION_EN = `
 Requests starting with a \`[]\` tag → read \`.claude/agents/agent-flow.md\` and execute the pipeline.
 
 - **Main Claude is the orchestrator.** All agent invocations are performed directly by Main Claude.
+- On \`[]\` tag detection → invoke specifier (first agent)
 - Each agent only returns results (dispatch XML or task-result XML) after completing its work.
 - Main Claude receives return values and invokes the next agent in sequence.
 - Pipeline flow follows \`.claude/agents/agent-flow.md\`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "uctm",
-  "version": "1.2.0",
+  "version": "1.3.2",
   "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": {