claude-code-workflow 7.2.27 → 7.2.29

package/.codex/skills/investigate/phases/05-verification-report.md

@@ -0,0 +1,240 @@
+# Phase 5: Verification & Report
+
+> **COMPACT PROTECTION**: This is a core execution phase. If context compression has occurred and this file is only a summary, **MUST `Read` this file again before executing any Step**. Do not execute from memory.
+
+Run full test suite, check for regressions, and generate the structured debug report.
+
+## Objective
+
+- Run the full test suite to verify no regressions were introduced
+- Generate a structured debug report for future reference
+- Output the report to `.workflow/.debug/` directory
+
+## Input
+
+| Source | Required | Description |
+|--------|----------|-------------|
+| investigation-report (phases 1-4) | Yes | All phases populated: evidence, root cause, fix_applied |
+| assign_task message | Yes | Phase 5 instruction |
+
+## Execution Steps
+
+### Step 1: Detect and Run Full Test Suite
+
+Detect the project's test framework by checking for project files, then run the full suite:
+
+| Detection file | Test command |
+|---------------|-------------|
+| `package.json` with `test` script | `npm test` |
+| `pytest.ini` or `pyproject.toml` | `pytest` |
+| `go.mod` | `go test ./...` |
+| `Cargo.toml` | `cargo test` |
+| `Makefile` with `test` target | `make test` |
+| None detected | Try `npm test`, `pytest`, `go test ./...` sequentially |
+
+```
+Bash: mkdir -p .workflow/.debug
+Bash: <detected test command>
+```
+
+Record test results:
+
+```
+test_results = {
+  total: <count>,
+  passed: <count>,
+  failed: <count>,
+  skipped: <count>,
+  regression_test_passed: true|false,
+  new_failures: []
+}
+```
+
+---
+
+### Step 2: Regression Check
+
+Verify specifically:
+
+1. The new regression test passes (check by test name from fix_applied.regression_test.test_name).
+2. All tests that were passing before the fix still pass.
+3. No new warnings or errors appeared in test output.
+
+**Decision table for new failures**:
+
+| New failure | Assessment | Action |
+|-------------|-----------|--------|
+| Related to fix (same module, same code path) | Fix introduced regression | Return to Phase 4 to adjust fix |
+| Unrelated to fix (different module, pre-existing) | Pre-existing failure | Document in pre_existing_failures, proceed |
+| Regression test itself fails | Fix is not working correctly | Return to Phase 4 |
+
+Classify failures:
+
+```
+regression_check_result = {
+  passed: true|false,
+  total_tests: <count>,
+  new_failures: ["<test names that newly fail>"],
+  pre_existing_failures: ["<tests that were already failing>"]
+}
+```
+
+---
+
+### Step 3: Generate Structured Debug Report
+
+Compile all investigation data into the final debug report JSON following the schema from `~/.codex/skills/investigate/specs/debug-report-format.md`:
+
+```
+debug_report = {
+  "bug_description": "<concise one-sentence description of the bug>",
+  "reproduction_steps": [
+    "<step 1>",
+    "<step 2>",
+    "<step 3: observe error>"
+  ],
+  "root_cause": "<confirmed root cause description with technical detail and file:line reference>",
+  "evidence_chain": [
+    "Phase 1: <error message X observed in module Y>",
+    "Phase 2: <pattern analysis found N similar occurrences>",
+    "Phase 3: hypothesis H<N> confirmed — <specific condition at file:line>"
+  ],
+  "fix_description": "<what was changed and why>",
+  "files_changed": [
+    {
+      "path": "<src/module/file.ts>",
+      "change_type": "add|modify|remove",
+      "description": "<brief description of changes to this file>"
+    }
+  ],
+  "tests_added": [
+    {
+      "file": "<src/module/__tests__/file.test.ts>",
+      "test_name": "<should handle null return from X>",
+      "type": "regression|unit|integration"
+    }
+  ],
+  "regression_check_result": {
+    "passed": true|false,
+    "total_tests": <count>,
+    "new_failures": [],
+    "pre_existing_failures": []
+  },
+  "completion_status": "DONE|DONE_WITH_CONCERNS|BLOCKED",
+  "concerns": [],
+  "timestamp": "<ISO-8601 timestamp>",
+  "investigation_duration_phases": 5
+}
+```
+
+**Field sources**:
+
+| Field | Source Phase | Description |
+|-------|-------------|-------------|
+| `bug_description` | Phase 1 | User-reported symptom, one sentence |
+| `reproduction_steps` | Phase 1 | Ordered steps to trigger the bug |
+| `root_cause` | Phase 3 | Confirmed cause with file:line reference |
+| `evidence_chain` | Phase 1-3 | Each item prefixed with "Phase N:" |
+| `fix_description` | Phase 4 | What code was changed and why |
+| `files_changed` | Phase 4 | Each file with change type and description |
+| `tests_added` | Phase 4 | Regression tests covering the bug |
+| `regression_check_result` | Phase 5 | Full test suite results |
+| `completion_status` | Phase 5 | Final status per protocol |
+| `concerns` | Phase 5 | Non-blocking issues (if any) |
+| `timestamp` | Phase 5 | When report was generated |
+| `investigation_duration_phases` | Phase 5 | Always 5 for complete investigation |
+
+---
+
+### Step 4: Write Report File
+
+Compute the filename:
+- `<slug>` = bug_description lowercased, non-alphanumeric characters replaced with `-`, truncated to 40 chars
+- `<date>` = current date as YYYY-MM-DD
+
+```
+Bash: mkdir -p .workflow/.debug
+Write: .workflow/.debug/debug-report-<date>-<slug>.json
+Content: <debug_report JSON with 2-space indent>
+```
+
+---
+
+### Step 5: Output Completion Status
+
+Determine status and output completion block:
+
+**Status determination**:
+
+| Condition | Status |
+|-----------|--------|
+| Regression test passes, no new failures, all quality checks met | DONE |
+| Fix applied but partial test coverage, minor warnings, or non-critical concerns | DONE_WITH_CONCERNS |
+| New test failures introduced by fix (unresolvable), or critical concern | BLOCKED |
+
+**DONE output**:
+
+```
+## STATUS: DONE
+
+**Summary**: Fixed <bug_description> — root cause was <root_cause_summary>
+
+### Details
+- Phases completed: 5/5
+- Root cause: <confirmed_root_cause.description>
+- Fix: <fix_description>
+- Regression test: <test_name> in <test_file>
+
+### Outputs
+- Debug report: .workflow/.debug/debug-report-<date>-<slug>.json
+- Files changed: <list>
+- Tests added: <list>
+```
+
+**DONE_WITH_CONCERNS output**:
+
+```
+## STATUS: DONE_WITH_CONCERNS
+
+**Summary**: Fixed <bug_description> with concerns
+
+### Details
+- Phases completed: 5/5
+- Concerns:
+  1. <concern> — Impact: low|medium — Suggested fix: <action>
+
+### Outputs
+- Debug report: .workflow/.debug/debug-report-<date>-<slug>.json
+- Files changed: <list>
+- Tests added: <list>
+```
+
+---
+
+## Output
+
+| Artifact | Format | Description |
+|----------|--------|-------------|
+| `.workflow/.debug/debug-report-<date>-<slug>.json` | JSON file | Full structured investigation report |
+| Completion status block | Structured text output | Final status per Completion Status Protocol |
+
+## Success Criteria
+
+| Criterion | Validation Method |
+|-----------|-------------------|
+| Full test suite executed | Test command ran and produced output |
+| Regression test passes | test_results.regression_test_passed: true |
+| No new failures introduced | regression_check_result.new_failures is empty (or documented as pre-existing) |
+| Debug report written | File exists at `.workflow/.debug/debug-report-<date>-<slug>.json` |
+| Completion status output | Status block follows protocol format |
+
+## Error Handling
+
+| Scenario | Resolution |
+|----------|------------|
+| Test framework not detected | Try common commands in order; document uncertainty in concerns |
+| New failures related to fix | Return to Phase 4 to adjust; do not write report until resolved |
+| New failures unrelated | Document as pre_existing_failures, set DONE_WITH_CONCERNS if impactful |
+| Report directory not writable | Try alternate path `.workflow/debug/`; document in output |
+| Test suite takes >5 minutes | Run regression test only; note full suite skipped in concerns |
+| Regression test was not added in Phase 4 | Document as DONE_WITH_CONCERNS concern |

