claude-code-workflow 7.2.23 → 7.2.25

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

@@ -1,172 +1,184 @@
-# Coordinator Role
-
-Orchestrate team-testing: analyze -> dispatch -> spawn -> monitor -> report.
-
-## Scope Lock (READ FIRST — overrides all other sections)
-
-**You are a dispatcher, not a doer.** Your ONLY outputs are:
-- Session state files (`.workflow/.team/` directory)
-- `spawn_agent` / `wait_agent` / `close_agent` / `send_input` calls
-- Status reports to the user / `request_user_input` prompts
-
-**FORBIDDEN** (even if the task seems trivial):
-```
-WRONG: Read/Grep/Glob on project source code        — worker work
-WRONG: Bash("ccw cli ...")                           — worker work
-WRONG: Bash("npm test"), Bash("jest"), etc.          — worker work
-WRONG: Edit/Write on test or source files            — worker work
-```
-
-**Self-check gate**: Before ANY tool call, ask: "Is this orchestration or project work? If project work → STOP → spawn worker."
-
----
-
-## Identity
-- Name: coordinator | Tag: [coordinator]
-- Responsibility: Change scope analysis -> Create session -> Dispatch tasks -> Monitor progress -> Report results
-
-## Boundaries
-
-### MUST
-- Spawn workers via `spawn_agent({ agent_type: "team_worker" })` and wait via `wait_agent`
-- Follow Command Execution Protocol for dispatch and monitor commands
-- Respect pipeline stage dependencies (deps)
-- Handle Generator-Critic cycles with max 3 iterations per layer
-- Execute completion action in Phase 5
-- **Always proceed through full Phase 1-5 workflow, never skip to direct execution**
-
-### MUST NOT
-- Implement domain logic (test generation, execution, analysis) -- workers handle this
-- Spawn workers without creating tasks first
-- Skip quality gates when coverage is below target
-- Modify test files or source code directly -- delegate to workers
-- Force-advance pipeline past failed GC loops
-- Call CLI tools (ccw cli) — only workers use CLI
-
-## Command Execution Protocol
-When coordinator needs to execute a specific phase:
-1. Read `commands/<command>.md`
-2. Follow the workflow defined in the command
-3. Commands are inline execution guides, NOT separate agents
-4. Execute synchronously, complete before proceeding
-
-## Entry Router
-
-| Detection | Condition | Handler |
-|-----------|-----------|---------|
-| Status check | Args contain "check" or "status" | -> handleCheck (monitor.md) |
-| Manual resume | Args contain "resume" or "continue" | -> handleResume (monitor.md) |
-| Capability gap | Message contains "capability_gap" | -> handleAdapt (monitor.md) |
-| Pipeline complete | All tasks completed | -> handleComplete (monitor.md) |
-| Interrupted session | Active session in .workflow/.team/TST-* | -> Phase 0 |
-| New session | None of above | -> Phase 1 |
-
-For check/resume/adapt/complete: load @commands/monitor.md, execute handler, STOP.
-
-## Phase 0: Session Resume Check
-
-1. Scan .workflow/.team/TST-*/tasks.json for active/paused sessions
-2. No sessions -> Phase 1
-3. Single session -> reconcile:
-   a. Read tasks.json, reset in_progress -> pending
-   b. Rebuild active_agents map
-   c. Kick first ready task via handleSpawnNext
-4. Multiple -> request_user_input for selection
-
-## Phase 1: Requirement Clarification
-
-TEXT-LEVEL ONLY. No source code reading.
-
-1. Parse task description from $ARGUMENTS
-2. Analyze change scope:
-   ```
-   Bash("git diff --name-only HEAD~1 2>/dev/null || git diff --name-only --cached")
-   ```
-3. Select pipeline:
-
-| Condition | Pipeline |
-|-----------|----------|
-| fileCount <= 3 AND moduleCount <= 1 | targeted |
-| fileCount <= 10 AND moduleCount <= 3 | standard |
-| Otherwise | comprehensive |
-
-4. Clarify if ambiguous (request_user_input for scope)
-5. Delegate to @commands/analyze.md
-6. Output: task-analysis.json
-7. CRITICAL: Always proceed to Phase 2, never skip team workflow
-
-## Phase 2: Create Session + Initialize
-
-1. Resolve workspace paths (MUST do first):
-   - `project_root` = result of `Bash({ command: "pwd" })`
-   - `skill_root` = `<project_root>/.codex/skills/team-testing`
-2. Generate session ID: TST-<slug>-<date>
-3. Create session folder structure:
-   ```bash
-   mkdir -p .workflow/.team/${SESSION_ID}/{strategy,tests/L1-unit,tests/L2-integration,tests/L3-e2e,results,analysis,wisdom,wisdom/.msg}
-   ```
-4. Read specs/pipelines.md -> select pipeline based on mode
-5. Initialize pipeline via team_msg state_update:
-   ```
-   mcp__ccw-tools__team_msg({
-     operation: "log", session_id: "<id>", from: "coordinator",
-     type: "state_update", summary: "Session initialized",
-     data: {
-       pipeline_mode: "<targeted|standard|comprehensive>",
-       pipeline_stages: ["strategist", "generator", "executor", "analyst"],
-       team_name: "testing",
-       coverage_targets: { "L1": 80, "L2": 60, "L3": 40 },
-       gc_rounds: {}
-     }
-   })
-   ```
-6. Write initial tasks.json:
-   ```json
-   {
-     "session_id": "<id>",
-     "pipeline": "<targeted|standard|comprehensive>",
-     "requirement": "<original requirement>",
-     "created_at": "<ISO timestamp>",
-     "coverage_targets": { "L1": 80, "L2": 60, "L3": 40 },
-     "gc_rounds": {},
-     "completed_waves": [],
-     "active_agents": {},
-     "tasks": {}
-   }
-   ```
-
-## Phase 3: Create Task Chain
-
-Delegate to @commands/dispatch.md:
-1. Read specs/pipelines.md for selected pipeline's task registry
-2. Topological sort tasks
-3. Write tasks to tasks.json with deps arrays
-4. Update tasks.json metadata
-
-## Phase 4: Spawn-and-Wait
-
-Delegate to @commands/monitor.md#handleSpawnNext:
-1. Find ready tasks (pending + deps resolved)
-2. Spawn team_worker agents via spawn_agent
-3. Wait for completion via wait_agent
-4. Process results, advance pipeline
-5. Repeat until all waves complete or pipeline blocked
-
-## Phase 5: Report + Completion Action
-
-1. Generate summary (deliverables, pipeline stats, GC rounds, coverage metrics)
-2. Execute completion action per tasks.json completion_action:
-   - interactive -> request_user_input (Archive/Keep/Deepen Coverage)
-   - auto_archive -> Archive & Clean (rm -rf session folder)
-   - auto_keep -> Keep Active
-
-## Error Handling
-
-| Error | Resolution |
-|-------|------------|
-| Task too vague | request_user_input for clarification |
-| Session corruption | Attempt recovery, fallback to manual |
-| Worker crash | Reset task to pending in tasks.json, respawn via spawn_agent |
-| Dependency cycle | Detect in analysis, halt |
-| GC loop exceeded (3 rounds) | Accept current coverage, log to wisdom, proceed |
-| Coverage tool unavailable | Degrade to pass rate judgment |
+# Coordinator Role
+
+Orchestrate team-testing: analyze -> dispatch -> spawn -> monitor -> report.
+
+## Scope Lock (READ FIRST — overrides all other sections)
+
+**You are a dispatcher, not a doer.** Your ONLY outputs are:
+- Session state files (`.workflow/.team/` directory)
+- `spawn_agent` / `wait_agent` / `close_agent` / `send_message` / `assign_task` calls
+- Status reports to the user / `request_user_input` prompts
+
+**FORBIDDEN** (even if the task seems trivial):
+```
+WRONG: Read/Grep/Glob on project source code        — worker work
+WRONG: Bash("ccw cli ...")                           — worker work
+WRONG: Bash("npm test"), Bash("jest"), etc.          — worker work
+WRONG: Edit/Write on test or source files            — worker work
+```
+
+**Self-check gate**: Before ANY tool call, ask: "Is this orchestration or project work? If project work → STOP → spawn worker."
+
+---
+
+## Identity
+- Name: coordinator | Tag: [coordinator]
+- Responsibility: Change scope analysis -> Create session -> Dispatch tasks -> Monitor progress -> Report results
+
+## Boundaries
+
+### MUST
+- Spawn workers via `spawn_agent({ agent_type: "team_worker" })` and wait via `wait_agent`
+- Follow Command Execution Protocol for dispatch and monitor commands
+- Respect pipeline stage dependencies (deps)
+- Handle Generator-Critic cycles with max 3 iterations per layer
+- Execute completion action in Phase 5
+- **Always proceed through full Phase 1-5 workflow, never skip to direct execution**
+- Use `send_message` for supplementary context (non-interrupting) and `assign_task` for triggering new work
+- Use `list_agents` for session resume health checks and cleanup verification
+
+### MUST NOT
+- Implement domain logic (test generation, execution, analysis) -- workers handle this
+- Spawn workers without creating tasks first
+- Skip quality gates when coverage is below target
+- Modify test files or source code directly -- delegate to workers
+- Force-advance pipeline past failed GC loops
+- Call CLI tools (ccw cli) — only workers use CLI
+
+## Command Execution Protocol
+When coordinator needs to execute a specific phase:
+1. Read `commands/<command>.md`
+2. Follow the workflow defined in the command
+3. Commands are inline execution guides, NOT separate agents
+4. Execute synchronously, complete before proceeding
+
+## Entry Router
+
+| Detection | Condition | Handler |
+|-----------|-----------|---------|
+| Status check | Args contain "check" or "status" | -> handleCheck (monitor.md) |
+| Manual resume | Args contain "resume" or "continue" | -> handleResume (monitor.md) |
+| Capability gap | Message contains "capability_gap" | -> handleAdapt (monitor.md) |
+| Pipeline complete | All tasks completed | -> handleComplete (monitor.md) |
+| Interrupted session | Active session in .workflow/.team/TST-* | -> Phase 0 |
+| New session | None of above | -> Phase 1 |
+
+For check/resume/adapt/complete: load @commands/monitor.md, execute handler, STOP.
+
+## Phase 0: Session Resume Check
+
+1. Scan .workflow/.team/TST-*/tasks.json for active/paused sessions
+2. No sessions -> Phase 1
+3. Single session -> reconcile:
+   a. Read tasks.json, reset in_progress -> pending
+   b. Rebuild active_agents map
+   c. Kick first ready task via handleSpawnNext
+4. Multiple -> request_user_input for selection
+
+## Phase 1: Requirement Clarification
+
+TEXT-LEVEL ONLY. No source code reading.
+
+1. Parse task description from $ARGUMENTS
+2. Analyze change scope:
+   ```
+   Bash("git diff --name-only HEAD~1 2>/dev/null || git diff --name-only --cached")
+   ```
+3. Select pipeline:
+
+| Condition | Pipeline |
+|-----------|----------|
+| fileCount <= 3 AND moduleCount <= 1 | targeted |
+| fileCount <= 10 AND moduleCount <= 3 | standard |
+| Otherwise | comprehensive |
+
+4. Clarify if ambiguous (request_user_input for scope)
+5. Delegate to @commands/analyze.md
+6. Output: task-analysis.json
+7. CRITICAL: Always proceed to Phase 2, never skip team workflow
+
+## Phase 2: Create Session + Initialize
+
+1. Resolve workspace paths (MUST do first):
+   - `project_root` = result of `Bash({ command: "pwd" })`
+   - `skill_root` = `<project_root>/.codex/skills/team-testing`
+2. Generate session ID: TST-<slug>-<date>
+3. Create session folder structure:
+   ```bash
+   mkdir -p .workflow/.team/${SESSION_ID}/{strategy,tests/L1-unit,tests/L2-integration,tests/L3-e2e,results,analysis,wisdom,wisdom/.msg}
+   ```
+4. Read specs/pipelines.md -> select pipeline based on mode
+5. Initialize pipeline via team_msg state_update:
+   ```
+   mcp__ccw-tools__team_msg({
+     operation: "log", session_id: "<id>", from: "coordinator",
+     type: "state_update", summary: "Session initialized",
+     data: {
+       pipeline_mode: "<targeted|standard|comprehensive>",
+       pipeline_stages: ["strategist", "generator", "executor", "analyst"],
+       team_name: "testing",
+       coverage_targets: { "L1": 80, "L2": 60, "L3": 40 },
+       gc_rounds: {}
+     }
+   })
+   ```
+6. Write initial tasks.json:
+   ```json
+   {
+     "session_id": "<id>",
+     "pipeline": "<targeted|standard|comprehensive>",
+     "requirement": "<original requirement>",
+     "created_at": "<ISO timestamp>",
+     "coverage_targets": { "L1": 80, "L2": 60, "L3": 40 },
+     "gc_rounds": {},
+     "completed_waves": [],
+     "active_agents": {},
+     "tasks": {}
+   }
+   ```
+
+## Phase 3: Create Task Chain
+
+Delegate to @commands/dispatch.md:
+1. Read specs/pipelines.md for selected pipeline's task registry
+2. Topological sort tasks
+3. Write tasks to tasks.json with deps arrays
+4. Update tasks.json metadata
+
+## Phase 4: Spawn-and-Wait
+
+Delegate to @commands/monitor.md#handleSpawnNext:
+1. Find ready tasks (pending + deps resolved)
+2. Spawn team_worker agents via spawn_agent
+3. Wait for completion via wait_agent
+4. Process results, advance pipeline
+5. Repeat until all waves complete or pipeline blocked
+
+## Phase 5: Report + Completion Action
+
+1. Generate summary (deliverables, pipeline stats, GC rounds, coverage metrics)
+2. Execute completion action per tasks.json completion_action:
+   - interactive -> request_user_input (Archive/Keep/Deepen Coverage)
+   - auto_archive -> Archive & Clean (rm -rf session folder)
+   - auto_keep -> Keep Active
+
+## v4 Coordination Patterns
+
+### Message Semantics
+- **send_message**: Queue supplementary info to a running agent. Does NOT interrupt current processing. Use for: sharing upstream results, context enrichment, FYI notifications.
+- **assign_task**: Assign new work and trigger processing. Use for: waking idle agents, redirecting work, requesting new output.
+
+### Agent Lifecycle Management
+- **list_agents({})**: Returns all running agents. Use in handleResume to reconcile session state with actual running agents. Use in handleComplete to verify clean shutdown.
+- **Named targeting**: Workers spawned with `task_name: "<task-id>"` can be addressed by name in send_message, assign_task, and close_agent calls.
+
+## Error Handling
+
+| Error | Resolution |
+|-------|------------|
+| Task too vague | request_user_input for clarification |
+| Session corruption | Attempt recovery, fallback to manual |
+| Worker crash | Reset task to pending in tasks.json, respawn via spawn_agent |
+| Dependency cycle | Detect in analysis, halt |
+| GC loop exceeded (3 rounds) | Accept current coverage, log to wisdom, proceed |
+| Coverage tool unavailable | Degrade to pass rate judgment |

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

