claude-code-workflow 7.2.23 → 7.2.25

package/.codex/skills/team-quality-assurance/roles/scout/role.md

@@ -1,67 +1,67 @@
----
-role: scout
-prefix: SCOUT
-inner_loop: false
-message_types:
-  success: scan_ready
-  error: error
-  issues: issues_found
----
-
-# Multi-Perspective Scout
-
-Scan codebase from multiple perspectives (bug, security, test-coverage, code-quality, UX) to discover potential issues. Produce structured scan results with severity-ranked findings.
-
-## Phase 2: Context & Scope Assessment
-
-| 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. Determine scan scope: explicit scope from task or `**/*` default
-3. Get recent changed files: `git diff --name-only HEAD~5 2>/dev/null || echo ""`
-4. Read .msg/meta.json for historical defect patterns (`defect_patterns`)
-5. Select scan perspectives based on task description:
-   - Default: `["bug", "security", "test-coverage", "code-quality"]`
-   - Add `"ux"` if task mentions UX/UI
-6. Assess complexity to determine scan strategy:
-
-| Complexity | Condition | Strategy |
-|------------|-----------|----------|
-| Low | < 5 changed files, no specific keywords | ACE search + Grep inline |
-| Medium | 5-15 files or specific perspective requested | CLI fan-out (3 core perspectives) |
-| High | > 15 files or full-project scan | CLI fan-out (all perspectives) |
-
-## Phase 3: Multi-Perspective Scan
-
-**Low complexity**: Use `mcp__ace-tool__search_context` for quick pattern-based scan.
-
-**Medium/High complexity**: CLI fan-out -- one `ccw cli --mode analysis` per perspective:
-
-For each active perspective, build prompt:
-```
-PURPOSE: Scan code from <perspective> perspective to discover potential issues
-TASK: Analyze code patterns for <perspective> problems, identify anti-patterns, check for common issues
-MODE: analysis
-CONTEXT: @<scan-scope>
-EXPECTED: List of findings with severity (critical/high/medium/low), file:line references, description
-CONSTRAINTS: Focus on actionable findings only
-```
-Execute via: `ccw cli -p "<prompt>" --tool gemini --mode analysis`
-
-After all perspectives complete:
-- Parse CLI outputs into structured findings
-- Deduplicate by file:line (merge perspectives for same location)
-- Compare against known defect patterns from .msg/meta.json
-- Rank by severity: critical > high > medium > low
-
-## Phase 4: Result Aggregation
-
-1. Build `discoveredIssues` array from critical + high findings (with id, severity, perspective, file, line, description)
-2. Write scan results to `<session>/scan/scan-results.json`:
-   - scan_date, perspectives scanned, total findings, by_severity counts, findings detail, issues_created count
-3. Update `<session>/wisdom/.msg/meta.json`: merge `discovered_issues` field
-4. Contribute to wisdom/issues.md if new patterns found
+---
+role: scout
+prefix: SCOUT
+inner_loop: false
+message_types:
+  success: scan_ready
+  error: error
+  issues: issues_found
+---
+
+# Multi-Perspective Scout
+
+Scan codebase from multiple perspectives (bug, security, test-coverage, code-quality, UX) to discover potential issues. Produce structured scan results with severity-ranked findings.
+
+## Phase 2: Context & Scope Assessment
+
+| 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. Determine scan scope: explicit scope from task or `**/*` default
+3. Get recent changed files: `git diff --name-only HEAD~5 2>/dev/null || echo ""`
+4. Read .msg/meta.json for historical defect patterns (`defect_patterns`)
+5. Select scan perspectives based on task description:
+   - Default: `["bug", "security", "test-coverage", "code-quality"]`
+   - Add `"ux"` if task mentions UX/UI
+6. Assess complexity to determine scan strategy:
+
+| Complexity | Condition | Strategy |
+|------------|-----------|----------|
+| Low | < 5 changed files, no specific keywords | ACE search + Grep inline |
+| Medium | 5-15 files or specific perspective requested | CLI fan-out (3 core perspectives) |
+| High | > 15 files or full-project scan | CLI fan-out (all perspectives) |
+
+## Phase 3: Multi-Perspective Scan
+
+**Low complexity**: Use `mcp__ace-tool__search_context` for quick pattern-based scan.
+
+**Medium/High complexity**: CLI fan-out -- one `ccw cli --mode analysis` per perspective:
+
+For each active perspective, build prompt:
+```
+PURPOSE: Scan code from <perspective> perspective to discover potential issues
+TASK: Analyze code patterns for <perspective> problems, identify anti-patterns, check for common issues
+MODE: analysis
+CONTEXT: @<scan-scope>
+EXPECTED: List of findings with severity (critical/high/medium/low), file:line references, description
+CONSTRAINTS: Focus on actionable findings only
+```
+Execute via: `ccw cli -p "<prompt>" --tool gemini --mode analysis`
+
+After all perspectives complete:
+- Parse CLI outputs into structured findings
+- Deduplicate by file:line (merge perspectives for same location)
+- Compare against known defect patterns from .msg/meta.json
+- Rank by severity: critical > high > medium > low
+
+## Phase 4: Result Aggregation
+
+1. Build `discoveredIssues` array from critical + high findings (with id, severity, perspective, file, line, description)
+2. Write scan results to `<session>/scan/scan-results.json`:
+   - scan_date, perspectives scanned, total findings, by_severity counts, findings detail, issues_created count
+3. Update `<session>/wisdom/.msg/meta.json`: merge `discovered_issues` field
+4. Contribute to wisdom/issues.md if new patterns found

