claude-code-workflow 6.1.4 → 6.2.2

package/.claude/commands/workflow/debug.md

@@ -0,0 +1,321 @@
+---
+name: debug
+description: Interactive hypothesis-driven debugging with NDJSON logging, iterative until resolved
+argument-hint: "\"bug description or error message\""
+allowed-tools: TodoWrite(*), Task(*), AskUserQuestion(*), Read(*), Grep(*), Glob(*), Bash(*), Edit(*), Write(*)
+---
+
+# Workflow Debug Command (/workflow:debug)
+
+## Overview
+
+Evidence-based interactive debugging command. Systematically identifies root causes through hypothesis-driven logging and iterative verification.
+
+**Core workflow**: Explore → Add Logging → Reproduce → Analyze Log → Fix → Verify
+
+## Usage
+
+```bash
+/workflow:debug <BUG_DESCRIPTION>
+
+# Arguments
+<bug-description>          Bug description, error message, or stack trace (required)
+```
+
+## Execution Process
+
+```
+Session Detection:
+   ├─ Check if debug session exists for this bug
+   ├─ EXISTS + debug.log has content → Analyze mode
+   └─ NOT_FOUND or empty log → Explore mode
+
+Explore Mode:
+   ├─ Locate error source in codebase
+   ├─ Generate testable hypotheses (dynamic count)
+   ├─ Add NDJSON logging instrumentation
+   └─ Output: Hypothesis list + await user reproduction
+
+Analyze Mode:
+   ├─ Parse debug.log, validate each hypothesis
+   └─ Decision:
+       ├─ Confirmed → Fix root cause
+       ├─ Inconclusive → Add more logging, iterate
+       └─ All rejected → Generate new hypotheses
+
+Fix & Cleanup:
+   ├─ Apply fix based on confirmed hypothesis
+   ├─ User verifies
+   ├─ Remove debug instrumentation
+   └─ If not fixed → Return to Analyze mode
+```
+
+## Implementation
+
+### Session Setup & Mode Detection
+
+```javascript
+const getUtc8ISOString = () => new Date(Date.now() + 8 * 60 * 60 * 1000).toISOString()
+
+const bugSlug = bug_description.toLowerCase().replace(/[^a-z0-9]+/g, '-').substring(0, 30)
+const dateStr = getUtc8ISOString().substring(0, 10)
+
+const sessionId = `DBG-${bugSlug}-${dateStr}`
+const sessionFolder = `.workflow/.debug/${sessionId}`
+const debugLogPath = `${sessionFolder}/debug.log`
+
+// Auto-detect mode
+const sessionExists = fs.existsSync(sessionFolder)
+const logHasContent = sessionExists && fs.existsSync(debugLogPath) && fs.statSync(debugLogPath).size > 0
+
+const mode = logHasContent ? 'analyze' : 'explore'
+
+if (!sessionExists) {
+  bash(`mkdir -p ${sessionFolder}`)
+}
+```
+
+---
+
+### Explore Mode
+
+**Step 1.1: Locate Error Source**
+
+```javascript
+// Extract keywords from bug description
+const keywords = extractErrorKeywords(bug_description)
+// e.g., ['Stack Length', '未找到', 'registered 0']
+
+// Search codebase for error locations
+for (const keyword of keywords) {
+  Grep({ pattern: keyword, path: ".", output_mode: "content", "-C": 3 })
+}
+
+// Identify affected files and functions
+const affectedLocations = [...]  // from search results
+```
+
+**Step 1.2: Generate Hypotheses (Dynamic)**
+
+```javascript
+// Hypothesis categories based on error pattern
+const HYPOTHESIS_PATTERNS = {
+  "not found|missing|undefined|未找到": "data_mismatch",
+  "0|empty|zero|registered 0": "logic_error",
+  "timeout|connection|sync": "integration_issue",
+  "type|format|parse": "type_mismatch"
+}
+
+// Generate hypotheses based on actual issue (NOT fixed count)
+function generateHypotheses(bugDescription, affectedLocations) {
+  const hypotheses = []
+
+  // Analyze bug and create targeted hypotheses
+  // Each hypothesis has:
+  // - id: H1, H2, ... (dynamic count)
+  // - description: What might be wrong
+  // - testable_condition: What to log
+  // - logging_point: Where to add instrumentation
+
+  return hypotheses  // Could be 1, 3, 5, or more
+}
+
+const hypotheses = generateHypotheses(bug_description, affectedLocations)
+```
+
+**Step 1.3: Add NDJSON Instrumentation**
+
+For each hypothesis, add logging at the relevant location:
+
+**Python template**:
+```python
+# region debug [H{n}]
+try:
+    import json, time
+    _dbg = {
+        "sid": "{sessionId}",
+        "hid": "H{n}",
+        "loc": "{file}:{line}",
+        "msg": "{testable_condition}",
+        "data": {
+            # Capture relevant values here
+        },
+        "ts": int(time.time() * 1000)
+    }
+    with open(r"{debugLogPath}", "a", encoding="utf-8") as _f:
+        _f.write(json.dumps(_dbg, ensure_ascii=False) + "\n")
+except: pass
+# endregion
+```
+
+**JavaScript/TypeScript template**:
+```javascript
+// region debug [H{n}]
+try {
+  require('fs').appendFileSync("{debugLogPath}", JSON.stringify({
+    sid: "{sessionId}",
+    hid: "H{n}",
+    loc: "{file}:{line}",
+    msg: "{testable_condition}",
+    data: { /* Capture relevant values */ },
+    ts: Date.now()
+  }) + "\n");
+} catch(_) {}
+// endregion
+```
+
+**Output to user**:
+```
+## Hypotheses Generated
+
+Based on error "{bug_description}", generated {n} hypotheses:
+
+{hypotheses.map(h => `
+### ${h.id}: ${h.description}
+- Logging at: ${h.logging_point}
+- Testing: ${h.testable_condition}
+`).join('')}
+
+**Debug log**: ${debugLogPath}
+
+**Next**: Run reproduction steps, then come back for analysis.
+```
+
+---
+
+### Analyze Mode
+
+```javascript
+// Parse NDJSON log
+const entries = Read(debugLogPath).split('\n')
+  .filter(l => l.trim())
+  .map(l => JSON.parse(l))
+
+// Group by hypothesis
+const byHypothesis = groupBy(entries, 'hid')
+
+// Validate each hypothesis
+for (const [hid, logs] of Object.entries(byHypothesis)) {
+  const hypothesis = hypotheses.find(h => h.id === hid)
+  const latestLog = logs[logs.length - 1]
+
+  // Check if evidence confirms or rejects hypothesis
+  const verdict = evaluateEvidence(hypothesis, latestLog.data)
+  // Returns: 'confirmed' | 'rejected' | 'inconclusive'
+}
+```
+
+**Output**:
+```
+## Evidence Analysis
+
+Analyzed ${entries.length} log entries.
+
+${results.map(r => `
+### ${r.id}: ${r.description}
+- **Status**: ${r.verdict}
+- **Evidence**: ${JSON.stringify(r.evidence)}
+- **Reason**: ${r.reason}
+`).join('')}
+
+${confirmedHypothesis ? `
+## Root Cause Identified
+
+**${confirmedHypothesis.id}**: ${confirmedHypothesis.description}
+
+Ready to fix.
+` : `
+## Need More Evidence
+
+Add more logging or refine hypotheses.
+`}
+```
+
+---
+
+### Fix & Cleanup
+
+```javascript
+// Apply fix based on confirmed hypothesis
+// ... Edit affected files
+
+// After user verifies fix works:
+
+// Remove debug instrumentation (search for region markers)
+const instrumentedFiles = Grep({
+  pattern: "# region debug|// region debug",
+  output_mode: "files_with_matches"
+})
+
+for (const file of instrumentedFiles) {
+  // Remove content between region markers
+  removeDebugRegions(file)
+}
+
+console.log(`
+## Debug Complete
+
+- Root cause: ${confirmedHypothesis.description}
+- Fix applied to: ${modifiedFiles.join(', ')}
+- Debug instrumentation removed
+`)
+```
+
+---
+
+## Debug Log Format (NDJSON)
+
+Each line is a JSON object:
+
+```json
+{"sid":"DBG-xxx-2025-12-18","hid":"H1","loc":"file.py:func:42","msg":"Check dict keys","data":{"keys":["a","b"],"target":"c","found":false},"ts":1734567890123}
+```
+
+| Field | Description |
+|-------|-------------|
+| `sid` | Session ID |
+| `hid` | Hypothesis ID (H1, H2, ...) |
+| `loc` | Code location |
+| `msg` | What's being tested |
+| `data` | Captured values |
+| `ts` | Timestamp (ms) |
+
+## Session Folder
+
+```
+.workflow/.debug/DBG-{slug}-{date}/
+├── debug.log          # NDJSON log (main artifact)
+└── resolution.md      # Summary after fix (optional)
+```
+
+## Iteration Flow
+
+```
+First Call (/workflow:debug "error"):
+   ├─ No session exists → Explore mode
+   ├─ Extract error keywords, search codebase
+   ├─ Generate hypotheses, add logging
+   └─ Await user reproduction
+
+After Reproduction (/workflow:debug "error"):
+   ├─ Session exists + debug.log has content → Analyze mode
+   ├─ Parse log, evaluate hypotheses
+   └─ Decision:
+       ├─ Confirmed → Fix → User verify
+       │   ├─ Fixed → Cleanup → Done
+       │   └─ Not fixed → Add logging → Iterate
+       ├─ Inconclusive → Add logging → Iterate
+       └─ All rejected → New hypotheses → Iterate
+
+Output:
+   └─ .workflow/.debug/DBG-{slug}-{date}/debug.log
+```
+
+## Error Handling
+
+| Situation | Action |
+|-----------|--------|
+| Empty debug.log | Verify reproduction triggered the code path |
+| All hypotheses rejected | Generate new hypotheses with broader scope |
+| Fix doesn't work | Iterate with more granular logging |
+| >5 iterations | Escalate to `/workflow:lite-fix` with evidence |