package/.codex/skills/issue-discover/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: issue-discover
 description: "Unified issue discovery and creation. Create issues from GitHub/text, discover issues via multi-perspective analysis, or prompt-driven iterative exploration. Triggers on \"issue:new\", \"issue:discover\", \"issue:discover-by-prompt\", \"create issue\", \"discover issues\", \"find issues\"."
-allowed-tools: spawn_agent, wait, send_input, close_agent, request_user_input, Read, Write, Edit, Bash, Glob, Grep, mcp__ace-tool__search_context, mcp__exa__search
+allowed-tools: spawn_agent, wait_agent, send_message, assign_task, close_agent, request_user_input, Read, Write, Edit, Bash, Glob, Grep, mcp__ace-tool__search_context, mcp__exa__search
 ---
 
 # Issue Discover
@@ -54,7 +54,7 @@ Unified issue discovery and creation skill covering three entry points: manual i
 2. **Progressive Phase Loading**: Only read the selected phase document
 3. **CLI-First Data Access**: All issue CRUD via `ccw issue` CLI commands
 4. **Auto Mode Support**: `-y` flag skips action selection with auto-detection
-5. **Subagent Lifecycle**: Explicit lifecycle management with spawn_agent → wait → close_agent
+5. **Subagent Lifecycle**: Explicit lifecycle management with spawn_agent → wait_agent → close_agent
 6. **Role Path Loading**: Subagent roles loaded via path reference in MANDATORY FIRST STEPS
 
 ## Auto Mode
@@ -130,7 +130,7 @@ Post-Phase:
 5. **Auto-Detect Input**: Smart input parsing reduces need for explicit --action flag
 6. **⚠️ CRITICAL: DO NOT STOP**: Continuous multi-phase workflow. After completing each phase, immediately proceed to next
 7. **Progressive Phase Loading**: Read phase docs ONLY when that phase is about to execute
-8. **Explicit Lifecycle**: Always close_agent after wait completes to free resources
+8. **Explicit Lifecycle**: Always close_agent after wait_agent completes to free resources
 
 ## Input Processing
 
@@ -246,18 +246,18 @@ ${deliverables}
 })
 ```
 
-### wait
+### wait_agent
 
 Get results from subagent (only way to retrieve results).
 
 ```javascript
-const result = wait({
-  ids: [agentId],
+const result = wait_agent({
+  targets: [agentId],
   timeout_ms: 600000  // 10 minutes
 })
 
 if (result.timed_out) {
-  // Handle timeout - can continue waiting or send_input to prompt completion
+  // Handle timeout - can use assign_task to prompt completion
 }
 
 // Check completion status
@@ -266,20 +266,20 @@ if (result.status[agentId].completed) {
 }
 ```
 
-### send_input
+### assign_task
 
-Continue interaction with active subagent (for clarification or follow-up).
+Assign new work to active subagent (for clarification or follow-up).
 
 ```javascript
-send_input({
-  id: agentId,
-  message: `
+assign_task({
+  target: agentId,
+  items: [{ type: "text", text: `
 ## CLARIFICATION ANSWERS
 ${answers}
 
 ## NEXT STEP
 Continue with plan generation.
-`
+` }]
 })
 ```
 

package/.codex/skills/issue-discover/phases/02-discover.md

@@ -164,8 +164,8 @@ ${getPerspectiveGuidance(perspective)}
 
 // Step 2: Batch wait for all agents
 const agentIds = perspectiveAgents.map(a => a.agentId);
-const results = wait({
-  ids: agentIds,
+const results = wait_agent({
+  targets: agentIds,
   timeout_ms: 600000  // 10 minutes
 });
 
@@ -220,8 +220,8 @@ Research industry best practices for ${perspective} using Exa search
 `
   });
 