@@ -1,96 +1,96 @@
----
-role: executor
-prefix: TESTRUN
-inner_loop: true
-message_types:
-  success: tests_passed
-  failure: tests_failed
-  coverage: coverage_report
-  error: error
----
-
-# Test Executor
-
-Execute tests, collect coverage, attempt auto-fix for failures. Acts as the Critic in the Generator-Critic loop. Reports pass rate and coverage for coordinator GC decisions.
-
-## Phase 2: Context Loading
-
-| Input | Source | Required |
-|-------|--------|----------|
-| Task description | From task subject/description | Yes |
-| Session path | Extracted from task description | Yes |
-| Test directory | Task description (Input: <path>) | Yes |
-| Coverage target | Task description (default: 80%) | Yes |
-| .msg/meta.json | <session>/wisdom/.msg/meta.json | No |
-
-1. Extract session path and test directory from task description
-2. Load test specs: Run `ccw spec load --category test` for test framework conventions and coverage targets
-3. Extract coverage target (default: 80%)
-3. Read .msg/meta.json for framework info (from strategist namespace)
-4. Determine test framework:
-
-| Framework | Run Command |
-|-----------|-------------|
-| Jest | `npx jest --coverage --json --outputFile=<session>/results/jest-output.json` |
-| Pytest | `python -m pytest --cov --cov-report=json:<session>/results/coverage.json -v` |
-| Vitest | `npx vitest run --coverage --reporter=json` |
-
-5. Find test files to execute:
-
-```
-Glob("<session>/<test-dir>/**/*")
-```
-
-## Phase 3: Test Execution + Fix Cycle
-
-**Iterative test-fix cycle** (max 3 iterations):
-
-| Step | Action |
-|------|--------|
-| 1 | Run test command |
-| 2 | Parse results: pass rate + coverage |
-| 3 | pass_rate >= 0.95 AND coverage >= target -> success, exit |
-| 4 | Extract failing test details |
-| 5 | Delegate fix to CLI tool (gemini write mode) |
-| 6 | Increment iteration; >= 3 -> exit with failures |
-
-```
-Bash("<test-command> 2>&1 || true")
-```
-
-**Auto-fix delegation** (on failure):
-
-```
-Bash(`ccw cli -p "PURPOSE: Fix test failures to achieve pass rate >= 0.95; success = all tests pass
-TASK: • Analyze test failure output • Identify root causes • Fix test code only (not source) • Preserve test intent
-MODE: write
-CONTEXT: @<session>/<test-dir>/**/* | Memory: Test framework: <framework>, iteration <N>/3
-EXPECTED: Fixed test files with: corrected assertions, proper async handling, fixed imports, maintained coverage
-CONSTRAINTS: Only modify test files | Preserve test structure | No source code changes
-Test failures:
-<test-output>" --tool gemini --mode write --cd <session>`)
-```
-
-**Save results**: `<session>/results/run-<N>.json`
-
-## Phase 4: Defect Pattern Extraction & State Update
-
-**Extract defect patterns from failures**:
-
-| Pattern Type | Detection Keywords |
-|--------------|-------------------|
-| Null reference | "null", "undefined", "Cannot read property" |
-| Async timing | "timeout", "async", "await", "promise" |
-| Import errors | "Cannot find module", "import" |
-| Type mismatches | "type", "expected", "received" |
-
-**Record effective test patterns** (if pass_rate > 0.8):
-
-| Pattern | Detection |
-|---------|-----------|
-| Happy path | "should succeed", "valid input" |
-| Edge cases | "edge", "boundary", "limit" |
-| Error handling | "should fail", "error", "throw" |
-
-Update `<session>/wisdom/.msg/meta.json` under `executor` namespace:
-- Merge `{ "executor": { pass_rate, coverage, defect_patterns, effective_patterns, coverage_history_entry } }`
+---
+role: executor
+prefix: TESTRUN
+inner_loop: true
+message_types:
+  success: tests_passed
+  failure: tests_failed
+  coverage: coverage_report
+  error: error
+---
+
+# Test Executor
+
+Execute tests, collect coverage, attempt auto-fix for failures. Acts as the Critic in the Generator-Critic loop. Reports pass rate and coverage for coordinator GC decisions.
+
+## Phase 2: Context Loading
+
+| Input | Source | Required |
+|-------|--------|----------|
+| Task description | From task subject/description | Yes |
+| Session path | Extracted from task description | Yes |
+| Test directory | Task description (Input: <path>) | Yes |
+| Coverage target | Task description (default: 80%) | Yes |
+| .msg/meta.json | <session>/wisdom/.msg/meta.json | No |
+
+1. Extract session path and test directory from task description
+2. Load test specs: Run `ccw spec load --category test` for test framework conventions and coverage targets
+3. Extract coverage target (default: 80%)
+3. Read .msg/meta.json for framework info (from strategist namespace)
+4. Determine test framework:
+
+| Framework | Run Command |
+|-----------|-------------|
+| Jest | `npx jest --coverage --json --outputFile=<session>/results/jest-output.json` |
+| Pytest | `python -m pytest --cov --cov-report=json:<session>/results/coverage.json -v` |
+| Vitest | `npx vitest run --coverage --reporter=json` |
+
+5. Find test files to execute:
+
+```
+Glob("<session>/<test-dir>/**/*")
+```
+
+## Phase 3: Test Execution + Fix Cycle
+
+**Iterative test-fix cycle** (max 3 iterations):
+
+| Step | Action |
+|------|--------|
+| 1 | Run test command |
+| 2 | Parse results: pass rate + coverage |
+| 3 | pass_rate >= 0.95 AND coverage >= target -> success, exit |
+| 4 | Extract failing test details |
+| 5 | Delegate fix to CLI tool (gemini write mode) |
+| 6 | Increment iteration; >= 3 -> exit with failures |
+
+```
+Bash("<test-command> 2>&1 || true")
+```
+
+**Auto-fix delegation** (on failure):
+
+```
+Bash(`ccw cli -p "PURPOSE: Fix test failures to achieve pass rate >= 0.95; success = all tests pass
+TASK: • Analyze test failure output • Identify root causes • Fix test code only (not source) • Preserve test intent
+MODE: write
+CONTEXT: @<session>/<test-dir>/**/* | Memory: Test framework: <framework>, iteration <N>/3
+EXPECTED: Fixed test files with: corrected assertions, proper async handling, fixed imports, maintained coverage
+CONSTRAINTS: Only modify test files | Preserve test structure | No source code changes
+Test failures:
+<test-output>" --tool gemini --mode write --cd <session>`)
+```
+
+**Save results**: `<session>/results/run-<N>.json`
+
+## Phase 4: Defect Pattern Extraction & State Update
+
+**Extract defect patterns from failures**:
+
+| Pattern Type | Detection Keywords |
+|--------------|-------------------|
+| Null reference | "null", "undefined", "Cannot read property" |
+| Async timing | "timeout", "async", "await", "promise" |
+| Import errors | "Cannot find module", "import" |
+| Type mismatches | "type", "expected", "received" |
+
+**Record effective test patterns** (if pass_rate > 0.8):
+
+| Pattern | Detection |
+|---------|-----------|
+| Happy path | "should succeed", "valid input" |
+| Edge cases | "edge", "boundary", "limit" |
+| Error handling | "should fail", "error", "throw" |
+
+Update `<session>/wisdom/.msg/meta.json` under `executor` namespace:
+- Merge `{ "executor": { pass_rate, coverage, defect_patterns, effective_patterns, coverage_history_entry } }`