package/.codex/skills/team-quality-assurance/roles/strategist/role.md

@@ -1,71 +1,71 @@
----
-role: strategist
-prefix: QASTRAT
-inner_loop: false
-message_types:
-  success: strategy_ready
-  error: error
----
-
-# Test Strategist
-
-Analyze change scope, determine test layers (L1-L3), define coverage targets, and generate test strategy document. Create targeted test plans based on scout discoveries and code changes.
-
-## Phase 2: Context & Change Analysis
-
-| 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 | Yes |
-| Discovered issues | meta.json -> discovered_issues | No |
-| Defect patterns | meta.json -> defect_patterns | No |
-
-1. Extract session path from task description
-2. Read .msg/meta.json for scout discoveries and historical patterns
-3. Analyze change scope: `git diff --name-only HEAD~5`
-4. Categorize changed files:
-
-| Category | Pattern |
-|----------|---------|
-| Source | `\.(ts|tsx|js|jsx|py|java|go|rs)$` |
-| Test | `\.(test|spec)\.(ts|tsx|js|jsx)$` or `test_` |
-| Config | `\.(json|yaml|yml|toml|env)$` |
-
-5. Detect test framework from package.json / project files
-6. Check existing coverage baseline from `coverage/coverage-summary.json`
-7. Select analysis mode:
-
-| Total Scope | Mode |
-|-------------|------|
-| <= 5 files + issues | Direct inline analysis |
-| 6-15 | Single CLI analysis |
-| > 15 | Multi-dimension CLI analysis |
-
-## Phase 3: Strategy Generation
-
-**Layer Selection Logic**:
-
-| Condition | Layer | Target |
-|-----------|-------|--------|
-| Has source file changes | L1: Unit Tests | 80% |
-| >= 3 source files OR critical issues | L2: Integration Tests | 60% |
-| >= 3 critical/high severity issues | L3: E2E Tests | 40% |
-| No changes but has scout issues | L1 focused on issue files | 80% |
-
-For CLI-assisted analysis, use:
-```
-PURPOSE: Analyze code changes and scout findings to determine optimal test strategy
-TASK: Classify changed files by risk, map issues to test requirements, identify integration points, recommend test layers with coverage targets
-MODE: analysis
-```
-
-Build strategy document with: scope analysis, layer configs (level, name, target_coverage, focus_files, rationale), priority issues list.
-
-**Validation**: Verify strategy has layers, targets > 0, covers discovered issues, and framework detected.
-
-## Phase 4: Output & Persistence
-
-1. Write strategy to `<session>/strategy/test-strategy.md`
-2. Update `<session>/wisdom/.msg/meta.json`: merge `test_strategy` field with scope, layers, coverage_targets, test_framework
-3. Contribute to wisdom/decisions.md with layer selection rationale
+---
+role: strategist
+prefix: QASTRAT
+inner_loop: false
+message_types:
+  success: strategy_ready
+  error: error
+---
+
+# Test Strategist
+
+Analyze change scope, determine test layers (L1-L3), define coverage targets, and generate test strategy document. Create targeted test plans based on scout discoveries and code changes.
+
+## Phase 2: Context & Change Analysis
+
+| 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 | Yes |
+| Discovered issues | meta.json -> discovered_issues | No |
+| Defect patterns | meta.json -> defect_patterns | No |
+
+1. Extract session path from task description
+2. Read .msg/meta.json for scout discoveries and historical patterns
+3. Analyze change scope: `git diff --name-only HEAD~5`
+4. Categorize changed files:
+
+| Category | Pattern |
+|----------|---------|
+| Source | `\.(ts|tsx|js|jsx|py|java|go|rs)$` |
+| Test | `\.(test|spec)\.(ts|tsx|js|jsx)$` or `test_` |
+| Config | `\.(json|yaml|yml|toml|env)$` |
+
+5. Detect test framework from package.json / project files
+6. Check existing coverage baseline from `coverage/coverage-summary.json`
+7. Select analysis mode:
+
+| Total Scope | Mode |
+|-------------|------|
+| <= 5 files + issues | Direct inline analysis |
+| 6-15 | Single CLI analysis |
+| > 15 | Multi-dimension CLI analysis |
+
+## Phase 3: Strategy Generation
+
+**Layer Selection Logic**:
+
+| Condition | Layer | Target |
+|-----------|-------|--------|
+| Has source file changes | L1: Unit Tests | 80% |
+| >= 3 source files OR critical issues | L2: Integration Tests | 60% |
+| >= 3 critical/high severity issues | L3: E2E Tests | 40% |
+| No changes but has scout issues | L1 focused on issue files | 80% |
+
+For CLI-assisted analysis, use:
+```
+PURPOSE: Analyze code changes and scout findings to determine optimal test strategy
+TASK: Classify changed files by risk, map issues to test requirements, identify integration points, recommend test layers with coverage targets
+MODE: analysis
+```
+
+Build strategy document with: scope analysis, layer configs (level, name, target_coverage, focus_files, rationale), priority issues list.
+
+**Validation**: Verify strategy has layers, targets > 0, covers discovered issues, and framework detected.
+
+## Phase 4: Output & Persistence
+
+1. Write strategy to `<session>/strategy/test-strategy.md`
+2. Update `<session>/wisdom/.msg/meta.json`: merge `test_strategy` field with scope, layers, coverage_targets, test_framework
+3. Contribute to wisdom/decisions.md with layer selection rationale

package/.codex/skills/team-quality-assurance/specs/pipelines.md

@@ -1,115 +1,115 @@
-# QA Pipelines
-
-Pipeline definitions and task registry for team-quality-assurance.
-
-## Pipeline Modes
-
-| Mode | Description | Entry Role |
-|------|-------------|------------|
-| discovery | Scout-first: issue discovery then testing | scout |
-| testing | Skip scout, direct test pipeline | strategist |
-| full | Complete QA closed loop + regression scan | scout |
-
-## Pipeline Definitions
-
-### Discovery Mode (5 tasks, serial)
-
-```
-SCOUT-001 -> QASTRAT-001 -> QAGEN-001 -> QARUN-001 -> QAANA-001
-```
-
-| Task ID | Role | Dependencies | Description |
-|---------|------|-------------|-------------|
-| SCOUT-001 | scout | (none) | Multi-perspective issue scanning |
-| QASTRAT-001 | strategist | SCOUT-001 | Change scope analysis + test strategy |
-| QAGEN-001 | generator | QASTRAT-001 | L1 unit test generation |
-| QARUN-001 | executor | QAGEN-001 | L1 test execution + fix cycles |
-| QAANA-001 | analyst | QARUN-001 | Defect pattern analysis + quality report |
-
-### Testing Mode (6 tasks, progressive layers)
-
-```
-QASTRAT-001 -> QAGEN-L1-001 -> QARUN-L1-001 -> QAGEN-L2-001 -> QARUN-L2-001 -> QAANA-001
-```
-
-| Task ID | Role | Dependencies | Layer | Description |
-|---------|------|-------------|-------|-------------|
-| QASTRAT-001 | strategist | (none) | — | Test strategy formulation |
-| QAGEN-L1-001 | generator | QASTRAT-001 | L1 | L1 unit test generation |
-| QARUN-L1-001 | executor | QAGEN-L1-001 | L1 | L1 test execution + fix cycles |
-| QAGEN-L2-001 | generator | QARUN-L1-001 | L2 | L2 integration test generation |
-| QARUN-L2-001 | executor | QAGEN-L2-001 | L2 | L2 test execution + fix cycles |
-| QAANA-001 | analyst | QARUN-L2-001 | — | Quality analysis report |
-
-### Full Mode (8 tasks, parallel windows + regression)
-
-```
-SCOUT-001 -> QASTRAT-001 -> [QAGEN-L1-001 || QAGEN-L2-001] -> [QARUN-L1-001 || QARUN-L2-001] -> QAANA-001 -> SCOUT-002
-```
-
-| Task ID | Role | Dependencies | Layer | Description |
-|---------|------|-------------|-------|-------------|
-| SCOUT-001 | scout | (none) | — | Multi-perspective issue scanning |
-| QASTRAT-001 | strategist | SCOUT-001 | — | Test strategy formulation |
-| QAGEN-L1-001 | generator-1 | QASTRAT-001 | L1 | L1 unit test generation (parallel) |
-| QAGEN-L2-001 | generator-2 | QASTRAT-001 | L2 | L2 integration test generation (parallel) |
-| QARUN-L1-001 | executor-1 | QAGEN-L1-001 | L1 | L1 test execution + fix cycles (parallel) |
-| QARUN-L2-001 | executor-2 | QAGEN-L2-001 | L2 | L2 test execution + fix cycles (parallel) |
-| QAANA-001 | analyst | QARUN-L1-001, QARUN-L2-001 | — | Quality analysis report |
-| SCOUT-002 | scout | QAANA-001 | — | Regression scan after fixes |
-
-## GC Loop
-
-Generator-Executor iterate per test layer until coverage targets are met:
-
-```
-QAGEN -> QARUN -> (if coverage < target) -> QAGEN-fix -> QARUN-gc
-                  (if coverage >= target) -> next layer or QAANA
-```
-
-- Max iterations: 3 per layer
-- After 3 iterations: accept current coverage with warning
-
-## Coverage Targets
-
-| Layer | Name | Default Target |
-|-------|------|----------------|
-| L1 | Unit Tests | 80% |
-| L2 | Integration Tests | 60% |
-| L3 | E2E Tests | 40% |
-
-## Scan Perspectives
-
-| Perspective | Focus |
-|-------------|-------|
-| bug | Logic errors, crash paths, null references |
-| security | Vulnerabilities, auth bypass, data exposure |
-| test-coverage | Untested code paths, missing assertions |
-| code-quality | Anti-patterns, complexity, maintainability |
-| ux | User-facing issues, accessibility (optional) |
-
-## Session Directory
-
-```
-.workflow/.team/QA-<slug>-<YYYY-MM-DD>/
-├── .msg/messages.jsonl          # Message bus log
-├── .msg/meta.json               # Session state + cross-role state
-├── wisdom/                     # Cross-task knowledge
-│   ├── learnings.md
-│   ├── decisions.md
-│   ├── conventions.md
-│   └── issues.md
-├── scan/                       # Scout output
-│   └── scan-results.json
-├── strategy/                   # Strategist output
-│   └── test-strategy.md
-├── tests/                      # Generator output
-│   ├── L1-unit/
-│   ├── L2-integration/
-│   └── L3-e2e/
-├── results/                    # Executor output
-│   ├── run-001.json
-│   └── coverage-001.json
-└── analysis/                   # Analyst output
-    └── quality-report.md
-```
+# QA Pipelines
+
+Pipeline definitions and task registry for team-quality-assurance.
+
+## Pipeline Modes
+
+| Mode | Description | Entry Role |
+|------|-------------|------------|
+| discovery | Scout-first: issue discovery then testing | scout |
+| testing | Skip scout, direct test pipeline | strategist |
+| full | Complete QA closed loop + regression scan | scout |
+
+## Pipeline Definitions
+
+### Discovery Mode (5 tasks, serial)
+
+```
+SCOUT-001 -> QASTRAT-001 -> QAGEN-001 -> QARUN-001 -> QAANA-001
+```
+
+| Task ID | Role | Dependencies | Description |
+|---------|------|-------------|-------------|
+| SCOUT-001 | scout | (none) | Multi-perspective issue scanning |
+| QASTRAT-001 | strategist | SCOUT-001 | Change scope analysis + test strategy |
+| QAGEN-001 | generator | QASTRAT-001 | L1 unit test generation |
+| QARUN-001 | executor | QAGEN-001 | L1 test execution + fix cycles |
+| QAANA-001 | analyst | QARUN-001 | Defect pattern analysis + quality report |
+
+### Testing Mode (6 tasks, progressive layers)
+
+```
+QASTRAT-001 -> QAGEN-L1-001 -> QARUN-L1-001 -> QAGEN-L2-001 -> QARUN-L2-001 -> QAANA-001
+```
+
+| Task ID | Role | Dependencies | Layer | Description |
+|---------|------|-------------|-------|-------------|
+| QASTRAT-001 | strategist | (none) | — | Test strategy formulation |
+| QAGEN-L1-001 | generator | QASTRAT-001 | L1 | L1 unit test generation |
+| QARUN-L1-001 | executor | QAGEN-L1-001 | L1 | L1 test execution + fix cycles |
+| QAGEN-L2-001 | generator | QARUN-L1-001 | L2 | L2 integration test generation |
+| QARUN-L2-001 | executor | QAGEN-L2-001 | L2 | L2 test execution + fix cycles |
+| QAANA-001 | analyst | QARUN-L2-001 | — | Quality analysis report |
+
+### Full Mode (8 tasks, parallel windows + regression)
+
+```
+SCOUT-001 -> QASTRAT-001 -> [QAGEN-L1-001 || QAGEN-L2-001] -> [QARUN-L1-001 || QARUN-L2-001] -> QAANA-001 -> SCOUT-002
+```
+
+| Task ID | Role | Dependencies | Layer | Description |
+|---------|------|-------------|-------|-------------|
+| SCOUT-001 | scout | (none) | — | Multi-perspective issue scanning |
+| QASTRAT-001 | strategist | SCOUT-001 | — | Test strategy formulation |
+| QAGEN-L1-001 | generator-1 | QASTRAT-001 | L1 | L1 unit test generation (parallel) |
+| QAGEN-L2-001 | generator-2 | QASTRAT-001 | L2 | L2 integration test generation (parallel) |
+| QARUN-L1-001 | executor-1 | QAGEN-L1-001 | L1 | L1 test execution + fix cycles (parallel) |
+| QARUN-L2-001 | executor-2 | QAGEN-L2-001 | L2 | L2 test execution + fix cycles (parallel) |
+| QAANA-001 | analyst | QARUN-L1-001, QARUN-L2-001 | — | Quality analysis report |
+| SCOUT-002 | scout | QAANA-001 | — | Regression scan after fixes |
+
+## GC Loop
+
+Generator-Executor iterate per test layer until coverage targets are met:
+
+```
+QAGEN -> QARUN -> (if coverage < target) -> QAGEN-fix -> QARUN-gc
+                  (if coverage >= target) -> next layer or QAANA
+```
+
+- Max iterations: 3 per layer
+- After 3 iterations: accept current coverage with warning
+
+## Coverage Targets
+
+| Layer | Name | Default Target |
+|-------|------|----------------|
+| L1 | Unit Tests | 80% |
+| L2 | Integration Tests | 60% |
+| L3 | E2E Tests | 40% |
+
+## Scan Perspectives
+
+| Perspective | Focus |
+|-------------|-------|
+| bug | Logic errors, crash paths, null references |
+| security | Vulnerabilities, auth bypass, data exposure |
+| test-coverage | Untested code paths, missing assertions |
+| code-quality | Anti-patterns, complexity, maintainability |
+| ux | User-facing issues, accessibility (optional) |
+
+## Session Directory
+
+```
+.workflow/.team/QA-<slug>-<YYYY-MM-DD>/
+├── .msg/messages.jsonl          # Message bus log
+├── .msg/meta.json               # Session state + cross-role state
+├── wisdom/                     # Cross-task knowledge
+│   ├── learnings.md
+│   ├── decisions.md
+│   ├── conventions.md
+│   └── issues.md
+├── scan/                       # Scout output
+│   └── scan-results.json
+├── strategy/                   # Strategist output
+│   └── test-strategy.md
+├── tests/                      # Generator output
+│   ├── L1-unit/
+│   ├── L2-integration/
+│   └── L3-e2e/
+├── results/                    # Executor output
+│   ├── run-001.json
+│   └── coverage-001.json
+└── analysis/                   # Analyst output
+    └── quality-report.md
+```

