claude-code-workflow 6.1.4 → 6.2.2

package/.codex/AGENTS.md

@@ -1,330 +1,63 @@
-# Codex Agent Execution Protocol
-
-## Overview
-
-**Role**: Autonomous development, implementation, and testing specialist
-
-## Prompt Structure
-
-All prompts follow this 6-field format:
-
-```
-PURPOSE: [development goal]
-TASK: [specific implementation task]
-MODE: [auto|write]
-CONTEXT: [file patterns]
-EXPECTED: [deliverables]
-RULES: [templates | additional constraints]
-```
-
-**Subtask indicator**: `Subtask N of M: [title]` or `CONTINUE TO NEXT SUBTASK`
-
-## MODE Definitions
-
-### MODE: auto (default)
-
-**Permissions**:
-- Full file operations (create/modify/delete)
-- Run tests and builds
-- Commit code incrementally
-
-**Execute**:
-1. Parse PURPOSE and TASK
-2. Analyze CONTEXT files - find 3+ similar patterns
-3. Plan implementation following RULES
-4. Generate code with tests
-5. Run tests continuously
-6. Commit working code incrementally
-7. Validate EXPECTED deliverables
-8. Report results (with context for next subtask if multi-task)
-
-**Constraint**: Must test every change
-
-### MODE: write
-
-**Permissions**:
-- Focused file operations
-- Create/modify specific files
-- Run tests for validation
-
-**Execute**:
-1. Analyze CONTEXT files
-2. Make targeted changes
-3. Validate tests pass
-4. Report file changes
-
-## Execution Protocol
-
-### Core Requirements
-
-**ALWAYS**:
-- Parse all 6 fields (PURPOSE, TASK, MODE, CONTEXT, EXPECTED, RULES)
-- Study CONTEXT files - find 3+ similar patterns before implementing
-- Apply RULES (templates + constraints) exactly
-- Test continuously after every change
-- Commit incrementally with working code
-- Match project style and patterns exactly
-- List all created/modified files at output beginning
-- Use direct binary calls (avoid shell wrappers)
-- Prefer apply_patch for text edits
-- Configure Windows UTF-8 encoding for Chinese support
-
-**NEVER**:
-- Make assumptions without code verification
-- Ignore existing patterns
-- Skip tests
-- Use clever tricks over boring solutions
-- Over-engineer solutions
-- Break existing code or backward compatibility
-- Exceed 3 failed attempts without stopping
-
-### RULES Processing
-
-- Parse RULES field to extract template content and constraints
-- Recognize `|` as separator: `template content | additional constraints`
-- Apply ALL template guidelines as mandatory
-- Apply ALL additional constraints as mandatory
-- Treat rule violations as task failures
-
-### Multi-Task Execution (Resume Pattern)
-
-**First subtask**: Standard execution flow above
-**Subsequent subtasks** (via `resume --last`):
-- Recall context from previous subtasks
-- Build on previous work (don't repeat)
-- Maintain consistency with established patterns
-- Focus on current subtask scope only
-- Test integration with previous work
-- Report context for next subtask
-
-## System Optimization
-
-**Direct Binary Calls**: Always call binaries directly in `functions.shell`, set `workdir`, avoid shell wrappers (`bash -lc`, `cmd /c`, etc.)
-
-**Text Editing Priority**:
-1. Use `apply_patch` tool for all routine text edits
-2. Fall back to `sed` for single-line substitutions if unavailable
-3. Avoid Python editing scripts unless both fail
-
-**apply_patch invocation**:
-```json
-{
-  "command": ["apply_patch", "*** Begin Patch\n*** Update File: path/to/file\n@@\n- old\n+ new\n*** End Patch\n"],
-  "workdir": "<workdir>",
-  "justification": "Brief reason"
-}
-```
-
-**Windows UTF-8 Encoding** (before commands):
-```powershell
-[Console]::InputEncoding  = [Text.UTF8Encoding]::new($false)
-[Console]::OutputEncoding = [Text.UTF8Encoding]::new($false)
-chcp 65001 > $null
-```
-
-## Output Standards
-
-### Format Priority
-
-**If template defines output format** → Follow template format EXACTLY (all sections mandatory)
-
-**If template has no format** → Use default format below based on task type
-
-### Default Output Formats
-
-#### Single Task Implementation
-
-```markdown
-# Implementation: [TASK Title]
-
-## Changes
-- Created: `path/to/file1.ext` (X lines)
-- Modified: `path/to/file2.ext` (+Y/-Z lines)
-- Deleted: `path/to/file3.ext`
-
-## Summary
-[2-3 sentence overview of what was implemented]
-
-## Key Decisions
-1. [Decision] - Rationale and reference to similar pattern
-2. [Decision] - path/to/reference:line
-
-## Implementation Details
-[Evidence-based description with code references]
-
-## Testing
-- Tests written: X new tests
-- Tests passing: Y/Z tests
-- Coverage: N%
-
-## Validation
-✅ Tests: X passing
-✅ Coverage: Y%
-✅ Build: Success
-
-## Next Steps
-[Recommendations or future improvements]
-```
-
-#### Multi-Task Execution (with Resume)
-
-**First Subtask**:
-```markdown
-# Subtask 1/N: [TASK Title]
-
-## Changes
-[List of file changes]
-
-## Implementation
-[Details with code references]
-
-## Testing
-✅ Tests: X passing
-✅ Integration: Compatible with existing code
-
-## Context for Next Subtask
-- Key decisions: [established patterns]
-- Files created: [paths and purposes]
-- Integration points: [where next subtask should connect]
-```
-
-**Subsequent Subtasks**:
-```markdown
-# Subtask N/M: [TASK Title]
-
-## Changes
-[List of file changes]
-
-## Integration Notes
-✅ Compatible with subtask N-1
-✅ Maintains established patterns
-✅ Tests pass with previous work
-
-## Implementation
-[Details with code references]
-
-## Testing
-✅ Tests: X passing
-✅ Total coverage: Y%
-
-## Context for Next Subtask
-[If not final subtask, provide context for continuation]
-```
-
-#### Partial Completion
-
-```markdown
-# Task Status: Partially Completed
-
-## Completed
-- [What worked successfully]
-- Files: `path/to/completed.ext`
-
-## Blocked
-- **Issue**: [What failed]
-- **Root Cause**: [Analysis of failure]
-- **Attempted**: [Solutions tried - attempt X of 3]
-
-## Required
-[What's needed to proceed]
-
-## Recommendation
-[Suggested next steps or alternative approaches]
-```
-
-### Code References
-
-**Format**: `path/to/file:line_number`
-
-**Example**: `src/auth/jwt.ts:45` - Implemented token validation following pattern from `src/auth/session.ts:78`
-
-### Related Files Section
-
-**Always include at output beginning** - List ALL files analyzed, created, or modified:
-
-```markdown
-## Related Files
-- `path/to/file1.ext` - [Role in implementation]
-- `path/to/file2.ext` - [Reference pattern used]
-- `path/to/file3.ext` - [Modified for X reason]
-```
-
-## Error Handling
-
-### Three-Attempt Rule
-
-**On 3rd failed attempt**:
-1. Stop execution
-2. Report: What attempted, what failed, root cause
-3. Request guidance or suggest alternatives
-
-### Recovery Strategies
-
-| Error Type | Response |
-|------------|----------|
-| **Syntax/Type** | Review errors → Fix → Re-run tests → Validate build |
-| **Runtime** | Analyze stack trace → Add error handling → Test error cases |
-| **Test Failure** | Debug in isolation → Review setup → Fix implementation/test |
-| **Build Failure** | Check messages → Fix incrementally → Validate each fix |
-
-## Quality Standards
-
-### Code Quality
-- Follow project's existing patterns
-- Match import style and naming conventions
-- Single responsibility per function/class
-- DRY (Don't Repeat Yourself)
-- YAGNI (You Aren't Gonna Need It)
-
-### Testing
-- Test all public functions
-- Test edge cases and error conditions
-- Mock external dependencies
-- Target 80%+ coverage
-
-### Error Handling
-- Proper try-catch blocks
-- Clear error messages
-- Graceful degradation
-- Don't expose sensitive info
-
-## Core Principles
-
-**Incremental Progress**:
-- Small, testable changes
-- Commit working code frequently
-- Build on previous work (subtasks)
-
-**Evidence-Based**:
-- Study 3+ similar patterns before implementing
-- Match project style exactly
-- Verify with existing code
-
-**Pragmatic**:
-- Boring solutions over clever code
-- Simple over complex
-- Adapt to project reality
-
-**Context Continuity** (Multi-Task):
-- Leverage resume for consistency
-- Maintain established patterns
-- Test integration between subtasks
-
-## Execution Checklist
-
-**Before**:
-- [ ] Understand PURPOSE and TASK clearly
-- [ ] Review CONTEXT files, find 3+ patterns
-- [ ] Check RULES templates and constraints
-
-**During**:
-- [ ] Follow existing patterns exactly
-- [ ] Write tests alongside code
-- [ ] Run tests after every change
-- [ ] Commit working code incrementally
-
-**After**:
-- [ ] All tests pass
-- [ ] Coverage meets target
-- [ ] Build succeeds
-- [ ] All EXPECTED deliverables met
+# Codex Code Guidelines
+
+## Code Quality Standards
+
+### Code Quality
+- Follow project's existing patterns
+- Match import style and naming conventions
+- Single responsibility per function/class
+- DRY (Don't Repeat Yourself)
+- YAGNI (You Aren't Gonna Need It)
+
+### Testing
+- Test all public functions
+- Test edge cases and error conditions
+- Mock external dependencies
+- Target 80%+ coverage
+
+### Error Handling
+- Proper try-catch blocks
+- Clear error messages
+- Graceful degradation
+- Don't expose sensitive info
+
+## Core Principles
+
+**Incremental Progress**:
+- Small, testable changes
+- Commit working code frequently
+- Build on previous work (subtasks)
+
+**Evidence-Based**:
+- Study 3+ similar patterns before implementing
+- Match project style exactly
+- Verify with existing code
+
+**Pragmatic**:
+- Boring solutions over clever code
+- Simple over complex
+- Adapt to project reality
+
+**Context Continuity** (Multi-Task):
+- Leverage resume for consistency
+- Maintain established patterns
+- Test integration between subtasks
+
+## Execution Checklist
+
+**Before**:
+- [ ] Understand PURPOSE and TASK clearly
+- [ ] Review CONTEXT files, find 3+ patterns
+- [ ] Check RULES templates and constraints
+
+**During**:
+- [ ] Follow existing patterns exactly
+- [ ] Write tests alongside code
+- [ ] Run tests after every change
+- [ ] Commit working code incrementally
+
+**After**:
+- [ ] All tests pass
+- [ ] Coverage meets target
+- [ ] Build succeeds
+- [ ] All EXPECTED deliverables met

package/.codex/prompts/debug.md

@@ -0,0 +1,318 @@
+---
+description: Interactive hypothesis-driven debugging with NDJSON logging, iterative until resolved
+argument-hint: BUG="<bug description or error message>"
+---
+
+# Workflow Debug Command
+
+## 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
+
+## Bug Description
+
+**Target bug**: $BUG
+
+## 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".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")
+// 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", 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", 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 (/prompts:debug BUG="error"):
+   ├─ No session exists → Explore mode
+   ├─ Extract error keywords, search codebase
+   ├─ Generate hypotheses, add logging
+   └─ Await user reproduction
+
+After Reproduction (/prompts:debug BUG="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 with collected evidence |
+
+---
+
+**Now execute the debug workflow for bug**: $BUG