claude-code-workflow 6.2.3 → 6.2.5

package/.codex/AGENTS.md

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

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

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