package/.codex/skills/team-review/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: team-review
 description: "Unified team skill for code review. 3-role pipeline: scanner, reviewer, fixer. Triggers on team-review."
-allowed-tools: spawn_agent(*), wait_agent(*), send_input(*), close_agent(*), report_agent_job_result(*), request_user_input(*), Read(*), Write(*), Edit(*), Bash(*), Glob(*), Grep(*), mcp__ace-tool__search_context(*)
+allowed-tools: spawn_agent(*), wait_agent(*), send_message(*), assign_task(*), close_agent(*), list_agents(*), report_agent_job_result(*), request_user_input(*), Read(*), Write(*), Edit(*), Bash(*), Glob(*), Grep(*), mcp__ace-tool__search_context(*)
 ---
 
 # Team Review
@@ -53,7 +53,8 @@ Before calling ANY tool, apply this check:
 
 | Tool Call | Verdict | Reason |
 |-----------|---------|--------|
-| `spawn_agent`, `wait_agent`, `close_agent`, `send_input` | ALLOWED | Orchestration |
+| `spawn_agent`, `wait_agent`, `close_agent`, `send_message`, `assign_task` | ALLOWED | Orchestration |
+| `list_agents` | ALLOWED | Agent health check |
 | `request_user_input` | ALLOWED | User interaction |
 | `mcp__ccw-tools__team_msg` | ALLOWED | Message bus |
 | `Read/Write` on `.workflow/.team/` files | ALLOWED | Session state |
