claude-code-workflow 6.3.37 → 6.3.39

package/.codex/skills/parallel-dev-cycle/phases/orchestrator.md

@@ -0,0 +1,696 @@
+# Orchestrator - Multi-Agent Coordination (Codex Pattern)
+
+Orchestrate parallel dev cycle using Codex subagent pattern with continuous iteration support.
+
+## Role
+
+Coordinate four specialized agents → Manage state → Support continuous iteration → Generate unified documentation.
+
+## Codex Pattern Overview
+
+```
+Main Orchestrator Flow:
+
+┌─── spawn_agent (orchestrator role) ────────────────────────────┐
+│                                                                 │
+│  Phase 1: INIT (Check control signals)                          │
+│       ↓                                                         │
+│  wait() → Parse cycle state                                    │
+│       ↓                                                         │
+│  Phase 2: AGENT ORCHESTRATION                                  │
+│       ↓                                                         │
+│  spawn_agent(RA) | spawn_agent(EP)                             │
+│  spawn_agent(CD) | spawn_agent(VAS)                            │
+│       ↓                                                         │
+│  wait({ ids: [RA, EP, CD, VAS] }) → Collect all results       │
+│       ↓                                                         │
+│  Phase 3: ITERATION HANDLING                                   │
+│       ↓                                                         │
+│  [If extension needed]                                          │
+│  send_input to affected agents                                 │
+│  wait() for updated results                                    │
+│       ↓                                                         │
+│  Phase 4: AGGREGATION                                          │
+│       ↓                                                         │
+│  Merge all outputs → Generate unified documentation            │
+│       ↓                                                         │
+│  Update cycle state                                            │
+│       ↓                                                         │
+│  [Loop if more iterations]                                     │
+│       ↓                                                         │
+│  close_agent() when complete                                   │
+│                                                                 │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+## State Management
+
+### Read Cycle State
+
+```javascript
+const getUtc8ISOString = () => new Date(Date.now() + 8 * 60 * 60 * 1000).toISOString()
+
+function readCycleState(cycleId) {
+  const stateFile = `.workflow/.cycle/${cycleId}.json`
+  if (!fs.existsSync(stateFile)) {
+    return null
+  }
+  return JSON.parse(Read(stateFile))
+}
+```
+
+### Create New Cycle State
+
+```javascript
+function createCycleState(cycleId, taskDescription) {
+  const stateFile = `.workflow/.cycle/${cycleId}.json`
+  const now = getUtc8ISOString()
+
+  const state = {
+    // Metadata
+    cycle_id: cycleId,
+    title: taskDescription.substring(0, 100),
+    description: taskDescription,
+    max_iterations: 5,
+    status: 'running',
+    created_at: now,
+    updated_at: now,
+
+    // Agent tracking
+    agents: {
+      ra: { status: 'idle', output_files: [] },
+      ep: { status: 'idle', output_files: [] },
+      cd: { status: 'idle', output_files: [] },
+      vas: { status: 'idle', output_files: [] }
+    },
+
+    // Phase tracking
+    current_phase: 'init',
+    completed_phases: [],
+    current_iteration: 0,
+
+    // Shared context (populated by agents)
+    requirements: null,
+    exploration: null,
+    plan: null,
+    changes: [],
+    test_results: null
+  }
+
+  // Create directories
+  mkdir -p `.workflow/.cycle/${cycleId}.progress/{ra,ep,cd,vas,coordination}`
+
+  Write(stateFile, JSON.stringify(state, null, 2))
+  return state
+}
+```
+
+## Main Execution Flow (Codex Subagent)
+
+```javascript
+async function runOrchestrator(options = {}) {
+  const { cycleId: existingCycleId, task, mode = 'interactive', extension } = options
+
+  console.log('=== Parallel Dev Cycle Orchestrator Started ===')
+
+  // 1. Determine cycleId and initial state
+  let cycleId
+  let state
+
+  if (existingCycleId) {
+    // Continue existing cycle
+    cycleId = existingCycleId
+    state = readCycleState(cycleId)
+
+    if (!state) {
+      console.error(`Cycle not found: ${cycleId}`)
+      return { status: 'error', message: 'Cycle not found' }
+    }
+
+    console.log(`Resuming cycle: ${cycleId}`)
+    if (extension) {
+      console.log(`Extension: ${extension}`)
+      state.description += `\n\n--- ITERATION ${state.current_iteration + 1} ---\n${extension}`
+    }
+
+  } else if (task) {
+    // Create new cycle
+    const timestamp = getUtc8ISOString().replace(/[-:]/g, '').split('.')[0]
+    const random = Math.random().toString(36).substring(2, 10)
+    cycleId = `cycle-v1-${timestamp}-${random}`
+
+    console.log(`Creating new cycle: ${cycleId}`)
+    state = createCycleState(cycleId, task)
+
+  } else {
+    console.error('Either --cycle-id or task description is required')
+    return { status: 'error', message: 'Missing cycleId or task' }
+  }
+
+  const progressDir = `.workflow/.cycle/${cycleId}.progress`
+
+  // 2. Main orchestration loop
+  let iteration = state.current_iteration || 0
+  const maxIterations = state.max_iterations || 5
+  let continueLoop = true
+
+  while (continueLoop && iteration < maxIterations) {
+    iteration++
+    state.current_iteration = iteration
+
+    console.log(`\n========== ITERATION ${iteration} ==========`)
+
+    // 3. Spawn four agents in parallel
+    console.log('Spawning agents...')
+
+    const agents = {
+      ra: spawnRAAgent(cycleId, state, progressDir),
+      ep: spawnEPAgent(cycleId, state, progressDir),
+      cd: spawnCDAgent(cycleId, state, progressDir),
+      vas: spawnVASAgent(cycleId, state, progressDir)
+    }
+
+    // 4. Wait for all agents to complete
+    console.log('Waiting for all agents...')
+    const results = wait({
+      ids: [agents.ra, agents.ep, agents.cd, agents.vas],
+      timeout_ms: 1800000  // 30 minutes
+    })
+
+    if (results.timed_out) {
+      console.log('Some agents timed out, sending convergence request...')
+      Object.entries(agents).forEach(([name, id]) => {
+        if (!results.status[id].completed) {
+          send_input({
+            id: id,
+            message: `
+## TIMEOUT NOTIFICATION
+
+Execution timeout reached. Please:
+1. Output current progress to markdown file
+2. Save all state updates
+3. Return completion status
+`
+          })
+        }
+      })
+      continue
+    }
+
+    // 5. Collect all agent outputs
+    const agentOutputs = {
+      ra: results.status[agents.ra].completed,
+      ep: results.status[agents.ep].completed,
+      cd: results.status[agents.cd].completed,
+      vas: results.status[agents.vas].completed
+    }
+
+    // 6. Parse and aggregate results
+    const parsedResults = parseAgentOutputs(agentOutputs)
+
+    // Update state with agent results
+    state.agents.ra.status = 'completed'
+    state.agents.ep.status = 'completed'
+    state.agents.cd.status = 'completed'
+    state.agents.vas.status = 'completed'
+
+    state.requirements = parsedResults.ra.requirements
+    state.exploration = parsedResults.ep.exploration
+    state.plan = parsedResults.ep.plan
+    state.changes = parsedResults.cd.changes
+    state.test_results = parsedResults.vas.test_results
+
+    state.completed_phases.push(...['ra', 'ep', 'cd', 'vas'])
+    state.updated_at = getUtc8ISOString()
+
+    // Save state
+    Write(`.workflow/.cycle/${cycleId}.json`, JSON.stringify(state, null, 2))
+
+    // 7. Check for issues and determine next iteration
+    const hasIssues = parsedResults.vas.test_results?.passed === false ||
+                     parsedResults.cd.issues?.length > 0
+
+    if (hasIssues && iteration < maxIterations) {
+      console.log('Issues detected, preparing for next iteration...')
+
+      // Generate feedback for agents
+      const feedback = generateFeedback(parsedResults)
+
+      // Send feedback to relevant agents
+      if (feedback.ra) {
+        send_input({
+          id: agents.ra,
+          message: feedback.ra
+        })
+      }
+
+      if (feedback.cd) {
+        send_input({
+          id: agents.cd,
+          message: feedback.cd
+        })
+      }
+
+      // Wait for updates
+      const updatedResults = wait({
+        ids: [agents.ra, agents.cd].filter(Boolean),
+        timeout_ms: 900000
+      })
+
+      console.log('Agents updated, continuing...')
+
+    } else if (!hasIssues) {
+      console.log('All phases completed successfully')
+      continueLoop = false
+
+    } else if (iteration >= maxIterations) {
+      console.log(`Reached maximum iterations (${maxIterations})`)
+      continueLoop = false
+    }
+  }
+
+  // 8. Generate unified summary
+  console.log('Generating final summary...')
+  generateFinalSummary(cycleId, state)
+
+  // 9. Update final state
+  state.status = 'completed'
+  state.completed_at = getUtc8ISOString()
+  Write(`.workflow/.cycle/${cycleId}.json`, JSON.stringify(state, null, 2))
+
+  // 10. Cleanup
+  Object.values(agents).forEach(id => {
+    try {
+      close_agent({ id })
+    } catch (e) {
+      console.warn(`Failed to close agent ${id}`)
+    }
+  })
+
+  console.log('\n=== Parallel Dev Cycle Orchestrator Finished ===')
+
+  return {
+    status: 'completed',
+    cycle_id: cycleId,
+    iterations: iteration,
+    final_state: state
+  }
+}
+```
+
+## Agent Spawning Functions
+
+### Spawn RA Agent
+
+```javascript
+function spawnRAAgent(cycleId, state, progressDir) {
+  return spawn_agent({
+    message: `
+## TASK ASSIGNMENT
+
+### MANDATORY FIRST STEPS (Agent Execute)
+1. **Read role definition**: ~/.codex/agents/requirements-analyst.md
+2. Read: .workflow/project-tech.json (if exists)
+3. Read: .workflow/project-guidelines.json (if exists)
+4. Read: .workflow/.cycle/${cycleId}.progress/coordination/feedback.md (if exists)
+
+---
+
+## CYCLE CONTEXT
+
+- **Cycle ID**: ${cycleId}
+- **Progress Dir**: ${progressDir}/ra/
+- **Current Iteration**: ${state.current_iteration}
+- **Task Description**: ${state.description}
+
+## CURRENT REQUIREMENTS STATE
+
+${state.requirements ? JSON.stringify(state.requirements, null, 2) : 'No previous requirements'}
+
+## YOUR ROLE
+
+Requirements Analyst - Analyze and refine requirements throughout the cycle.
+
+## RESPONSIBILITIES
+
+1. Analyze initial task description
+2. Generate comprehensive requirements specification
+3. Identify edge cases and implicit requirements
+4. Track requirement changes across iterations
+5. Maintain requirements.md and changes.log
+
+## DELIVERABLES
+
+Write files to ${progressDir}/ra/:
+- requirements.md: Full requirements specification
+- edge-cases.md: Edge case analysis
+- changes.log: NDJSON format change tracking
+
+## OUTPUT FORMAT
+
+\`\`\`
+PHASE_RESULT:
+- phase: ra
+- status: success | failed
+- files_written: [list]
+- summary: one-line summary
+- issues: []
+\`\`\`
+`
+  })
+}
+```
+
+### Spawn EP Agent
+
+```javascript
+function spawnEPAgent(cycleId, state, progressDir) {
+  return spawn_agent({
+    message: `
+## TASK ASSIGNMENT
+
+### MANDATORY FIRST STEPS (Agent Execute)
+1. **Read role definition**: ~/.codex/agents/exploration-planner.md
+2. Read: .workflow/project-tech.json
+3. Read: .workflow/project-guidelines.json
+4. Read: ${progressDir}/ra/requirements.md
+
+---
+
+## CYCLE CONTEXT
+
+- **Cycle ID**: ${cycleId}
+- **Progress Dir**: ${progressDir}/ep/
+- **Requirements**: See requirements.md
+- **Current Plan**: ${state.plan ? 'Existing' : 'None - first iteration'}
+
+## YOUR ROLE
+
+Exploration & Planning Agent - Explore architecture and generate implementation plan.
+
+## RESPONSIBILITIES
+
+1. Explore codebase architecture
+2. Map integration points
+3. Design implementation approach
+4. Generate plan.json with task breakdown
+5. Update or iterate on existing plan
+
+## DELIVERABLES
+
+Write files to ${progressDir}/ep/:
+- exploration.md: Codebase exploration findings
+- architecture.md: Architecture design
+- plan.json: Implementation plan (structured)
+
+## OUTPUT FORMAT
+
+\`\`\`
+PHASE_RESULT:
+- phase: ep
+- status: success | failed
+- files_written: [list]
+- summary: one-line summary
+- plan_version: X.Y.Z
+\`\`\`
+`
+  })
+}
+```
+
+### Spawn CD Agent
+
+```javascript
+function spawnCDAgent(cycleId, state, progressDir) {
+  return spawn_agent({
+    message: `
+## TASK ASSIGNMENT
+
+### MANDATORY FIRST STEPS (Agent Execute)
+1. **Read role definition**: ~/.codex/agents/code-developer.md
+2. Read: ${progressDir}/ep/plan.json
+3. Read: ${progressDir}/ra/requirements.md
+
+---
+
+## CYCLE CONTEXT
+
+- **Cycle ID**: ${cycleId}
+- **Progress Dir**: ${progressDir}/cd/
+- **Plan Version**: ${state.plan?.version || 'N/A'}
+- **Previous Changes**: ${state.changes?.length || 0} files
+
+## YOUR ROLE
+
+Code Developer - Implement features based on plan and requirements.
+
+## RESPONSIBILITIES
+
+1. Implement features from plan
+2. Track code changes
+3. Handle integration issues
+4. Maintain code quality
+5. Report implementation progress and issues
+
+## DELIVERABLES
+
+Write files to ${progressDir}/cd/:
+- implementation.md: Implementation progress and decisions
+- code-changes.log: NDJSON format, each line: {file, action, timestamp}
+- issues.md: Development issues and blockers
+
+## OUTPUT FORMAT
+
+\`\`\`
+PHASE_RESULT:
+- phase: cd
+- status: success | failed | partial
+- files_changed: [count]
+- summary: one-line summary
+- blockers: []
+\`\`\`
+`
+  })
+}
+```
+
+### Spawn VAS Agent
+
+```javascript
+function spawnVASAgent(cycleId, state, progressDir) {
+  return spawn_agent({
+    message: `
+## TASK ASSIGNMENT
+
+### MANDATORY FIRST STEPS (Agent Execute)
+1. **Read role definition**: ~/.codex/agents/validation-archivist.md
+2. Read: ${progressDir}/cd/code-changes.log
+
+---
+
+## CYCLE CONTEXT
+
+- **Cycle ID**: ${cycleId}
+- **Progress Dir**: ${progressDir}/vas/
+- **Changes Count**: ${state.changes?.length || 0}
+- **Iteration**: ${state.current_iteration}
+
+## YOUR ROLE
+
+Validation & Archival Specialist - Validate quality and create documentation.
+
+## RESPONSIBILITIES
+
+1. Run tests on implemented features
+2. Generate coverage reports
+3. Create archival documentation
+4. Summarize cycle results
+5. Generate version history
+
+## DELIVERABLES
+
+Write files to ${progressDir}/vas/:
+- validation.md: Test validation results
+- test-results.json: Detailed test results
+- coverage.md: Coverage report
+- summary.md: Cycle summary and recommendations
+
+## OUTPUT FORMAT
+
+\`\`\`
+PHASE_RESULT:
+- phase: vas
+- status: success | failed
+- test_pass_rate: X%
+- coverage: X%
+- issues: []
+\`\`\`
+`
+  })
+}
+```
+
+## Result Parsing
+
+```javascript
+function parseAgentOutputs(agentOutputs) {
+  const results = {
+    ra: parseOutput(agentOutputs.ra, 'ra'),
+    ep: parseOutput(agentOutputs.ep, 'ep'),
+    cd: parseOutput(agentOutputs.cd, 'cd'),
+    vas: parseOutput(agentOutputs.vas, 'vas')
+  }
+  return results
+}
+
+function parseOutput(output, agent) {
+  const result = {
+    agent: agent,
+    status: 'unknown',
+    data: {}
+  }
+
+  // Parse PHASE_RESULT block
+  const match = output.match(/PHASE_RESULT:\s*([\s\S]*?)(?:\n\n|$)/)
+  if (match) {
+    const lines = match[1].split('\n')
+    for (const line of lines) {
+      const m = line.match(/^-\s*(\w+):\s*(.+)$/)
+      if (m) {
+        result[m[1]] = m[2].trim()
+      }
+    }
+  }
+
+  return result
+}
+```
+
+## Feedback Generation
+
+```javascript
+function generateFeedback(parsedResults) {
+  const feedback = {}
+
+  // Check VAS results
+  if (parsedResults.vas.test_pass_rate < 100) {
+    feedback.cd = `
+## FEEDBACK FROM VALIDATION
+
+Test pass rate: ${parsedResults.vas.test_pass_rate}%
+
+## ISSUES TO FIX
+
+${parsedResults.vas.data.issues || 'See test-results.json for details'}
+
+## NEXT STEP
+
+Fix failing tests and update implementation.md with resolution.
+`
+  }
+
+  // Check CD blockers
+  if (parsedResults.cd.blockers?.length > 0) {
+    feedback.ra = `
+## FEEDBACK FROM DEVELOPMENT
+
+Blockers encountered:
+${parsedResults.cd.blockers.map(b => `- ${b}`).join('\n')}
+
+## NEXT STEP
+
+Clarify requirements or identify alternative approaches.
+Update requirements.md if needed.
+`
+  }
+
+  return feedback
+}
+```
+
+## Summary Generation
+
+```javascript
+function generateFinalSummary(cycleId, state) {
+  const summaryFile = `.workflow/.cycle/${cycleId}.progress/coordination/summary.md`
+
+  const summary = `# Cycle Summary - ${cycleId}
+
+## Metadata
+- Cycle ID: ${cycleId}
+- Started: ${state.created_at}
+- Completed: ${state.completed_at}
+- Iterations: ${state.current_iteration}
+- Status: ${state.status}
+
+## Phase Results
+- Requirements Analysis: ✓ Completed
+- Exploration & Planning: ✓ Completed
+- Code Development: ✓ Completed
+- Validation & Archival: ✓ Completed
+
+## Key Deliverables
+- Requirements: ${state.requirements ? '✓' : '✗'}
+- Architecture Plan: ${state.plan ? '✓' : '✗'}
+- Code Changes: ${state.changes?.length || 0} files
+- Test Results: ${state.test_results?.pass_rate || '0'}% passing
+
+## Generated Files
+- .workflow/.cycle/${cycleId}.progress/ra/requirements.md
+- .workflow/.cycle/${cycleId}.progress/ep/plan.json
+- .workflow/.cycle/${cycleId}.progress/cd/code-changes.log
+- .workflow/.cycle/${cycleId}.progress/vas/summary.md
+
+## Continuation Instructions
+
+To extend this cycle:
+
+\`\`\`bash
+/parallel-dev-cycle --cycle-id=${cycleId} --extend="New requirement or feedback"
+\`\`\`
+
+This will spawn agents for iteration ${state.current_iteration + 1}.
+`
+
+  Write(summaryFile, summary)
+}
+```
+
+## Control Signal Checking
+
+```javascript
+function checkControlSignals(cycleId) {
+  const state = readCycleState(cycleId)
+
+  switch (state?.status) {
+    case 'paused':
+      return { continue: false, action: 'pause_exit' }
+    case 'failed':
+      return { continue: false, action: 'stop_exit' }
+    case 'running':
+      return { continue: true, action: 'continue' }
+    default:
+      return { continue: false, action: 'stop_exit' }
+  }
+}
+```
+
+## Error Recovery Strategies
+
+| Error Type | Recovery |
+|------------|----------|
+| Agent timeout | send_input requesting convergence |
+| State corrupted | Rebuild from progress markdown files |
+| Agent failed | Re-spawn agent with previous context |
+| Conflicting results | Orchestrator sends reconciliation request |
+| Missing files | RA/EP agents identify and request clarification |
+
+## Codex Best Practices Applied
+
+1. **Single Orchestrator**: One main agent manages all phases
+2. **Parallel Workers**: Four specialized agents execute simultaneously
+3. **Batch wait()**: Wait for all agents with `wait({ ids: [...] })`
+4. **Deep Interaction**: Use send_input for iteration and refinement
+5. **Delayed close_agent**: Only after all phases and iterations complete
+6. **Role Path Passing**: Each agent reads its own role definition
+7. **Persistent Context**: Cycle state shared across all agents