claude-code-workflow 7.2.15 → 7.2.16

package/.codex/skills/team-arch-opt/roles/analyzer/role.md

@@ -0,0 +1,78 @@
+---
+role: analyzer
+prefix: ANALYZE
+inner_loop: false
+message_types: [state_update]
+---
+
+# Architecture Analyzer
+
+Analyze codebase architecture to identify structural issues: dependency cycles, coupling/cohesion problems, layering violations, God Classes, code duplication, dead code, and API surface bloat. Produce quantified baseline metrics and a ranked architecture report.
+
+## Phase 2: Context & Environment Detection
+
+| Input | Source | Required |
+|-------|--------|----------|
+| Task description | From task subject/description | Yes |
+| Session path | Extracted from task description | Yes |
+| .msg/meta.json | <session>/wisdom/.msg/meta.json | No |
+
+1. Extract session path and target scope from task description
+2. Detect project type by scanning for framework markers:
+
+| Signal File | Project Type | Analysis Focus |
+|-------------|-------------|----------------|
+| package.json + React/Vue/Angular | Frontend | Component tree, prop drilling, state management, barrel exports |
+| package.json + Express/Fastify/NestJS | Backend Node | Service layer boundaries, middleware chains, DB access patterns |
+| Cargo.toml / go.mod / pom.xml | Native/JVM Backend | Module boundaries, trait/interface usage, dependency injection |
+| Mixed framework markers | Full-stack / Monorepo | Cross-package dependencies, shared types, API contracts |
+| CLI entry / bin/ directory | CLI Tool | Command structure, plugin architecture, configuration layering |
+| No detection | Generic | All architecture dimensions |
+
+3. Use `explore` CLI tool to map module structure, dependency graph, and layer boundaries within target scope
+4. Detect available analysis tools (linters, dependency analyzers, build tools)
+
+## Phase 3: Architecture Analysis
+
+Execute analysis based on detected project type:
+
+**Dependency analysis**:
+- Build import/require graph across modules
+- Detect circular dependencies (direct and transitive cycles)
+- Identify layering violations (e.g., UI importing from data layer, utils importing from domain)
+- Calculate fan-in/fan-out per module (high fan-out = fragile hub, high fan-in = tightly coupled)
+
+**Structural analysis**:
+- Identify God Classes / God Modules (> 500 LOC, > 10 public methods, too many responsibilities)
+- Calculate coupling metrics (afferent/efferent coupling per module)
+- Calculate cohesion metrics (LCOM -- Lack of Cohesion of Methods)
+- Detect code duplication (repeated logic blocks, copy-paste patterns)
+- Identify missing abstractions (repeated conditionals, switch-on-type patterns)
+
+**API surface analysis**:
+- Count exported symbols per module (export bloat detection)
+- Identify dead exports (exported but never imported elsewhere)
+- Detect dead code (unreachable functions, unused variables, orphan files)
+- Check for pattern inconsistencies (mixed naming conventions, inconsistent error handling)
+
+**All project types**:
+- Collect quantified architecture baseline metrics (dependency count, cycle count, coupling scores, LOC distribution)
+- Rank top 3-7 architecture issues by severity (Critical / High / Medium)
+- Record evidence: file paths, line numbers, measured values
+
+## Phase 4: Report Generation
+
+1. Write architecture baseline to `<session>/artifacts/architecture-baseline.json`:
+   - Module count, dependency count, cycle count, average coupling, average cohesion
+   - God Class candidates with LOC and method count
+   - Dead code file count, dead export count
+   - Timestamp and project type details
+
+2. Write architecture report to `<session>/artifacts/architecture-report.md`:
+   - Ranked list of architecture issues with severity, location (file:line or module), measured impact
+   - Issue categories: CYCLE, COUPLING, COHESION, GOD_CLASS, DUPLICATION, LAYER_VIOLATION, DEAD_CODE, API_BLOAT
+   - Evidence summary per issue
+   - Detected project type and analysis methods used
+
+3. Update `<session>/wisdom/.msg/meta.json` under `analyzer` namespace:
+   - Read existing -> merge `{ "analyzer": { project_type, issue_count, top_issue, scope, categories } }` -> write back

package/.codex/skills/team-arch-opt/roles/coordinator/commands/analyze.md