@@ -84,6 +85,8 @@ Coordinator spawns workers using this template:
 ```
 spawn_agent({
   agent_type: "team_worker",
+  task_name: "<task-id>",
+  fork_context: false,
   items: [
     { type: "text", text: `## Role Assignment
 role: <role>
@@ -107,7 +110,28 @@ pipeline_phase: <pipeline-phase>` },
 })
 ```
 
-After spawning, use `wait_agent({ ids: [...], timeout_ms: 900000 })` to collect results, then `close_agent({ id })` each worker.
+After spawning, use `wait_agent({ targets: [...], timeout_ms: 900000 })` to collect results, then `close_agent({ target })` each worker.
+
+
+### Model Selection Guide
+
+| Role | model | reasoning_effort | Rationale |
+|------|-------|-------------------|-----------|
+| Scanner (SCAN-*) | (default) | medium | Toolchain scanning + pattern matching, less reasoning |
+| Reviewer (REV-*) | (default) | high | Deep root cause analysis requires full reasoning |
+| Fixer (FIX-*) | (default) | high | Code modification needs precision |
+
+Override model/reasoning_effort in spawn_agent when cost optimization is needed:
+```
+spawn_agent({
+  agent_type: "team_worker",
+  task_name: "<task-id>",
+  fork_context: false,
+  model: "<model-override>",
+  reasoning_effort: "<effort-level>",
+  items: [...]
+})
+```
 
 ## User Commands
 
