claude-code-workflow 7.2.23 → 7.2.25

package/.codex/skills/team-testing/roles/generator/role.md

@@ -1,95 +1,95 @@
----
-role: generator
-prefix: TESTGEN
-inner_loop: true
-message_types:
-  success: tests_generated
-  revision: tests_revised
-  error: error
----
-
-# Test Generator
-
-Generate test code by layer (L1 unit / L2 integration / L3 E2E). Acts as the Generator in the Generator-Critic loop. Supports revision mode for GC loop iterations.
-
-## Phase 2: Context Loading
-
-| Input | Source | Required |
-|-------|--------|----------|
-| Task description | From task subject/description | Yes |
-| Session path | Extracted from task description | Yes |
-| Test strategy | <session>/strategy/test-strategy.md | Yes |
-| .msg/meta.json | <session>/wisdom/.msg/meta.json | No |
-
-1. Extract session path and layer from task description
-2. Load test specs: Run `ccw spec load --category test` for test framework conventions and coverage targets
-3. Read test strategy:
-
-```
-Read("<session>/strategy/test-strategy.md")
-```
-
-3. Read source files to test (from strategy priority_files, limit 20)
-4. Read .msg/meta.json for framework and scope context
-
-5. Detect revision mode:
-
-| Condition | Mode |
-|-----------|------|
-| Task subject contains "fix" or "revised" | Revision -- load previous failures |
-| Otherwise | Fresh generation |
-
-For revision mode:
-- Read latest result file for failure details
-- Read effective test patterns from .msg/meta.json
-
-6. Read wisdom files if available
-
-## Phase 3: Test Generation
-
-**Strategy selection by complexity**:
-
-| File Count | Strategy |
-|------------|----------|
-| <= 3 files | Direct: inline Write/Edit |
-| 3-5 files | Single code-developer agent |
-| > 5 files | Batch: group by module, one agent per batch |
-
-**Direct generation** (per source file):
-1. Generate test path: `<session>/tests/<layer>/<test-file>`
-2. Generate test code: happy path, edge cases, error handling
-3. Write test file
-
-**CLI delegation** (medium/high complexity):
-
-```
-Bash(`ccw cli -p "PURPOSE: Generate <layer> tests using <framework> to achieve coverage target; success = all priority files covered with quality tests
-TASK: • Analyze source files • Generate test cases (happy path, edge cases, errors) • Write test files with proper structure • Ensure import resolution
-MODE: write
-CONTEXT: @<source-files> @<session>/strategy/test-strategy.md | Memory: Framework: <framework>, Layer: <layer>, Round: <round>
-<if-revision: Previous failures: <failure-details>
-Effective patterns: <patterns-from-meta>>
-EXPECTED: Test files in <session>/tests/<layer>/ with: proper test structure, comprehensive coverage, correct imports, framework conventions
-CONSTRAINTS: Follow test strategy priorities | Use framework best practices | <layer>-appropriate assertions
-Source files to test:
-<file-list-with-content>" --tool gemini --mode write --cd <session>`)
-```
-
-**Output verification**:
-
-```
-Glob("<session>/tests/<layer>/**/*")
-```
-
-## Phase 4: Self-Validation & State Update
-
-**Validation checks**:
-
-| Check | Method | Action on Fail |
-|-------|--------|----------------|
-| Syntax | `tsc --noEmit` or equivalent | Auto-fix imports/types |
-| File count | Count generated files | Report issue |
-| Import resolution | Check broken imports | Fix import paths |
-
-Update `<session>/wisdom/.msg/meta.json` under `generator` namespace:
-- Merge `{ "generator": { test_files, layer, round, is_revision } }`
+---
+role: generator
+prefix: TESTGEN
+inner_loop: true
+message_types:
+  success: tests_generated
+  revision: tests_revised
+  error: error
+---
+
+# Test Generator
+
+Generate test code by layer (L1 unit / L2 integration / L3 E2E). Acts as the Generator in the Generator-Critic loop. Supports revision mode for GC loop iterations.
+
+## Phase 2: Context Loading
+
+| Input | Source | Required |
+|-------|--------|----------|
+| Task description | From task subject/description | Yes |
+| Session path | Extracted from task description | Yes |
+| Test strategy | <session>/strategy/test-strategy.md | Yes |
+| .msg/meta.json | <session>/wisdom/.msg/meta.json | No |
+
+1. Extract session path and layer from task description
+2. Load test specs: Run `ccw spec load --category test` for test framework conventions and coverage targets
+3. Read test strategy:
+
+```
+Read("<session>/strategy/test-strategy.md")
+```
+
+3. Read source files to test (from strategy priority_files, limit 20)
+4. Read .msg/meta.json for framework and scope context
+
+5. Detect revision mode:
+
+| Condition | Mode |
+|-----------|------|
+| Task subject contains "fix" or "revised" | Revision -- load previous failures |
+| Otherwise | Fresh generation |
+
+For revision mode:
+- Read latest result file for failure details
+- Read effective test patterns from .msg/meta.json
+
+6. Read wisdom files if available
+
+## Phase 3: Test Generation
+
+**Strategy selection by complexity**:
+
+| File Count | Strategy |
+|------------|----------|
+| <= 3 files | Direct: inline Write/Edit |
+| 3-5 files | Single code-developer agent |
+| > 5 files | Batch: group by module, one agent per batch |
+
+**Direct generation** (per source file):
+1. Generate test path: `<session>/tests/<layer>/<test-file>`
+2. Generate test code: happy path, edge cases, error handling
+3. Write test file
+
+**CLI delegation** (medium/high complexity):
+
+```
+Bash(`ccw cli -p "PURPOSE: Generate <layer> tests using <framework> to achieve coverage target; success = all priority files covered with quality tests
+TASK: • Analyze source files • Generate test cases (happy path, edge cases, errors) • Write test files with proper structure • Ensure import resolution
+MODE: write
+CONTEXT: @<source-files> @<session>/strategy/test-strategy.md | Memory: Framework: <framework>, Layer: <layer>, Round: <round>
+<if-revision: Previous failures: <failure-details>
+Effective patterns: <patterns-from-meta>>
+EXPECTED: Test files in <session>/tests/<layer>/ with: proper test structure, comprehensive coverage, correct imports, framework conventions
+CONSTRAINTS: Follow test strategy priorities | Use framework best practices | <layer>-appropriate assertions
+Source files to test:
+<file-list-with-content>" --tool gemini --mode write --cd <session>`)
+```
+
+**Output verification**:
+
+```
+Glob("<session>/tests/<layer>/**/*")
+```
+
+## Phase 4: Self-Validation & State Update
+
+**Validation checks**:
+
+| Check | Method | Action on Fail |
+|-------|--------|----------------|
+| Syntax | `tsc --noEmit` or equivalent | Auto-fix imports/types |
+| File count | Count generated files | Report issue |
+| Import resolution | Check broken imports | Fix import paths |
+
+Update `<session>/wisdom/.msg/meta.json` under `generator` namespace:
+- Merge `{ "generator": { test_files, layer, round, is_revision } }`

package/.codex/skills/team-testing/roles/strategist/role.md

@@ -1,83 +1,83 @@
----
-role: strategist
-prefix: STRATEGY
-inner_loop: false
-message_types:
-  success: strategy_ready
-  error: error
----
-
-# Test Strategist
-
-Analyze git diff, determine test layers, define coverage targets, and formulate test strategy with prioritized execution order.
-
-## Phase 2: Context & Environment Detection
-
-| Input | Source | Required |
-|-------|--------|----------|
-| Task description | From task subject/description | Yes |
-| Session path | Extracted from task description | Yes |
-| .msg/meta.json | <session>/wisdom/.msg/meta.json | No |
-
-1. Extract session path and scope from task description
-2. Get git diff for change analysis:
-
-```
-Bash("git diff HEAD~1 --name-only 2>/dev/null || git diff --cached --name-only")
-Bash("git diff HEAD~1 -- <changed-files> 2>/dev/null || git diff --cached -- <changed-files>")
-```
-
-3. Detect test framework from project files:
-
-| Signal File | Framework | Test Pattern |
-|-------------|-----------|-------------|
-| jest.config.js/ts | Jest | `**/*.test.{ts,tsx,js}` |
-| vitest.config.ts/js | Vitest | `**/*.test.{ts,tsx}` |
-| pytest.ini / pyproject.toml | Pytest | `**/test_*.py` |
-| No detection | Default | Jest patterns |
-
-4. Scan existing test patterns:
-
-```
-Glob("**/*.test.*")
-Glob("**/*.spec.*")
-```
-
-5. Read .msg/meta.json if exists for session context
-
-## Phase 3: Strategy Formulation
-
-**Change analysis dimensions**:
-
-| Change Type | Analysis | Priority |
-|-------------|----------|----------|
-| New files | Need new tests | High |
-| Modified functions | Need updated tests | Medium |
-| Deleted files | Need test cleanup | Low |
-| Config changes | May need integration tests | Variable |
-
-**Strategy output structure**:
-
-1. **Change Analysis Table**: File, Change Type, Impact, Priority
-2. **Test Layer Recommendations**:
-   - L1 Unit: Scope, Coverage Target, Priority Files, Patterns
-   - L2 Integration: Scope, Coverage Target, Integration Points
-   - L3 E2E: Scope, Coverage Target, User Scenarios
-3. **Risk Assessment**: Risk, Probability, Impact, Mitigation
-4. **Test Execution Order**: Prioritized sequence
-
-Write strategy to `<session>/strategy/test-strategy.md`
-
-**Self-validation**:
-
-| Check | Criteria | Fallback |
-|-------|----------|----------|
-| Has L1 scope | L1 scope not empty | Default to all changed files |
-| Has coverage targets | L1 target > 0 | Use defaults (80/60/40) |
-| Has priority files | List not empty | Use all changed files |
-
-## Phase 4: Wisdom & State Update
-
-1. Write discoveries to `<session>/wisdom/conventions.md` (detected framework, patterns)
-2. Update `<session>/wisdom/.msg/meta.json` under `strategist` namespace:
-   - Read existing -> merge `{ "strategist": { framework, layers, coverage_targets, priority_files, risks } }` -> write back
+---
+role: strategist
+prefix: STRATEGY
+inner_loop: false
+message_types:
+  success: strategy_ready
+  error: error
+---
+
+# Test Strategist
+
+Analyze git diff, determine test layers, define coverage targets, and formulate test strategy with prioritized execution order.
+
+## Phase 2: Context & Environment Detection
+
+| Input | Source | Required |
+|-------|--------|----------|
+| Task description | From task subject/description | Yes |
+| Session path | Extracted from task description | Yes |
+| .msg/meta.json | <session>/wisdom/.msg/meta.json | No |
+
+1. Extract session path and scope from task description
+2. Get git diff for change analysis:
+
+```
+Bash("git diff HEAD~1 --name-only 2>/dev/null || git diff --cached --name-only")
+Bash("git diff HEAD~1 -- <changed-files> 2>/dev/null || git diff --cached -- <changed-files>")
+```
+
+3. Detect test framework from project files:
+
+| Signal File | Framework | Test Pattern |
+|-------------|-----------|-------------|
+| jest.config.js/ts | Jest | `**/*.test.{ts,tsx,js}` |
+| vitest.config.ts/js | Vitest | `**/*.test.{ts,tsx}` |
+| pytest.ini / pyproject.toml | Pytest | `**/test_*.py` |
+| No detection | Default | Jest patterns |
+
+4. Scan existing test patterns:
+
+```
+Glob("**/*.test.*")
+Glob("**/*.spec.*")
+```
+
+5. Read .msg/meta.json if exists for session context
+
+## Phase 3: Strategy Formulation
+
+**Change analysis dimensions**:
+
+| Change Type | Analysis | Priority |
+|-------------|----------|----------|
+| New files | Need new tests | High |
+| Modified functions | Need updated tests | Medium |
+| Deleted files | Need test cleanup | Low |
+| Config changes | May need integration tests | Variable |
+
+**Strategy output structure**:
+
+1. **Change Analysis Table**: File, Change Type, Impact, Priority
+2. **Test Layer Recommendations**:
+   - L1 Unit: Scope, Coverage Target, Priority Files, Patterns
+   - L2 Integration: Scope, Coverage Target, Integration Points
+   - L3 E2E: Scope, Coverage Target, User Scenarios
+3. **Risk Assessment**: Risk, Probability, Impact, Mitigation
+4. **Test Execution Order**: Prioritized sequence
+
+Write strategy to `<session>/strategy/test-strategy.md`
+
+**Self-validation**:
+
+| Check | Criteria | Fallback |
+|-------|----------|----------|
+| Has L1 scope | L1 scope not empty | Default to all changed files |
+| Has coverage targets | L1 target > 0 | Use defaults (80/60/40) |
+| Has priority files | List not empty | Use all changed files |
+
+## Phase 4: Wisdom & State Update
+
+1. Write discoveries to `<session>/wisdom/conventions.md` (detected framework, patterns)
+2. Update `<session>/wisdom/.msg/meta.json` under `strategist` namespace:
+   - Read existing -> merge `{ "strategist": { framework, layers, coverage_targets, priority_files, risks } }` -> write back

package/.codex/skills/team-testing/specs/pipelines.md

@@ -1,101 +1,101 @@
-# Testing Pipelines
-
-Pipeline definitions and task registry for team-testing.
-
-## Pipeline Selection
-
-| Condition | Pipeline |
-|-----------|----------|
-| fileCount <= 3 AND moduleCount <= 1 | targeted |
-| fileCount <= 10 AND moduleCount <= 3 | standard |
-| Otherwise | comprehensive |
-
-## Pipeline Definitions
-
-### Targeted Pipeline (3 tasks, serial)
-
-```
-STRATEGY-001 -> TESTGEN-001 -> TESTRUN-001
-```
-
-| Task ID | Role | Dependencies | Layer | Description |
-|---------|------|-------------|-------|-------------|
-| STRATEGY-001 | strategist | (none) | — | Analyze changes, define test strategy |
-| TESTGEN-001 | generator | STRATEGY-001 | L1 | Generate L1 unit tests |
-| TESTRUN-001 | executor | TESTGEN-001 | L1 | Execute L1 tests, collect coverage |
-
-### Standard Pipeline (6 tasks, progressive layers)
-
-```
-STRATEGY-001 -> TESTGEN-001 -> TESTRUN-001 -> TESTGEN-002 -> TESTRUN-002 -> TESTANA-001
-```
-
-| Task ID | Role | Dependencies | Layer | Description |
-|---------|------|-------------|-------|-------------|
-| STRATEGY-001 | strategist | (none) | — | Analyze changes, define test strategy |
-| TESTGEN-001 | generator | STRATEGY-001 | L1 | Generate L1 unit tests |
-| TESTRUN-001 | executor | TESTGEN-001 | L1 | Execute L1 tests, collect coverage |
-| TESTGEN-002 | generator | TESTRUN-001 | L2 | Generate L2 integration tests |
-| TESTRUN-002 | executor | TESTGEN-002 | L2 | Execute L2 tests, collect coverage |
-| TESTANA-001 | analyst | TESTRUN-002 | — | Defect pattern analysis, quality report |
-
-### Comprehensive Pipeline (8 tasks, parallel windows)
-
-```
-STRATEGY-001 -> [TESTGEN-001 || TESTGEN-002] -> [TESTRUN-001 || TESTRUN-002] -> TESTGEN-003 -> TESTRUN-003 -> TESTANA-001
-```
-
-| Task ID | Role | Dependencies | Layer | Description |
-|---------|------|-------------|-------|-------------|
-| STRATEGY-001 | strategist | (none) | — | Analyze changes, define test strategy |
-| TESTGEN-001 | generator-1 | STRATEGY-001 | L1 | Generate L1 unit tests (parallel) |
-| TESTGEN-002 | generator-2 | STRATEGY-001 | L2 | Generate L2 integration tests (parallel) |
-| TESTRUN-001 | executor-1 | TESTGEN-001 | L1 | Execute L1 tests (parallel) |
-| TESTRUN-002 | executor-2 | TESTGEN-002 | L2 | Execute L2 tests (parallel) |
-| TESTGEN-003 | generator | TESTRUN-001, TESTRUN-002 | L3 | Generate L3 E2E tests |
-| TESTRUN-003 | executor | TESTGEN-003 | L3 | Execute L3 tests, collect coverage |
-| TESTANA-001 | analyst | TESTRUN-003 | — | Defect pattern analysis, quality report |
-
-## GC Loop (Generator-Critic)
-
-Generator and executor iterate per test layer:
-
-```
-TESTGEN -> TESTRUN -> (if pass_rate < 0.95 OR coverage < target) -> TESTGEN-fix -> TESTRUN-fix
-                      (if pass_rate >= 0.95 AND coverage >= target) -> next layer or TESTANA
-```
-
-- Max iterations: 3 per layer
-- After 3 iterations: accept current state with warning
-
-## Coverage Targets
-
-| Layer | Name | Default Target |
-|-------|------|----------------|
-| L1 | Unit Tests | 80% |
-| L2 | Integration Tests | 60% |
-| L3 | E2E Tests | 40% |
-
-## Session Directory
-
-```
-.workflow/.team/TST-<slug>-<YYYY-MM-DD>/
-├── .msg/messages.jsonl          # Message bus log
-├── .msg/meta.json               # Session metadata
-├── wisdom/                     # Cross-task knowledge
-│   ├── learnings.md
-│   ├── decisions.md
-│   ├── conventions.md
-│   └── issues.md
-├── 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
-```
+# Testing Pipelines
+
+Pipeline definitions and task registry for team-testing.
+
+## Pipeline Selection
+
+| Condition | Pipeline |
+|-----------|----------|
+| fileCount <= 3 AND moduleCount <= 1 | targeted |
+| fileCount <= 10 AND moduleCount <= 3 | standard |
+| Otherwise | comprehensive |
+
+## Pipeline Definitions
+
+### Targeted Pipeline (3 tasks, serial)
+
+```
+STRATEGY-001 -> TESTGEN-001 -> TESTRUN-001
+```
+
+| Task ID | Role | Dependencies | Layer | Description |
+|---------|------|-------------|-------|-------------|
+| STRATEGY-001 | strategist | (none) | — | Analyze changes, define test strategy |
+| TESTGEN-001 | generator | STRATEGY-001 | L1 | Generate L1 unit tests |
+| TESTRUN-001 | executor | TESTGEN-001 | L1 | Execute L1 tests, collect coverage |
+
+### Standard Pipeline (6 tasks, progressive layers)
+
+```
+STRATEGY-001 -> TESTGEN-001 -> TESTRUN-001 -> TESTGEN-002 -> TESTRUN-002 -> TESTANA-001
+```
+
+| Task ID | Role | Dependencies | Layer | Description |
+|---------|------|-------------|-------|-------------|
+| STRATEGY-001 | strategist | (none) | — | Analyze changes, define test strategy |
+| TESTGEN-001 | generator | STRATEGY-001 | L1 | Generate L1 unit tests |
+| TESTRUN-001 | executor | TESTGEN-001 | L1 | Execute L1 tests, collect coverage |
+| TESTGEN-002 | generator | TESTRUN-001 | L2 | Generate L2 integration tests |
+| TESTRUN-002 | executor | TESTGEN-002 | L2 | Execute L2 tests, collect coverage |
+| TESTANA-001 | analyst | TESTRUN-002 | — | Defect pattern analysis, quality report |
+
+### Comprehensive Pipeline (8 tasks, parallel windows)
+
+```
+STRATEGY-001 -> [TESTGEN-001 || TESTGEN-002] -> [TESTRUN-001 || TESTRUN-002] -> TESTGEN-003 -> TESTRUN-003 -> TESTANA-001
+```
+
+| Task ID | Role | Dependencies | Layer | Description |
+|---------|------|-------------|-------|-------------|
+| STRATEGY-001 | strategist | (none) | — | Analyze changes, define test strategy |
+| TESTGEN-001 | generator-1 | STRATEGY-001 | L1 | Generate L1 unit tests (parallel) |
+| TESTGEN-002 | generator-2 | STRATEGY-001 | L2 | Generate L2 integration tests (parallel) |
+| TESTRUN-001 | executor-1 | TESTGEN-001 | L1 | Execute L1 tests (parallel) |
+| TESTRUN-002 | executor-2 | TESTGEN-002 | L2 | Execute L2 tests (parallel) |
+| TESTGEN-003 | generator | TESTRUN-001, TESTRUN-002 | L3 | Generate L3 E2E tests |
+| TESTRUN-003 | executor | TESTGEN-003 | L3 | Execute L3 tests, collect coverage |
+| TESTANA-001 | analyst | TESTRUN-003 | — | Defect pattern analysis, quality report |
+
+## GC Loop (Generator-Critic)
+
+Generator and executor iterate per test layer:
+
+```
+TESTGEN -> TESTRUN -> (if pass_rate < 0.95 OR coverage < target) -> TESTGEN-fix -> TESTRUN-fix
+                      (if pass_rate >= 0.95 AND coverage >= target) -> next layer or TESTANA
+```
+
+- Max iterations: 3 per layer
+- After 3 iterations: accept current state with warning
+
+## Coverage Targets
+
+| Layer | Name | Default Target |
+|-------|------|----------------|
+| L1 | Unit Tests | 80% |
+| L2 | Integration Tests | 60% |
+| L3 | E2E Tests | 40% |
+
+## Session Directory
+
+```
+.workflow/.team/TST-<slug>-<YYYY-MM-DD>/
+├── .msg/messages.jsonl          # Message bus log
+├── .msg/meta.json               # Session metadata
+├── wisdom/                     # Cross-task knowledge
+│   ├── learnings.md
+│   ├── decisions.md
+│   ├── conventions.md
+│   └── issues.md
+├── 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-uidesign/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: team-uidesign
 description: Unified team skill for UI design team. Research -> design tokens -> audit -> implementation. Uses team-worker agent architecture with roles/ for domain logic. Coordinator orchestrates dual-track pipeline with GC loops and sync points. Triggers on "team ui design", "ui design team".
