claude-code-workflow 7.2.23 → 7.2.25

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

@@ -1,115 +1,115 @@
----
-role: validator
-prefix: VALIDATE
-inner_loop: false
-message_types: [state_update]
----
-
-# Architecture Validator
-
-Validate refactoring changes by running build checks, test suites, dependency metric comparisons, and API compatibility verification. Ensure refactoring improves architecture without breaking functionality.
-
-## Phase 2: Environment & Baseline Loading
-
-| Input | Source | Required |
-|-------|--------|----------|
-| Architecture baseline | <session>/artifacts/architecture-baseline.json (shared) | Yes |
-| Refactoring plan / detail | Varies by mode (see below) | Yes |
-| .msg/meta.json | <session>/wisdom/.msg/meta.json | Yes |
-
-1. Extract session path from task description
-2. **Detect branch/pipeline context** from task description:
-
-| Task Description Field | Value | Context |
-|----------------------|-------|---------|
-| `BranchId: B{NN}` | Present | Fan-out branch -- validate only this branch's changes |
-| `PipelineId: {P}` | Present | Independent pipeline -- use pipeline-scoped baseline |
-| Neither present | - | Single mode -- full validation |
-
-3. **Load architecture baseline**:
-   - Single / Fan-out: Read `<session>/artifacts/architecture-baseline.json` (shared baseline)
-   - Independent: Read `<session>/artifacts/pipelines/{P}/architecture-baseline.json`
-
-4. **Load refactoring context**:
-   - Single: Read `<session>/artifacts/refactoring-plan.md` -- all success criteria
-   - Fan-out branch: Read `<session>/artifacts/branches/B{NN}/refactoring-detail.md` -- only this branch's criteria
-   - Independent: Read `<session>/artifacts/pipelines/{P}/refactoring-plan.md`
-
-5. Load .msg/meta.json for project type and refactoring scope
-6. Detect available validation tools from project:
-
-| Signal | Validation Tool | Method |
-|--------|----------------|--------|
-| package.json + tsc | TypeScript compiler | Type-check entire project |
-| package.json + vitest/jest | Test runner | Run existing test suite |
-| package.json + eslint | Linter | Run lint checks for import/export issues |
-| Cargo.toml | Rust compiler | cargo check + cargo test |
-| go.mod | Go tools | go build + go test |
-| Makefile with test target | Custom tests | make test |
-| No tooling detected | Manual validation | File existence + import grep checks |
-
-7. Get changed files scope from .msg/meta.json:
-   - Single: `refactorer` namespace
-   - Fan-out: `refactorer.B{NN}` namespace
-   - Independent: `refactorer.{P}` namespace
-
-## Phase 3: Validation Execution
-
-Run validations across four dimensions:
-
-**Build validation**:
-- Compile/type-check the project -- zero new errors allowed
-- Verify all moved/renamed files are correctly referenced
-- Check for missing imports or unresolved modules
-
-**Test validation**:
-- Run existing test suite -- all previously passing tests must still pass
-- Identify any tests that need updating due to module moves (update, don't skip)
-- Check for test file imports that reference old paths
-
-**Dependency metric validation**:
-- Recalculate architecture metrics post-refactoring
-- Compare coupling scores against baseline (must improve or stay neutral)
-- Verify no new circular dependencies introduced
-- Check cohesion metrics for affected modules
-
-**API compatibility validation**:
-- Verify public API signatures are preserved (exported function/class/type names)
-- Check for dangling references (imports pointing to removed/moved files)
-- Verify no new dead exports introduced by the refactoring
-- Check that re-exports maintain backward compatibility where needed
-
-**Branch-scoped validation** (fan-out mode):
-- Only validate metrics relevant to this branch's refactoring (from refactoring-detail.md)
-- Still check for regressions across all metrics (not just branch-specific ones)
-
-## Phase 4: Result Analysis
-
-Compare against baseline and plan criteria:
-
-| Metric | Threshold | Verdict |
-|--------|-----------|---------|
-| Build passes | Zero compilation errors | PASS |
-| All tests pass | No new test failures | PASS |
-| Coupling improved or neutral | No metric degradation > 5% | PASS |
-| No new cycles introduced | Cycle count <= baseline | PASS |
-| All plan success criteria met | Every criterion satisfied | PASS |
-| Partial improvement | Some metrics improved, none degraded | WARN |
-| Build fails | Compilation errors detected | FAIL -> fix_required |
-| Test failures | Previously passing tests now fail | FAIL -> fix_required |
-| New cycles introduced | Cycle count > baseline | FAIL -> fix_required |
-| Dangling references | Unresolved imports detected | FAIL -> fix_required |
-
-1. Write validation results to output path:
-   - Single: `<session>/artifacts/validation-results.json`
-   - Fan-out: `<session>/artifacts/branches/B{NN}/validation-results.json`
-   - Independent: `<session>/artifacts/pipelines/{P}/validation-results.json`
-   - Content: Per-dimension: name, baseline value, current value, improvement/regression, verdict; Overall verdict: PASS / WARN / FAIL; Failure details (if any)
-
-2. Update `<session>/wisdom/.msg/meta.json` under scoped namespace:
-   - Single: merge `{ "validator": { verdict, improvements, regressions, build_pass, test_pass } }`
-   - Fan-out: merge `{ "validator.B{NN}": { verdict, improvements, regressions, build_pass, test_pass } }`
-   - Independent: merge `{ "validator.{P}": { verdict, improvements, regressions, build_pass, test_pass } }`
-
-3. If verdict is FAIL, include detailed feedback in message for FIX task creation:
-   - Which validations failed, specific errors, suggested investigation areas
+---
+role: validator
+prefix: VALIDATE
+inner_loop: false
+message_types: [state_update]
+---
+
+# Architecture Validator
+
+Validate refactoring changes by running build checks, test suites, dependency metric comparisons, and API compatibility verification. Ensure refactoring improves architecture without breaking functionality.
+
+## Phase 2: Environment & Baseline Loading
+
+| Input | Source | Required |
+|-------|--------|----------|
+| Architecture baseline | <session>/artifacts/architecture-baseline.json (shared) | Yes |
+| Refactoring plan / detail | Varies by mode (see below) | Yes |
+| .msg/meta.json | <session>/wisdom/.msg/meta.json | Yes |
+
+1. Extract session path from task description
+2. **Detect branch/pipeline context** from task description:
+
+| Task Description Field | Value | Context |
+|----------------------|-------|---------|
+| `BranchId: B{NN}` | Present | Fan-out branch -- validate only this branch's changes |
+| `PipelineId: {P}` | Present | Independent pipeline -- use pipeline-scoped baseline |
+| Neither present | - | Single mode -- full validation |
+
+3. **Load architecture baseline**:
+   - Single / Fan-out: Read `<session>/artifacts/architecture-baseline.json` (shared baseline)
+   - Independent: Read `<session>/artifacts/pipelines/{P}/architecture-baseline.json`
+
+4. **Load refactoring context**:
+   - Single: Read `<session>/artifacts/refactoring-plan.md` -- all success criteria
+   - Fan-out branch: Read `<session>/artifacts/branches/B{NN}/refactoring-detail.md` -- only this branch's criteria
+   - Independent: Read `<session>/artifacts/pipelines/{P}/refactoring-plan.md`
+
+5. Load .msg/meta.json for project type and refactoring scope
+6. Detect available validation tools from project:
+
+| Signal | Validation Tool | Method |
+|--------|----------------|--------|
+| package.json + tsc | TypeScript compiler | Type-check entire project |
+| package.json + vitest/jest | Test runner | Run existing test suite |
+| package.json + eslint | Linter | Run lint checks for import/export issues |
+| Cargo.toml | Rust compiler | cargo check + cargo test |
+| go.mod | Go tools | go build + go test |
+| Makefile with test target | Custom tests | make test |
+| No tooling detected | Manual validation | File existence + import grep checks |
+
+7. Get changed files scope from .msg/meta.json:
+   - Single: `refactorer` namespace
+   - Fan-out: `refactorer.B{NN}` namespace
+   - Independent: `refactorer.{P}` namespace
+
+## Phase 3: Validation Execution
+
+Run validations across four dimensions:
+
+**Build validation**:
+- Compile/type-check the project -- zero new errors allowed
+- Verify all moved/renamed files are correctly referenced
+- Check for missing imports or unresolved modules
+
+**Test validation**:
+- Run existing test suite -- all previously passing tests must still pass
+- Identify any tests that need updating due to module moves (update, don't skip)
+- Check for test file imports that reference old paths
+
+**Dependency metric validation**:
+- Recalculate architecture metrics post-refactoring
+- Compare coupling scores against baseline (must improve or stay neutral)
+- Verify no new circular dependencies introduced
+- Check cohesion metrics for affected modules
+
+**API compatibility validation**:
+- Verify public API signatures are preserved (exported function/class/type names)
+- Check for dangling references (imports pointing to removed/moved files)
+- Verify no new dead exports introduced by the refactoring
+- Check that re-exports maintain backward compatibility where needed
+
+**Branch-scoped validation** (fan-out mode):
+- Only validate metrics relevant to this branch's refactoring (from refactoring-detail.md)
+- Still check for regressions across all metrics (not just branch-specific ones)
+
+## Phase 4: Result Analysis
+
+Compare against baseline and plan criteria:
+
+| Metric | Threshold | Verdict |
+|--------|-----------|---------|
+| Build passes | Zero compilation errors | PASS |
+| All tests pass | No new test failures | PASS |
+| Coupling improved or neutral | No metric degradation > 5% | PASS |
+| No new cycles introduced | Cycle count <= baseline | PASS |
+| All plan success criteria met | Every criterion satisfied | PASS |
+| Partial improvement | Some metrics improved, none degraded | WARN |
+| Build fails | Compilation errors detected | FAIL -> fix_required |
+| Test failures | Previously passing tests now fail | FAIL -> fix_required |
+| New cycles introduced | Cycle count > baseline | FAIL -> fix_required |
+| Dangling references | Unresolved imports detected | FAIL -> fix_required |
+
+1. Write validation results to output path:
+   - Single: `<session>/artifacts/validation-results.json`
+   - Fan-out: `<session>/artifacts/branches/B{NN}/validation-results.json`
+   - Independent: `<session>/artifacts/pipelines/{P}/validation-results.json`
+   - Content: Per-dimension: name, baseline value, current value, improvement/regression, verdict; Overall verdict: PASS / WARN / FAIL; Failure details (if any)
+
+2. Update `<session>/wisdom/.msg/meta.json` under scoped namespace:
+   - Single: merge `{ "validator": { verdict, improvements, regressions, build_pass, test_pass } }`
+   - Fan-out: merge `{ "validator.B{NN}": { verdict, improvements, regressions, build_pass, test_pass } }`
+   - Independent: merge `{ "validator.{P}": { verdict, improvements, regressions, build_pass, test_pass } }`
+
+3. If verdict is FAIL, include detailed feedback in message for FIX task creation:
+   - Which validations failed, specific errors, suggested investigation areas

package/.codex/skills/team-arch-opt/specs/pipelines.md

@@ -1,102 +1,102 @@
-# Pipeline Definitions — team-arch-opt
-
-## Available Pipelines
-
-### Single Mode (Linear)
-
-```
-ANALYZE-001 → DESIGN-001 → REFACTOR-001 → VALIDATE-001 + REVIEW-001
-[analyzer]    [designer]    [refactorer]    [validator]    [reviewer]
-                                ^                |
-                                +<-- FIX-001 ----+
-                                          (max 3 iterations)
-```
-
-### Fan-out Mode (Shared Stages + Parallel Branches)
-
-```
-ANALYZE-001 → DESIGN-001 --+→ REFACTOR-B01 → VALIDATE-B01 + REVIEW-B01
-[analyzer]    [designer]    |  [refactorer]    [validator]    [reviewer]
-                            +→ REFACTOR-B02 → VALIDATE-B02 + REVIEW-B02
-                            +→ REFACTOR-B0N → VALIDATE-B0N + REVIEW-B0N
-                                                           |
-                                                      AGGREGATE → Phase 5
-```
-
-Branch tasks created at CP-2.5 after DESIGN-001 completes.
-
-### Independent Mode (M Complete Pipelines)
-
-```
-Pipeline A: ANALYZE-A01 → DESIGN-A01 → REFACTOR-A01 → VALIDATE-A01 + REVIEW-A01
-Pipeline B: ANALYZE-B01 → DESIGN-B01 → REFACTOR-B01 → VALIDATE-B01 + REVIEW-B01
-...                                                               |
-                                                             AGGREGATE → Phase 5
-```
-
-### Auto Mode
-
-Auto-detects based on refactoring count at CP-2.5:
-- count <= 2 → switch to single mode
-- count >= 3 → switch to fan-out mode
-
-## Task Metadata Registry
-
-### Single Mode
-
-| Task ID | Role | Phase | Dependencies | Description |
-|---------|------|-------|-------------|-------------|
-| ANALYZE-001 | analyzer | Stage 1 | (none) | Analyze architecture, identify structural issues |
-| DESIGN-001 | designer | Stage 2 | ANALYZE-001 | Design refactoring plan from architecture report |
-| REFACTOR-001 | refactorer | Stage 3 | DESIGN-001 | Implement highest-priority refactorings |
-| VALIDATE-001 | validator | Stage 4 | REFACTOR-001 | Validate build, tests, metrics, API compatibility |
-| REVIEW-001 | reviewer | Stage 4 | REFACTOR-001 | Review refactoring code for correctness |
-| FIX-001 | refactorer | Stage 3 (cycle) | REVIEW-001 or VALIDATE-001 | Fix issues found in review/validation |
-
-### Fan-out Mode (Branch Tasks at CP-2.5)
-
-| Task ID | Role | Phase | Dependencies | Description |
-|---------|------|-------|-------------|-------------|
-| ANALYZE-001 | analyzer | Stage 1 (shared) | (none) | Analyze architecture |
-| DESIGN-001 | designer | Stage 2 (shared) | ANALYZE-001 | Design plan with discrete REFACTOR-IDs |
-| REFACTOR-B{NN} | refactorer | Stage 3 (branch) | DESIGN-001 | Implement REFACTOR-{NNN} only |
-| VALIDATE-B{NN} | validator | Stage 4 (branch) | REFACTOR-B{NN} | Validate branch B{NN} |
-| REVIEW-B{NN} | reviewer | Stage 4 (branch) | REFACTOR-B{NN} | Review branch B{NN} |
-| FIX-B{NN}-{cycle} | refactorer | Fix (branch) | (none) | Fix issues in branch B{NN} |
-
-### Independent Mode
-
-| Task ID | Role | Phase | Dependencies | Description |
-|---------|------|-------|-------------|-------------|
-| ANALYZE-{P}01 | analyzer | Stage 1 | (none) | Analyze for pipeline {P} target |
-| DESIGN-{P}01 | designer | Stage 2 | ANALYZE-{P}01 | Design for pipeline {P} |
-| REFACTOR-{P}01 | refactorer | Stage 3 | DESIGN-{P}01 | Implement pipeline {P} refactorings |
-| VALIDATE-{P}01 | validator | Stage 4 | REFACTOR-{P}01 | Validate pipeline {P} |
-| REVIEW-{P}01 | reviewer | Stage 4 | REFACTOR-{P}01 | Review pipeline {P} |
-
-## Checkpoints
-
-| Checkpoint | Trigger | Location | Behavior |
-|------------|---------|----------|----------|
-| CP-1 | ANALYZE-001 complete | After Stage 1 | User reviews architecture report, can refine scope |
-| CP-2 | DESIGN-001 complete | After Stage 2 | User reviews refactoring plan, can adjust priorities |
-| CP-2.5 | DESIGN-001 complete (auto/fan-out) | After Stage 2 | Auto-create N branch tasks, spawn all REFACTOR-B* in parallel |
-| CP-3 | REVIEW/VALIDATE fail | Stage 4 (per-branch) | Auto-create FIX task for that branch only (max 3x per branch) |
-| CP-4 | All tasks/branches complete | Phase 5 | Aggregate results, interactive completion action |
-
-## Task Naming Rules
-
-| Mode | Stage 3 | Stage 4 | Fix | Retry |
-|------|---------|---------|-----|-------|
-| Single | REFACTOR-001 | VALIDATE-001, REVIEW-001 | FIX-001 | VALIDATE-001-R1, REVIEW-001-R1 |
-| Fan-out | REFACTOR-B01 | VALIDATE-B01, REVIEW-B01 | FIX-B01-1 | VALIDATE-B01-R1, REVIEW-B01-R1 |
-| Independent | REFACTOR-A01 | VALIDATE-A01, REVIEW-A01 | FIX-A01-1 | VALIDATE-A01-R1, REVIEW-A01-R1 |
-
-## Parallel Mode Invocation
-
-```bash
-Skill(skill="team-arch-opt", args="<task-description>")                           # auto mode
-Skill(skill="team-arch-opt", args="--parallel-mode=fan-out <task-description>")   # force fan-out
-Skill(skill="team-arch-opt", args='--parallel-mode=independent "target1" "target2"')  # independent
-Skill(skill="team-arch-opt", args="--max-branches=3 <task-description>")           # limit branches
-```
+# Pipeline Definitions — team-arch-opt
+
+## Available Pipelines
+
+### Single Mode (Linear)
+
+```
+ANALYZE-001 → DESIGN-001 → REFACTOR-001 → VALIDATE-001 + REVIEW-001
+[analyzer]    [designer]    [refactorer]    [validator]    [reviewer]
+                                ^                |
+                                +<-- FIX-001 ----+
+                                          (max 3 iterations)
+```
+
+### Fan-out Mode (Shared Stages + Parallel Branches)
+
+```
+ANALYZE-001 → DESIGN-001 --+→ REFACTOR-B01 → VALIDATE-B01 + REVIEW-B01
+[analyzer]    [designer]    |  [refactorer]    [validator]    [reviewer]
+                            +→ REFACTOR-B02 → VALIDATE-B02 + REVIEW-B02
+                            +→ REFACTOR-B0N → VALIDATE-B0N + REVIEW-B0N
+                                                           |
+                                                      AGGREGATE → Phase 5
+```
+
+Branch tasks created at CP-2.5 after DESIGN-001 completes.
+
+### Independent Mode (M Complete Pipelines)
+
+```
+Pipeline A: ANALYZE-A01 → DESIGN-A01 → REFACTOR-A01 → VALIDATE-A01 + REVIEW-A01
+Pipeline B: ANALYZE-B01 → DESIGN-B01 → REFACTOR-B01 → VALIDATE-B01 + REVIEW-B01
+...                                                               |
+                                                             AGGREGATE → Phase 5
+```
+
+### Auto Mode
+
+Auto-detects based on refactoring count at CP-2.5:
+- count <= 2 → switch to single mode
+- count >= 3 → switch to fan-out mode
+
+## Task Metadata Registry
+
+### Single Mode
+
+| Task ID | Role | Phase | Dependencies | Description |
+|---------|------|-------|-------------|-------------|
+| ANALYZE-001 | analyzer | Stage 1 | (none) | Analyze architecture, identify structural issues |
+| DESIGN-001 | designer | Stage 2 | ANALYZE-001 | Design refactoring plan from architecture report |
+| REFACTOR-001 | refactorer | Stage 3 | DESIGN-001 | Implement highest-priority refactorings |
+| VALIDATE-001 | validator | Stage 4 | REFACTOR-001 | Validate build, tests, metrics, API compatibility |
+| REVIEW-001 | reviewer | Stage 4 | REFACTOR-001 | Review refactoring code for correctness |
+| FIX-001 | refactorer | Stage 3 (cycle) | REVIEW-001 or VALIDATE-001 | Fix issues found in review/validation |
+
+### Fan-out Mode (Branch Tasks at CP-2.5)
+
+| Task ID | Role | Phase | Dependencies | Description |
+|---------|------|-------|-------------|-------------|
+| ANALYZE-001 | analyzer | Stage 1 (shared) | (none) | Analyze architecture |
+| DESIGN-001 | designer | Stage 2 (shared) | ANALYZE-001 | Design plan with discrete REFACTOR-IDs |
+| REFACTOR-B{NN} | refactorer | Stage 3 (branch) | DESIGN-001 | Implement REFACTOR-{NNN} only |
+| VALIDATE-B{NN} | validator | Stage 4 (branch) | REFACTOR-B{NN} | Validate branch B{NN} |
+| REVIEW-B{NN} | reviewer | Stage 4 (branch) | REFACTOR-B{NN} | Review branch B{NN} |
+| FIX-B{NN}-{cycle} | refactorer | Fix (branch) | (none) | Fix issues in branch B{NN} |
+
+### Independent Mode
+
+| Task ID | Role | Phase | Dependencies | Description |
+|---------|------|-------|-------------|-------------|
+| ANALYZE-{P}01 | analyzer | Stage 1 | (none) | Analyze for pipeline {P} target |
+| DESIGN-{P}01 | designer | Stage 2 | ANALYZE-{P}01 | Design for pipeline {P} |
+| REFACTOR-{P}01 | refactorer | Stage 3 | DESIGN-{P}01 | Implement pipeline {P} refactorings |
+| VALIDATE-{P}01 | validator | Stage 4 | REFACTOR-{P}01 | Validate pipeline {P} |
+| REVIEW-{P}01 | reviewer | Stage 4 | REFACTOR-{P}01 | Review pipeline {P} |
+
+## Checkpoints
+
+| Checkpoint | Trigger | Location | Behavior |
+|------------|---------|----------|----------|
+| CP-1 | ANALYZE-001 complete | After Stage 1 | User reviews architecture report, can refine scope |
+| CP-2 | DESIGN-001 complete | After Stage 2 | User reviews refactoring plan, can adjust priorities |
+| CP-2.5 | DESIGN-001 complete (auto/fan-out) | After Stage 2 | Auto-create N branch tasks, spawn all REFACTOR-B* in parallel |
+| CP-3 | REVIEW/VALIDATE fail | Stage 4 (per-branch) | Auto-create FIX task for that branch only (max 3x per branch) |
+| CP-4 | All tasks/branches complete | Phase 5 | Aggregate results, interactive completion action |
+
+## Task Naming Rules
+
+| Mode | Stage 3 | Stage 4 | Fix | Retry |
+|------|---------|---------|-----|-------|
+| Single | REFACTOR-001 | VALIDATE-001, REVIEW-001 | FIX-001 | VALIDATE-001-R1, REVIEW-001-R1 |
+| Fan-out | REFACTOR-B01 | VALIDATE-B01, REVIEW-B01 | FIX-B01-1 | VALIDATE-B01-R1, REVIEW-B01-R1 |
+| Independent | REFACTOR-A01 | VALIDATE-A01, REVIEW-A01 | FIX-A01-1 | VALIDATE-A01-R1, REVIEW-A01-R1 |
+
+## Parallel Mode Invocation
+
+```bash
+Skill(skill="team-arch-opt", args="<task-description>")                           # auto mode
+Skill(skill="team-arch-opt", args="--parallel-mode=fan-out <task-description>")   # force fan-out
+Skill(skill="team-arch-opt", args='--parallel-mode=independent "target1" "target2"')  # independent
+Skill(skill="team-arch-opt", args="--max-branches=3 <task-description>")           # limit branches
+```

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

@@ -1,7 +1,7 @@
 ---
 name: team-brainstorm
 description: Unified team skill for brainstorming team. Uses team-worker agent architecture with role directories for domain logic. Coordinator orchestrates pipeline, workers are team-worker agents. Triggers on "team brainstorm".
-allowed-tools: spawn_agent(*), wait_agent(*), send_input(*), close_agent(*), report_agent_job_result(*), request_user_input(*), Read(*), Write(*), Edit(*), Bash(*), Glob(*), Grep(*)
+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(*)
 ---
 
 # Team Brainstorm
@@ -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 |
@@ -83,6 +84,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>
@@ -106,7 +109,7 @@ 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: <name> })` each worker.
 
 **Parallel ideator spawn** (Full pipeline with N angles):
 
@@ -115,6 +118,8 @@ When Full pipeline has N parallel IDEA tasks, spawn N distinct team-worker agent
 ```
 spawn_agent({
   agent_type: "team_worker",
+  task_name: "ideator-<N>",
+  fork_context: false,
   items: [
     { type: "text", text: `## Role Assignment
 role: ideator
@@ -139,7 +144,29 @@ 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: <name> })` each worker.
+
+
+### Model Selection Guide
+
+| Role | model | reasoning_effort | Rationale |
+|------|-------|-------------------|-----------|
+| Ideator (IDEA-*) | (default) | high | Creative divergent thinking requires full reasoning |
+| Challenger (CHALLENGE-*) | (default) | high | Critical analysis of ideas needs deep reasoning |
+| Synthesizer (SYNTH-*) | (default) | medium | Aggregation and convergence over generation |
+| Evaluator (EVAL-*) | (default) | medium | Scoring and ranking against criteria |
+
+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
 
@@ -178,6 +205,47 @@ After spawning, use `wait_agent({ ids: [...], timeout_ms: 900000 })` to collect
 
 - [specs/pipelines.md](specs/pipelines.md) — Pipeline definitions and task registry
 
+## v4 Agent Coordination
+
+### Message Semantics
+
+| Intent | API | Example |
+|--------|-----|---------|
+| Share idea context across ideators | `send_message` | Send seed ideas to running ideator for cross-pollination |
+| Not used in this skill | `assign_task` | No resident agents -- all workers are one-shot |
+| Check running agents | `list_agents` | Verify parallel ideator health during Full pipeline |
+
+### Parallel Ideator Coordination (Full Pipeline)
+
+Full pipeline spawns N parallel ideators for different brainstorming angles. Use batch spawn + wait:
+
+```
+// Spawn N ideators in parallel, each with a different angle
+const ideatorNames = ["IDEA-001", "IDEA-002", "IDEA-003"]
+for (const name of ideatorNames) {
+  spawn_agent({ agent_type: "team_worker", task_name: name, fork_context: false, ... })
+}
+wait_agent({ targets: ideatorNames, timeout_ms: 900000 })
+// Collect all idea outputs, feed to challenger as upstream context
+```
+
+### 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: "IDEA-002", items: [...] })` -- share context from another ideator
+- `close_agent({ target: "IDEA-001" })` -- cleanup by name after wait_agent returns
+
 ## Error Handling
 
 | Scenario | Resolution |