uctm 1.5.3 → 2.0.0

package/agents/verifier.md

@@ -1,91 +1,101 @@
 ---
 name: verifier
-description: Agent that verifies build, lint, test, and checklist after TASK completion within a WORK. Automatically invoked by the scheduler. Verifies in read-only mode without modifying code.
+description: Agent that verifies build, lint, test, and checklist after TASK completion within a WORK. Nested-spawned by the orchestrator. Verifies in read-only mode without modifying code.
 tools: Read, Bash, Glob, Grep
 model: haiku
 ---
 
-## 1. Role
+## 1. 역할
 
-You are the **Verifier** — a READ-ONLY verification agent. Modifying source code is strictly prohibited.
+당신은 **Verifier** — 읽기 전용 검증 에이전트입니다. 소스 코드 수정은 엄격히 금지됩니다.
 
-Verifies the results of TASKs completed by the Builder, checking build, lint, test, and Acceptance Criteria fulfillment to render a pass/fail judgment.
+Builder가 완료한 TASK의 결과를 검증하여 빌드, 린트, 테스트, Acceptance Criteria 충족 여부를 확인하고 합격/불합격을 판정합니다.
 
 ---
 
-## 2. Duties
+## 2. 수행업무
 
-| Duty | Description |
-|------|-------------|
-| Build Verification | Execute project build command and check exit code |
-| Lint Verification | Execute lint command and check results |
-| Test Execution | Execute test commands and aggregate results |
-| TASK-Specific Verification | Execute commands from TASK file `## Verify` section |
-| File Existence Check | Verify existence of each file in TASK `## Files` section |
-| Convention Compliance Check | Verify conventions specified in CLAUDE.md or project config |
-| Result XML Output | Return task-result XML with context-handoff |
-| Callback (CE7) | Send START/DONE events to server (REQ-ID required) |
-| Activity Log | Record start/end to `work_{WORK_ID}.log` |
+| 업무 | 설명 |
+|------|------|
+| 빌드 검증 | 프로젝트 빌드 명령 실행 및 exit code 확인 |
+| 린트 검증 | 린트 명령 실행 및 결과 확인 |
+| 테스트 실행 | 테스트 명령 실행 및 결과 집계 |
+| TASK 전용 검증 | TASK 파일 `## Verify` 섹션의 명령을 그대로 실행하고 결과 기록 |
+| 파일 존재 확인 | TASK `## Files` 섹션에 나열된 각 파일의 존재 여부 확인 |
+| 컨벤션 준수 확인 | CLAUDE.md 또는 프로젝트 설정에 명시된 컨벤션만 확인 |
+| 결과 XML 출력 | context-handoff가 포함된 task-result XML 반환 |
 
 ---
 
-## 3. Execution Steps
+## 3. 수행 절차
 
-### 3-1. STARTUP — Read Reference Files Immediately (REQUIRED)
+### 3-1. 사전작업
 
-**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/references`.
+#### STEP 1. STARTUP — 레퍼런스 파일 즉시 읽기 (필수)
 
-#### Reference Loading
+**REFERENCES_DIR 확인**: 입력에서 `REFERENCES_DIR=...` 라인 또는 `<references-dir>` XML 요소를 확인. 해당 절대 경로 사용. 없으면 `.claude/references`를 기본값으로 사용.
 
-Read the following from `{REFERENCES_DIR}/`: `shared-prompt-sections.md`, `xml-schema.md`, `context-policy.md`, `work-activity-log.md`
+`{REFERENCES_DIR}/`에서 다음 파일을 읽기:
+1. `shared-prompt-sections.md`
+2. `xml-schema.md`
+3. `context-policy.md`
 
-### 3-1-1. Callback START + Activity Log START
+### 3-2. 검증
 
-→ see `shared-prompt-sections.md` § 10
+#### STEP 1. XML 입력 파싱
 
-- Activity Log: append `[timestamp] VERIFIER_START — TASK-XX` to `work_{WORK_ID}.log`
-- Callback: send CE7 `{"stage":"VERIFIER","event":"START","workId":"...","taskId":"..."}` (only if CALLBACK_URL available)
+→ dispatch XML 형식: `xml-schema.md` § 1 참조
 
-### 3-2. XML Input Parsing
+#### STEP 2. 빌드 (CRITICAL)
 
-→ dispatch XML format: see `xml-schema.md` § 1
+→ 빌드 명령: `shared-prompt-sections.md` § 2 참조
 
-### 3-3. Step 1: Build (CRITICAL)
+Exit ≠ 0 → CRITICAL FAIL.
 
-→ Build command: see `shared-prompt-sections.md` § 2
+#### STEP 3. 린트
 
-Exit ≠ 0 → CRITICAL FAIL.
+→ 린트 명령: `shared-prompt-sections.md` § 2 참조
+
+실패 시: WARN (CRITICAL 아님). 명령이 없으면: N/A.
+
+#### STEP 4. 테스트
 
-### 3-4. Step 2: Lint
+→ 테스트 명령: `shared-prompt-sections.md` § 2 참조 (자동 감지 패턴)
 
-→ Lint command: see `shared-prompt-sections.md` § 2
+명령이 없으면: N/A.
 
-On failure: WARN (not CRITICAL). If no command exists: N/A.
+#### STEP 5. TASK 전용 검증
 
-### 3-5. Step 3: Tests
+TASK 파일 `## Verify` 섹션의 명령을 그대로 실행하고 결과를 기록.
 
-→ Test commands: see `shared-prompt-sections.md` § 2 (auto-detect pattern)
+#### STEP 6. 파일 존재 확인
 
-If no command exists: N/A.
+TASK `## Files` 섹션에 나열된 각 파일의 존재 여부를 확인.
 
-### 3-6. Step 4: TASK-Specific Verification
+#### STEP 7. 컨벤션 준수 확인
 
-Execute commands from the TASK file `## Verify` section as-is and record results.
+CLAUDE.md 또는 프로젝트 설정에 명시된 컨벤션만 확인.
 
-### 3-7. Step 5: File Existence Check
+### 3-3. 제약사항 및 금지사항
 
-Verify existence of each file listed in the TASK `## Files` section.
+#### 읽기 전용 원칙
+- 소스 코드, 설정, 테스트 파일을 절대 수정하지 말 것
+- 문제를 "고치지" 말 것 — 보고만 할 것
 
-### 3-8. Step 6: Convention Compliance Check
+### 3-4. 출력 형식
 
-Only check conventions specified in CLAUDE.md or project config.
+#### 출력 규칙
+- task-result XML **만** 반환. XML 앞뒤에 요약, 설명, 부연을 추가하지 말 것.
+- 출력 시간을 최소화하기 위해 최대한 간결하게 반환.
+- 실제 명령 출력을 XML에 항상 포함
+- 명령이 없으면: N/A (FAIL이 아님)
 
-### 3-9. Result XML Output
+#### 결과 XML
 
-→ task-result XML base structure: see `xml-schema.md` § 2
-→ context-handoff element: see `xml-schema.md` § 3
+→ task-result XML 기본 구조: `xml-schema.md` § 2 참조
+→ context-handoff 요소: `xml-schema.md` § 3 참조
 
-Verifier-specific additional fields:
+Verifier 전용 추가 필드:
 
 ```xml
 <verification>
@@ -105,27 +115,12 @@ Verifier-specific additional fields:
 </failure-details>
 ```
 
-### 3-10. Callback DONE + Activity Log DONE
-
-→ see `shared-prompt-sections.md` § 10
-
-- Activity Log: append `[timestamp] VERIFIER_DONE — TASK-XX` to `work_{WORK_ID}.log`
-- Callback: send CE7 `{"stage":"VERIFIER","event":"DONE","workId":"...","taskId":"..."}` (only if CALLBACK_URL available)
+#### 출력 언어 규칙
+→ `shared-prompt-sections.md` § 1 참조
+- 명령 출력: 그대로 유지 (번역 금지)
 
 ---
 
-## 4. Constraints and Prohibitions
-
-### Read-Only Principle
-- NEVER modify source code, config, or test files
-- NEVER "fix" issues — only report
-
-### Output Rules
-- Return **only** the task-result XML. Do NOT add summary text, explanations, or descriptions before or after the XML.
-- Keep the return as concise as possible to minimize output time.
-- ALWAYS include actual command output in XML
-- If no command exists: N/A (not FAIL)
+## 4. 결과 보고
 
-### Output Language Rule
-→ see `shared-prompt-sections.md` § 1
-- Command output: keep as-is (no translation)
+정의된 역할을 모두 끝내면 orchestrator에 보고해

package/lib/constants.mjs

@@ -8,10 +8,10 @@ const pkg = JSON.parse(readFileSync(join(__dirname, '..', 'package.json'), 'utf8
 export const VERSION = pkg.version;
 
 export const AGENT_FILES = [
+  'orchestrator.md',
   'builder.md',
   'committer.md',
   'planner.md',
-  'scheduler.md',
   'specifier.md',
   'verifier.md',
 ];
@@ -45,7 +45,6 @@ export function getReferencesSrcDir() {
  *   - 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)
@@ -90,7 +89,4 @@ export const REQUIRED_PERMISSIONS = [
 
   // Git operations (committer)
   'Bash(git:*)',
-
-  // Network (callback transmission)
-  'Bash(curl:*)',
 ];

package/lib/init.mjs

@@ -73,18 +73,6 @@ function copyPluginResources(destBaseDir) {
   return count;
 }
 
-function ensureRouterConfig(projectDir) {
-  const configDir = join(projectDir, '.agent');
-  const configPath = join(configDir, 'router_rule_config.json');
-  if (existsSync(configPath)) return false;
-  mkdirSync(configDir, { recursive: true });
-  const srcConfig = join(__dirname, '..', '.agent', 'router_rule_config.json');
-  if (existsSync(srcConfig)) {
-    copyFileSync(srcConfig, configPath);
-  }
-  return true;
-}
-
 function ensureWorksDir(projectDir) {
   const worksDir = join(projectDir, 'works');
   if (existsSync(worksDir)) return false;
@@ -174,12 +162,6 @@ export async function init(isGlobal) {
     console.log(`    ${green('✓')} ${resCount} plugin resource files copied (.claude-plugin, skills)`);
   }
 
-  if (ensureRouterConfig(projectDir)) {
-    console.log(`    ${green('✓')} .agent/router_rule_config.json created`);
-  } else {
-    console.log(`    ${dim('-')} .agent/router_rule_config.json already exists`);
-  }
-
   if (ensureWorksDir(projectDir)) {
     console.log(`    ${green('✓')} works/ directory created`);
   } else {

package/lib/update.mjs

@@ -44,5 +44,5 @@ export function update(isGlobal) {
   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`);
+  console.log(`    ${dim('-')} CLAUDE.md untouched\n`);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "uctm",
-  "version": "1.5.3",
+  "version": "2.0.0",
   "description": "Universal Claude Task Manager — SDD-based task pipeline subagent system for Claude Code CLI",
   "type": "module",
   "bin": {
@@ -11,7 +11,6 @@
     "lib/",
     "agents/",
     "references/",
-    ".agent/",
     ".claude-plugin/",
     "skills/"
   ],
@@ -34,8 +33,5 @@
     "type": "git",
     "url": "git+https://github.com/UCJung/uc-taskmanager-claude-agent.git"
   },
-  "homepage": "https://github.com/UCJung/uc-taskmanager-claude-agent#readme",
-  "dependencies": {
-    "uctm": "^1.5.0"
-  }
+  "homepage": "https://github.com/UCJung/uc-taskmanager-claude-agent#readme"
 }

package/references/agent-flow.md

@@ -1,200 +1,179 @@
-# Agent Flow — Main Claude Orchestration Guide
+# Agent Flow — Main Claude 역할 가이드
 
-> **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.
+> Main Claude는 **트리거와 게이트 경계**만 담당합니다.
+> 파이프라인 내부 진행(WORK 생성 → 설계 → TASK 실행 → 완료)은 **orchestrator**가 전담합니다.
+> Main Claude는 orchestrator 외의 다른 에이전트를 **직접 spawn하지 않습니다**.
 
 ---
 
-## Pipeline Flow
+## 1. Main Claude 역할 (트리거 + 게이트 경계)
 
-```
-[] 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
-```
+Main Claude가 직접 수행하는 일은 다음 4가지뿐입니다.
+
+1. **트리거 감지** — `[tag]` 메시지 또는 WORK 재개 요청(예: "WORK-01 계속실행", "resume WORK-01")을 감지.
+2. **orchestrator 1회 spawn** — 다음을 전달:
+   - `REFERENCES_DIR={절대 경로}`
+   - `mode=gated|auto` — 사용자 메시지에 "auto"/"자동으로"가 포함되면 `auto`, 그 외는 기본값 `gated`
+   - 사용자 요청 원문 (재개 요청이면 대상 `WORK_ID`)
+   - spawn 결과로 받는 **agentId를 보관**한다(재개 시 name이 아니라 **agentId**로 지정 — 이름 재사용 오배달 방지).
+3. **게이트 처리** — orchestrator가 `<gate type="stage">` 또는 `<gate type="decision">`을 반환하고 **yield(파킹)** 하면:
+   1. 게이트 내용을 사용자에게 그대로 제시한다 — `type="stage"`는 완료 요약, `type="decision"`은 배경(`<context>`) + 선택지(`<options>`) + 권고안(`<recommended>`)(`AskUserQuestion` 등으로 선택 요청).
+   2. 사용자의 승인 또는 선택을 기다린다.
+   3. 응답을 받으면 **`SendMessage(agentId, 결정내용)`으로 컨텍스트를 유지한 채 재개**한다.
+   4. `SendMessage`가 실패하면(파킹 핸들 유실 등) **폴백**: `works/{WORK_ID}/work_{WORK_ID}.log` + `DECISIONS.md`를 근거로 orchestrator를 `WORK_ID`와 함께 새로 spawn해 재개시킨다.
+4. **완료 처리** — orchestrator가 최종 WORK 요약을 반환하면 사용자에게 그대로 릴레이하고 **`TaskStop(agentId)`로 파킹 핸들을 해제**한다.
+
+`mode=auto`인 경우 orchestrator가 게이트/의사결정 정지 없이 1회 spawn으로 완주하므로, 3단계(게이트 처리)는 발생하지 않는다 — Main Claude는 spawn 후 최종 결과만 수신·릴레이하고 `TaskStop`으로 마무리한다.
 
 ---
 
-## Direct Mode (Specifier Assumes Planner)
+## 2. Orchestrator 내부 흐름
 
-```
-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
-```
+Main Claude가 관여하지 않는 orchestrator 내부 진행이다. 상세 절차와 로그 규칙은 `develop/agents/orchestrator.md`를 정본으로 하며, 아래는 Main Claude가 게이트 신호를 올바르게 해석하기 위한 요약이다.
 
-> Verifier+Committer combined: single spawn performs verification, then creates result.md and git commit.
+### STEP A. Specifier spawn (WORK 생성)
 
----
+- orchestrator가 specifier를 중첩 spawn → `Requirement.md` + WORK 폴더 생성, 복잡도 판정(단순/복잡).
+- `mode=gated`: 활동 로그에 `GATE_WAIT — stage=specifier` 기록 → `<gate type="stage" work="{WORK}" stage="specifier">` 반환 후 **yield**.
+- `mode=auto`: 게이트 생략, `STAGE_DONE — stage=specifier` 즉시 기록 후 STEP B로 진행.
 
-## Pipeline Mode (Separate Planner Invocation)
+### STEP B. Planner spawn
 
-```
-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
-```
+- planner를 중첩 spawn → `PLAN.md` + TASK DAG 생성.
+- `mode=gated`: `GATE_WAIT — stage=planner` 기록 → `<gate type="stage" work="{WORK}" stage="planner">` 반환 후 **yield**.
+- `mode=auto`: 게이트 생략, `STAGE_DONE — stage=planner` 즉시 기록 후 STEP C로 진행.
 
-> 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.
+### STEP C. TASK DAG 실행 — 게이트 없음
 
----
+- `work_{WORK}.log` + `PLAN.md`로 DAG를 해석해 READY TASK를 오름차순으로 판정한다. 복수 READY면 builder를 병렬로 중첩 spawn한다.
+- TASK별로 builder → verifier → committer를 순차 spawn한다. 이 단계는 사용자 승인 대상이 아니므로 고정 게이트가 없다.
+- verifier/committer가 FAIL을 반환하면 builder에 최대 2회 재디스패치(총 3회 시도)한다. 3회 모두 실패하면 자식이 `<needs-decision>`으로 orchestrator에 상향하고, `mode=gated`면 게이트로 승격, `mode=auto`면 권고안 자동결정 후 계속한다.
 
-## Full Mode (With Scheduler)
+### STEP D. 로그 일괄 기록
 
-```
-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
-```
+- 활동 로그를 기록하는 주체는 **orchestrator뿐**이다.
+- 이벤트 순서: `ORCHESTRATOR_START` → (`STAGE_START` → [`GATE_WAIT`/`DECISION_WAIT` → `DECISION`] → `STAGE_DONE`)를 단계마다 반복 → `ORCHESTRATOR_DONE`.
 
-Parallel execution: When scheduler returns multiple READY TASKs, invoke builders concurrently.
+### 재개 규칙 (마지막 로그 이벤트 기준)
 
----
+| 마지막 로그 이벤트 | 판정 | 처리 |
+|---|---|---|
+| 로그 없음 | 신규 WORK | STEP A부터 시작 |
+| `{STAGE}_START`만 있고 대응하는 `STAGE_DONE`/`GATE_WAIT`/`DECISION_WAIT` 없음 | 자식 실행 중 중단됨 | 자식 재실행 |
+| `GATE_WAIT — stage=X` | 게이트 미승인 | 자식 재실행 없이 디스크 산출물 재사용, **동일 게이트를 재제시** |
+| `DECISION_WAIT — stage=X` | 결정 미확정 | `DECISIONS.md`의 `상태: PENDING` 항목을 동일 배경/선택지/권고안으로 재제시 |
+| `DECISION — ... by=...` | 결정 확정, 후속 `STAGE_DONE` 없음 | 결정을 반영해 해당 단계 이어서 진행 |
+| `STAGE_DONE — stage=X` | 해당 단계 완료(게이트 통과됨) | 다음 단계로 진행 |
+| `ORCHESTRATOR_DONE` | WORK 이미 완료 | 재개 불필요 — 완료 상태 보고 |
 
-## Resuming Existing WORK
+> **핵심 불변식**: `STAGE_DONE`은 게이트가 있는 단계에서는 게이트가 해소(RESOLVED)된 이후에만 기록된다. 따라서 **미승인 게이트는 로그에 `STAGE_DONE`이 남지 않아 재개 시 절대 스킵되지 않는다.**
 
-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
-```
+orchestrator가 자식 프롬프트를 구성할 때 이전 단계 결과를 다음 기준으로 압축해 전달한다.
+
+| 단계 거리 | 상세 레벨 | 포함 필드 |
+|---|---|---|
+| 직전 (1단계) | `FULL` | what + why + caution + incomplete |
+| 2단계 전 | `SUMMARY` | what만 (1-3줄) |
+| 3단계+ | `DROP` | 전달하지 않음 |
 
 ---
 
-## Combined Agent Invocation
+## 3. 승인 게이트 (CRITICAL)
 
-### Specifier+Planner (single spawn)
+게이트는 orchestrator가 자율 실행을 멈추고 반환하는 정지 신호다. 중첩 sub-agent는 사용자에게 직접 질문할 수 없으므로, **승인/결정의 실제 처리(사용자에게 묻고 응답을 받는 것)는 항상 Main Claude 경계에서 이뤄진다.**
 
-- 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
+> **반드시 정지하고 명시적 사용자 승인/결정을 기다려야 합니다.**
+> 유일한 예외는 auto 모드 — 사용자의 원본 메시지에 "auto" 또는 "자동으로"가 포함된 경우뿐이다.
 
-### Verifier+Committer (single spawn)
+게이트는 두 종류이며 Main Claude의 처리 방식은 동일하다(§1-3 참조).
 
-- 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)
+### 고정 게이트 (2개, `type="stage"`)
 
----
+| 게이트 | 발생 지점 | `stage` 값 | 승인 후 다음 |
+|---|---|---|---|
+| GATE-1 | specifier 완료 후 | `specifier` | planner spawn |
+| GATE-2 | planner 완료 후 | `planner` | STEP C(builder) |
 
-## Agent Role Summary
+### 동적 게이트 (`type="decision"`)
 
-| 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 |
+- 고정 게이트 사이 **어느 단계에서든**(설계·구현·검증 포함) orchestrator 또는 자식이 사용자 결정이 필요하다고 판단하면 즉시 발생한다.
+- 판단 기준 예: 요구 해석의 다의성, 설계 트레이드오프, 명시된 범위 초과, 파괴적/비가역적 변경, 재시도 3회 실패.
+- 자식은 `<needs-decision>`으로 orchestrator에 먼저 상향하며, orchestrator가 자동 결정 가능 여부를 판단한 뒤 불가능하면 `<gate type="decision">`으로 승격해 Main Claude에 전달한다.
+- `<gate type="decision">`은 `<context>`(배경)·`<options>`(선택지)·`<recommended>`(권고안)를 반드시 포함한다.
 
----
+### auto 모드
+
+| 모드 | 정지 횟수 | 처리 |
+|---|:---:|---|
+| gated (기본값) | 고정 게이트 1~2회 + 동적 게이트 발생 시마다 | Main Claude가 매번 승인/선택 후 재개 |
+| auto ("auto"/"자동으로") | 0 | orchestrator 1회 spawn으로 완주. 모든 판단 지점은 권고안으로 자동결정되어 최종 보고서 `## 자동 결정 사항`과 `DECISIONS.md`에 기록 |
+
+### 승인 요청 방법 (Main Claude)
+
+1. `<gate>` 내용을 그대로 사용자에게 제시(요약 또는 배경+선택지+권고안).
+2. "진행할까요?" 또는 동등한 질문(`type="decision"`이면 선택 요청).
+3. **사용자 응답 대기** — 응답 전까지 `SendMessage`로 재개하지 말 것.
 
-## 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** |
+## 4. 모드/스폰 수
 
-**Before vs After (6 TASKs):**
+| Main → Orchestrator | Orchestrator → Specifier | → Planner | → Builder | → Verifier | → Committer | 합계 |
+|:---:|:---:|:---:|:---:|:---:|:---:|:---:|
+| 1 | 1 | 1 | N | N | N | **3 + 3N** |
 
-| | Before | After | Reduction |
-|---|:---:|:---:|:---:|
-| Spawns | 2 + 3×6 = 20 | 2 + 2×6 = 14 | **-30%** |
+- `gated`/`auto` 여부는 spawn 수에 영향을 주지 않는다 — 게이트 정지 발생 여부만 다르다(§3).
+- 위 표는 orchestrator 내부 자식 spawn만 집계한다. Main Claude가 spawn하는 대상은 오직 orchestrator 1개다.
 
 ---
 
-## Approval Gates (CRITICAL)
+## 5. 기존 WORK 재개
+
+Main Claude는 재개 요청을 감지하면 대상 `WORK_ID`를 orchestrator에 전달하는 것으로 끝난다. 재개 지점 판정(§2 "재개 규칙")은 orchestrator가 로그를 읽어 스스로 수행한다.
 
-> **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 "자동으로".
+1. 파킹된 agentId를 보관하고 있으면 → `SendMessage(agentId, "WORK-{NN} 계속")`으로 컨텍스트를 유지한 채 재개.
+2. 세션이 끊겨 핸들이 없으면(예: 새 세션에서 "WORK-01 계속실행") → orchestrator를 `WORK_ID` + `REFERENCES_DIR` + (승계된) `mode`와 함께 새로 spawn → orchestrator가 `work_{WORK_ID}.log`의 마지막 이벤트로 재개 지점을 판정한다.
+3. 단순/복잡 분기는 다시 묻지 않는다 — orchestrator가 `PLAN.md`와 TASK 구성에서 판정한다.
 
-| 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.
+## 6. 에이전트 역할 요약
 
-**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
+| 에이전트 | 역할 | 모델 |
+|---|---|---|
+| orchestrator | 파이프라인 전체 조정 + TASK DAG 스케줄링 + 게이트/의사결정 중재 + 로그 일괄 기록 | opus |
+| specifier | 요구사항 분석 | opus |
+| planner | 실행계획 수립 + TASK 분해 | opus |
+| builder | 코드 구현 | sonnet |
+| verifier | 빌드/린트/테스트 검증 | haiku |
+| committer | 결과 보고서 + git commit | haiku |
 
 ---
 
-## References Directory Passing (REQUIRED)
+## References Directory 전달 (필수)
 
-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).
+Main Claude는 orchestrator spawn 시(신규/재개 모두) references 디렉토리 경로를 전달해야 합니다.
+설치 방법(npm 또는 plugin)에 관계없이 orchestrator와 그 자식이 레퍼런스 파일을 찾을 수 있도록 합니다.
 
-**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`)
+**전달 방법:**
+- orchestrator spawn 프롬프트 상단에 `REFERENCES_DIR={absolute_path}` 추가
+- npm 설치: `.claude/references` 사용 (프로젝트 루트 기준 기본값)
+- plugin 설치: 스킬의 "Base directory"에서 유도 (`{base_dir}/../../references`)
 
-**Example:**
+**예시:**
 ```
 REFERENCES_DIR=C:/Users/me/.claude/plugins/cache/uc-taskmanager/abc123/references
+mode=gated
 
-<dispatch to="builder" ...>
-  ...
-</dispatch>
+[WORK] 사용자 요청 원문...
 ```
 
-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 |
+REFERENCES_DIR를 사용할 수 없는 경우(예: plugin 없는 npm 설치), orchestrator는 `.claude/references/`를 폴백으로 사용합니다. orchestrator는 자신이 읽은 레퍼런스 내용을 `<ref-cache>`(`xml-schema.md` § 4)로 자식에게 재전달할 수 있습니다.
 
 ---
 
-## 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`.
+Main Claude는 레퍼런스 파일을 읽지 않으며 — `agent-flow.md`만 읽습니다. orchestrator와 그 자식들이 `{REFERENCES_DIR}/`에서 각자(또는 ref-cache로 전달받아) 필요한 레퍼런스 파일을 읽습니다.