package/.claude/commands/workflow/execute.md

@@ -56,6 +56,7 @@ Phase 2: Planning Document Validation
    └─ Validate .task/ contains IMPL-*.json files
 
 Phase 3: TodoWrite Generation
+   ├─ Update session status to "active" (Step 0)
    ├─ Parse TODO_LIST.md for task statuses
    ├─ Generate TodoWrite for entire workflow
    └─ Prepare session context paths
@@ -80,6 +81,7 @@ Phase 5: Completion
 Resume Mode (--resume-session):
    ├─ Skip Phase 1 & Phase 2
    └─ Entry Point: Phase 3 (TodoWrite Generation)
+      ├─ Update session status to "active" (if not already)
       └─ Continue: Phase 4 → Phase 5
 ```
 
@@ -179,6 +181,16 @@ bash(cat .workflow/active/${sessionId}/workflow-session.json)
 ### Phase 3: TodoWrite Generation
 **Applies to**: Both normal and resume modes (resume mode entry point)
 
+**Step 0: Update Session Status to Active**
+Before generating TodoWrite, update session status from "planning" to "active":
+```bash
+# Update session status (idempotent - safe to run if already active)
+jq '.status = "active" | .execution_started_at = (.execution_started_at // now | todate)' \
+  .workflow/active/${sessionId}/workflow-session.json > tmp.json && \
+  mv tmp.json .workflow/active/${sessionId}/workflow-session.json
+```
+This ensures the dashboard shows the session as "ACTIVE" during execution.
+
 **Process**:
 1. **Create TodoWrite List**: Generate task list from TODO_LIST.md (not from task JSONs)
    - Parse TODO_LIST.md to extract all tasks with current statuses
@@ -380,6 +392,7 @@ TodoWrite({
 
 ```bash
 Task(subagent_type="{meta.agent}",
+     run_in_background=false,
      prompt="Execute task: {task.title}
 
      {[FLOW_CONTROL]}

package/.claude/commands/workflow/init.md

@@ -1,164 +1,165 @@
----
-name: init
-description: Initialize project-level state with intelligent project analysis using cli-explore-agent
-argument-hint: "[--regenerate]"
-examples:
-  - /workflow:init
-  - /workflow:init --regenerate
----
-
-# Workflow Init Command (/workflow:init)
-
-## Overview
-Initialize `.workflow/project.json` with comprehensive project understanding by delegating analysis to **cli-explore-agent**.
-
-**Note**: This command may be called by other workflow commands. Upon completion, return immediately to continue the calling workflow without interrupting the task flow.
-
-## Usage
-```bash
-/workflow:init                 # Initialize (skip if exists)
-/workflow:init --regenerate    # Force regeneration
-```
-
-## Execution Process
-
-```
-Input Parsing:
-   └─ Parse --regenerate flag → regenerate = true | false
-
-Decision:
-   ├─ EXISTS + no --regenerate → Exit: "Already initialized"
-   ├─ EXISTS + --regenerate → Backup existing → Continue analysis
-   └─ NOT_FOUND → Continue analysis
-
-Analysis Flow:
-   ├─ Get project metadata (name, root)
-   ├─ Invoke cli-explore-agent
-   │   ├─ Structural scan (get_modules_by_depth.sh, find, wc)
-   │   ├─ Semantic analysis (Gemini CLI)
-   │   ├─ Synthesis and merge
-   │   └─ Write .workflow/project.json
-   └─ Display summary
-
-Output:
-   └─ .workflow/project.json (+ .backup if regenerate)
-```
-
-## Implementation
-
-### Step 1: Parse Input and Check Existing State
-
-**Parse --regenerate flag**:
-```javascript
-const regenerate = $ARGUMENTS.includes('--regenerate')
-```
-
-**Check existing state**:
-
-```bash
-bash(test -f .workflow/project.json && echo "EXISTS" || echo "NOT_FOUND")
-```
-
-**If EXISTS and no --regenerate**: Exit early
-```
-Project already initialized at .workflow/project.json
-Use /workflow:init --regenerate to rebuild
-Use /workflow:status --project to view state
-```
-
-### Step 2: Get Project Metadata
-
-```bash
-bash(basename "$(git rev-parse --show-toplevel 2>/dev/null || pwd)")
-bash(git rev-parse --show-toplevel 2>/dev/null || pwd)
-bash(mkdir -p .workflow)
-```
-
-### Step 3: Invoke cli-explore-agent
-
-**For --regenerate**: Backup and preserve existing data
-```bash
-bash(cp .workflow/project.json .workflow/project.json.backup)
-```
-
-**Delegate analysis to agent**:
-
-```javascript
-Task(
-  subagent_type="cli-explore-agent",
-  description="Deep project analysis",
-  prompt=`
-Analyze project for workflow initialization and generate .workflow/project.json.
-
-## MANDATORY FIRST STEPS
-1. Execute: cat ~/.claude/workflows/cli-templates/schemas/project-json-schema.json (get schema reference)
-2. Execute: ccw tool exec get_modules_by_depth '{}' (get project structure)
-
-## Task
-Generate complete project.json with:
-- project_name: ${projectName}
-- initialized_at: current ISO timestamp
-- overview: {description, technology_stack, architecture, key_components}
-- features: ${regenerate ? 'preserve from backup' : '[] (empty)'}
-- development_index: ${regenerate ? 'preserve from backup' : '{feature: [], enhancement: [], bugfix: [], refactor: [], docs: []}'}
-- statistics: ${regenerate ? 'preserve from backup' : '{total_features: 0, total_sessions: 0, last_updated}'}
-- _metadata: {initialized_by: "cli-explore-agent", analysis_timestamp, analysis_mode}
-
-## Analysis Requirements
-
-**Technology Stack**:
-- Languages: File counts, mark primary
-- Frameworks: From package.json, requirements.txt, go.mod, etc.
-- Build tools: npm, cargo, maven, webpack, vite
-- Test frameworks: jest, pytest, go test, junit
-
-**Architecture**:
-- Style: MVC, microservices, layered (from structure & imports)
-- Layers: presentation, business-logic, data-access
-- Patterns: singleton, factory, repository
-- Key components: 5-10 modules {name, path, description, importance}
-
-## Execution
-1. Structural scan: get_modules_by_depth.sh, find, wc -l
-2. Semantic analysis: Gemini for patterns/architecture
-3. Synthesis: Merge findings
-4. ${regenerate ? 'Merge with preserved features/development_index/statistics from .workflow/project.json.backup' : ''}
-5. Write JSON: Write('.workflow/project.json', jsonContent)
-6. Report: Return brief completion summary
-
-Project root: ${projectRoot}
-`
-)
-```
-
-### Step 4: Display Summary
-
-```javascript
-const projectJson = JSON.parse(Read('.workflow/project.json'));
-
-console.log(`
-✓ Project initialized successfully
-
-## Project Overview
-Name: ${projectJson.project_name}
-Description: ${projectJson.overview.description}
-
-### Technology Stack
-Languages: ${projectJson.overview.technology_stack.languages.map(l => l.name).join(', ')}
-Frameworks: ${projectJson.overview.technology_stack.frameworks.join(', ')}
-
-### Architecture
-Style: ${projectJson.overview.architecture.style}
-Components: ${projectJson.overview.key_components.length} core modules
-
----
-Project state: .workflow/project.json
-${regenerate ? 'Backup: .workflow/project.json.backup' : ''}
-`);
-```
-
-## Error Handling
-
-**Agent Failure**: Fall back to basic initialization with placeholder overview
-**Missing Tools**: Agent uses Qwen fallback or bash-only
-**Empty Project**: Create minimal JSON with all gaps identified
+---
+name: init
+description: Initialize project-level state with intelligent project analysis using cli-explore-agent
+argument-hint: "[--regenerate]"
+examples:
+  - /workflow:init
+  - /workflow:init --regenerate
+---
+
+# Workflow Init Command (/workflow:init)
+
+## Overview
+Initialize `.workflow/project.json` with comprehensive project understanding by delegating analysis to **cli-explore-agent**.
+
+**Note**: This command may be called by other workflow commands. Upon completion, return immediately to continue the calling workflow without interrupting the task flow.
+
+## Usage
+```bash
+/workflow:init                 # Initialize (skip if exists)
+/workflow:init --regenerate    # Force regeneration
+```
+
+## Execution Process
+
+```
+Input Parsing:
+   └─ Parse --regenerate flag → regenerate = true | false
+
+Decision:
+   ├─ EXISTS + no --regenerate → Exit: "Already initialized"
+   ├─ EXISTS + --regenerate → Backup existing → Continue analysis
+   └─ NOT_FOUND → Continue analysis
+
+Analysis Flow:
+   ├─ Get project metadata (name, root)
+   ├─ Invoke cli-explore-agent
+   │   ├─ Structural scan (get_modules_by_depth.sh, find, wc)
+   │   ├─ Semantic analysis (Gemini CLI)
+   │   ├─ Synthesis and merge
+   │   └─ Write .workflow/project.json
+   └─ Display summary
+
+Output:
+   └─ .workflow/project.json (+ .backup if regenerate)
+```
+
+## Implementation
+
+### Step 1: Parse Input and Check Existing State
+
+**Parse --regenerate flag**:
+```javascript
+const regenerate = $ARGUMENTS.includes('--regenerate')
+```
+
+**Check existing state**:
+
+```bash
+bash(test -f .workflow/project.json && echo "EXISTS" || echo "NOT_FOUND")
+```
+
+**If EXISTS and no --regenerate**: Exit early
+```
+Project already initialized at .workflow/project.json
+Use /workflow:init --regenerate to rebuild
+Use /workflow:status --project to view state
+```
+
+### Step 2: Get Project Metadata
+
+```bash
+bash(basename "$(git rev-parse --show-toplevel 2>/dev/null || pwd)")
+bash(git rev-parse --show-toplevel 2>/dev/null || pwd)
+bash(mkdir -p .workflow)
+```
+
+### Step 3: Invoke cli-explore-agent
+
+**For --regenerate**: Backup and preserve existing data
+```bash
+bash(cp .workflow/project.json .workflow/project.json.backup)
+```
+
+**Delegate analysis to agent**:
+
+```javascript
+Task(
+  subagent_type="cli-explore-agent",
+  run_in_background=false,
+  description="Deep project analysis",
+  prompt=`
+Analyze project for workflow initialization and generate .workflow/project.json.
+
+## MANDATORY FIRST STEPS
+1. Execute: cat ~/.claude/workflows/cli-templates/schemas/project-json-schema.json (get schema reference)
+2. Execute: ccw tool exec get_modules_by_depth '{}' (get project structure)
+
+## Task
+Generate complete project.json with:
+- project_name: ${projectName}
+- initialized_at: current ISO timestamp
+- overview: {description, technology_stack, architecture, key_components}
+- features: ${regenerate ? 'preserve from backup' : '[] (empty)'}
+- development_index: ${regenerate ? 'preserve from backup' : '{feature: [], enhancement: [], bugfix: [], refactor: [], docs: []}'}
+- statistics: ${regenerate ? 'preserve from backup' : '{total_features: 0, total_sessions: 0, last_updated}'}
+- _metadata: {initialized_by: "cli-explore-agent", analysis_timestamp, analysis_mode}
+
+## Analysis Requirements
+
+**Technology Stack**:
+- Languages: File counts, mark primary
+- Frameworks: From package.json, requirements.txt, go.mod, etc.
+- Build tools: npm, cargo, maven, webpack, vite
+- Test frameworks: jest, pytest, go test, junit
+
+**Architecture**:
+- Style: MVC, microservices, layered (from structure & imports)
+- Layers: presentation, business-logic, data-access
+- Patterns: singleton, factory, repository
+- Key components: 5-10 modules {name, path, description, importance}
+
+## Execution
+1. Structural scan: get_modules_by_depth.sh, find, wc -l
+2. Semantic analysis: Gemini for patterns/architecture
+3. Synthesis: Merge findings
+4. ${regenerate ? 'Merge with preserved features/development_index/statistics from .workflow/project.json.backup' : ''}
+5. Write JSON: Write('.workflow/project.json', jsonContent)
+6. Report: Return brief completion summary
+
+Project root: ${projectRoot}
+`
+)
+```
+
+### Step 4: Display Summary
+
+```javascript
+const projectJson = JSON.parse(Read('.workflow/project.json'));
+
+console.log(`
+✓ Project initialized successfully
+
+## Project Overview
+Name: ${projectJson.project_name}
+Description: ${projectJson.overview.description}
+
+### Technology Stack
+Languages: ${projectJson.overview.technology_stack.languages.map(l => l.name).join(', ')}
+Frameworks: ${projectJson.overview.technology_stack.frameworks.join(', ')}
+
+### Architecture
+Style: ${projectJson.overview.architecture.style}
+Components: ${projectJson.overview.key_components.length} core modules
+
+---
+Project state: .workflow/project.json
+${regenerate ? 'Backup: .workflow/project.json.backup' : ''}
+`);
+```
+
+## Error Handling
+
+**Agent Failure**: Fall back to basic initialization with placeholder overview
+**Missing Tools**: Agent uses Qwen fallback or bash-only
+**Empty Project**: Create minimal JSON with all gaps identified