@@ -0,0 +1,57 @@
+# Analyze Task
+
+Parse user task -> detect architecture capabilities -> build dependency graph -> design roles.
+
+**CONSTRAINT**: Text-level analysis only. NO source code reading, NO codebase exploration.
+
+## Signal Detection
+
+| Keywords | Capability | Prefix |
+|----------|------------|--------|
+| analyze, scan, audit, map, identify | analyzer | ANALYZE |
+| design, plan, strategy, refactoring-plan | designer | DESIGN |
+| refactor, implement, fix, apply | refactorer | REFACTOR |
+| validate, build, test, verify, compile | validator | VALIDATE |
+| review, audit-code, quality, check-code | reviewer | REVIEW |
+
+## Dependency Graph
+
+Natural ordering tiers:
+- Tier 0: analyzer (knowledge gathering -- no dependencies)
+- Tier 1: designer (requires analyzer output)
+- Tier 2: refactorer (requires designer output)
+- Tier 3: validator, reviewer (validation requires refactored artifacts, can run in parallel)
+
+## Complexity Scoring
+
+| Factor | Points |
+|--------|--------|
+| Per capability | +1 |
+| Cross-domain refactoring | +2 |
+| Parallel branches requested | +1 per branch |
+| Serial depth > 3 | +1 |
+| Multiple targets (independent mode) | +2 |
+
+Results: 1-3 Low, 4-6 Medium, 7+ High
+
+## Role Minimization
+
+- Cap at 5 roles
+- Merge overlapping capabilities
+- Absorb trivial single-step roles
+
+## Output
+
+Write <session>/task-analysis.json:
+```json
+{
+  "task_description": "<original>",
+  "pipeline_type": "<single|fan-out|independent|auto>",
+  "capabilities": [{ "name": "<cap>", "prefix": "<PREFIX>", "keywords": ["..."] }],
+  "dependency_graph": { "<TASK-ID>": { "role": "<role>", "blockedBy": ["..."], "priority": "P0|P1|P2" } },
+  "roles": [{ "name": "<role>", "prefix": "<PREFIX>", "inner_loop": false }],
+  "complexity": { "score": 0, "level": "Low|Medium|High" },
+  "parallel_mode": "<auto|single|fan-out|independent>",
+  "max_branches": 5
+}
+```

package/.codex/skills/team-arch-opt/roles/coordinator/commands/dispatch.md