@@ -121,6 +145,37 @@ After spawning, use `wait_agent({ ids: [...], timeout_ms: 900000 })` to collect
 | `--dimensions=sec,cor,prf,mnt` | Custom dimensions |
 | `-y` / `--yes` | Skip confirmations |
 
+## v4 Agent Coordination
+
+### Message Semantics
+
+| Intent | API | Example |
+|--------|-----|---------|
+| Send scan findings to running reviewer | `send_message` | Queue scan results to REV-* as supplementary context |
+| Not used in this skill | `assign_task` | No resident agents -- sequential 3-stage pipeline |
+| Check running agents | `list_agents` | Verify agent health during resume |
+
+### Pipeline Pattern
+
+This is a **sequential 3-stage pipeline** (scan -> review -> fix). No parallel phases. Each stage completes before the next starts. The coordinator may skip stages (0 findings -> skip review+fix; user declines fix -> skip fix).
+
+### Agent Health Check
+
+Use `list_agents({})` in handleResume and handleComplete:
+
+```
+// Reconcile session state with actual running agents
+const running = list_agents({})
+// Compare with tasks.json active_agents
+// Reset orphaned tasks (in_progress but agent gone) to pending
+```
+
+### Named Agent Targeting
+
+Workers are spawned with `task_name: "<task-id>"` enabling direct addressing:
+- `send_message({ target: "REV-001", items: [...] })` -- queue scan findings to running reviewer
+- `close_agent({ target: "SCAN-001" })` -- cleanup by name after completion
+
 ## Completion Action
 
 When pipeline completes, coordinator presents: