claude-code-workflow 7.2.23 → 7.2.25

package/.codex/skills/team-tech-debt/roles/scanner/role.md

@@ -1,82 +1,82 @@
----
-role: scanner
-prefix: TDSCAN
-inner_loop: false
-message_types: [state_update]
----
-
-# Tech Debt Scanner
-
-Multi-dimension tech debt scanner. Scan codebase across 5 dimensions (code, architecture, testing, dependency, documentation), produce structured debt inventory with severity rankings.
-
-## Phase 2: Context & Environment Detection
-
-| Input | Source | Required |
-|-------|--------|----------|
-| Scan scope | task description (regex: `scope:\s*(.+)`) | No (default: `**/*`) |
-| Session path | task description (regex: `session:\s*(.+)`) | Yes |
-| .msg/meta.json | <session>/.msg/meta.json | Yes |
-
-1. Extract session path and scan scope from task description
-2. Load debug specs: Run `ccw spec load --category debug` for known issues, workarounds, and root-cause notes
-3. Read .msg/meta.json for team context
-3. Detect project type and framework:
-
-| Signal File | Project Type |
-|-------------|-------------|
-| package.json + React/Vue/Angular | Frontend Node |
-| package.json + Express/Fastify/NestJS | Backend Node |
-| pyproject.toml / requirements.txt | Python |
-| go.mod | Go |
-| No detection | Generic |
-
-4. Determine scan dimensions (default: code, architecture, testing, dependency, documentation)
-5. Detect perspectives from task description:
-
-| Condition | Perspective |
-|-----------|-------------|
-| `security\|auth\|inject\|xss` | security |
-| `performance\|speed\|optimize` | performance |
-| `quality\|clean\|maintain\|debt` | code-quality |
-| `architect\|pattern\|structure` | architecture |
-| Default | code-quality + architecture |
-
-6. Assess complexity:
-
-| Score | Complexity | Strategy |
-|-------|------------|----------|
-| >= 4 | High | Triple Fan-out: CLI explore + CLI 5 dimensions + multi-perspective Gemini |
-| 2-3 | Medium | Dual Fan-out: CLI explore + CLI 3 dimensions |
-| 0-1 | Low | Inline: ACE search + Grep |
-
-## Phase 3: Multi-Dimension Scan
-
-**Low Complexity** (inline):
-- Use `mcp__ace-tool__search_context` for code smells, TODO/FIXME, deprecated APIs, complex functions, dead code, missing tests
-- Classify findings into dimensions
-
-**Medium/High Complexity** (Fan-out):
-- Fan-out A: CLI exploration (structure, patterns, dependencies angles) via `ccw cli --tool gemini --mode analysis`
-- Fan-out B: CLI dimension analysis (parallel gemini per dimension -- code, architecture, testing, dependency, documentation)
-- Fan-out C (High only): Multi-perspective Gemini analysis (security, performance, code-quality, architecture)
-- Fan-in: Merge results, cross-deduplicate by file:line, boost severity for multi-source findings
-
-**Standardize each finding**:
-
-| Field | Description |
-|-------|-------------|
-| `id` | `TD-NNN` (sequential) |
-| `dimension` | code, architecture, testing, dependency, documentation |
-| `severity` | critical, high, medium, low |
-| `file` | File path |
-| `line` | Line number |
-| `description` | Issue description |
-| `suggestion` | Fix suggestion |
-| `estimated_effort` | small, medium, large, unknown |
-
-## Phase 4: Aggregate & Save
-
-1. Deduplicate findings across Fan-out layers (file:line key), merge cross-references
-2. Sort by severity (cross-referenced items boosted)
-3. Write `<session>/scan/debt-inventory.json` with scan_date, dimensions, total_items, by_dimension, by_severity, items
-4. Update .msg/meta.json with `debt_inventory` array and `debt_score_before` count
+---
+role: scanner
+prefix: TDSCAN
+inner_loop: false
+message_types: [state_update]
+---
+
+# Tech Debt Scanner
+
+Multi-dimension tech debt scanner. Scan codebase across 5 dimensions (code, architecture, testing, dependency, documentation), produce structured debt inventory with severity rankings.
+
+## Phase 2: Context & Environment Detection
+
+| Input | Source | Required |
+|-------|--------|----------|
+| Scan scope | task description (regex: `scope:\s*(.+)`) | No (default: `**/*`) |
+| Session path | task description (regex: `session:\s*(.+)`) | Yes |
+| .msg/meta.json | <session>/.msg/meta.json | Yes |
+
+1. Extract session path and scan scope from task description
+2. Load debug specs: Run `ccw spec load --category debug` for known issues, workarounds, and root-cause notes
+3. Read .msg/meta.json for team context
+3. Detect project type and framework:
+
+| Signal File | Project Type |
+|-------------|-------------|
+| package.json + React/Vue/Angular | Frontend Node |
+| package.json + Express/Fastify/NestJS | Backend Node |
+| pyproject.toml / requirements.txt | Python |
+| go.mod | Go |
+| No detection | Generic |
+
+4. Determine scan dimensions (default: code, architecture, testing, dependency, documentation)
+5. Detect perspectives from task description:
+
+| Condition | Perspective |
+|-----------|-------------|
+| `security\|auth\|inject\|xss` | security |
+| `performance\|speed\|optimize` | performance |
+| `quality\|clean\|maintain\|debt` | code-quality |
+| `architect\|pattern\|structure` | architecture |
+| Default | code-quality + architecture |
+
+6. Assess complexity:
+
+| Score | Complexity | Strategy |
+|-------|------------|----------|
+| >= 4 | High | Triple Fan-out: CLI explore + CLI 5 dimensions + multi-perspective Gemini |
+| 2-3 | Medium | Dual Fan-out: CLI explore + CLI 3 dimensions |
+| 0-1 | Low | Inline: ACE search + Grep |
+
+## Phase 3: Multi-Dimension Scan
+
+**Low Complexity** (inline):
+- Use `mcp__ace-tool__search_context` for code smells, TODO/FIXME, deprecated APIs, complex functions, dead code, missing tests
+- Classify findings into dimensions
+
+**Medium/High Complexity** (Fan-out):
+- Fan-out A: CLI exploration (structure, patterns, dependencies angles) via `ccw cli --tool gemini --mode analysis`
+- Fan-out B: CLI dimension analysis (parallel gemini per dimension -- code, architecture, testing, dependency, documentation)
+- Fan-out C (High only): Multi-perspective Gemini analysis (security, performance, code-quality, architecture)
+- Fan-in: Merge results, cross-deduplicate by file:line, boost severity for multi-source findings
+
+**Standardize each finding**:
+
+| Field | Description |
+|-------|-------------|
+| `id` | `TD-NNN` (sequential) |
+| `dimension` | code, architecture, testing, dependency, documentation |
+| `severity` | critical, high, medium, low |
+| `file` | File path |
+| `line` | Line number |
+| `description` | Issue description |
+| `suggestion` | Fix suggestion |
+| `estimated_effort` | small, medium, large, unknown |
+
+## Phase 4: Aggregate & Save
+
+1. Deduplicate findings across Fan-out layers (file:line key), merge cross-references
+2. Sort by severity (cross-referenced items boosted)
+3. Write `<session>/scan/debt-inventory.json` with scan_date, dimensions, total_items, by_dimension, by_severity, items
+4. Update .msg/meta.json with `debt_inventory` array and `debt_score_before` count

package/.codex/skills/team-tech-debt/roles/validator/role.md

@@ -1,75 +1,75 @@
----
-role: validator
-prefix: TDVAL
-inner_loop: false
-message_types: [state_update]
----
-
-# Tech Debt Validator
-
-Cleanup result validator. Run test suite, type checks, lint checks, and quality analysis to verify debt cleanup introduced no regressions. Compare before/after debt scores, produce validation-report.json.
-
-## Phase 2: Load Context
-
-| Input | Source | Required |
-|-------|--------|----------|
-| Session path | task description (regex: `session:\s*(.+)`) | Yes |
-| .msg/meta.json | <session>/.msg/meta.json | Yes |
-| Fix log | <session>/fixes/fix-log.json | No |
-
-1. Extract session path from task description
-2. Read .msg/meta.json for: worktree.path, debt_inventory, fix_results, debt_score_before
-3. Determine command prefix: `cd "<worktree-path>" && ` if worktree exists
-4. Read fix-log.json for modified files list
-5. Detect available validation tools in worktree:
-
-| Signal | Tool | Method |
-|--------|------|--------|
-| package.json + npm | npm test | Test suite |
-| pytest available | python -m pytest | Test suite |
-| npx tsc available | npx tsc --noEmit | Type check |
-| npx eslint available | npx eslint | Lint check |
-
-## Phase 3: Run Validation Checks
-
-Execute 4-layer validation (all commands in worktree):
-
-**1. Test Suite**:
-- Run `npm test` or `python -m pytest` in worktree
-- PASS if no FAIL/error/failed keywords; FAIL with regression count otherwise
-- Skip with "no-tests" if no test runner available
-
-**2. Type Check**:
-- Run `npx tsc --noEmit` in worktree
-- Count `error TS` occurrences for error count
-
-**3. Lint Check**:
-- Run `npx eslint --no-error-on-unmatched-pattern <modified-files>` in worktree
-- Count error occurrences
-
-**4. Quality Analysis** (optional, when > 5 modified files):
-- Use gemini CLI to compare code quality before/after
-- Assess complexity, duplication, naming quality improvements
-
-**Debt Score Calculation**:
-- debt_score_after = debt items NOT in modified files (remaining unfixed items)
-- improvement_percentage = ((before - after) / before) * 100
-
-**Auto-fix attempt** (when total_regressions <= 3):
-- Use CLI tool to fix regressions in worktree:
-  ```
-  Bash(`cd "${worktreePath}" && ccw cli -p "PURPOSE: Fix regressions found in validation
-  TASK: ${regressionDetails}
-  MODE: write
-  CONTEXT: @${modifiedFiles.join(' @')}
-  EXPECTED: Fixed regressions
-  CONSTRAINTS: Fix only regressions | Preserve debt cleanup changes | No suppressions" --tool gemini --mode write`)
-  ```
-- Re-run validation checks after fix attempt
-
-## Phase 4: Compare & Report
-
-1. Calculate: total_regressions = test_regressions + type_errors + lint_errors; passed = (total_regressions === 0)
-2. Write `<session>/validation/validation-report.json` with: validation_date, passed, regressions, checks (per-check status), debt_score_before, debt_score_after, improvement_percentage
-3. Update .msg/meta.json with `validation_results` and `debt_score_after`
-4. Select message type: `validation_complete` if passed, `regression_found` if not
+---
+role: validator
+prefix: TDVAL
+inner_loop: false
+message_types: [state_update]
+---
+
+# Tech Debt Validator
+
+Cleanup result validator. Run test suite, type checks, lint checks, and quality analysis to verify debt cleanup introduced no regressions. Compare before/after debt scores, produce validation-report.json.
+
+## Phase 2: Load Context
+
+| Input | Source | Required |
+|-------|--------|----------|
+| Session path | task description (regex: `session:\s*(.+)`) | Yes |
+| .msg/meta.json | <session>/.msg/meta.json | Yes |
+| Fix log | <session>/fixes/fix-log.json | No |
+
+1. Extract session path from task description
+2. Read .msg/meta.json for: worktree.path, debt_inventory, fix_results, debt_score_before
+3. Determine command prefix: `cd "<worktree-path>" && ` if worktree exists
+4. Read fix-log.json for modified files list
+5. Detect available validation tools in worktree:
+
+| Signal | Tool | Method |
+|--------|------|--------|
+| package.json + npm | npm test | Test suite |
+| pytest available | python -m pytest | Test suite |
+| npx tsc available | npx tsc --noEmit | Type check |
+| npx eslint available | npx eslint | Lint check |
+
+## Phase 3: Run Validation Checks
+
+Execute 4-layer validation (all commands in worktree):
+
+**1. Test Suite**:
+- Run `npm test` or `python -m pytest` in worktree
+- PASS if no FAIL/error/failed keywords; FAIL with regression count otherwise
+- Skip with "no-tests" if no test runner available
+
+**2. Type Check**:
+- Run `npx tsc --noEmit` in worktree
+- Count `error TS` occurrences for error count
+
+**3. Lint Check**:
+- Run `npx eslint --no-error-on-unmatched-pattern <modified-files>` in worktree
+- Count error occurrences
+
+**4. Quality Analysis** (optional, when > 5 modified files):
+- Use gemini CLI to compare code quality before/after
+- Assess complexity, duplication, naming quality improvements
+
+**Debt Score Calculation**:
+- debt_score_after = debt items NOT in modified files (remaining unfixed items)
+- improvement_percentage = ((before - after) / before) * 100
+
+**Auto-fix attempt** (when total_regressions <= 3):
+- Use CLI tool to fix regressions in worktree:
+  ```
+  Bash(`cd "${worktreePath}" && ccw cli -p "PURPOSE: Fix regressions found in validation
+  TASK: ${regressionDetails}
+  MODE: write
+  CONTEXT: @${modifiedFiles.join(' @')}
+  EXPECTED: Fixed regressions
+  CONSTRAINTS: Fix only regressions | Preserve debt cleanup changes | No suppressions" --tool gemini --mode write`)
+  ```
+- Re-run validation checks after fix attempt
+
+## Phase 4: Compare & Report
+
+1. Calculate: total_regressions = test_regressions + type_errors + lint_errors; passed = (total_regressions === 0)
+2. Write `<session>/validation/validation-report.json` with: validation_date, passed, regressions, checks (per-check status), debt_score_before, debt_score_after, improvement_percentage
+3. Update .msg/meta.json with `validation_results` and `debt_score_after`
+4. Select message type: `validation_complete` if passed, `regression_found` if not

package/.codex/skills/team-tech-debt/specs/pipelines.md

@@ -1,47 +1,47 @@
-# Pipeline Definitions
-
-Tech debt pipeline modes and task registry.
-
-## Pipeline Modes
-
-| Mode | Description | Task Chain |
-|------|-------------|------------|
-| scan | Scan and assess only, no fixes | TDSCAN-001 -> TDEVAL-001 |
-| remediate | Full pipeline: scan -> assess -> plan -> fix -> validate | TDSCAN-001 -> TDEVAL-001 -> TDPLAN-001 -> TDFIX-001 -> TDVAL-001 |
-| targeted | Skip scan/assess, direct fix path | TDPLAN-001 -> TDFIX-001 -> TDVAL-001 |
-
-## Task Registry
-
-| Task ID | Role | Prefix | blockedBy | Description |
-|---------|------|--------|-----------|-------------|
-| TDSCAN-001 | scanner | TDSCAN | [] | Fan-out multi-dimension codebase scan (code, architecture, testing, dependency, documentation) |
-| TDEVAL-001 | assessor | TDEVAL | [TDSCAN-001] | Severity assessment with priority quadrant matrix |
-| TDPLAN-001 | planner | TDPLAN | [TDEVAL-001] | 3-phase remediation plan with effort estimates |
-| TDFIX-001 | executor | TDFIX | [TDPLAN-001] | Worktree-based incremental fixes (inner_loop: true) |
-| TDVAL-001 | validator | TDVAL | [TDFIX-001] | 4-layer validation: syntax, tests, integration, regression |
-
-## Checkpoints
-
-| Checkpoint | Trigger | Condition | Action |
-|------------|---------|-----------|--------|
-| Plan Approval Gate | TDPLAN-001 completes | Always | request_user_input: Approve / Revise / Abort |
-| Worktree Creation | Plan approved | Before TDFIX | git worktree add .worktrees/TD-<slug>-<date> |
-| Fix-Verify GC Loop | TDVAL-* completes | Regressions found | Create TDFIX-fix-<round> + TDVAL-recheck-<round> (max 3 rounds) |
-
-## GC Loop Behavior
-
-| Condition | Action |
-|-----------|--------|
-| No regressions | Pipeline complete |
-| Regressions AND gc_rounds < 3 | Create fix-verify tasks, increment gc_rounds |
-| Regressions AND gc_rounds >= 3 | Accept current state, handleComplete |
-
-## Output Artifacts
-
-| Task | Output Path |
-|------|-------------|
-| TDSCAN-001 | <session>/scan/scan-report.json |
-| TDEVAL-001 | <session>/assessment/debt-assessment.json |
-| TDPLAN-001 | <session>/plan/remediation-plan.md |
-| TDFIX-001 | <session>/fixes/ (worktree) |
-| TDVAL-001 | <session>/validation/validation-report.md |
+# Pipeline Definitions
+
+Tech debt pipeline modes and task registry.
+
+## Pipeline Modes
+
+| Mode | Description | Task Chain |
+|------|-------------|------------|
+| scan | Scan and assess only, no fixes | TDSCAN-001 -> TDEVAL-001 |
+| remediate | Full pipeline: scan -> assess -> plan -> fix -> validate | TDSCAN-001 -> TDEVAL-001 -> TDPLAN-001 -> TDFIX-001 -> TDVAL-001 |
+| targeted | Skip scan/assess, direct fix path | TDPLAN-001 -> TDFIX-001 -> TDVAL-001 |
+
+## Task Registry
+
+| Task ID | Role | Prefix | blockedBy | Description |
+|---------|------|--------|-----------|-------------|
+| TDSCAN-001 | scanner | TDSCAN | [] | Fan-out multi-dimension codebase scan (code, architecture, testing, dependency, documentation) |
+| TDEVAL-001 | assessor | TDEVAL | [TDSCAN-001] | Severity assessment with priority quadrant matrix |
+| TDPLAN-001 | planner | TDPLAN | [TDEVAL-001] | 3-phase remediation plan with effort estimates |
+| TDFIX-001 | executor | TDFIX | [TDPLAN-001] | Worktree-based incremental fixes (inner_loop: true) |
+| TDVAL-001 | validator | TDVAL | [TDFIX-001] | 4-layer validation: syntax, tests, integration, regression |
+
+## Checkpoints
+
+| Checkpoint | Trigger | Condition | Action |
+|------------|---------|-----------|--------|
+| Plan Approval Gate | TDPLAN-001 completes | Always | request_user_input: Approve / Revise / Abort |
+| Worktree Creation | Plan approved | Before TDFIX | git worktree add .worktrees/TD-<slug>-<date> |
+| Fix-Verify GC Loop | TDVAL-* completes | Regressions found | Create TDFIX-fix-<round> + TDVAL-recheck-<round> (max 3 rounds) |
+
+## GC Loop Behavior
+
+| Condition | Action |
+|-----------|--------|
+| No regressions | Pipeline complete |
+| Regressions AND gc_rounds < 3 | Create fix-verify tasks, increment gc_rounds |
+| Regressions AND gc_rounds >= 3 | Accept current state, handleComplete |
+
+## Output Artifacts
+
+| Task | Output Path |
+|------|-------------|
+| TDSCAN-001 | <session>/scan/scan-report.json |
+| TDEVAL-001 | <session>/assessment/debt-assessment.json |
+| TDPLAN-001 | <session>/plan/remediation-plan.md |
+| TDFIX-001 | <session>/fixes/ (worktree) |
+| TDVAL-001 | <session>/validation/validation-report.md |

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

@@ -1,7 +1,7 @@
 ---
 name: team-testing
 description: Unified team skill for testing team. Progressive test coverage through Generator-Critic loops, shared memory, and dynamic layer selection. Triggers on "team testing".
-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 Testing
@@ -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,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 })` each worker.
+
+
+### Model Selection Guide
+
+| Role | model | reasoning_effort | Rationale |
+|------|-------|-------------------|-----------|
+| Strategist (STRATEGY-*) | (default) | high | Test strategy requires deep code understanding |
+| Generator (TESTGEN-*) | (default) | high | Test code generation needs precision |
+| Executor (TESTRUN-*) | (default) | medium | Running tests and collecting results, less reasoning |
+| Analyst (TESTANA-*) | (default) | high | Coverage analysis and quality assessment |
+
+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
 
@@ -119,6 +144,50 @@ After spawning, use `wait_agent({ ids: [...], timeout_ms: 900000 })` to collect
 | `revise <TASK-ID>` | Revise specific task |
 | `feedback <text>` | Inject feedback for revision |
 
+## v4 Agent Coordination
+
+### Message Semantics
+
+| Intent | API | Example |
+|--------|-----|---------|
+| Send strategy to running generators | `send_message` | Queue test strategy findings to TESTGEN-* workers |
+| Not used in this skill | `assign_task` | No resident agents -- all workers are one-shot |
+| Check running agents | `list_agents` | Verify parallel generator/executor health |
+
+### Parallel Test Generation
+
+Comprehensive pipeline spawns multiple generators (per layer) and executors in parallel:
+
+```
+// Spawn parallel generators for L1 and L2
+const genNames = ["TESTGEN-001", "TESTGEN-002"]
+for (const name of genNames) {
+  spawn_agent({ agent_type: "team_worker", task_name: name, ... })
+}
+wait_agent({ targets: genNames, timeout_ms: 900000 })
+```
+
+### GC Loop Coordination
+
+Generator-Critic loops create dynamic TESTGEN-fix and TESTRUN-fix tasks. The coordinator tracks `gc_rounds[layer]` and creates fix tasks dynamically when coverage is below target.
+
+### 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: "TESTGEN-001", items: [...] })` -- queue strategy context to running generator
+- `close_agent({ target: "TESTRUN-001" })` -- cleanup by name after wait_agent returns
+
 ## Completion Action
 
 When pipeline completes, coordinator presents: