claude-code-workflow 6.3.37 → 6.3.39

package/.codex/skills/ccw-loop/phases/state-schema.md

@@ -0,0 +1,388 @@
+# State Schema (Codex Version)
+
+CCW Loop state structure definition for Codex subagent pattern.
+
+## State File
+
+**Location**: `.workflow/.loop/{loopId}.json` (unified location, API + Skill shared)
+
+## Structure Definition
+
+### Unified Loop State Interface
+
+```typescript
+/**
+ * Unified Loop State - API and Skill shared state structure
+ * API (loop-v2-routes.ts) owns state control
+ * Skill (ccw-loop) reads and updates this state via subagent
+ */
+interface LoopState {
+  // =====================================================
+  // API FIELDS (from loop-v2-routes.ts)
+  // These fields are managed by API, Skill read-only
+  // =====================================================
+
+  loop_id: string                // Loop ID, e.g., "loop-v2-20260122-abc123"
+  title: string                  // Loop title
+  description: string            // Loop description
+  max_iterations: number         // Maximum iteration count
+  status: 'created' | 'running' | 'paused' | 'completed' | 'failed' | 'user_exit'
+  current_iteration: number      // Current iteration count
+  created_at: string             // Creation time (ISO8601)
+  updated_at: string             // Last update time (ISO8601)
+  completed_at?: string          // Completion time (ISO8601)
+  failure_reason?: string        // Failure reason
+
+  // =====================================================
+  // SKILL EXTENSION FIELDS
+  // These fields are managed by Skill executor agent
+  // =====================================================
+
+  skill_state?: {
+    // Current execution action
+    current_action: 'init' | 'develop' | 'debug' | 'validate' | 'complete' | null
+    last_action: string | null
+    completed_actions: string[]
+    mode: 'interactive' | 'auto'
+
+    // === Development Phase ===
+    develop: {
+      total: number
+      completed: number
+      current_task?: string
+      tasks: DevelopTask[]
+      last_progress_at: string | null
+    }
+
+    // === Debug Phase ===
+    debug: {
+      active_bug?: string
+      hypotheses_count: number
+      hypotheses: Hypothesis[]
+      confirmed_hypothesis: string | null
+      iteration: number
+      last_analysis_at: string | null
+    }
+
+    // === Validation Phase ===
+    validate: {
+      pass_rate: number           // Test pass rate (0-100)
+      coverage: number            // Coverage (0-100)
+      test_results: TestResult[]
+      passed: boolean
+      failed_tests: string[]
+      last_run_at: string | null
+    }
+
+    // === Error Tracking ===
+    errors: Array<{
+      action: string
+      message: string
+      timestamp: string
+    }>
+
+    // === Summary (after completion) ===
+    summary?: {
+      duration: number
+      iterations: number
+      develop: object
+      debug: object
+      validate: object
+    }
+  }
+}
+
+interface DevelopTask {
+  id: string
+  description: string
+  tool: 'gemini' | 'qwen' | 'codex' | 'bash'
+  mode: 'analysis' | 'write'
+  status: 'pending' | 'in_progress' | 'completed' | 'failed'
+  files_changed: string[]
+  created_at: string
+  completed_at: string | null
+}
+
+interface Hypothesis {
+  id: string                    // H1, H2, ...
+  description: string
+  testable_condition: string
+  logging_point: string
+  evidence_criteria: {
+    confirm: string
+    reject: string
+  }
+  likelihood: number            // 1 = most likely
+  status: 'pending' | 'confirmed' | 'rejected' | 'inconclusive'
+  evidence: Record<string, any> | null
+  verdict_reason: string | null
+}
+
+interface TestResult {
+  test_name: string
+  suite: string
+  status: 'passed' | 'failed' | 'skipped'
+  duration_ms: number
+  error_message: string | null
+  stack_trace: string | null
+}
+```
+
+## Initial State
+
+### Created by API (Dashboard Trigger)
+
+```json
+{
+  "loop_id": "loop-v2-20260122-abc123",
+  "title": "Implement user authentication",
+  "description": "Add login/logout functionality",
+  "max_iterations": 10,
+  "status": "created",
+  "current_iteration": 0,
+  "created_at": "2026-01-22T10:00:00+08:00",
+  "updated_at": "2026-01-22T10:00:00+08:00"
+}
+```
+
+### After Skill Initialization (INIT action)
+
+```json
+{
+  "loop_id": "loop-v2-20260122-abc123",
+  "title": "Implement user authentication",
+  "description": "Add login/logout functionality",
+  "max_iterations": 10,
+  "status": "running",
+  "current_iteration": 0,
+  "created_at": "2026-01-22T10:00:00+08:00",
+  "updated_at": "2026-01-22T10:00:05+08:00",
+
+  "skill_state": {
+    "current_action": "init",
+    "last_action": null,
+    "completed_actions": [],
+    "mode": "auto",
+
+    "develop": {
+      "total": 3,
+      "completed": 0,
+      "current_task": null,
+      "tasks": [
+        { "id": "task-001", "description": "Create auth component", "status": "pending" }
+      ],
+      "last_progress_at": null
+    },
+
+    "debug": {
+      "active_bug": null,
+      "hypotheses_count": 0,
+      "hypotheses": [],
+      "confirmed_hypothesis": null,
+      "iteration": 0,
+      "last_analysis_at": null
+    },
+
+    "validate": {
+      "pass_rate": 0,
+      "coverage": 0,
+      "test_results": [],
+      "passed": false,
+      "failed_tests": [],
+      "last_run_at": null
+    },
+
+    "errors": []
+  }
+}
+```
+
+## Control Signal Checking (Codex Pattern)
+
+Agent checks control signals at start of every action:
+
+```javascript
+/**
+ * Check API control signals
+ * MUST be called at start of every action
+ * @returns { continue: boolean, action: 'pause_exit' | 'stop_exit' | 'continue' }
+ */
+function checkControlSignals(loopId) {
+  const state = JSON.parse(Read(`.workflow/.loop/${loopId}.json`))
+
+  switch (state.status) {
+    case 'paused':
+      // API paused the loop, Skill should exit and wait for resume
+      return { continue: false, action: 'pause_exit' }
+
+    case 'failed':
+      // API stopped the loop (user manual stop)
+      return { continue: false, action: 'stop_exit' }
+
+    case 'running':
+      // Normal continue
+      return { continue: true, action: 'continue' }
+
+    default:
+      // Abnormal status
+      return { continue: false, action: 'stop_exit' }
+  }
+}
+```
+
+## State Transitions
+
+### 1. Initialization (INIT action)
+
+```javascript
+{
+  status: 'created' -> 'running',  // Or keep 'running' if API already set
+  updated_at: timestamp,
+
+  skill_state: {
+    current_action: 'init',
+    mode: 'auto',
+    develop: {
+      tasks: [...parsed_tasks],
+      total: N,
+      completed: 0
+    }
+  }
+}
+```
+
+### 2. Development (DEVELOP action)
+
+```javascript
+{
+  updated_at: timestamp,
+  current_iteration: state.current_iteration + 1,
+
+  skill_state: {
+    current_action: 'develop',
+    last_action: 'DEVELOP',
+    completed_actions: [..., 'DEVELOP'],
+    develop: {
+      current_task: 'task-xxx',
+      completed: N+1,
+      last_progress_at: timestamp
+    }
+  }
+}
+```
+
+### 3. Debugging (DEBUG action)
+
+```javascript
+{
+  updated_at: timestamp,
+  current_iteration: state.current_iteration + 1,
+
+  skill_state: {
+    current_action: 'debug',
+    last_action: 'DEBUG',
+    debug: {
+      active_bug: '...',
+      hypotheses_count: N,
+      hypotheses: [...new_hypotheses],
+      iteration: N+1,
+      last_analysis_at: timestamp
+    }
+  }
+}
+```
+
+### 4. Validation (VALIDATE action)
+
+```javascript
+{
+  updated_at: timestamp,
+  current_iteration: state.current_iteration + 1,
+
+  skill_state: {
+    current_action: 'validate',
+    last_action: 'VALIDATE',
+    validate: {
+      test_results: [...results],
+      pass_rate: 95.5,
+      coverage: 85.0,
+      passed: true | false,
+      failed_tests: ['test1', 'test2'],
+      last_run_at: timestamp
+    }
+  }
+}
+```
+
+### 5. Completion (COMPLETE action)
+
+```javascript
+{
+  status: 'running' -> 'completed',
+  completed_at: timestamp,
+  updated_at: timestamp,
+
+  skill_state: {
+    current_action: 'complete',
+    last_action: 'COMPLETE',
+    summary: { ... }
+  }
+}
+```
+
+## File Sync
+
+### Unified Location
+
+State-to-file mapping:
+
+| State Field | Sync File | Sync Timing |
+|-------------|-----------|-------------|
+| Entire LoopState | `.workflow/.loop/{loopId}.json` | Every state change (master) |
+| `skill_state.develop` | `.workflow/.loop/{loopId}.progress/develop.md` | After each dev operation |
+| `skill_state.debug` | `.workflow/.loop/{loopId}.progress/debug.md` | After each debug operation |
+| `skill_state.validate` | `.workflow/.loop/{loopId}.progress/validate.md` | After each validation |
+| Code changes log | `.workflow/.loop/{loopId}.progress/changes.log` | Each file modification (NDJSON) |
+| Debug log | `.workflow/.loop/{loopId}.progress/debug.log` | Each debug log (NDJSON) |
+
+### File Structure
+
+```
+.workflow/.loop/
++-- loop-v2-20260122-abc123.json         # Master state file (API + Skill)
++-- loop-v2-20260122-abc123.tasks.jsonl  # Task list (API managed)
++-- loop-v2-20260122-abc123.progress/    # Skill progress files
+    +-- develop.md                       # Development progress
+    +-- debug.md                         # Debug understanding
+    +-- validate.md                      # Validation report
+    +-- changes.log                      # Code changes (NDJSON)
+    +-- debug.log                        # Debug log (NDJSON)
+    +-- summary.md                       # Completion summary
+```
+
+## State Recovery
+
+If master state file corrupted, rebuild skill_state from progress files:
+
+```javascript
+function rebuildSkillStateFromProgress(loopId) {
+  const progressDir = `.workflow/.loop/${loopId}.progress`
+
+  // Parse progress files to rebuild state
+  const skill_state = {
+    develop: parseProgressFile(`${progressDir}/develop.md`),
+    debug: parseProgressFile(`${progressDir}/debug.md`),
+    validate: parseProgressFile(`${progressDir}/validate.md`)
+  }
+
+  return skill_state
+}
+```
+
+## Codex Pattern Notes
+
+1. **Agent reads state**: Agent reads `.workflow/.loop/{loopId}.json` at action start
+2. **Agent writes state**: Agent updates state after action completion
+3. **Orchestrator tracks iterations**: Main loop tracks `current_iteration`
+4. **Single agent context**: All state updates in same agent conversation via send_input
+5. **No context serialization loss**: State transitions happen in-memory within agent

