claude-code-workflow 6.3.53 → 7.0.0

package/.claude/skills/team-lifecycle-v4/roles/coordinator/commands/monitor.md

@@ -0,0 +1,413 @@
+# Command: monitor
+
+## Purpose
+
+Event-driven pipeline coordination with Spawn-and-Stop pattern. v4 enhanced with worker fast-advance awareness. Three wake-up sources: worker callbacks (auto-advance), user `check` (status report), user `resume` (manual advance).
+
+## Constants
+
+| Constant | Value | Description |
+|----------|-------|-------------|
+| SPAWN_MODE | background | All workers spawned via `Task(run_in_background: true)` |
+| ONE_STEP_PER_INVOCATION | true | Coordinator does one operation then STOPS |
+| FAST_ADVANCE_AWARE | true | Workers may skip coordinator for simple linear successors |
+
+## Phase 2: Context Loading
+
+| Input | Source | Required |
+|-------|--------|----------|
+| Session file | `<session-folder>/team-session.json` | Yes |
+| Task list | `TaskList()` | Yes |
+| Active workers | session.active_workers[] | Yes |
+| Pipeline mode | session.mode | Yes |
+
+## Phase 3: Handler Routing
+
+### Wake-up Source Detection
+
+Parse `$ARGUMENTS` to determine handler:
+
+| Priority | Condition | Handler |
+|----------|-----------|---------|
+| 1 | Message contains `[<role-name>]` from known worker role | handleCallback |
+| 2 | Contains "check" or "status" | handleCheck |
+| 3 | Contains "resume", "continue", or "next" | handleResume |
+| 4 | None of the above (initial spawn after dispatch) | handleSpawnNext |
+| 5 | Contains "revise" + task ID pattern | handleRevise |
+| 6 | Contains "feedback" + quoted/unquoted text | handleFeedback |
+| 7 | Contains "recheck" | handleRecheck |
+| 8 | Contains "improve" (optionally + dimension name) | handleImprove |
+
+Known worker roles: analyst, writer, planner, executor, tester, reviewer, architect, fe-developer, fe-qa.
+
+> **Note**: `discussant` and `explorer` are no longer worker roles in v4. They are subagents called inline by produce roles.
+
+---
+
+### Handler: handleCallback
+
+Worker completed a task. Verify completion, update state, auto-advance.
+
+```
+Receive callback from [<role>]
+  +- Find matching active worker by role
+  +- 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
+  |   |   +- Handle checkpoints (see below)
+  |   |   +- -> 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 note**: A worker may have already spawned its successor via fast-advance. When processing a callback:
+1. Check if the expected next task is already `in_progress` (fast-advanced)
+2. If yes -> skip spawning that task, update active_workers to include the fast-advanced worker
+3. If no -> normal handleSpawnNext
+
+---
+
+### Handler: handleCheck
+
+Read-only status report. No pipeline advancement.
+
+**Output format**:
+
+```
+[coordinator] Pipeline Status (v4)
+[coordinator] Mode: <mode> | Progress: <completed>/<total> (<percent>%)
+
+[coordinator] Execution Graph:
+  Spec Phase: (if applicable)
+    [<icon> RESEARCH-001(+D1)] -> [<icon> DRAFT-001(+D2)] -> [<icon> DRAFT-002(+D3)]
+    -> [<icon> DRAFT-003(+D4)] -> [<icon> DRAFT-004(+D5)] -> [<icon> QUALITY-001(+D6)]
+  Impl Phase: (if applicable)
+    [<icon> PLAN-001]
+      +- BE: [<icon> IMPL-001] -> [<icon> TEST-001] -> [<icon> REVIEW-001]
+      +- FE: [<icon> DEV-FE-001] -> [<icon> QA-FE-001]
+
+  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
+```
+
+**Icon mapping**: completed=done, in_progress=>>>, pending=o, not created=.
+
+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 workers in background, update session, STOP.
+
+```
+Collect task states from TaskList()
+  +- completedSubjects: status = completed
+  +- inProgressSubjects: status = in_progress
+  +- readySubjects: pending + all blockedBy in completedSubjects
+
+Ready tasks found?
+  +- NONE + work in progress -> report waiting -> STOP
+  +- NONE + nothing in progress -> PIPELINE_COMPLETE -> Phase 5
+  +- HAS ready tasks -> for each:
+      +- Is task owner 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
+      +- TaskUpdate -> in_progress
+      +- team_msg log -> task_unblocked
+      +- Spawn worker (see tool call below)
+      +- Add to session.active_workers
+      Update session file -> output summary -> STOP
+```
+
+**Spawn worker tool call** (one per ready task):
+
+```bash
+Task({
+  subagent_type: "general-purpose",
+  description: "Spawn <role> worker for <subject>",
+  team_name: <team-name>,
+  name: "<role>",
+  run_in_background: true,
+  prompt: "<worker prompt from SKILL.md Coordinator Spawn Template>"
+})
+```
+
+---
+
+### Handler: handleRevise
+
+User requests targeted revision of a completed task.
+
+```
+Parse: revise <TASK-ID> [feedback-text]
+  +- Validate TASK-ID exists and is completed
+  |   +- NOT completed -> error: "Task <ID> is not completed, cannot revise"
+  +- Determine role and doc type from TASK-ID prefix
+  +- Create revision task:
+  |   TaskCreate({
+  |     subject: "<TASK-ID>-R1",
+  |     owner: "<same-role>",
+  |     description: "User-requested revision of <TASK-ID>.\n
+  |       Session: <session-folder>\n
+  |       Original artifact: <artifact-path>\n
+  |       User feedback: <feedback-text or 'general revision requested'>\n
+  |       Revision scope: targeted\n
+  |       InlineDiscuss: <same-discuss-round>\n
+  |       InnerLoop: true",
+  |     status: "pending"
+  |   })
+  +- Cascade check (auto):
+  |   +- Find all completed tasks downstream of TASK-ID
+  |   +- For each downstream completed task -> create <ID>-R1
+  |   +- Chain blockedBy: each R1 blockedBy its predecessor R1
+  |   +- Always end with QUALITY-001-R1 (recheck)
+  +- Spawn worker for first revision task -> STOP
+```
+
+**Cascade Rules**:
+
+| Revised Task | Downstream (auto-cascade) |
+|-------------|--------------------------|
+| RESEARCH-001 | DRAFT-001~004-R1, QUALITY-001-R1 |
+| DRAFT-001 | DRAFT-002~004-R1, QUALITY-001-R1 |
+| DRAFT-002 | DRAFT-003~004-R1, QUALITY-001-R1 |
+| DRAFT-003 | DRAFT-004-R1, QUALITY-001-R1 |
+| DRAFT-004 | QUALITY-001-R1 |
+| QUALITY-001 | (no cascade, just recheck) |
+
+**Cascade depth control**: Only cascade tasks that are already completed. Pending/in_progress tasks will naturally pick up changes.
+
+---
+
+### Handler: handleFeedback
+
+User injects feedback into pipeline context.
+
+```
+Parse: feedback <text>
+  +- Determine pipeline state:
+  |   +- Spec phase in progress -> find earliest affected DRAFT task
+  |   +- Spec phase complete (at checkpoint) -> analyze full impact
+  |   +- Impl phase in progress -> log to wisdom/decisions.md, no revision
+  +- Analyze feedback impact:
+  |   +- Keyword match against doc types:
+  |       "vision/market/MVP/scope" -> DRAFT-001 (product-brief)
+  |       "requirement/feature/NFR/user story" -> DRAFT-002 (requirements)
+  |       "architecture/ADR/component/tech stack" -> DRAFT-003 (architecture)
+  |       "epic/story/sprint/priority" -> DRAFT-004 (epics)
+  |   +- If unclear -> default to earliest incomplete or most recent completed
+  +- Write feedback to wisdom/decisions.md
+  +- Create revision chain (same as handleRevise from determined start point)
+  +- Spawn worker -> STOP
+```
+
+---
+
+### Handler: handleRecheck
+
+Re-run quality check after manual edits or revisions.
+
+```
+Parse: recheck
+  +- Validate QUALITY-001 exists and is completed
+  |   +- NOT completed -> error: "Quality check hasn't run yet"
+  +- Create recheck task:
+  |   TaskCreate({
+  |     subject: "QUALITY-001-R1",
+  |     owner: "reviewer",
+  |     description: "Re-run spec quality check.\n
+  |       Session: <session-folder>\n
+  |       Scope: full recheck\n
+  |       InlineDiscuss: DISCUSS-006",
+  |     status: "pending"
+  |   })
+  +- Spawn reviewer -> STOP
+```
+
+---
+
+### Handler: handleImprove
+
+Quality-driven improvement based on readiness report dimensions.
+
+```
+Parse: improve [dimension]
+  +- Read <session>/spec/readiness-report.md
+  |   +- NOT found -> error: "No readiness report. Run quality check first."
+  +- Extract dimension scores
+  +- Select target:
+  |   +- dimension specified -> use it
+  |   +- not specified -> pick lowest scoring dimension
+  +- Map dimension to improvement strategy:
+  |
+  |   | Dimension | Strategy | Target Tasks |
+  |   |-----------|----------|-------------|
+  |   | completeness | Fill missing sections | DRAFT with missing sections |
+  |   | consistency | Unify terminology/format | All DRAFT (batch) |
+  |   | traceability | Strengthen Goals->Reqs->Arch->Stories chain | DRAFT-002, DRAFT-003, DRAFT-004 |
+  |   | depth | Enhance AC/ADR detail | Weakest sub-dimension's DRAFT |
+  |   | coverage | Add uncovered requirements | DRAFT-002 |
+  |
+  +- Create improvement task:
+  |   TaskCreate({
+  |     subject: "IMPROVE-<dimension>-001",
+  |     owner: "writer",
+  |     description: "Quality improvement: <dimension>.\n
+  |       Session: <session-folder>\n
+  |       Current score: <X>%\n
+  |       Target: 80%\n
+  |       Weak areas: <from readiness-report>\n
+  |       Strategy: <from table>\n
+  |       InnerLoop: true",
+  |     status: "pending"
+  |   })
+  +- Create QUALITY-001-R1 (blockedBy: IMPROVE task)
+  +- Spawn writer -> STOP
+```
+
+---
+
+### Checkpoints
+
+| Completed Task | Mode Condition | Action |
+|---------------|----------------|--------|
+| QUALITY-001 | full-lifecycle or full-lifecycle-fe | Read readiness-report.md -> extract gate + scores -> output Checkpoint Output Template (see SKILL.md) -> pause for user action |
+
+---
+
+### Worker Failure Handling
+
+When a worker has unexpected status (not completed, not in_progress):
+
+1. Reset task -> pending via TaskUpdate
+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 (task in_progress but no callback and worker gone):
+
+```
+handleCallback / handleResume detects:
+  +- Task is in_progress (was fast-advanced by predecessor)
+  +- No active_worker entry for this task
+  +- Original fast-advancing worker has already completed and exited
+  +- Resolution:
+      1. TaskUpdate -> reset task to pending
+      2. Remove stale active_worker entry (if any)
+      3. Log via team_msg (type: error, summary: "Fast-advanced task <ID> failed, resetting for retry")
+      4. -> handleSpawnNext (will re-spawn the task normally)
+```
+
+**Detection in handleResume**:
+
+```
+For each in_progress task in TaskList():
+  +- Has matching active_worker? -> normal, skip
+  +- No matching active_worker? -> orphaned (likely fast-advance failure)
+      +- Check creation time: if > 5 minutes with no progress callback
+      +- Reset to pending -> handleSpawnNext
+```
+
+**Prevention**: Fast-advance failures are self-healing. The coordinator reconciles orphaned tasks on every `resume`/`check` cycle. No manual intervention required unless the same task fails repeatedly (3+ resets -> escalate to user).
+
+### Consensus-Blocked Handling
+
+When a produce role reports `consensus_blocked` in its callback:
+
+```
+handleCallback receives message with consensus_blocked flag
+  +- Extract: divergence_severity, blocked_round, action_recommendation
+  +- Route by severity:
+      |
+      +- severity = HIGH (rating <= 2 or critical risk)
+      |   +- Is this DISCUSS-006 (final sign-off)?
+      |   |   +- YES -> PAUSE: output warning, wait for user `resume` with decision
+      |   |   +- NO -> Create REVISION task:
+      |   |       +- Same role, same doc type, incremented suffix (e.g., DRAFT-001-R1)
+      |   |       +- Description includes: divergence details + action items from discuss
+      |   |       +- blockedBy: none (immediate execution)
+      |   |       +- Max 1 revision per task (DRAFT-001 -> DRAFT-001-R1, no R2)
+      |   |       +- If already revised once -> PAUSE, escalate to user
+      |   +- Update session: mark task as "revised", log revision chain
+      |
+      +- severity = MEDIUM (rating spread or single low rating)
+      |   +- Proceed with warning: include divergence in next task's context
+      |   +- Log action items to wisdom/issues.md for downstream awareness
+      |   +- Normal handleSpawnNext
+      |
+      +- severity = LOW (minor suggestions only)
+          +- Proceed normally: treat as consensus_reached with notes
+          +- Normal handleSpawnNext
+```
+
+**Revision task template** (for HIGH severity):
+
+```
+TaskCreate({
+  subject: "<ORIGINAL-ID>-R1",
+  description: "Revision of <ORIGINAL-ID>: address consensus-blocked divergences.\n
+    Session: <session-folder>\n
+    Original artifact: <artifact-path>\n
+    Divergences:\n<divergence-details>\n
+    Action items:\n<action-items-from-discuss>\n
+    InlineDiscuss: <same-round-id>",
+  owner: "<same-role>",
+  status: "pending"
+})
+```
+
+## Phase 4: Validation
+
+| Check | Criteria |
+|-------|----------|
+| Session state consistent | active_workers matches TaskList in_progress tasks |
+| No orphaned tasks | Every in_progress task has an active_worker entry |
+| Pipeline completeness | All expected tasks exist per mode |
+| Completion detection | readySubjects=0 + inProgressSubjects=0 -> PIPELINE_COMPLETE |
+| Fast-advance tracking | Detect tasks already in_progress via fast-advance, sync to active_workers |
+| Fast-advance orphan check | in_progress tasks without active_worker entry -> reset to pending |
+| Consensus-blocked routing | HIGH -> revision/pause, MEDIUM -> warn+proceed, LOW -> proceed |
+
+## 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 |
+| Fast-advance task orphaned | Reset to pending, re-spawn via handleSpawnNext |
+| consensus_blocked HIGH | Create revision task (max 1) or pause for user |
+| consensus_blocked MEDIUM | Proceed with warning, log to wisdom/issues.md |
+| Revision task also blocked | Escalate to user, pause pipeline |

package/.claude/skills/team-lifecycle-v4/roles/coordinator/role.md

@@ -0,0 +1,230 @@
+# Coordinator Role
+
+Orchestrate the team-lifecycle workflow: team creation, task dispatching, progress monitoring, session state. Optimized for v4 reduced pipeline with inline discuss and shared explore.
+
+## Identity
+
+- **Name**: `coordinator` | **Tag**: `[coordinator]`
+- **Responsibility**: Parse requirements -> Create team -> Dispatch tasks -> Monitor progress -> Report results
+
+## Boundaries
+
+### MUST
+- Parse user requirements and clarify ambiguous inputs via AskUserQuestion
+- Create team and spawn worker subagents in background
+- Dispatch tasks with proper dependency chains (see SKILL.md Task Metadata Registry)
+- Monitor progress via worker callbacks and route messages
+- Maintain session state persistence (team-session.json)
+
+### MUST NOT
+- Execute spec/impl/research work directly (delegate to workers)
+- Modify task outputs (workers own their deliverables)
+- Call implementation subagents (code-developer, etc.) directly
+- Skip dependency validation when creating task chains
+
+---
+
+## Command Execution Protocol
+
+When coordinator needs to execute a command (dispatch, monitor):
+
+1. **Read the command file**: `roles/coordinator/commands/<command-name>.md`
+2. **Follow the workflow** defined in the command file (Phase 2-4 structure)
+3. **Commands are inline execution guides** - NOT separate agents or subprocesses
+4. **Execute synchronously** - complete the command workflow before proceeding
+
+Example:
+```
+Phase 3 needs task dispatch
+  -> Read roles/coordinator/commands/dispatch.md
+  -> Execute Phase 2 (Context Loading)
+  -> Execute Phase 3 (Task Chain Creation)
+  -> Execute Phase 4 (Validation)
+  -> Continue to Phase 4
+```
+
+---
+
+## Entry Router
+
+When coordinator is invoked, first detect the invocation type:
+
+| Detection | Condition | Handler |
+|-----------|-----------|---------|
+| Worker callback | Message contains `[role-name]` tag from a known worker role | -> handleCallback: auto-advance pipeline |
+| Status check | Arguments contain "check" or "status" | -> handleCheck: output execution graph, no advancement |
+| Manual resume | Arguments contain "resume" or "continue" | -> handleResume: check worker states, advance pipeline |
+| Interrupted session | Active/paused session exists in `.workflow/.team/TLS-*` | -> Phase 0 (Session Resume Check) |
+| New session | None of the above | -> Phase 1 (Requirement Clarification) |
+
+For callback/check/resume: load `commands/monitor.md` and execute the appropriate handler, then STOP.
+
+### Router Implementation
+
+1. **Load session context** (if exists):
+   - Scan `.workflow/.team/TLS-*/team-session.json` for active/paused sessions
+   - If found, extract known worker roles from session or SKILL.md Role Registry
+
+2. **Parse $ARGUMENTS** for detection keywords
+
+3. **Route to handler**:
+   - For monitor handlers: Read `commands/monitor.md`, execute matched handler section, STOP
+   - For Phase 0: Execute Session Resume Check below
+   - For Phase 1: Execute Requirement Clarification below
+
+---
+
+## Phase 0: Session Resume Check
+
+**Objective**: Detect and resume interrupted sessions before creating new ones.
+
+**Workflow**:
+1. Scan `.workflow/.team/TLS-*/team-session.json` for sessions with status "active" or "paused"
+2. No sessions found -> proceed to Phase 1
+3. Single session found -> resume it (-> Session Reconciliation)
+4. Multiple sessions -> AskUserQuestion for user selection
+
+**Session Reconciliation**:
+1. Audit TaskList -> get real status of all tasks
+2. Reconcile: session.completed_tasks <-> TaskList status (bidirectional sync)
+3. Reset any in_progress tasks -> pending (they were interrupted)
+4. Determine remaining pipeline from reconciled state
+5. Rebuild team if disbanded (TeamCreate + spawn needed workers only)
+6. Create missing tasks with correct blockedBy dependencies
+7. Verify dependency chain integrity
+8. Update session file with reconciled state
+9. Kick first executable task's worker -> Phase 4
+
+---
+
+## Phase 1: Requirement Clarification
+
+**Objective**: Parse user input and gather execution parameters.
+
+**Workflow**:
+
+1. **Parse arguments** for explicit settings: mode, scope, focus areas, depth
+
+2. **Ask for missing parameters** via AskUserQuestion:
+   - Mode: spec-only / impl-only / full-lifecycle / fe-only / fullstack / full-lifecycle-fe
+   - Scope: project description
+   - Execution method: sequential / parallel
+
+3. **Frontend auto-detection** (for impl-only and full-lifecycle modes):
+
+   | Signal | Detection | Pipeline Upgrade |
+   |--------|----------|-----------------|
+   | FE keywords (component, page, UI, React, Vue, CSS...) | Keyword match in description | impl-only -> fe-only or fullstack |
+   | BE keywords also present (API, database, server...) | Both FE + BE keywords | impl-only -> fullstack |
+   | FE framework in package.json | grep react/vue/svelte/next | full-lifecycle -> full-lifecycle-fe |
+
+4. **Store requirements**: mode, scope, focus, depth, executionMethod
+
+**Success**: All parameters captured, mode finalized.
+
+---
+
+## Phase 2: Create Team + Initialize Session
+
+**Objective**: Initialize team, session file, and wisdom directory.
+
+**Workflow**:
+1. Generate session ID: `TLS-<slug>-<date>`
+2. Create session folder: `.workflow/.team/<session-id>/`
+3. Call TeamCreate with team name
+4. Initialize wisdom directory (learnings.md, decisions.md, conventions.md, issues.md)
+5. Initialize explorations directory with empty cache-index.json
+6. Write team-session.json with: session_id, mode, scope, status="active", tasks_total, tasks_completed=0
+
+**Task counts by mode (v4)**:
+
+| Mode | Tasks | v3 Tasks | Savings |
+|------|-------|----------|---------|
+| spec-only | 6 | 12 | -6 (discuss inlined) |
+| impl-only | 4 | 4 | 0 |
+| fe-only | 3 | 3 | 0 |
+| fullstack | 6 | 6 | 0 |
+| full-lifecycle | 10 | 16 | -6 (discuss inlined) |
+| full-lifecycle-fe | 12 | 18 | -6 (discuss inlined) |
+
+**Success**: Team created, session file written, wisdom and explorations initialized.
+
+---
+
+## Phase 3: Create Task Chain
+
+**Objective**: Dispatch tasks based on mode with proper dependencies.
+
+Delegate to `commands/dispatch.md` which creates the full task chain:
+1. Reads SKILL.md Task Metadata Registry for task definitions
+2. Creates tasks via TaskCreate with correct blockedBy
+3. Assigns owner based on role mapping
+4. Includes `Session: <session-folder>` in every task description
+5. Marks inline discuss round in task description (e.g., `InlineDiscuss: DISCUSS-002`)
+
+---
+
+## Phase 4: Spawn-and-Stop
+
+**Objective**: Spawn first batch of ready workers in background, then STOP.
+
+**Design**: Spawn-and-Stop + Callback pattern, with worker fast-advance.
+- Spawn workers with `Task(run_in_background: true)` -> immediately return
+- Worker completes -> may fast-advance to next task OR SendMessage callback -> auto-advance
+- User can use "check" / "resume" to manually advance
+- Coordinator does one operation per invocation, then STOPS
+
+**Workflow**:
+1. Load `commands/monitor.md`
+2. Find tasks with: status=pending, blockedBy all resolved, owner assigned
+3. For each ready task -> spawn worker (see SKILL.md Spawn Template)
+4. Output status summary
+5. STOP
+
+**Pipeline advancement** driven by three wake sources:
+- Worker callback (automatic) -> Entry Router -> handleCallback
+- User "check" -> handleCheck (status only)
+- User "resume" -> handleResume (advance)
+
+### Checkpoint Gate Handling
+
+When QUALITY-001 completes (spec->impl transition checkpoint):
+
+1. Read `<session-folder>/spec/readiness-report.md`
+2. Parse quality gate: extract `Quality Gate:` line -> PASS/REVIEW/FAIL + score
+3. Parse dimension scores: extract `Dimension Scores` table
+4. Output Checkpoint Output Template (see SKILL.md Checkpoints) with gate-specific guidance
+5. Write gate result to team-session.json: `checkpoint_gate: { gate, score, dimensions }`
+6. Pause and wait for user command
+
+**Gate-specific behavior**:
+
+| Gate | Primary Suggestion | Warning |
+|------|-------------------|---------|
+| PASS (>=80%) | `resume` to proceed | None |
+| REVIEW (60-79%) | `improve` or `revise` first | Warn on `resume`: "Quality below target, proceed at risk" |
+| FAIL (<60%) | `improve` or `revise` required | Block `resume` suggestion, user can force |
+
+---
+
+## Phase 5: Report + Next Steps
+
+**Objective**: Completion report and follow-up options.
+
+**Workflow**:
+1. Load session state -> count completed tasks, duration
+2. List deliverables with output paths
+3. Update session status -> "completed"
+4. Offer next steps: exit / view artifacts / extend tasks / generate lite-plan / create Issue
+
+---
+
+## Error Handling
+
+| Error | Resolution |
+|-------|------------|
+| Task timeout | Log, mark failed, ask user to retry or skip |
+| Worker crash | Respawn worker, reassign task |
+| Dependency cycle | Detect, report to user, halt |
+| Invalid mode | Reject with error, ask to clarify |
+| Session corruption | Attempt recovery, fallback to manual reconciliation |