claude-code-workflow 7.2.15 → 7.2.16

package/.codex/skills/team-coordinate/roles/coordinator/commands/analyze-task.md

@@ -0,0 +1,247 @@
+# Command: analyze-task
+
+## Purpose
+
+Parse user task description -> detect required capabilities -> build dependency graph -> design dynamic roles with role-spec metadata. Outputs structured task-analysis.json with frontmatter fields for role-spec generation.
+
+## CRITICAL CONSTRAINT
+
+**TEXT-LEVEL analysis only. MUST NOT read source code or explore codebase.**
+
+**Allowed:**
+- Parse user task description text
+- request_user_input for clarification
+- Keyword-to-capability mapping
+- Write `task-analysis.json`
+
+If task context requires codebase knowledge, set `needs_research: true`. Phase 2 will spawn researcher worker.
+
+## When to Use
+
+| Trigger | Condition |
+|---------|-----------|
+| New task | Coordinator Phase 1 receives task description |
+| Re-analysis | User provides revised requirements |
+| Adapt | handleAdapt extends analysis for new capability |
+
+## Strategy
+
+- **Delegation**: Inline execution (coordinator processes directly)
+- **Mode**: Text-level analysis only (no codebase reading)
+- **Output**: `<session>/task-analysis.json`
+
+## Phase 2: Context Loading
+
+| Input | Source | Required |
+|-------|--------|----------|
+| Task description | User input from Phase 1 | Yes |
+| Clarification answers | request_user_input results (if any) | No |
+| Session folder | From coordinator Phase 2 | Yes |
+
+## Phase 3: Task Analysis
+
+### Step 1: Signal Detection
+
+Scan task description for capability keywords:
+
+| Signal | Keywords | Capability | Prefix | Responsibility Type |
+|--------|----------|------------|--------|---------------------|
+| Research | investigate, explore, compare, survey, find, research, discover, benchmark, study | researcher | RESEARCH | orchestration |
+| Writing | write, draft, document, article, report, blog, describe, explain, summarize, content | writer | DRAFT | code-gen (docs) |
+| Coding | implement, build, code, fix, refactor, develop, create app, program, migrate, port | developer | IMPL | code-gen (code) |
+| Design | design, architect, plan, structure, blueprint, model, schema, wireframe, layout | designer | DESIGN | orchestration |
+| Analysis | analyze, review, audit, assess, evaluate, inspect, examine, diagnose, profile | analyst | ANALYSIS | read-only |
+| Testing | test, verify, validate, QA, quality, check, assert, coverage, regression | tester | TEST | validation |
+| Planning | plan, breakdown, organize, schedule, decompose, roadmap, strategy, prioritize | planner | PLAN | orchestration |
+
+**Multi-match**: A task may trigger multiple capabilities.
+
+**No match**: Default to a single `general` capability with `TASK` prefix.
+
+### Step 2: Artifact Inference
+
+Each capability produces default output artifacts:
+
+| Capability | Default Artifact | Format |
+|------------|-----------------|--------|
+| researcher | Research findings | `<session>/artifacts/research-findings.md` |
+| writer | Written document(s) | `<session>/artifacts/<doc-name>.md` |
+| developer | Code implementation | Source files + `<session>/artifacts/implementation-summary.md` |
+| designer | Design document | `<session>/artifacts/design-spec.md` |
+| analyst | Analysis report | `<session>/artifacts/analysis-report.md` |
+| tester | Test results | `<session>/artifacts/test-report.md` |
+| planner | Execution plan | `<session>/artifacts/execution-plan.md` |
+
+### Step 2.5: Key File Inference
+
+For each task, infer relevant files based on capability type and task keywords:
+
+| Capability | File Inference Strategy |
+|------------|------------------------|
+| researcher | Extract domain keywords -> map to likely directories (e.g., "auth" -> `src/auth/**`, `middleware/auth.ts`) |
+| developer | Extract feature/module keywords -> map to source files (e.g., "payment" -> `src/payments/**`, `types/payment.ts`) |
+| designer | Look for architecture/config keywords -> map to config/schema files |
+| analyst | Extract target keywords -> map to files under analysis |
+| tester | Extract test target keywords -> map to source + test files |
+| writer | Extract documentation target -> map to relevant source files for context |
+| planner | No specific files (planning is abstract) |
+
+**Inference rules:**
+- Extract nouns and verbs from task description
+- Match against common directory patterns (src/, lib/, components/, services/, utils/)
+- Include related type definition files (types/, *.d.ts)
+- For "fix bug" tasks, include error-prone areas (error handlers, validation)
+- For "implement feature" tasks, include similar existing features as reference
+
+### Step 3: Dependency Graph Construction
+
+Build a DAG of work streams using natural ordering tiers:
+
+| Tier | Capabilities | Description |
+|------|-------------|-------------|
+| 0 | researcher, planner | Knowledge gathering / planning |
+| 1 | designer | Design (requires context from tier 0 if present) |
+| 2 | writer, developer | Creation (requires design/plan if present) |
+| 3 | analyst, tester | Validation (requires artifacts to validate) |
+
+### Step 4: Complexity Scoring
+
+| Factor | Weight | Condition |
+|--------|--------|-----------|
+| Capability count | +1 each | Number of distinct capabilities |
+| Cross-domain factor | +2 | Capabilities span 3+ tiers |
+| Parallel tracks | +1 each | Independent parallel work streams |
+| Serial depth | +1 per level | Longest dependency chain length |
+
+| Total Score | Complexity | Role Limit |
+|-------------|------------|------------|
+| 1-3 | Low | 1-2 roles |
+| 4-6 | Medium | 2-3 roles |
+| 7+ | High | 3-5 roles |
+
+### Step 5: Role Minimization
+
+Apply merging rules to reduce role count (cap at 5).
+
+### Step 6: Role-Spec Metadata Assignment
+
+For each role, determine frontmatter and generation hints:
+
+| Field | Derivation |
+|-------|------------|
+| `prefix` | From capability prefix (e.g., RESEARCH, DRAFT, IMPL) |
+| `inner_loop` | `true` if role has 2+ serial same-prefix tasks |
+| `CLI tools` | Suggested, not mandatory -- coordinator may adjust based on task needs |
+| `pattern_hint` | Reference pattern name from role-spec-template (research/document/code/analysis/validation) -- guides coordinator's Phase 2-4 composition, NOT a rigid template selector |
+| `output_type` | `artifact` (new files in session/artifacts/) / `codebase` (modify existing project files) / `mixed` (both) -- determines verification strategy in Behavioral Traits |
+| `message_types.success` | `<prefix>_complete` |
+| `message_types.error` | `error` |
+
+**output_type derivation**:
+
+| Task Signal | output_type | Example |
+|-------------|-------------|---------|
+| "write report", "analyze", "research" | `artifact` | New analysis-report.md in session |
+| "update docs", "modify code", "fix bug" | `codebase` | Modify existing project files |
+| "implement feature + write summary" | `mixed` | Code changes + implementation summary |
+
+## Phase 4: Output
+
+Write `<session-folder>/task-analysis.json`:
+
+```json
+{
+  "task_description": "<original user input>",
+  "capabilities": [
+    {
+      "name": "researcher",
+      "prefix": "RESEARCH",
+      "responsibility_type": "orchestration",
+      "tasks": [
+        {
+          "id": "RESEARCH-001",
+          "goal": "What this task achieves and why",
+          "steps": [
+            "step 1: specific action with clear verb",
+            "step 2: specific action with clear verb",
+            "step 3: specific action with clear verb"
+          ],
+          "key_files": [
+            "src/path/to/relevant.ts",
+            "src/path/to/other.ts"
+          ],
+          "upstream_artifacts": [],
+          "success_criteria": "Measurable completion condition",
+          "constraints": "Scope limits, focus areas"
+        }
+      ],
+      "artifacts": ["research-findings.md"]
+    }
+  ],
+  "dependency_graph": {
+    "RESEARCH-001": [],
+    "DRAFT-001": ["RESEARCH-001"],
+    "ANALYSIS-001": ["DRAFT-001"]
+  },
+  "roles": [
+    {
+      "name": "researcher",
+      "prefix": "RESEARCH",
+      "responsibility_type": "orchestration",
+      "task_count": 1,
+      "inner_loop": false,
+      "role_spec_metadata": {
+        "CLI tools": ["explore"],
+        "pattern_hint": "research",
+        "output_type": "artifact",
+        "message_types": {
+          "success": "research_complete",
+          "error": "error"
+        }
+      }
+    }
+  ],
+  "complexity": {
+    "capability_count": 2,
+    "cross_domain_factor": false,
+    "parallel_tracks": 0,
+    "serial_depth": 2,
+    "total_score": 3,
+    "level": "low"
+  },
+  "needs_research": false,
+  "artifacts": [
+    { "name": "research-findings.md", "producer": "researcher", "path": "artifacts/research-findings.md" }
+  ]
+}
+```
+
+## Complexity Interpretation
+
+**CRITICAL**: Complexity score is for **role design optimization**, NOT for skipping team workflow.
+
+| Complexity | Team Structure | Coordinator Action |
+|------------|----------------|-------------------|
+| Low (1-2 roles) | Minimal team | Generate 1-2 role-specs, create team, spawn workers |
+| Medium (2-3 roles) | Standard team | Generate role-specs, create team, spawn workers |
+| High (3-5 roles) | Full team | Generate role-specs, create team, spawn workers |
+
+**All complexity levels use team_worker architecture**:
+- Single-role tasks still spawn team_worker agent
+- Coordinator NEVER executes task work directly
+- Team infrastructure provides session management, message bus, fast-advance
+
+**Purpose of complexity score**:
+- Determine optimal role count (merge vs separate)
+- Guide dependency graph design
+- Inform user about task scope
+- NOT for deciding whether to use team workflow
+
+## Error Handling
+
+| Scenario | Resolution |
+|----------|------------|
+| No capabilities detected | Default to single `general` role with TASK prefix |
+| Circular dependency in graph | Break cycle at lowest-tier edge, warn |
+| Task description too vague | Return minimal analysis, coordinator will request_user_input |
+| All capabilities merge into one | Valid -- single-role execution via team_worker |

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

@@ -0,0 +1,126 @@
+# Command: dispatch
+
+## Purpose
+
+Create task chains from dynamic dependency graphs. Builds pipelines from the task-analysis.json produced by Phase 1. Workers are spawned as team_worker agents with role-spec paths.
+
+## When to Use
+
+| Trigger | Condition |
+|---------|-----------|
+| After analysis | Phase 1 complete, task-analysis.json exists |
+| After adapt | handleAdapt created new roles, needs new tasks |
+| Re-dispatch | Pipeline restructuring (rare) |
+
+## Strategy
+
+- **Delegation**: Inline execution (coordinator processes directly)
+- **Inputs**: task-analysis.json + team-session.json
+- **Output**: tasks.json with dependency chains
+
+## Phase 2: Context Loading
+
+| Input | Source | Required |
+|-------|--------|----------|
+| Task analysis | `<session-folder>/task-analysis.json` | Yes |
+| Session file | `<session-folder>/team-session.json` | Yes |
+| Role registry | `team-session.json#roles` | Yes |
+| Scope | User requirements description | Yes |
+
+## Phase 3: Task Chain Creation
+
+### Workflow
+
+1. **Read dependency graph** from `task-analysis.json#dependency_graph`
+2. **Topological sort** tasks to determine creation order
+3. **Validate** all task roles exist in role registry
+4. **Build tasks array** (in topological order):
+
+```json
+[
+  {
+    "id": "<PREFIX>-<NNN>",
+    "title": "<PREFIX>-<NNN>",
+    "description": "PURPOSE: <goal> | Success: <success_criteria>\nTASK:\n  - <step 1>\n  - <step 2>\n  - <step 3>\nCONTEXT:\n  - Session: <session-folder>\n  - Upstream artifacts: <artifact-1.md>, <artifact-2.md>\n  - Key files: <file1>, <file2>\n  - Shared state: team_msg(operation=\"get_state\", session_id=<session-id>)\nEXPECTED: <deliverable path> + <quality criteria>\nCONSTRAINTS: <scope limits>\n---\nInnerLoop: <true|false>\nRoleSpec: <session-folder>/role-specs/<role-name>.md",
+    "status": "pending",
+    "role": "<role-name>",
+    "prefix": "<PREFIX>",
+    "deps": ["<dependency-list from graph>"],
+    "findings": "",
+    "error": ""
+  }
+]
+```
+
+5. **Write tasks.json** with the complete array
+6. **Update team-session.json** with pipeline and tasks_total
+7. **Validate** created chain
+
+### Task Description Template
+
+Every task description includes structured fields for clarity:
+
+```
+PURPOSE: <goal from task-analysis.json#tasks[].goal> | Success: <success_criteria from task-analysis.json#tasks[].success_criteria>
+TASK:
+  - <step 1 from task-analysis.json#tasks[].steps[]>
+  - <step 2 from task-analysis.json#tasks[].steps[]>
+  - <step 3 from task-analysis.json#tasks[].steps[]>
+CONTEXT:
+  - Session: <session-folder>
+  - Upstream artifacts: <comma-separated list from task-analysis.json#tasks[].upstream_artifacts[]>
+  - Key files: <comma-separated list from task-analysis.json#tasks[].key_files[]>
+  - Shared state: team_msg(operation="get_state", session_id=<session-id>)
+EXPECTED: <artifact path from task-analysis.json#capabilities[].artifacts[]> + <quality criteria based on capability type>
+CONSTRAINTS: <constraints from task-analysis.json#tasks[].constraints>
+---
+InnerLoop: <true|false>
+RoleSpec: <session-folder>/role-specs/<role-name>.md
+```
+
+**Field Mapping**:
+- `PURPOSE`: From `task-analysis.json#capabilities[].tasks[].goal` + `success_criteria`
+- `TASK`: From `task-analysis.json#capabilities[].tasks[].steps[]`
+- `CONTEXT.Upstream artifacts`: From `task-analysis.json#capabilities[].tasks[].upstream_artifacts[]`
+- `CONTEXT.Key files`: From `task-analysis.json#capabilities[].tasks[].key_files[]`
+- `EXPECTED`: From `task-analysis.json#capabilities[].artifacts[]` + quality criteria
+- `CONSTRAINTS`: From `task-analysis.json#capabilities[].tasks[].constraints`
+
+### InnerLoop Flag Rules
+
+| Condition | InnerLoop |
+|-----------|-----------|
+| Role has 2+ serial same-prefix tasks | true |
+| Role has 1 task | false |
+| Tasks are parallel (no dependency between them) | false |
+
+### Dependency Validation
+
+| Check | Criteria |
+|-------|----------|
+| No orphan tasks | Every task is reachable from at least one root |
+| No circular deps | Topological sort succeeds without cycle |
+| All roles valid | Every task role exists in team-session.json#roles |
+| All deps valid | Every deps entry references an existing task id |
+| Session reference | Every task description contains `Session: <session-folder>` |
+| RoleSpec reference | Every task description contains `RoleSpec: <path>` |
+
+## Phase 4: Validation
+
+| Check | Criteria |
+|-------|----------|
+| Task count | Matches dependency_graph node count |
+| Dependencies | Every deps entry references an existing task id |
+| Role assignment | Each task role is in role registry |
+| Session reference | Every task description contains `Session:` |
+| Pipeline integrity | No disconnected subgraphs (warn if found) |
+
+## Error Handling
+
+| Scenario | Resolution |
+|----------|------------|
+| Circular dependency detected | Report cycle, halt task creation |
+| Role not in role registry | Error, coordinator must fix roles first |
+| Task creation fails | Log error, report to coordinator |
+| Duplicate task id | Skip creation, log warning |
+| Empty dependency graph | Error, task analysis may have failed |

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

@@ -0,0 +1,327 @@
+# Command: monitor
+
+## Purpose
+
+Event-driven pipeline coordination with Spawn-and-Stop pattern. Role names are read from `team-session.json#roles`. Workers are spawned as `team_worker` agents with role-spec paths. Includes `handleComplete` for pipeline completion action and `handleAdapt` for mid-pipeline capability gap handling.
+
+## When to Use
+
+| Trigger | Condition |
+|---------|-----------|
+| Worker result | Result from wait_agent contains [role-name] from session roles |
+| User command | "check", "status", "resume", "continue" |
+| Capability gap | Worker reports capability_gap |
+| Pipeline spawn | After dispatch, initial spawn needed |
+| Pipeline complete | All tasks done |
+
+## Strategy
+
+- **Delegation**: Inline execution with handler routing
+- **Beat model**: ONE_STEP_PER_INVOCATION -- one handler then STOP
+- **Workers**: Spawned as team_worker via spawn_agent
+
+## Constants
+
+| Constant | Value | Description |
+|----------|-------|-------------|
+| SPAWN_MODE | spawn_agent | All workers spawned via `spawn_agent` |
+| ONE_STEP_PER_INVOCATION | true | Coordinator does one operation then STOPS |
+| FAST_ADVANCE_AWARE | true | Workers may skip coordinator for simple linear successors |
+| WORKER_AGENT | team_worker | All workers spawned as team_worker agents |
+
+## Phase 2: Context Loading
+
+| Input | Source | Required |
+|-------|--------|----------|
+| Session file | `<session-folder>/team-session.json` | Yes |
+| Task list | Read tasks.json | Yes |
+| Active workers | session.active_workers[] | Yes |
+| Role registry | session.roles[] | Yes |
+
+**Dynamic role resolution**: Known worker roles are loaded from `session.roles[].name`. Role-spec paths are in `session.roles[].role_spec`.
+
+## Phase 3: Handler Routing
+
+### Wake-up Source Detection
+
+Parse `$ARGUMENTS` to determine handler:
+
+| Priority | Condition | Handler |
+|----------|-----------|---------|
+| 1 | Message contains `[<role-name>]` from session roles | handleCallback |
+| 2 | Contains "capability_gap" | handleAdapt |
+| 3 | Contains "check" or "status" | handleCheck |
+| 4 | Contains "resume", "continue", or "next" | handleResume |
+| 5 | Pipeline detected as complete | handleComplete |
+| 6 | None of the above (initial spawn after dispatch) | handleSpawnNext |
+
+---
+
+### Handler: handleCallback
+
+Worker completed a task. Verify completion, update state, auto-advance.
+
+```
+Receive result from wait_agent for [<role>]
+  +- Find matching active worker by role (from session.roles)
+  +- Is this a progress update (not final)? (Inner Loop intermediate task completion)
+  |   +- YES -> Update session state, do NOT remove from active_workers -> STOP
+  +- Task status = completed?
+  |   +- YES -> remove from active_workers -> update session
+  |   |   +- Close agent: close_agent({ id: <agentId> })
+  |   |   +- -> handleSpawnNext
+  |   +- NO -> progress message, do not advance -> STOP
+  +- No matching worker found
+      +- Scan all active workers for completed tasks
+      +- Found completed -> process each -> handleSpawnNext
+      +- None completed -> STOP
+```
+
+**Fast-advance reconciliation**: A worker may have already spawned its successor via fast-advance. When processing any callback or resume:
+1. Read recent `fast_advance` messages from team_msg (type="fast_advance")
+2. For each fast_advance message: add the spawned successor to `active_workers` if not already present
+3. Check if the expected next task is already `in_progress` (fast-advanced)
+4. If yes -> skip spawning that task (already running)
+5. If no -> normal handleSpawnNext
+
+---
+
+### Handler: handleCheck
+
+Read-only status report. No pipeline advancement.
+
+**Output format**:
+
+```
+[coordinator] Pipeline Status
+[coordinator] Progress: <completed>/<total> (<percent>%)
+
+[coordinator] Execution Graph:
+  <visual representation of dependency graph with status icons>
+
+  done=completed  >>>=running  o=pending  .=not created
+
+[coordinator] Active Workers:
+  > <subject> (<role>) - running <elapsed> [inner-loop: N/M tasks done]
+
+[coordinator] Ready to spawn: <subjects>
+[coordinator] Commands: 'resume' to advance | 'check' to refresh
+```
+
+Then STOP.
+
+---
+
+### Handler: handleResume
+
+Check active worker completion, process results, advance pipeline.
+
+```
+Load active_workers from session
+  +- No active workers -> handleSpawnNext
+  +- Has active workers -> check each:
+      +- status = completed -> mark done, log
+      +- status = in_progress -> still running, log
+      +- other status -> worker failure -> reset to pending
+      After processing:
+        +- Some completed -> handleSpawnNext
+        +- All still running -> report status -> STOP
+        +- All failed -> handleSpawnNext (retry)
+```
+
+---
+
+### Handler: handleSpawnNext
+
+Find all ready tasks, spawn team_worker agents, update session, STOP.
+
+```
+Collect task states from tasks.json
+  +- completedSubjects: status = completed
+  +- inProgressSubjects: status = in_progress
+  +- readySubjects: pending + all deps in completedSubjects
+
+Ready tasks found?
+  +- NONE + work in progress -> report waiting -> STOP
+  +- NONE + nothing in progress -> PIPELINE_COMPLETE -> handleComplete
+  +- HAS ready tasks -> for each:
+      +- Is task role an Inner Loop role AND that role already has an active_worker?
+      |   +- YES -> SKIP spawn (existing worker will pick it up via inner loop)
+      |   +- NO -> normal spawn below
+      +- Update tasks.json entry status -> "in_progress"
+      +- team_msg log -> task_unblocked (session_id=<session-id>)
+      +- Spawn team_worker (see spawn call below)
+      +- Add to session.active_workers
+      Update session file -> output summary -> STOP
+```
+
+**Spawn worker call** (one per ready task):
+
+```
+const agentId = spawn_agent({
+  agent_type: "team_worker",
+  items: [{ type: "text", text: `## Role Assignment
+role: <role>
+role_spec: <session-folder>/role-specs/<role>.md
+session: <session-folder>
+session_id: <session-id>
+team_name: <team-name>
+requirement: <task-description>
+inner_loop: <true|false>
+
+Read role_spec file to load Phase 2-4 domain instructions.` }]
+})
+// Collect results:
+const result = wait_agent({ ids: [agentId], timeout_ms: 900000 })
+// Process result, update tasks.json
+close_agent({ id: agentId })
+```
+
+---
+
+### Handler: handleComplete
+
+Pipeline complete. Execute completion action based on session configuration.
+
+```
+All tasks completed (no pending, no in_progress)
+  +- Generate pipeline summary:
+  |   - Deliverables list with paths
+  |   - Pipeline stats (tasks completed, duration)
+  |   - Discussion verdicts (if any)
+  |
+  +- Read session.completion_action:
+      |
+      +- "interactive":
+      |   request_user_input({
+      |     questions: [{
+      |       question: "Team pipeline complete. What would you like to do?",
+      |       header: "Completion",
+      |       multiSelect: false,
+      |       options: [
+      |         { label: "Archive & Clean (Recommended)", description: "Archive session, clean up team" },
+      |         { label: "Keep Active", description: "Keep session for follow-up work" },
+      |         { label: "Export Results", description: "Export deliverables to target directory" }
+      |       ]
+      |     }]
+      |   })
+      |   +- "Archive & Clean":
+      |   |   Update session status="completed"
+      |   |   Clean up session
+      |   |   Output final summary with artifact paths
+      |   +- "Keep Active":
+      |   |   Update session status="paused"
+      |   |   Output: "Resume with: Skill(skill='team-coordinate', args='resume')"
+      |   +- "Export Results":
+      |       request_user_input for target directory
+      |       Copy deliverables to target
+      |       Execute Archive & Clean flow
+      |
+      +- "auto_archive":
+      |   Execute Archive & Clean without prompt
+      |
+      +- "auto_keep":
+          Execute Keep Active without prompt
+```
+
+**Fallback**: If completion action fails, default to Keep Active (session status="paused"), log warning.
+
+---
+
+### Handler: handleAdapt
+
+Handle mid-pipeline capability gap discovery. A worker reports `capability_gap` when it encounters work outside its scope.
+
+**CONSTRAINT**: Maximum 5 worker roles per session. handleAdapt MUST enforce this limit.
+
+```
+Parse capability_gap message:
+  +- Extract: gap_description, requesting_role, suggested_capability
+  +- Validate gap is genuine:
+      +- Check existing roles in session.roles -> does any role cover this?
+      |   +- YES -> redirect to that role -> STOP
+      |   +- NO -> genuine gap, proceed to role-spec generation
+  +- CHECK ROLE COUNT LIMIT (MAX 5 ROLES):
+      +- Count current roles in session.roles
+      +- If count >= 5:
+          +- Attempt to merge new capability into existing role
+          +- If merge NOT possible -> PAUSE, report to user
+  +- Generate new role-spec:
+      1. Read specs/role-spec-template.md
+      2. Fill template with: frontmatter (role, prefix, inner_loop, message_types) + Phase 2-4 content
+      3. Write to <session-folder>/role-specs/<new-role>.md
+      4. Add to session.roles[]
+  +- Create new task(s) (add to tasks.json)
+  +- Update team-session.json
+  +- Spawn new team_worker -> STOP
+```
+
+---
+
+### Worker Failure Handling
+
+When a worker has unexpected status (not completed, not in_progress):
+
+1. Reset task -> pending in tasks.json
+2. Log via team_msg (type: error)
+3. Report to user: task reset, will retry on next resume
+
+### Fast-Advance Failure Recovery
+
+When coordinator detects a fast-advanced task has failed:
+
+```
+handleCallback / handleResume detects:
+  +- Task is in_progress (was fast-advanced by predecessor)
+  +- No active_worker entry for this task
+  +- Resolution:
+      1. Update tasks.json -> reset task to pending
+      2. Remove stale active_worker entry (if any)
+      3. Log via team_msg (type: error)
+      4. -> handleSpawnNext (will re-spawn the task normally)
+```
+
+### Fast-Advance State Sync
+
+On every coordinator wake (handleCallback, handleResume, handleCheck):
+1. Read team_msg entries with `type="fast_advance"` since last coordinator wake
+2. For each entry: sync `active_workers` with the spawned successor
+3. This ensures coordinator's state reflects fast-advance decisions even before the successor's callback arrives
+
+### Consensus-Blocked Handling
+
+```
+handleCallback receives message with consensus_blocked flag
+  +- Route by severity:
+      +- severity = HIGH
+      |   +- Create REVISION task (same role, incremented suffix)
+      |   +- Max 1 revision per task. If already revised -> PAUSE, escalate to user
+      +- severity = MEDIUM
+      |   +- Proceed with warning, log to wisdom/issues.md
+      |   +- Normal handleSpawnNext
+      +- severity = LOW
+          +- Proceed normally, treat as consensus_reached with notes
+```
+
+## Phase 4: Validation
+
+| Check | Criteria |
+|-------|----------|
+| Session state consistent | active_workers matches tasks.json in_progress tasks |
+| No orphaned tasks | Every in_progress task has an active_worker entry |
+| Dynamic roles valid | All task roles exist in session.roles |
+| Completion detection | readySubjects=0 + inProgressSubjects=0 -> PIPELINE_COMPLETE |
+| Fast-advance tracking | Detect tasks already in_progress via fast-advance, sync to active_workers |
+
+## Error Handling
+
+| Scenario | Resolution |
+|----------|------------|
+| Session file not found | Error, suggest re-initialization |
+| Worker callback from unknown role | Log info, scan for other completions |
+| All workers still running on resume | Report status, suggest check later |
+| Pipeline stall (no ready, no running) | Check for missing tasks, report to user |
+| Fast-advance conflict | Coordinator reconciles, no duplicate spawns |
+| Dynamic role-spec file not found | Error, coordinator must regenerate from task-analysis |
+| capability_gap when role limit (5) reached | Attempt merge, else pause for user |
+| Completion action fails | Default to Keep Active, log warning |