package/.codex/skills/ccw-loop/specs/action-catalog.md

@@ -0,0 +1,182 @@
+# Action Catalog (Codex Version)
+
+CCW Loop available actions and their specifications.
+
+## Available Actions
+
+| Action | Purpose | Preconditions | Effects | Output |
+|--------|---------|---------------|---------|--------|
+| INIT | Initialize session | status=running, skill_state=null | skill_state initialized | progress/*.md created |
+| MENU | Display action menu | skill_state!=null, mode=interactive | Wait for user input | WAITING_INPUT |
+| DEVELOP | Execute dev task | pending tasks > 0 | Update progress.md | develop.md updated |
+| DEBUG | Hypothesis debug | needs debugging | Update understanding.md | debug.md updated |
+| VALIDATE | Run tests | needs validation | Update validation.md | validate.md updated |
+| COMPLETE | Finish loop | all done | status=completed | summary.md created |
+
+## Action Flow (Codex Pattern)
+
+```
+spawn_agent (ccw-loop-executor)
+       |
+       v
+   +-------+
+   |  INIT |  (if skill_state is null)
+   +-------+
+       |
+       v
+   +-------+    send_input
+   |  MENU | <------------- (user selection in interactive mode)
+   +-------+
+       |
+   +---+---+---+---+
+   |   |   |   |   |
+   v   v   v   v   v
+ DEV DBG VAL CMP EXIT
+       |
+       v
+   wait() -> get result
+       |
+       v
+   [Loop continues via send_input]
+       |
+       v
+  close_agent()
+```
+
+## Action Execution Pattern
+
+### Single Agent Deep Interaction
+
+All actions executed within same agent via `send_input`:
+
+```javascript
+// Initial spawn
+const agent = spawn_agent({ message: role + initial_task })
+
+// Execute INIT
+const initResult = wait({ ids: [agent] })
+
+// Continue with DEVELOP via send_input
+send_input({ id: agent, message: 'Execute DEVELOP' })
+const devResult = wait({ ids: [agent] })
+
+// Continue with VALIDATE via send_input
+send_input({ id: agent, message: 'Execute VALIDATE' })
+const valResult = wait({ ids: [agent] })
+
+// Only close when done
+close_agent({ id: agent })
+```
+
+### Action Output Format (Standardized)
+
+Every action MUST output:
+
+```
+ACTION_RESULT:
+- action: {ACTION_NAME}
+- status: success | failed | needs_input
+- message: {user-facing message}
+- state_updates: { ... }
+
+FILES_UPDATED:
+- {file_path}: {description}
+
+NEXT_ACTION_NEEDED: {NEXT_ACTION} | WAITING_INPUT | COMPLETED | PAUSED
+```
+
+## Action Selection Logic
+
+### Auto Mode
+
+```javascript
+function selectNextAction(state) {
+  const skillState = state.skill_state
+
+  // 1. Terminal conditions
+  if (state.status === 'completed') return null
+  if (state.status === 'failed') return null
+  if (state.current_iteration >= state.max_iterations) return 'COMPLETE'
+
+  // 2. Initialization check
+  if (!skillState) return 'INIT'
+
+  // 3. Auto selection based on state
+  const hasPendingDevelop = skillState.develop.tasks.some(t => t.status === 'pending')
+
+  if (hasPendingDevelop) {
+    return 'DEVELOP'
+  }
+
+  if (skillState.last_action === 'DEVELOP') {
+    const needsDebug = skillState.develop.completed < skillState.develop.total
+    if (needsDebug) return 'DEBUG'
+  }
+
+  if (skillState.last_action === 'DEBUG' || skillState.debug.confirmed_hypothesis) {
+    return 'VALIDATE'
+  }
+
+  if (skillState.last_action === 'VALIDATE') {
+    if (!skillState.validate.passed) return 'DEVELOP'
+  }
+
+  if (skillState.validate.passed && !hasPendingDevelop) {
+    return 'COMPLETE'
+  }
+
+  return 'DEVELOP'
+}
+```
+
+### Interactive Mode
+
+Returns `MENU` action, which displays options and waits for user input.
+
+## Action Dependencies
+
+| Action | Depends On | Leads To |
+|--------|------------|----------|
+| INIT | - | MENU or DEVELOP |
+| MENU | INIT | User selection |
+| DEVELOP | INIT | DEVELOP, DEBUG, VALIDATE |
+| DEBUG | INIT | DEVELOP, VALIDATE |
+| VALIDATE | DEVELOP or DEBUG | COMPLETE, DEBUG, DEVELOP |
+| COMPLETE | - | Terminal |
+
+## Action Sequences
+
+### Happy Path (Auto Mode)
+
+```
+INIT -> DEVELOP -> DEVELOP -> DEVELOP -> VALIDATE (pass) -> COMPLETE
+```
+
+### Debug Iteration Path
+
+```
+INIT -> DEVELOP -> VALIDATE (fail) -> DEBUG -> DEBUG -> VALIDATE (pass) -> COMPLETE
+```
+
+### Interactive Path
+
+```
+INIT -> MENU -> (user: develop) -> DEVELOP -> MENU -> (user: validate) -> VALIDATE -> MENU -> (user: complete) -> COMPLETE
+```
+
+## Error Recovery
+
+| Error | Recovery |
+|-------|----------|
+| Action timeout | send_input requesting convergence |
+| Action failed | Log error, continue or retry |
+| Agent closed unexpectedly | Re-spawn with previous output |
+| State corrupted | Rebuild from progress files |
+
+## Codex Best Practices
+
+1. **Single agent for all actions**: No need to spawn new agent for each action
+2. **Deep interaction via send_input**: Continue conversation in same context
+3. **Delayed close_agent**: Only close after all actions complete
+4. **Structured output**: Always use ACTION_RESULT format for parsing
+5. **Control signal checking**: Check state.status before every action