@@ -0,0 +1,287 @@
+# Command: Dispatch
+
+Create the architecture optimization task chain with correct dependencies and structured task descriptions. Supports single, fan-out, independent, and auto parallel modes.
+
+## Phase 2: Context Loading
+
+| Input | Source | Required |
+|-------|--------|----------|
+| User requirement | From coordinator Phase 1 | Yes |
+| Session folder | From coordinator Phase 2 | Yes |
+| Pipeline definition | From SKILL.md Pipeline Definitions | Yes |
+| Parallel mode | From tasks.json `parallel_mode` | Yes |
+| Max branches | From tasks.json `max_branches` | Yes |
+| Independent targets | From tasks.json `independent_targets` (independent mode only) | Conditional |
+
+1. Load user requirement and refactoring scope from tasks.json
+2. Load pipeline stage definitions from SKILL.md Task Metadata Registry
+3. Read `parallel_mode` and `max_branches` from tasks.json
+4. For `independent` mode: read `independent_targets` array from tasks.json
+
+## Phase 3: Task Chain Creation (Mode-Branched)
+
+### Task Entry Template
+
+Every task in tasks.json `tasks` object uses structured format:
+
+```json
+{
+  "<TASK-ID>": {
+    "title": "<concise title>",
+    "description": "PURPOSE: <what this task achieves> | Success: <measurable completion criteria>\nTASK:\n  - <step 1: specific action>\n  - <step 2: specific action>\n  - <step 3: specific action>\nCONTEXT:\n  - Session: <session-folder>\n  - Scope: <refactoring-scope>\n  - Branch: <branch-id or 'none'>\n  - Upstream artifacts: <artifact-1>, <artifact-2>\n  - Shared memory: <session>/wisdom/.msg/meta.json\nEXPECTED: <deliverable path> + <quality criteria>\nCONSTRAINTS: <scope limits, focus areas>\n---\nInnerLoop: <true|false>\nBranchId: <B01|A|none>",
+    "role": "<role-name>",
+    "prefix": "<PREFIX>",
+    "deps": ["<upstream-task-id>"],
+    "status": "pending",
+    "findings": null,
+    "error": null
+  }
+}
+```
+
+### Mode Router
+
+| Mode | Action |
+|------|--------|
+| `single` | Create 5 tasks (ANALYZE -> DESIGN -> REFACTOR -> VALIDATE + REVIEW) -- unchanged from linear pipeline |
+| `auto` | Create ANALYZE-001 + DESIGN-001 only. **Defer branch creation to CP-2.5** after design completes |
+| `fan-out` | Create ANALYZE-001 + DESIGN-001 only. **Defer branch creation to CP-2.5** after design completes |
+| `independent` | Create M complete pipelines immediately (one per target) |
+
+---
+
+### Single Mode Task Chain
+
+Create tasks in dependency order (backward compatible, unchanged):
+
+**ANALYZE-001** (analyzer, Stage 1):
+```json
+{
+  "ANALYZE-001": {
+    "title": "Analyze codebase architecture",
+    "description": "PURPOSE: Analyze codebase architecture to identify structural issues | Success: Baseline metrics captured, top 3-7 issues ranked by severity\nTASK:\n  - Detect project type and available analysis tools\n  - Execute analysis across relevant dimensions (dependencies, coupling, cohesion, layering, duplication, dead code)\n  - Collect baseline metrics and rank architecture issues by severity\nCONTEXT:\n  - Session: <session-folder>\n  - Scope: <refactoring-scope>\n  - Branch: none\n  - Shared memory: <session>/wisdom/.msg/meta.json\nEXPECTED: <session>/artifacts/architecture-baseline.json + <session>/artifacts/architecture-report.md | Quantified metrics with evidence\nCONSTRAINTS: Focus on <refactoring-scope> | Analyze before any changes\n---\nInnerLoop: false",
+    "role": "analyzer",
+    "prefix": "ANALYZE",
+    "deps": [],
+    "status": "pending",
+    "findings": null,
+    "error": null
+  }
+}
+```
+
+**DESIGN-001** (designer, Stage 2):
+```json
+{
+  "DESIGN-001": {
+    "title": "Design prioritized refactoring plan",
+    "description": "PURPOSE: Design prioritized refactoring plan from architecture analysis | Success: Actionable plan with measurable success criteria per refactoring\nTASK:\n  - Analyze architecture report and baseline metrics\n  - Select refactoring strategies per issue type\n  - Prioritize by impact/effort ratio, define success criteria\n  - Each refactoring MUST have a unique REFACTOR-ID (REFACTOR-001, REFACTOR-002, ...) with non-overlapping target files\nCONTEXT:\n  - Session: <session-folder>\n  - Scope: <refactoring-scope>\n  - Branch: none\n  - Upstream artifacts: architecture-baseline.json, architecture-report.md\n  - Shared memory: <session>/wisdom/.msg/meta.json\nEXPECTED: <session>/artifacts/refactoring-plan.md | Priority-ordered with structural improvement targets, discrete REFACTOR-IDs\nCONSTRAINTS: Focus on highest-impact refactorings | Risk assessment required | Non-overlapping file targets per REFACTOR-ID\n---\nInnerLoop: false",
+    "role": "designer",
+    "prefix": "DESIGN",
+    "deps": ["ANALYZE-001"],
+    "status": "pending",
+    "findings": null,
+    "error": null
+  }
+}
+```
+
+**REFACTOR-001** (refactorer, Stage 3):
+```json
+{
+  "REFACTOR-001": {
+    "title": "Implement refactoring changes per design plan",
+    "description": "PURPOSE: Implement refactoring changes per design plan | Success: All planned refactorings applied, code compiles, existing tests pass\nTASK:\n  - Load refactoring plan and identify target files\n  - Apply refactorings in priority order (P0 first)\n  - Update all import references for moved/renamed modules\n  - Validate changes compile and pass existing tests\nCONTEXT:\n  - Session: <session-folder>\n  - Scope: <refactoring-scope>\n  - Branch: none\n  - Upstream artifacts: refactoring-plan.md\n  - Shared memory: <session>/wisdom/.msg/meta.json\nEXPECTED: Modified source files + validation passing | Refactorings applied without regressions\nCONSTRAINTS: Preserve existing behavior | Update all references | Follow code conventions\n---\nInnerLoop: true",
+    "role": "refactorer",
+    "prefix": "REFACTOR",
+    "deps": ["DESIGN-001"],
+    "status": "pending",
+    "findings": null,
+    "error": null
+  }
+}
+```
+
+**VALIDATE-001** (validator, Stage 4 - parallel):
+```json
+{
+  "VALIDATE-001": {
+    "title": "Validate refactoring results against baseline",
+    "description": "PURPOSE: Validate refactoring results against baseline | Success: Build passes, tests pass, no metric regressions, API compatible\nTASK:\n  - Load architecture baseline and plan success criteria\n  - Run build validation (compilation, type checking)\n  - Run test validation (existing test suite)\n  - Compare dependency metrics against baseline\n  - Verify API compatibility (no dangling references)\nCONTEXT:\n  - Session: <session-folder>\n  - Scope: <refactoring-scope>\n  - Branch: none\n  - Upstream artifacts: architecture-baseline.json, refactoring-plan.md\n  - Shared memory: <session>/wisdom/.msg/meta.json\nEXPECTED: <session>/artifacts/validation-results.json | Per-dimension validation with verdicts\nCONSTRAINTS: Must compare against baseline | Flag any regressions or broken imports\n---\nInnerLoop: false",
+    "role": "validator",
+    "prefix": "VALIDATE",
+    "deps": ["REFACTOR-001"],
+    "status": "pending",
+    "findings": null,
+    "error": null
+  }
+}
+```
+
+**REVIEW-001** (reviewer, Stage 4 - parallel):
+```json
+{
+  "REVIEW-001": {
+    "title": "Review refactoring code for correctness and quality",
+    "description": "PURPOSE: Review refactoring code for correctness, pattern consistency, and migration safety | Success: All dimensions reviewed, verdict issued\nTASK:\n  - Load modified files and refactoring plan\n  - Review across 5 dimensions: correctness, pattern consistency, completeness, migration safety, best practices\n  - Issue verdict: APPROVE, REVISE, or REJECT with actionable feedback\nCONTEXT:\n  - Session: <session-folder>\n  - Scope: <refactoring-scope>\n  - Branch: none\n  - Upstream artifacts: refactoring-plan.md, validation-results.json (if available)\n  - Shared memory: <session>/wisdom/.msg/meta.json\nEXPECTED: <session>/artifacts/review-report.md | Per-dimension findings with severity\nCONSTRAINTS: Focus on refactoring changes only | Provide specific file:line references\n---\nInnerLoop: false",
+    "role": "reviewer",
+    "prefix": "REVIEW",
+    "deps": ["REFACTOR-001"],
+    "status": "pending",
+    "findings": null,
+    "error": null
+  }
+}
+```
+
+---
+
+### Auto / Fan-out Mode Task Chain (Deferred Branching)
+
+For `auto` and `fan-out` modes, create only shared stages now. Branch tasks are created at **CP-2.5** after DESIGN-001 completes.
+
+Create ANALYZE-001 and DESIGN-001 with same templates as single mode above.
+
+**Do NOT create REFACTOR/VALIDATE/REVIEW tasks yet.** They are created by the CP-2.5 Branch Creation subroutine in monitor.md.
+
+---
+
+### Independent Mode Task Chain
+
+For `independent` mode, create M complete pipelines -- one per target in `independent_targets` array.
+
+Pipeline prefix chars: `A, B, C, D, E, F, G, H, I, J` (from config `pipeline_prefix_chars`).
+
+For each target index `i` (0-based), with prefix char `P = pipeline_prefix_chars[i]`:
+
+```javascript
+// Create session subdirectory for this pipeline
+Bash("mkdir -p <session>/artifacts/pipelines/<P>")
+
+// Add pipeline tasks to tasks.json:
+state.tasks["ANALYZE-<P>01"] = { title: "...", role: "analyzer", prefix: "ANALYZE", deps: [], ... }
+state.tasks["DESIGN-<P>01"] = { title: "...", role: "designer", prefix: "DESIGN", deps: ["ANALYZE-<P>01"], ... }
+state.tasks["REFACTOR-<P>01"] = { title: "...", role: "refactorer", prefix: "REFACTOR", deps: ["DESIGN-<P>01"], ... }
+state.tasks["VALIDATE-<P>01"] = { title: "...", role: "validator", prefix: "VALIDATE", deps: ["REFACTOR-<P>01"], ... }
+state.tasks["REVIEW-<P>01"] = { title: "...", role: "reviewer", prefix: "REVIEW", deps: ["REFACTOR-<P>01"], ... }
+```
+
+Task descriptions follow same template as single mode, with additions:
+- `Pipeline: <P>` in CONTEXT
+- Artifact paths use `<session>/artifacts/pipelines/<P>/` instead of `<session>/artifacts/`
+- Meta.json namespace uses `<role>.<P>` (e.g., `analyzer.A`, `refactorer.B`)
+- Each pipeline's scope is its specific target from `independent_targets[i]`
+
+Example for pipeline A with target "refactor auth module":
+```json
+{
+  "ANALYZE-A01": {
+    "title": "Analyze auth module architecture",
+    "description": "PURPOSE: Analyze auth module architecture | Success: Auth module structural issues identified\nTASK:\n  - Detect project type and available analysis tools\n  - Execute architecture analysis focused on auth module\n  - Collect baseline metrics and rank auth module issues\nCONTEXT:\n  - Session: <session-folder>\n  - Scope: refactor auth module\n  - Pipeline: A\n  - Shared memory: <session>/wisdom/.msg/meta.json (namespace: analyzer.A)\nEXPECTED: <session>/artifacts/pipelines/A/architecture-baseline.json + architecture-report.md\nCONSTRAINTS: Focus on auth module scope\n---\nInnerLoop: false\nPipelineId: A",
+    "role": "analyzer",
+    "prefix": "ANALYZE",
+    "deps": [],
+    "status": "pending",
+    "findings": null,
+    "error": null
+  }
+}
+```
+
+---
+
+### CP-2.5: Branch Creation Subroutine
+
+**Triggered by**: monitor.md handleSpawnNext when DESIGN-001 completes in `auto` or `fan-out` mode.
+
+**Procedure**:
+
+1. Read `<session>/artifacts/refactoring-plan.md` to count REFACTOR-IDs
+2. Read `.msg/meta.json` -> `designer.refactoring_count`
+3. **Auto mode decision**:
+
+| Refactoring Count | Decision |
+|-------------------|----------|
+| count <= 2 | Switch to `single` mode -- add REFACTOR-001, VALIDATE-001, REVIEW-001 to tasks.json (standard single pipeline) |
+| count >= 3 | Switch to `fan-out` mode -- add branch tasks below |
+
+4. Update tasks.json with resolved `parallel_mode` (auto -> single or fan-out)
+
+5. **Fan-out branch creation** (when count >= 3 or forced fan-out):
+   - Truncate to `max_branches` if `refactoring_count > max_branches` (keep top N by priority)
+   - For each refactoring `i` (1-indexed), branch ID = `B{NN}` where NN = zero-padded i:
+
+```javascript
+// Create branch artifact directory
+Bash("mkdir -p <session>/artifacts/branches/B{NN}")
+
+// Extract single REFACTOR detail to branch
+Write("<session>/artifacts/branches/B{NN}/refactoring-detail.md",
+  extracted REFACTOR-{NNN} block from refactoring-plan.md)
+```
+
+6. Add branch tasks to tasks.json for each branch B{NN}:
+
+```json
+{
+  "REFACTOR-B{NN}": {
+    "title": "Implement refactoring REFACTOR-{NNN}",
+    "description": "PURPOSE: Implement refactoring REFACTOR-{NNN} | Success: Single refactoring applied, compiles, tests pass\nTASK:\n  - Load refactoring detail from branches/B{NN}/refactoring-detail.md\n  - Apply this single refactoring to target files\n  - Update all import references for moved/renamed modules\n  - Validate changes compile and pass existing tests\nCONTEXT:\n  - Session: <session-folder>\n  - Branch: B{NN}\n  - Upstream artifacts: branches/B{NN}/refactoring-detail.md\n  - Shared memory: <session>/wisdom/.msg/meta.json (namespace: refactorer.B{NN})\nEXPECTED: Modified source files for REFACTOR-{NNN} only\nCONSTRAINTS: Only implement this branch's refactoring | Do not touch files outside REFACTOR-{NNN} scope\n---\nInnerLoop: false\nBranchId: B{NN}",
+    "role": "refactorer",
+    "prefix": "REFACTOR",
+    "deps": ["DESIGN-001"],
+    "status": "pending",
+    "findings": null,
+    "error": null
+  },
+  "VALIDATE-B{NN}": {
+    "title": "Validate branch B{NN} refactoring",
+    "description": "PURPOSE: Validate branch B{NN} refactoring | Success: REFACTOR-{NNN} passes build, tests, and metric checks\nTASK:\n  - Load architecture baseline and REFACTOR-{NNN} success criteria\n  - Validate build, tests, dependency metrics, and API compatibility\n  - Compare against baseline, check for regressions\nCONTEXT:\n  - Session: <session-folder>\n  - Branch: B{NN}\n  - Upstream artifacts: architecture-baseline.json, branches/B{NN}/refactoring-detail.md\n  - Shared memory: <session>/wisdom/.msg/meta.json (namespace: validator.B{NN})\nEXPECTED: <session>/artifacts/branches/B{NN}/validation-results.json\nCONSTRAINTS: Only validate this branch's changes\n---\nInnerLoop: false\nBranchId: B{NN}",
+    "role": "validator",
+    "prefix": "VALIDATE",
+    "deps": ["REFACTOR-B{NN}"],
+    "status": "pending",
+    "findings": null,
+    "error": null
+  },
+  "REVIEW-B{NN}": {
+    "title": "Review branch B{NN} refactoring code",
+    "description": "PURPOSE: Review branch B{NN} refactoring code | Success: Code quality verified for REFACTOR-{NNN}\nTASK:\n  - Load modified files from refactorer.B{NN} namespace in .msg/meta.json\n  - Review across 5 dimensions for this branch's changes only\n  - Issue verdict: APPROVE, REVISE, or REJECT\nCONTEXT:\n  - Session: <session-folder>\n  - Branch: B{NN}\n  - Upstream artifacts: branches/B{NN}/refactoring-detail.md\n  - Shared memory: <session>/wisdom/.msg/meta.json (namespace: reviewer.B{NN})\nEXPECTED: <session>/artifacts/branches/B{NN}/review-report.md\nCONSTRAINTS: Only review this branch's changes\n---\nInnerLoop: false\nBranchId: B{NN}",
+    "role": "reviewer",
+    "prefix": "REVIEW",
+    "deps": ["REFACTOR-B{NN}"],
+    "status": "pending",
+    "findings": null,
+    "error": null
+  }
+}
+```
+
+7. Update tasks.json:
+   - `branches`: array of branch IDs (["B01", "B02", ...])
+   - `fix_cycles`: object keyed by branch ID, all initialized to 0
+
+---
+
+## Phase 4: Validation
+
+Verify task chain integrity:
+
+| Check | Method | Expected |
+|-------|--------|----------|
+| Task count correct | tasks.json task count | single: 5, auto/fan-out: 2 (pre-CP-2.5), independent: 5*M |
+| Dependencies correct | Trace dependency graph | Acyclic, correct deps |
+| No circular dependencies | Trace dependency graph | Acyclic |
+| Task IDs use correct prefixes | Pattern check | Match naming rules per mode |
+| Structured descriptions complete | Each has PURPOSE/TASK/CONTEXT/EXPECTED/CONSTRAINTS | All present |
+| Branch/Pipeline IDs consistent | Cross-check with tasks.json | Match |
+
+### Naming Rules Summary
+
+| Mode | Stage 3 | Stage 4 | Fix |
+|------|---------|---------|-----|
+| Single | REFACTOR-001 | VALIDATE-001, REVIEW-001 | FIX-001, FIX-002 |
+| Fan-out | REFACTOR-B01 | VALIDATE-B01, REVIEW-B01 | FIX-B01-1, FIX-B01-2 |
+| Independent | REFACTOR-A01 | VALIDATE-A01, REVIEW-A01 | FIX-A01-1, FIX-A01-2 |
+
+If validation fails, fix the specific task and re-validate.

package/.codex/skills/team-arch-opt/roles/coordinator/commands/monitor.md

@@ -0,0 +1,204 @@
+# Monitor Pipeline
+
+Synchronous pipeline coordination using spawn_agent + wait_agent.
+
+## Constants
+
+- WORKER_AGENT: team_worker
+- ONE_STEP_PER_INVOCATION: false (synchronous wait loop)
+- FAST_ADVANCE_AWARE: true
+
+## Handler Router
+
+| Source | Handler |
+|--------|---------|
+| Message contains branch tag [refactorer-B01], etc. | handleSpawnNext (branch-aware) |
+| Message contains pipeline tag [analyzer-A], etc. | handleSpawnNext (pipeline-aware) |
+| "consensus_blocked" | handleConsensus |
+| "capability_gap" | handleAdapt |
+| "check" or "status" | handleCheck |
+| "resume" or "continue" | handleResume |
+| All tasks completed | handleComplete |
+| Default | handleSpawnNext |
+
+## handleCheck
+
+Read-only status report from tasks.json, then STOP.
+
+1. Read tasks.json
+2. Count tasks by status (pending, in_progress, completed, failed)
+
+Output (single mode):
+```
+[coordinator] Pipeline Status
+[coordinator] Progress: <done>/<total> (<pct>%)
+[coordinator] Active agents: <list from active_agents>
+[coordinator] Ready: <pending tasks with resolved deps>
+[coordinator] Commands: 'resume' to advance | 'check' to refresh
+```
+
+Fan-out mode adds per-branch grouping. Independent mode adds per-pipeline grouping.
+
+## handleResume
+
+1. Read tasks.json, check active_agents
+2. No active agents -> handleSpawnNext
+3. Has active agents -> check each status
+4. Proceed to handleSpawnNext
+
+## handleSpawnNext
+
+Find ready tasks, spawn workers, wait for completion, process results.
+
+1. Read tasks.json
+2. Collect: completedTasks, inProgressTasks, readyTasks (pending + all deps completed)
+3. No ready + nothing in progress -> handleComplete
+4. No ready + work in progress -> report waiting, STOP
+5. Has ready -> for each:
+   a. Check if inner loop role with active worker -> skip (worker picks up)
+   b. Update task status in tasks.json -> in_progress
+   c. team_msg log -> task_unblocked
+   d. **CP-2.5 check** (auto/fan-out mode only):
+      - If completed task is DESIGN-001 AND parallel_mode is `auto` or `fan-out`:
+      - Execute CP-2.5 Branch Creation from dispatch.md
+      - After branch creation, re-collect readyTasks (spawns all REFACTOR-B* in parallel)
+
+### Spawn Workers
+
+For each ready task:
+
+```javascript
+// 1) Update status in tasks.json
+state.tasks[taskId].status = 'in_progress'
+
+// 2) Spawn worker
+const agentId = spawn_agent({
+  agent_type: "team_worker",
+  items: [
+    { type: "text", text: `## Role Assignment
+role: ${task.role}
+role_spec: ${skillRoot}/roles/${task.role}/role.md
+session: ${sessionFolder}
+session_id: ${sessionId}
+team_name: arch-opt
+requirement: ${task.description}
+inner_loop: ${task.role === 'refactorer'}` },
+
+    { type: "text", text: `Read role_spec file (${skillRoot}/roles/${task.role}/role.md) to load Phase 2-4 domain instructions.
+Execute built-in Phase 1 (task discovery) -> role Phase 2-4 -> built-in Phase 5 (report).` },
+
+    { type: "text", text: `## Task Context
+task_id: ${taskId}
+title: ${task.title}
+description: ${task.description}` },
+
+    { type: "text", text: `## Upstream Context\n${prevContext}` }
+  ]
+})
+
+// 3) Track agent
+state.active_agents[taskId] = { agentId, role: task.role, started_at: now }
+```
+
+6. Parallel spawn rules by mode:
+
+| Mode | Scenario | Spawn Behavior |
+|------|----------|---------------|
+| Single | Stage 4 ready | Spawn VALIDATE-001 + REVIEW-001 in parallel |
+| Fan-out (CP-2.5 done) | All REFACTOR-B* unblocked | Spawn ALL REFACTOR-B* in parallel |
+| Fan-out (REFACTOR-B{NN} done) | VALIDATE + REVIEW ready | Spawn both for that branch in parallel |
+| Independent | Any unblocked task | Spawn all ready tasks across all pipelines in parallel |
+
+### Wait and Process Results
+
+After spawning all ready tasks:
+
+```javascript
+// 4) Batch wait for all spawned workers
+const agentIds = Object.values(state.active_agents).map(a => a.agentId)
+wait_agent({ ids: agentIds, timeout_ms: 900000 })
+
+// 5) Collect results
+for (const [taskId, agent] of Object.entries(state.active_agents)) {
+  state.tasks[taskId].status = 'completed'
+  close_agent({ id: agent.agentId })
+  delete state.active_agents[taskId]
+}
+```
+
+### Persist and Loop
+
+After processing all results:
+1. Write updated tasks.json
+2. Check stage checkpoints (CP-1, CP-2, CP-2.5, CP-3)
+3. Check if more tasks are now ready (deps newly resolved)
+4. If yes -> loop back to step 1 of handleSpawnNext
+5. If no more ready and all done -> handleComplete
+6. If no more ready but some still blocked -> report status, STOP
+
+## Review-Fix Cycle (CP-3)
+
+**Per-branch/pipeline scoping**: Each branch/pipeline has its own independent fix cycle.
+
+When both VALIDATE-* and REVIEW-* are completed for a branch/pipeline:
+
+1. Read validation verdict from scoped meta.json namespace
+2. Read review verdict from scoped meta.json namespace
+
+| Validate Verdict | Review Verdict | Action |
+|-----------------|----------------|--------|
+| PASS | APPROVE | -> handleComplete check |
+| PASS | REVISE | Create FIX task in tasks.json with review feedback |
+| FAIL | APPROVE | Create FIX task in tasks.json with validation feedback |
+| FAIL | REVISE/REJECT | Create FIX task in tasks.json with combined feedback |
+| Any | REJECT | Create FIX task in tasks.json + flag for designer re-evaluation |
+
+Fix cycle tracking per branch in tasks.json `fix_cycles`:
+- < 3: Add FIX task to tasks.json, increment cycle count
+- >= 3: Escalate THIS branch to user. Other branches continue
+
+## handleComplete
+
+Pipeline done. Generate report and completion action.
+
+Completion check by mode:
+| Mode | Completion Condition |
+|------|---------------------|
+| Single | All 5 tasks (+ any FIX/retry tasks) completed |
+| Fan-out | ALL branches have VALIDATE + REVIEW completed (or escalated), shared stages done |
+| Independent | ALL pipelines have VALIDATE + REVIEW completed (or escalated) |
+
+1. For fan-out/independent: aggregate per-branch/pipeline results to `<session>/artifacts/aggregate-results.json`
+2. If any tasks not completed, return to handleSpawnNext
+3. If all completed -> transition to coordinator Phase 5
+4. Execute completion action per tasks.json completion_action:
+   - interactive -> request_user_input (Archive/Keep/Export)
+   - auto_archive -> Archive & Clean (rm -rf session folder)
+   - auto_keep -> Keep Active (status=paused)
+
+## handleConsensus
+
+Handle consensus_blocked signals from discuss rounds.
+
+| Severity | Action |
+|----------|--------|
+| HIGH | Pause pipeline (or branch), notify user with findings summary |
+| MEDIUM | Add revision task to tasks.json for the blocked role (scoped to branch if applicable) |
+| LOW | Log finding, continue pipeline |
+
+## handleAdapt
+
+Capability gap reported mid-pipeline.
+
+1. Parse gap description
+2. Check if existing role covers it -> redirect
+3. Role count < 5 -> generate dynamic role-spec in <session>/role-specs/
+4. Add new task to tasks.json, spawn worker via spawn_agent + wait_agent
+5. Role count >= 5 -> merge or pause
+
+## Fast-Advance Reconciliation
+
+On every coordinator wake:
+1. Read team_msg entries with type="fast_advance"
+2. Sync active_agents with spawned successors
+3. No duplicate spawns