claude-code-workflow 6.2.1 → 6.2.2

package/.codex/AGENTS.md

@@ -0,0 +1,63 @@
+# 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

package/.codex/prompts/execute.md

@@ -0,0 +1,273 @@
+---
+description: Execute workflow tasks sequentially from session folder
+argument-hint: SESSION=<path-to-session-folder>
+---
+
+# Workflow Execute (Codex Version)
+
+## Core Principle
+
+**Serial Execution**: Execute tasks ONE BY ONE in dependency order. Complete current task fully before moving to next. Continue autonomously until ALL tasks complete.
+
+## Input
+
+Session folder path via `$SESSION` (e.g., `.workflow/active/WFS-auth-system`)
+
+## Task Tracking (JSON Source of Truth + Codex TODO Tool)
+
+- **Source of truth**: Task state MUST be read from and written to `$SESSION/.task/IMPL-*.json`.
+- **Markdown views**: `$SESSION/TODO_LIST.md` and `$SESSION/IMPL_PLAN.md` are views; use them for ordering and display, but do NOT trust them for status.
+- **Codex TODO tool**: Mirror the workflow into the built-in `update_plan` tool so progress is visible and consistent.
+
+### Status mapping (Task JSON → `update_plan`)
+
+- Task JSON uses workflow statuses (source of truth): `pending`, `in_progress`, `completed` (optionally also `blocked`, `cancelled`, `container`).
+- `update_plan` only supports: `pending`, `in_progress`, `completed`.
+- Map as:
+  - `pending|blocked|cancelled|container` → `pending`
+  - `in_progress` → `in_progress`
+  - `completed` → `completed`
+
+### `update_plan` rules (must follow)
+
+1. At most ONE step can be `in_progress` at a time.
+2. Do NOT jump `pending → completed`; always go through `in_progress`.
+3. Do NOT batch-complete steps after the fact; update as you go.
+4. If the plan changes (new tasks, re-order, merge/split), call `update_plan` with an `explanation`.
+5. After calling `update_plan`, do NOT repeat the full plan in chat; only output a short progress line.
+6. Keep each `step` short and stable (ID-first), e.g. `IMPL-1.1 - Add JWT middleware`.
+
+## Autonomous Execution Loop
+
+```
+INIT: Validate session folder structure
+
+WHILE tasks remain:
+  1. Read TODO_LIST.md → Get ordered task IDs (ignore checkbox status)
+  2. For each task ID, read $SESSION/.task/{task-id}.json → Get true status + deps
+  3. Find FIRST eligible task:
+     - status != "completed"
+     - deps = taskJson.depends_on OR taskJson.context.depends_on (source of truth)
+     - deps all completed (from JSON)
+     - task is executable (skip status="container" or tasks with subtasks)
+  4. Mark task JSON status to "in_progress" (immediately)
+  5. Mirror status to `update_plan` (exactly one in_progress)
+  6. Execute task fully (pre-analysis → implementation → verification)
+  7. Mark task JSON status to "completed" (immediately after verification)
+  8. Mirror completion to `update_plan`, output progress line, CONTINUE (DO NOT STOP)
+
+WHEN all tasks completed:
+  Output final summary
+```
+
+## Execution Steps
+
+### Step 1: Validate Session
+
+Check required files exist:
+```
+$SESSION/
+├── IMPL_PLAN.md        ← Required
+├── TODO_LIST.md        ← Required
+└── .task/              ← Required, must have IMPL-*.json
+```
+
+If missing, report error and stop.
+
+### Step 2: Parse TODO_LIST.md
+
+Extract the ordered task list (IDs + titles). Do not treat checkbox states as authoritative.
+```markdown
+- ▸ **IMPL-1**: Parent task (container)
+- [x] IMPL-1: Task 1 title (completed)
+- [ ] IMPL-1.1: Task 2 title (pending) ← Execute this
+- [ ] IMPL-2: Task 3 title (pending, depends on IMPL-1.1)
+```
+
+### Step 3: Find Next Executable Task
+
+```javascript
+// Sequential scan for first eligible task
+for (task of todoList) {
+  taskJson = read(`$SESSION/.task/${task.id}.json`)
+  if (taskJson.status === "completed") continue
+  if (taskJson.status === "container") continue
+  
+  // Check dependencies from task JSON (source of truth)
+  const deps = taskJson.depends_on || taskJson.context?.depends_on || []
+  if (deps.every(dep => read(`$SESSION/.task/${dep}.json`).status === "completed")) {
+    return task  // Execute this one
+  }
+}
+return null  // All done or all blocked
+```
+
+### Step 4: Load Task Context
+
+```bash
+# Read task definition
+cat $SESSION/.task/$TASK_ID.json
+
+# Read context package if exists
+cat $SESSION/.process/context-package.json
+```
+
+### Step 5: Initialize Task Tracking (Codex TODO tool)
+
+Before executing the first task, initialize `update_plan` from the ordered task list:
+- Only include executable tasks (skip containers) to avoid non-actionable TODO items.
+- `step`: Use a stable ID-first label like `IMPL-1.1 - {title}`.
+- `status`: Map from task JSON status using the rules above.
+
+Keep this plan updated throughout execution (see rules above).
+
+Example initialization:
+```javascript
+update_plan({
+  plan: [
+    { step: "IMPL-1.1 - Task title", status: "pending" },
+    { step: "IMPL-2 - Task title", status: "pending" }
+  ]
+})
+```
+
+### Step 6: Execute Task
+
+#### 6A: Pre-Analysis (if flow_control.pre_analysis exists)
+```markdown
+## Pre-Analysis for: [task.title]
+
+Execute each step:
+1. [Read referenced files]
+2. [Search for patterns]
+3. [Load dependencies]
+```
+
+#### 6B: Implementation
+```markdown
+## Implementing: [task.title]
+
+**Requirements**:
+- [context.requirements[0]]
+- ...
+
+**Steps**:
+1. [flow_control.implementation_approach[0].step] - [flow_control.implementation_approach[0].action]
+2. [flow_control.implementation_approach[1].step] - [flow_control.implementation_approach[1].action]
+...
+
+**Focus Paths**:
+- [context.focus_paths[0]]
+- ...
+```
+
+#### 6C: Verification
+```markdown
+## Verifying: [task.title]
+
+**Acceptance Criteria**:
+- [x] [context.acceptance[0]]
+- [x] [context.acceptance[1]]
+
+All criteria met: YES → Mark completed
+```
+
+### Step 7: Update Status
+
+Update task JSON with correct transitions:
+- Before executing: `pending → in_progress`
+- After verification: `in_progress → completed`
+
+```json
+{
+  "id": "IMPL-1.1",
+  "status": "completed",
+  "completed_at": "2025-12-15T..."
+}
+```
+
+### Step 8: Continue Immediately
+
+**DO NOT STOP. Return to Step 2 to find next task.**
+
+Output progress:
+```
+✓ [3/7] Completed: IMPL-1.1 - [task title]
+→ Next: IMPL-2 - [next task title]
+```
+
+## Task JSON Structure
+
+```json
+{
+  "id": "IMPL-1.1",
+  "title": "Task Title",
+  "status": "pending|in_progress|completed|blocked|cancelled|container",
+  "meta": {
+    "type": "feature|test|docs",
+    "agent": "code-developer|test-fix-agent|..."
+  },
+  "context": {
+    "requirements": ["Requirement 1", "Requirement 2"],
+    "focus_paths": ["src/module/"],
+    "acceptance": ["Criterion 1", "Criterion 2"],
+    "depends_on": ["IMPL-1"]
+  },
+  "flow_control": {
+    "pre_analysis": ["step 1", "step 2"],
+    "implementation_approach": [
+      { "step": "Step 1", "action": "Do X" },
+      { "step": "Step 2", "action": "Do Y" }
+    ]
+  },
+  "depends_on": ["IMPL-1"]
+}
+```
+
+## Execution Rules
+
+1. **Never stop mid-workflow** - Continue until all tasks complete
+2. **One task at a time** - Fully complete before moving on
+3. **Respect dependencies** - Skip blocked tasks, find next eligible
+4. **Update status immediately** - Mark `in_progress` on start, `completed` right after verification
+5. **Self-verify** - All acceptance criteria must pass before marking done
+6. **Handle blocked state** - If all remaining tasks have unmet deps, report and stop
+7. **Keep tracking in sync** - Task JSON is truth; `update_plan` must reflect the same state
+
+## Final Summary
+
+When ALL tasks completed:
+
+```markdown
+## Workflow Execution Complete
+
+**Session**: $SESSION
+**Total Tasks**: N
+**Completed**: N
+
+### Execution Log
+| # | Task ID | Title | Status |
+|---|---------|-------|--------|
+| 1 | IMPL-1 | ... | ✓ |
+| 2 | IMPL-1.1 | ... | ✓ |
+| 3 | IMPL-2 | ... | ✓ |
+
+### Files Modified
+- `src/auth/login.ts`
+- `src/utils/validator.ts`
+
+### Summary
+[What was accomplished across all tasks]
+```
+
+## Error Handling
+
+| Situation | Action |
+|-----------|--------|
+| Session folder not found | Error and stop |
+| Missing required files | Error: specify which file missing |
+| Task JSON not found | Error, skip task, continue |
+| Task blocked (deps not met) | Skip, find next eligible task |
+| All tasks blocked | Report circular dependency, stop |
+| Execution error | Report, set task JSON back to `pending`, continue to next eligible task |
+| Verification failed | Retry once; if still failing, set back to `pending` and continue |