-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(*), mcp__ccw-tools__read_file(*), mcp__ccw-tools__write_file(*), mcp__ccw-tools__edit_file(*), mcp__ccw-tools__team_msg(*)
+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(*), mcp__ccw-tools__read_file(*), mcp__ccw-tools__write_file(*), mcp__ccw-tools__edit_file(*), mcp__ccw-tools__team_msg(*)
 ---
 
 # Team UI Design
@@ -54,7 +54,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 |
@@ -85,6 +86,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>
@@ -108,7 +111,38 @@ 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
+
+UI design is a creative pipeline where research findings inform design decisions. Researcher needs thorough analysis, designer needs creative reasoning.
+
+| Role | reasoning_effort | Rationale |
+|------|-------------------|-----------|
+| researcher | high | Deep analysis of existing design systems and patterns |
+| designer | high | Creative design token/component spec generation |
+| reviewer | high | Design audit must catch consistency and accessibility issues |
+| implementer | medium | Implementation follows defined design specs |
+
+### Research-to-Design Context Flow
+
+Researcher findings must reach designer via coordinator's upstream context:
+```
+// After RESEARCH-001 completes, coordinator sends findings to designer
+spawn_agent({
+  agent_type: "team_worker",
+  task_name: "DESIGN-001",
+  fork_context: false,
+  items: [
+    ...,
+    { type: "text", text: `## Upstream Context
+Research findings: <session>/research/design-intelligence.json
+Component inventory: <session>/research/component-inventory.json
+Accessibility audit: <session>/research/accessibility-audit.json` }
+  ]
+})
+```
 
 ## User Commands
 
@@ -145,6 +179,34 @@ After spawning, use `wait_agent({ ids: [...], timeout_ms: 900000 })` to collect
 └── wisdom/                    # Cross-task knowledge
 ```
 
+## v4 Agent Coordination
+
+### Message Semantics
+
+| Intent | API | Example |
+|--------|-----|---------|
+| Queue supplementary info (don't interrupt) | `send_message` | Send research findings to running designer |
+| Assign build from reviewed specs | `assign_task` | Assign BUILD task after audit passes |
+| Check running agents | `list_agents` | Verify agent health during resume |
+
+### Agent Health Check
+
+Use `list_agents({})` in handleResume and handleComplete:
+
+```
+// Reconcile session state with actual running agents
+const running = list_agents({})
+// Compare with meta.json active tasks
+// 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: "DESIGN-001", items: [...] })` -- send additional research findings to designer
+- `assign_task({ target: "BUILD-001", items: [...] })` -- assign implementation from reviewed design specs
+- `close_agent({ target: "AUDIT-001" })` -- cleanup after design audit
+
 ## Error Handling
 
 | Scenario | Resolution |