-  const exaResult = wait({
-    ids: [exaAgentId],
+  const exaResult = wait_agent({
+    targets: [exaAgentId],
     timeout_ms: 300000  // 5 minutes
   });
 

package/.codex/skills/issue-discover/phases/03-discover-by-prompt.md

@@ -242,8 +242,8 @@ while (shouldContinue && iteration < maxIterations) {
 
   // Step 2: Batch wait for all dimension agents
   const dimensionAgentIds = dimensionAgents.map(a => a.agentId);
-  const iterationResults = wait({
-    ids: dimensionAgentIds,
+  const iterationResults = wait_agent({
+    targets: dimensionAgentIds,
     timeout_ms: 600000  // 10 minutes
   });
 
@@ -297,7 +297,7 @@ while (shouldContinue && iteration < maxIterations) {
 │                                                             │
 │  2. Execute: Spawn agents for this iteration                │
 │     └─ Each agent: explore → collect → return summary       │
-│     └─ Lifecycle: spawn_agent → batch wait → close_agent    │
+│     └─ Lifecycle: spawn_agent → batch wait_agent → close_agent    │
 │                                                             │
 │  3. Analyze: Process iteration results                      │
 │     └─ New findings? Gaps? Contradictions?                  │

package/.codex/skills/parallel-dev-cycle/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: parallel-dev-cycle
 description: Multi-agent parallel development cycle with requirement analysis, exploration planning, code development, and validation. Orchestration runs inline in main flow (no separate orchestrator agent). Supports continuous iteration with markdown progress documentation. Triggers on "parallel-dev-cycle".
-allowed-tools: spawn_agent, wait, send_input, close_agent, request_user_input, Read, Write, Edit, Bash, Glob, Grep
+allowed-tools: spawn_agent, wait_agent, send_message, assign_task, close_agent, request_user_input, Read, Write, Edit, Bash, Glob, Grep
 ---
 
 # Parallel Dev Cycle
@@ -111,7 +111,7 @@ Phase 3: Result Aggregation & Iteration
       ├─ Parse PHASE_RESULT from each agent
       ├─ Detect issues (test failures, blockers)
       ├─ Decision: Issues found AND iteration < max?
-      │   ├─ Yes → Send feedback via send_input, loop back to Phase 2
+      │   ├─ Yes → Send feedback via assign_task, loop back to Phase 2
       │   └─ No → Proceed to Phase 4
       └─ Output: parsedResults, iteration status
 
@@ -330,7 +330,7 @@ PHASE_RESULT:
 
 ### Main Flow → Agent Communication
 
-Feedback via `send_input` (file refs + issue summary, never full content):
+Feedback via `assign_task` (file refs + issue summary, never full content):
 ```
 ## FEEDBACK FROM [Source]
 [Issue summary with file:line references]
@@ -357,7 +357,7 @@ Feedback via `send_input` (file refs + issue summary, never full content):
 
 | Error Type | Recovery |
 |------------|----------|
-| Agent timeout | send_input requesting convergence, then retry |
+| Agent timeout | assign_task requesting convergence, then retry |
 | State corrupted | Rebuild from progress markdown files and changes.log |
 | Agent failed | Re-spawn agent with previous context |
 | Conflicting results | Main flow sends reconciliation request |

package/.codex/skills/parallel-dev-cycle/phases/02-agent-execution.md

@@ -408,8 +408,8 @@ const agents = {
 
 // Wait for all agents to complete
 console.log('Waiting for all agents...')
-const results = wait({
-  ids: [agents.ra, agents.ep, agents.cd, agents.vas],
+const results = wait_agent({
+  targets: [agents.ra, agents.ep, agents.cd, agents.vas],
   timeout_ms: 1800000  // 30 minutes
 })
 ```
@@ -421,16 +421,16 @@ if (results.timed_out) {
   console.log('Some agents timed out, sending convergence request...')
   Object.entries(agents).forEach(([name, id]) => {
     if (!results.status[id].completed) {
-      send_input({
-        id: id,
-        message: `
+      assign_task({
+        target: id,
+        items: [{ type: "text", text: `
 ## TIMEOUT NOTIFICATION
 
 Execution timeout reached. Please:
 1. Output current progress to markdown file
 2. Save all state updates
 3. Return completion status
-`
+` }]
       })
     }
   })

package/.codex/skills/parallel-dev-cycle/phases/03-result-aggregation.md

@@ -148,29 +148,29 @@ Update requirements.md if needed.
 }
 ```
 
-### Step 3.6: Send Feedback via send_input
+### Step 3.6: Send Feedback via assign_task
 
 ```javascript
 const feedback = generateFeedback(parsedResults)
 
 // Send feedback to relevant agents
 if (feedback.ra) {
-  send_input({
-    id: agents.ra,
-    message: feedback.ra
+  assign_task({
+    target: agents.ra,
+    items: [{ type: "text", text: feedback.ra }]
   })
 }
 
 if (feedback.cd) {
-  send_input({
-    id: agents.cd,
-    message: feedback.cd
+  assign_task({
+    target: agents.cd,
+    items: [{ type: "text", text: feedback.cd }]
   })
 }
 
 // Wait for agents to process feedback and update
-const updatedResults = wait({
-  ids: [agents.ra, agents.cd].filter(Boolean),
+const updatedResults = wait_agent({
+  targets: [agents.ra, agents.cd].filter(Boolean),
   timeout_ms: 900000  // 15 minutes for fixes
 })
 
@@ -213,7 +213,7 @@ Phase 3: Result Aggregation
 │   ├─ No → Phase 4 (Complete)
 │   └─ Yes
 │       ├─ iteration < max?
-│       │   ├─ Yes → Generate feedback → send_input → Wait → Back to Phase 2
+│       │   ├─ Yes → Generate feedback → assign_task → Wait → Back to Phase 2
 │       │   └─ No → Phase 4 (Complete with issues)
 ```
 

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

@@ -316,18 +316,18 @@ ${deliverables}
 })
 ```
 
-### wait
+### wait_agent
 
 Get results from subagent (only way to retrieve results).
 
 ```javascript
-const result = wait({
-  ids: [agentId],
+const result = wait_agent({
+  targets: [agentId],
   timeout_ms: 600000  // 10 minutes
 })
 
 if (result.timed_out) {
-  // Handle timeout - can continue waiting or send_input to prompt completion
+  // Handle timeout - can use assign_task to prompt completion
 }
 
 // Check completion status
@@ -336,20 +336,20 @@ if (result.status[agentId].completed) {
 }
 ```
 
-### send_input
+### assign_task
 
-Continue interaction with active subagent (for clarification or follow-up).
+Assign new work to active subagent (for clarification or follow-up).
 
 ```javascript
-send_input({
-  id: agentId,
-  message: `
+assign_task({
+  target: agentId,
+  items: [{ type: "text", text: `
 ## CLARIFICATION ANSWERS
 ${answers}
 
 ## NEXT STEP
 Continue with analysis generation.
-`
+` }]
 })
 ```
 

package/.codex/skills/review-cycle/phases/02-parallel-review.md

@@ -173,8 +173,8 @@ ${getDimensionGuidance(dimension)}
 });
 
 // Step 2: Batch wait for all 7 agents
-const reviewResults = wait({
-  ids: reviewAgents,
+const reviewResults = wait_agent({
+  targets: reviewAgents,
   timeout_ms: 3600000  // 60 minutes
 });
 
@@ -296,8 +296,8 @@ ${getDimensionGuidance(dimension)}
 });
 
 // Step 2: Batch wait for all 7 agents
-const reviewResults = wait({
-  ids: reviewAgents,
+const reviewResults = wait_agent({
+  targets: reviewAgents,
   timeout_ms: 3600000  // 60 minutes
 });
 
@@ -407,8 +407,8 @@ Then apply **Deep Scan mode** for semantic analysis:
 });
 
 // Wait for completion
-const deepDiveResult = wait({
-  ids: [deepDiveAgentId],
+const deepDiveResult = wait_agent({
+  targets: [deepDiveAgentId],
   timeout_ms: 2400000  // 40 minutes
 });
 

package/.codex/skills/review-cycle/phases/04-iterative-deep-dive.md

@@ -163,8 +163,8 @@ Then apply **Deep Scan mode** for semantic analysis:
 });
 
 // Step 2: Batch wait for all deep-dive agents
-const deepDiveResults = wait({
-  ids: deepDiveAgents,
+const deepDiveResults = wait_agent({
+  targets: deepDiveAgents,
   timeout_ms: 2400000  // 40 minutes
 });
 
@@ -275,8 +275,8 @@ Then apply **Deep Scan mode** for semantic analysis:
 });
 
 // Step 2: Batch wait for all deep-dive agents
-const deepDiveResults = wait({
-  ids: deepDiveAgents,
+const deepDiveResults = wait_agent({
+  targets: deepDiveAgents,
   timeout_ms: 2400000  // 40 minutes
 });
 

package/.codex/skills/review-cycle/phases/07-fix-parallel-planning.md

@@ -43,8 +43,8 @@ for (let i = 0; i < batches.length; i += MAX_PARALLEL) {
   console.log(`Spawned ${agentIds.length} planning agents...`);
 
   // Step 2: Batch wait for all agents in this chunk
-  const chunkResults = wait({
-    ids: agentIds.map(a => a.agentId),
+  const chunkResults = wait_agent({
+    targets: agentIds.map(a => a.agentId),
     timeout_ms: 600000  // 10 minutes
   });
 
@@ -204,8 +204,8 @@ Before finalizing outputs:
 });
 
 // Wait for completion
-const result = wait({
-  ids: [agentId],
+const result = wait_agent({
+  targets: [agentId],
   timeout_ms: 600000  // 10 minutes
 });
 

package/.codex/skills/review-cycle/phases/08-fix-execution.md

@@ -221,8 +221,8 @@ Use fix_strategy.test_pattern to run affected tests:
 });
 
 // Wait for completion
-const execResult = wait({
-  ids: [execAgentId],
+const execResult = wait_agent({
+  targets: [execAgentId],
   timeout_ms: 1200000  // 20 minutes per group
 });
 

package/.codex/skills/roadmap-with-file/SKILL.md

@@ -56,33 +56,33 @@ ${deliverables}
 })
 ```
 
-### wait
+### wait_agent
 Get results from subagent (only way to retrieve results).
 
 ```javascript
-const result = wait({
-  ids: [agentId],
+const result = wait_agent({
+  targets: [agentId],
   timeout_ms: 600000  // 10 minutes
 })
 
 if (result.timed_out) {
-  // Handle timeout - can continue waiting or send_input to prompt completion
+  // Handle timeout - can use assign_task to prompt completion
 }
 ```
 
-### send_input
-Continue interaction with active subagent (for clarification or follow-up).
+### assign_task
+Assign new work to active subagent (for clarification or follow-up).
 
 ```javascript
-send_input({
-  id: agentId,
-  message: `
+assign_task({
+  target: agentId,
+  items: [{ type: "text", text: `
 ## CLARIFICATION ANSWERS
 ${answers}
 
 ## NEXT STEP
 Continue with plan generation.
-`
+` }]
 })
 ```
 
@@ -537,8 +537,8 @@ Return findings as JSON with schema:
 `
      })
 
-     const exploreResult = wait({
-       ids: [exploreAgentId],
+     const exploreResult = wait_agent({
+       targets: [exploreAgentId],
        timeout_ms: 120000
      })
 
@@ -629,8 +629,8 @@ ${selectedMode === 'progressive' ? `**Progressive Mode**:
 `
    })
 
-   const decompositionResult = wait({
-     ids: [decompositionAgentId],
+   const decompositionResult = wait_agent({
+     targets: [decompositionAgentId],
      timeout_ms: 300000  // 5 minutes for complex decomposition
    })