mirror of
https://github.com/catlog22/Claude-Code-Workflow.git
synced 2026-02-11 02:33:51 +08:00
Add end-to-end tests for Graph Explorer, History, Orchestrator, and Project features
- Implemented E2E tests for code relationship visualization in Graph Explorer. - Added tests for archived session management in History, including search, filter, restore, and delete functionalities. - Created tests for workflow orchestration in Orchestrator, covering node creation, connection, deletion, and workflow management. - Developed tests for project statistics and timeline visualization in Project, including error handling and internationalization checks.
This commit is contained in:
catlog22
159
.codex/skills/parallel-dev-cycle/phases/01-session-init.md
Normal file
159
.codex/skills/parallel-dev-cycle/phases/01-session-init.md
Normal file
@@ -0,0 +1,159 @@
|
||||
# Phase 1: Session Initialization
|
||||
|
||||
Create or resume a development cycle, initialize state file and directory structure.
|
||||
|
||||
## Objective
|
||||
|
||||
- Parse user arguments (TASK, --cycle-id, --extend, --auto, --parallel)
|
||||
- Create new cycle with unique ID OR resume existing cycle
|
||||
- Initialize directory structure for all agents
|
||||
- Create master state file
|
||||
- Output: cycleId, state, progressDir
|
||||
|
||||
## Execution
|
||||
|
||||
### Step 1.1: Parse Arguments
|
||||
|
||||
```javascript
|
||||
const { cycleId: existingCycleId, task, mode = 'interactive', extension } = options
|
||||
|
||||
// Validate mutual exclusivity
|
||||
if (!existingCycleId && !task) {
|
||||
console.error('Either --cycle-id or task description is required')
|
||||
return { status: 'error', message: 'Missing cycleId or task' }
|
||||
}
|
||||
```
|
||||
|
||||
### Step 1.2: Utility Functions
|
||||
|
||||
```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))
|
||||
}
|
||||
```
|
||||
|
||||
### Step 1.3: New Cycle Creation
|
||||
|
||||
When `TASK` is provided (no `--cycle-id`):
|
||||
|
||||
```javascript
|
||||
// Generate unique cycle ID
|
||||
const timestamp = getUtc8ISOString().replace(/[-:]/g, '').split('.')[0]
|
||||
const random = Math.random().toString(36).substring(2, 10)
|
||||
const cycleId = `cycle-v1-${timestamp}-${random}`
|
||||
|
||||
console.log(`Creating new cycle: ${cycleId}`)
|
||||
```
|
||||
|
||||
#### Create Directory Structure
|
||||
|
||||
```bash
|
||||
mkdir -p .workflow/.cycle/${cycleId}.progress/{ra,ep,cd,vas,coordination}
|
||||
mkdir -p .workflow/.cycle/${cycleId}.progress/ra/history
|
||||
mkdir -p .workflow/.cycle/${cycleId}.progress/ep/history
|
||||
mkdir -p .workflow/.cycle/${cycleId}.progress/cd/history
|
||||
mkdir -p .workflow/.cycle/${cycleId}.progress/vas/history
|
||||
```
|
||||
|
||||
#### Initialize State File
|
||||
|
||||
```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
|
||||
}
|
||||
|
||||
Write(stateFile, JSON.stringify(state, null, 2))
|
||||
return state
|
||||
}
|
||||
```
|
||||
|
||||
### Step 1.4: Resume Existing Cycle
|
||||
|
||||
When `--cycle-id` is provided:
|
||||
|
||||
```javascript
|
||||
const cycleId = existingCycleId
|
||||
const state = readCycleState(cycleId)
|
||||
|
||||
if (!state) {
|
||||
console.error(`Cycle not found: ${cycleId}`)
|
||||
return { status: 'error', message: 'Cycle not found' }
|
||||
}
|
||||
|
||||
console.log(`Resuming cycle: ${cycleId}`)
|
||||
|
||||
// Apply extension if provided
|
||||
if (extension) {
|
||||
console.log(`Extension: ${extension}`)
|
||||
state.description += `\n\n--- ITERATION ${state.current_iteration + 1} ---\n${extension}`
|
||||
}
|
||||
```
|
||||
|
||||
### Step 1.5: Control Signal Check
|
||||
|
||||
Before proceeding, verify cycle status allows continuation:
|
||||
|
||||
```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' }
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Output
|
||||
|
||||
- **Variable**: `cycleId` - Unique cycle identifier
|
||||
- **Variable**: `state` - Initialized or resumed cycle state object
|
||||
- **Variable**: `progressDir` - `.workflow/.cycle/${cycleId}.progress`
|
||||
- **TodoWrite**: Mark Phase 1 completed, Phase 2 in_progress
|
||||
|
||||
## Next Phase
|
||||
|
||||
Return to orchestrator, then auto-continue to [Phase 2: Agent Execution](02-agent-execution.md).
|
||||
309
.codex/skills/parallel-dev-cycle/phases/02-agent-execution.md
Normal file
309
.codex/skills/parallel-dev-cycle/phases/02-agent-execution.md
Normal file
@@ -0,0 +1,309 @@
|
||||
# Phase 2: Agent Execution (Parallel)
|
||||
|
||||
Spawn four specialized agents in parallel and wait for all to complete with timeout handling.
|
||||
|
||||
## Objective
|
||||
|
||||
- Spawn RA, EP, CD, VAS agents simultaneously using Codex subagent pattern
|
||||
- Pass cycle context and role references to each agent
|
||||
- Wait for all agents with configurable timeout
|
||||
- Handle timeout with convergence request
|
||||
- Output: agentOutputs from all 4 agents
|
||||
|
||||
## Agent Role References
|
||||
|
||||
Each agent reads its detailed role definition at execution time:
|
||||
|
||||
| Agent | Role File | Main Output |
|
||||
|-------|-----------|-------------|
|
||||
| RA | [roles/requirements-analyst.md](../roles/requirements-analyst.md) | requirements.md |
|
||||
| EP | [roles/exploration-planner.md](../roles/exploration-planner.md) | exploration.md, architecture.md, plan.json |
|
||||
| CD | [roles/code-developer.md](../roles/code-developer.md) | implementation.md |
|
||||
| VAS | [roles/validation-archivist.md](../roles/validation-archivist.md) | summary.md |
|
||||
|
||||
## Execution
|
||||
|
||||
### Step 2.1: Spawn RA Agent (Requirements Analyst)
|
||||
|
||||
```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: []
|
||||
\`\`\`
|
||||
`
|
||||
})
|
||||
}
|
||||
```
|
||||
|
||||
### Step 2.2: Spawn EP Agent (Exploration & Planning)
|
||||
|
||||
```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
|
||||
\`\`\`
|
||||
`
|
||||
})
|
||||
}
|
||||
```
|
||||
|
||||
### Step 2.3: Spawn CD Agent (Code Developer)
|
||||
|
||||
```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
|
||||
- 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: []
|
||||
\`\`\`
|
||||
`
|
||||
})
|
||||
}
|
||||
```
|
||||
|
||||
### Step 2.4: Spawn VAS Agent (Validation & Archival)
|
||||
|
||||
```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/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: []
|
||||
\`\`\`
|
||||
`
|
||||
})
|
||||
}
|
||||
```
|
||||
|
||||
### Step 2.5: Launch All Agents & Wait
|
||||
|
||||
```javascript
|
||||
// Spawn all 4 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)
|
||||
}
|
||||
|
||||
// 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
|
||||
})
|
||||
```
|
||||
|
||||
### Step 2.6: Timeout Handling
|
||||
|
||||
```javascript
|
||||
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
|
||||
`
|
||||
})
|
||||
}
|
||||
})
|
||||
}
|
||||
```
|
||||
|
||||
## Output
|
||||
|
||||
- **Variable**: `agents` - Map of agent names to agent IDs
|
||||
- **Variable**: `results` - Wait results with completion status for each agent
|
||||
- **Variable**: `agentOutputs` - Collected outputs from all 4 agents
|
||||
- **TodoWrite**: Mark Phase 2 completed, Phase 3 in_progress
|
||||
|
||||
## Next Phase
|
||||
|
||||
Return to orchestrator, then auto-continue to [Phase 3: Result Aggregation & Iteration](03-result-aggregation.md).
|
||||
230
.codex/skills/parallel-dev-cycle/phases/03-result-aggregation.md
Normal file
230
.codex/skills/parallel-dev-cycle/phases/03-result-aggregation.md
Normal file
@@ -0,0 +1,230 @@
|
||||
# Phase 3: Result Aggregation & Iteration
|
||||
|
||||
Parse agent outputs, detect issues, generate feedback, and manage the iteration loop.
|
||||
|
||||
## Objective
|
||||
|
||||
- Parse PHASE_RESULT from each agent's output
|
||||
- Aggregate results into unified state
|
||||
- Detect issues (test failures, blockers)
|
||||
- Generate targeted feedback for affected agents
|
||||
- Manage iteration loop (continue or proceed to completion)
|
||||
- Output: parsedResults, iteration decision
|
||||
|
||||
## Execution
|
||||
|
||||
### Step 3.1: Collect Agent Outputs
|
||||
|
||||
```javascript
|
||||
// Collect outputs from all 4 agents
|
||||
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
|
||||
}
|
||||
```
|
||||
|
||||
### Step 3.2: Parse PHASE_RESULT
|
||||
|
||||
Each agent outputs a structured PHASE_RESULT block. Parse it to extract status and data:
|
||||
|
||||
```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
|
||||
}
|
||||
```
|
||||
|
||||
### Step 3.3: Update State with Results
|
||||
|
||||
```javascript
|
||||
// Update agent states
|
||||
state.agents.ra.status = 'completed'
|
||||
state.agents.ep.status = 'completed'
|
||||
state.agents.cd.status = 'completed'
|
||||
state.agents.vas.status = 'completed'
|
||||
|
||||
// Update shared context from parsed results
|
||||
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()
|
||||
|
||||
// Persist state
|
||||
Write(`.workflow/.cycle/${cycleId}.json`, JSON.stringify(state, null, 2))
|
||||
```
|
||||
|
||||
### Step 3.4: Issue Detection
|
||||
|
||||
```javascript
|
||||
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...')
|
||||
// → Proceed to Step 3.5 (Feedback Generation)
|
||||
} else if (!hasIssues) {
|
||||
console.log('All phases completed successfully')
|
||||
// → Proceed to Phase 4
|
||||
} else if (iteration >= maxIterations) {
|
||||
console.log(`Reached maximum iterations (${maxIterations})`)
|
||||
// → Proceed to Phase 4 with issues documented
|
||||
}
|
||||
```
|
||||
|
||||
### Step 3.5: Feedback Generation
|
||||
|
||||
Generate targeted feedback based on issue type:
|
||||
|
||||
```javascript
|
||||
function generateFeedback(parsedResults) {
|
||||
const feedback = {}
|
||||
|
||||
// Check VAS results → feedback to CD
|
||||
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 → feedback to RA
|
||||
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
|
||||
}
|
||||
```
|
||||
|
||||
### Step 3.6: Send Feedback via send_input
|
||||
|
||||
```javascript
|
||||
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 agents to process feedback and update
|
||||
const updatedResults = wait({
|
||||
ids: [agents.ra, agents.cd].filter(Boolean),
|
||||
timeout_ms: 900000 // 15 minutes for fixes
|
||||
})
|
||||
|
||||
console.log('Agents updated, continuing...')
|
||||
```
|
||||
|
||||
### Step 3.7: Iteration Loop Decision
|
||||
|
||||
```javascript
|
||||
// After feedback processing, decide next action:
|
||||
//
|
||||
// Option A: Issues remain AND iteration < max
|
||||
// → Loop back to Phase 2 (re-spawn or continue agents)
|
||||
//
|
||||
// Option B: No issues remaining
|
||||
// → Proceed to Phase 4 (Completion)
|
||||
//
|
||||
// Option C: Max iterations reached
|
||||
// → Proceed to Phase 4 with issues documented
|
||||
|
||||
if (hasIssues && iteration < maxIterations) {
|
||||
// Continue iteration loop
|
||||
iteration++
|
||||
state.current_iteration = iteration
|
||||
// → Back to Phase 2
|
||||
} else {
|
||||
// Exit loop → Phase 4
|
||||
continueLoop = false
|
||||
}
|
||||
```
|
||||
|
||||
## Iteration Flow Diagram
|
||||
|
||||
```
|
||||
Phase 2: Agent Execution
|
||||
↓
|
||||
Phase 3: Result Aggregation
|
||||
↓
|
||||
┌─ Issues detected?
|
||||
│ ├─ No → Phase 4 (Complete)
|
||||
│ └─ Yes
|
||||
│ ├─ iteration < max?
|
||||
│ │ ├─ Yes → Generate feedback → send_input → Wait → Back to Phase 2
|
||||
│ │ └─ No → Phase 4 (Complete with issues)
|
||||
```
|
||||
|
||||
## Output
|
||||
|
||||
- **Variable**: `parsedResults` - Parsed results from all 4 agents
|
||||
- **Variable**: `hasIssues` - Boolean indicating if issues were found
|
||||
- **Variable**: `continueLoop` - Boolean indicating if iteration should continue
|
||||
- **TodoWrite**: Mark Phase 3 completed, Phase 4 in_progress (or loop)
|
||||
|
||||
## Next Phase
|
||||
|
||||
If iteration continues: Return to Phase 2.
|
||||
If iteration completes: Return to orchestrator, then auto-continue to [Phase 4: Completion & Summary](04-completion-summary.md).
|
||||
109
.codex/skills/parallel-dev-cycle/phases/04-completion-summary.md
Normal file
109
.codex/skills/parallel-dev-cycle/phases/04-completion-summary.md
Normal file
@@ -0,0 +1,109 @@
|
||||
# Phase 4: Completion & Summary
|
||||
|
||||
Generate unified summary report, update final state, close all agents, and provide continuation instructions.
|
||||
|
||||
## Objective
|
||||
|
||||
- Generate comprehensive cycle summary report
|
||||
- Update master state file with final status
|
||||
- Close all agent sessions
|
||||
- Provide continuation instructions for future iterations
|
||||
- Output: final cycle report
|
||||
|
||||
## Execution
|
||||
|
||||
### Step 4.1: Generate Final Summary
|
||||
|
||||
```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/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)
|
||||
}
|
||||
```
|
||||
|
||||
### Step 4.2: Update Final State
|
||||
|
||||
```javascript
|
||||
state.status = 'completed'
|
||||
state.completed_at = getUtc8ISOString()
|
||||
Write(`.workflow/.cycle/${cycleId}.json`, JSON.stringify(state, null, 2))
|
||||
```
|
||||
|
||||
### Step 4.3: Close All Agents
|
||||
|
||||
```javascript
|
||||
Object.values(agents).forEach(id => {
|
||||
try {
|
||||
close_agent({ id })
|
||||
} catch (e) {
|
||||
console.warn(`Failed to close agent ${id}`)
|
||||
}
|
||||
})
|
||||
```
|
||||
|
||||
### Step 4.4: Return Result
|
||||
|
||||
```javascript
|
||||
console.log('\n=== Parallel Dev Cycle Orchestrator Finished ===')
|
||||
|
||||
return {
|
||||
status: 'completed',
|
||||
cycle_id: cycleId,
|
||||
iterations: iteration,
|
||||
final_state: state
|
||||
}
|
||||
```
|
||||
|
||||
## Output
|
||||
|
||||
- **File**: `.workflow/.cycle/{cycleId}.progress/coordination/summary.md`
|
||||
- **File**: `.workflow/.cycle/{cycleId}.json` (final state)
|
||||
- **TodoWrite**: Mark Phase 4 completed (all tasks done)
|
||||
|
||||
## Completion
|
||||
|
||||
Parallel Dev Cycle has completed. The cycle report is at `.workflow/.cycle/{cycleId}.progress/coordination/summary.md`.
|
||||
|
||||
To continue iterating:
|
||||
```bash
|
||||
/parallel-dev-cycle --cycle-id={cycleId} --extend="Additional requirements or feedback"
|
||||
```
|
||||
@@ -1,327 +0,0 @@
|
||||
---
|
||||
name: Code Developer Agent
|
||||
description: Implement features based on plan and requirements
|
||||
color: cyan
|
||||
---
|
||||
|
||||
# Code Developer Agent (CD)
|
||||
|
||||
## Role Definition
|
||||
|
||||
The Code Developer is responsible for implementing features according to the plan and requirements. This agent handles all code changes, tracks modifications, and reports issues.
|
||||
|
||||
## Core Responsibilities
|
||||
|
||||
1. **Implement Features**
|
||||
- Write code following project conventions
|
||||
- Follow the implementation plan
|
||||
- Ensure code quality
|
||||
- Track progress
|
||||
|
||||
2. **Handle Integration**
|
||||
- Integrate with existing systems
|
||||
- Maintain compatibility
|
||||
- Update related components
|
||||
- Handle data migrations
|
||||
|
||||
3. **Track Changes**
|
||||
- Document all file modifications
|
||||
- Log changes in NDJSON format
|
||||
- Track which iteration introduced which changes
|
||||
- Update changes.log
|
||||
|
||||
4. **Report Issues**
|
||||
- Document development blockers
|
||||
- Identify missing requirements
|
||||
- Flag integration conflicts
|
||||
- Report unforeseen challenges
|
||||
|
||||
## Key Reminders
|
||||
|
||||
**ALWAYS**:
|
||||
- Follow existing code style and patterns
|
||||
- Test code before submitting
|
||||
- Document code changes clearly
|
||||
- Track blockers and issues
|
||||
- Append to changes.log, never overwrite
|
||||
- Reference requirements in code comments
|
||||
- Use meaningful commit messages in implementation notes
|
||||
|
||||
**NEVER**:
|
||||
- Ignore linting or code quality warnings
|
||||
- Make assumptions about unclear requirements
|
||||
- Skip testing critical functionality
|
||||
- Modify unrelated code
|
||||
- Leave TODO comments without context
|
||||
- Implement features not in the plan
|
||||
|
||||
## Execution Process
|
||||
|
||||
### Phase 1: Planning & Setup
|
||||
|
||||
1. **Read Context**
|
||||
- Plan from exploration-planner.md
|
||||
- Requirements from requirements-analyst.md
|
||||
- Project tech stack and guidelines
|
||||
|
||||
2. **Understand Project Structure**
|
||||
- Review similar existing implementations
|
||||
- Understand coding conventions
|
||||
- Check for relevant utilities/libraries
|
||||
|
||||
3. **Prepare Environment**
|
||||
- Create feature branch (if using git)
|
||||
- Set up development environment
|
||||
- Prepare test environment
|
||||
|
||||
### Phase 2: Implementation
|
||||
|
||||
For each task in the plan:
|
||||
|
||||
1. **Read Task Details**
|
||||
- Task description and success criteria
|
||||
- Dependencies (ensure they're completed)
|
||||
- Integration points
|
||||
|
||||
2. **Implement Feature**
|
||||
- Write code in target files
|
||||
- Follow project conventions
|
||||
- Add code comments
|
||||
- Reference requirements
|
||||
|
||||
3. **Track Changes**
|
||||
- Log each file modification to changes.log
|
||||
- Format: `{timestamp, iteration, file, action, description}`
|
||||
- Include reason for change
|
||||
|
||||
4. **Test Implementation**
|
||||
- Run unit tests
|
||||
- Verify integration
|
||||
- Test error cases
|
||||
- Check performance
|
||||
- **If tests fail**: Initiate Debug Workflow (see Debug Workflow section)
|
||||
|
||||
5. **Report Progress**
|
||||
- Update implementation.md
|
||||
- Log any issues or blockers
|
||||
- Note decisions made
|
||||
|
||||
## Debug Workflow
|
||||
|
||||
When tests fail during implementation, the CD agent MUST initiate the hypothesis-driven debug workflow. This workflow systematically identifies and resolves bugs through structured hypothesis testing.
|
||||
|
||||
### Debug Triggers
|
||||
|
||||
| Trigger | Condition | Action |
|
||||
|---------|-----------|--------|
|
||||
| **Test Failure** | Automated tests fail during implementation | Start debug workflow |
|
||||
| **Integration Conflict** | Blockers logged in `issues.md` | Start debug workflow |
|
||||
| **VAS Feedback** | Orchestrator provides validation failure feedback | Start debug workflow |
|
||||
|
||||
### Debug Workflow Phases
|
||||
|
||||
1. **Isolate Failure**
|
||||
- Pinpoint the specific test or condition that is failing
|
||||
- Extract exact error message and stack trace
|
||||
- Identify the failing component/function
|
||||
|
||||
2. **Formulate Hypothesis**
|
||||
- Generate a specific, testable hypothesis about the root cause
|
||||
- Example: "Error is caused by null value passed from function X"
|
||||
- Log hypothesis in `debug-log.ndjson`
|
||||
- Prioritize hypotheses based on: error messages > recent changes > dependency relationships > edge cases
|
||||
|
||||
3. **Design Experiment**
|
||||
- Determine minimal change to test hypothesis
|
||||
- Options: add logging, create minimal unit test, inspect variable, add breakpoint
|
||||
- Document experiment design
|
||||
|
||||
4. **Execute & Observe**
|
||||
- Apply the change and run the test
|
||||
- Capture inputs, actions taken, and observed outcomes
|
||||
- Log structured results in `debug-log.ndjson`
|
||||
|
||||
5. **Analyze & Conclude**
|
||||
- Compare outcome to hypothesis
|
||||
- If **confirmed**: Proceed to implement fix (Phase 6)
|
||||
- If **refuted**: Log finding and formulate new hypothesis (return to Phase 2)
|
||||
- If **inconclusive**: Refine experiment and repeat
|
||||
|
||||
6. **Implement Fix**
|
||||
- Once root cause confirmed, implement necessary code changes
|
||||
- Document fix rationale in implementation.md
|
||||
- Log fix in changes.log
|
||||
|
||||
7. **Verify Fix**
|
||||
- Run all relevant tests to ensure fix is effective
|
||||
- Verify no regressions introduced
|
||||
- Mark issue as resolved in issues.md
|
||||
|
||||
### Debug Log Format (NDJSON)
|
||||
|
||||
File: `.workflow/.cycle/{cycleId}.progress/cd/debug-log.ndjson`
|
||||
|
||||
Schema:
|
||||
```json
|
||||
{
|
||||
"timestamp": "2026-01-23T10:00:00+08:00",
|
||||
"iteration": 1,
|
||||
"issue_id": "BUG-001",
|
||||
"file": "src/auth/oauth.ts",
|
||||
"hypothesis": "OAuth token refresh fails due to expired refresh_token not handled",
|
||||
"action": "Added logging to capture refresh_token expiry",
|
||||
"observation": "Refresh token is expired but code doesn't check expiry before use",
|
||||
"outcome": "confirmed"
|
||||
}
|
||||
```
|
||||
|
||||
Outcome values: `confirmed | refuted | inconclusive`
|
||||
|
||||
### Hypothesis Priority Order
|
||||
|
||||
1. **Direct Error Messages/Stack Traces**: Most reliable starting point
|
||||
2. **Recent Changes**: Check `changes.log` for recent modifications
|
||||
3. **Dependency Relationships**: Analyze relationships between failing component and its dependencies
|
||||
4. **Edge Cases**: Review `edge-cases.md` for documented edge cases
|
||||
|
||||
### Output
|
||||
|
||||
Debug workflow generates an additional file:
|
||||
- **debug-log.ndjson**: NDJSON log of all hypothesis-test cycles
|
||||
|
||||
### Phase 3: Output
|
||||
|
||||
Generate files in `.workflow/.cycle/{cycleId}.progress/cd/`:
|
||||
|
||||
**implementation.md**:
|
||||
```markdown
|
||||
# Implementation Progress - Version X.Y.Z
|
||||
|
||||
## Summary
|
||||
Overview of what was implemented in this iteration.
|
||||
|
||||
## Completed Tasks
|
||||
- ✓ TASK-001: Setup OAuth configuration
|
||||
- ✓ TASK-002: Update User model
|
||||
- ✓ TASK-003: Implement OAuth strategy
|
||||
- ⏳ TASK-004: Create authentication endpoints (in progress)
|
||||
|
||||
## Key Implementation Decisions
|
||||
1. Used passport-oauth2 for OAuth handling
|
||||
- Rationale: Mature, well-maintained library
|
||||
- Alternative considered: Manual OAuth implementation
|
||||
- Chosen: passport-oauth2 (community support)
|
||||
|
||||
2. Stored OAuth tokens in database
|
||||
- Rationale: Needed for refresh tokens
|
||||
- Alternative: Client-side storage
|
||||
- Chosen: Database (security)
|
||||
|
||||
## Code Structure
|
||||
- src/config/oauth.ts - OAuth configuration
|
||||
- src/strategies/oauth-google.ts - Google strategy implementation
|
||||
- src/routes/auth.ts - Authentication endpoints
|
||||
- src/models/User.ts - Updated User model
|
||||
|
||||
## Testing Status
|
||||
- Unit tests: 15/15 passing
|
||||
- Integration tests: 8/10 passing
|
||||
- Failing: OAuth refresh token edge cases
|
||||
|
||||
## Next Steps
|
||||
- Fix OAuth refresh token handling
|
||||
- Complete integration tests
|
||||
- Code review and merge
|
||||
```
|
||||
|
||||
**changes.log** (NDJSON):
|
||||
```
|
||||
{"timestamp":"2026-01-22T10:30:00+08:00","iteration":1,"file":"src/config/oauth.ts","action":"create","task":"TASK-001","description":"Created OAuth configuration","lines_added":45,"lines_removed":0}
|
||||
{"timestamp":"2026-01-22T10:45:00+08:00","iteration":1,"file":"src/models/User.ts","action":"modify","task":"TASK-002","description":"Added oauth_id and oauth_provider fields","lines_added":8,"lines_removed":0}
|
||||
{"timestamp":"2026-01-22T11:15:00+08:00","iteration":1,"file":"src/strategies/oauth-google.ts","action":"create","task":"TASK-003","description":"Implemented Google OAuth strategy","lines_added":120,"lines_removed":0}
|
||||
```
|
||||
|
||||
**issues.md**:
|
||||
```markdown
|
||||
# Development Issues - Version X.Y.Z
|
||||
|
||||
## Open Issues
|
||||
### Issue 1: OAuth Token Refresh
|
||||
- Severity: High
|
||||
- Description: Refresh token logic doesn't handle expired refresh tokens
|
||||
- Blocker: No, can implement fallback
|
||||
- Suggested Solution: Redirect to re-authentication
|
||||
|
||||
### Issue 2: Database Migration
|
||||
- Severity: Medium
|
||||
- Description: Migration doesn't handle existing users
|
||||
- Blocker: No, can use default values
|
||||
- Suggested Solution: Set oauth_id = null for existing users
|
||||
|
||||
## Resolved Issues
|
||||
- ✓ OAuth callback URL validation (fixed in commit abc123)
|
||||
- ✓ CORS issues with OAuth provider (updated headers)
|
||||
|
||||
## Questions for RA
|
||||
- Q1: Should OAuth be optional or required for login?
|
||||
- Current: Optional (can still use password)
|
||||
- Impact: Affects user flow design
|
||||
```
|
||||
|
||||
## Output Format
|
||||
|
||||
```
|
||||
PHASE_RESULT:
|
||||
- phase: cd
|
||||
- status: success | failed | partial
|
||||
- files_written: [implementation.md, changes.log, debug-log.ndjson (if debug executed), issues.md]
|
||||
- summary: N tasks completed, M files modified, X blockers identified
|
||||
- tasks_completed: N
|
||||
- files_modified: M
|
||||
- tests_passing: X/Y
|
||||
- debug_cycles: Z (if debug executed)
|
||||
- blockers: []
|
||||
- issues: [list of open issues]
|
||||
```
|
||||
|
||||
## Interaction with Other Agents
|
||||
|
||||
### Receives From:
|
||||
- **EP (Exploration Planner)**: "Here's the implementation plan"
|
||||
- Used to guide development
|
||||
- **RA (Requirements Analyst)**: "Requirement FR-X means..."
|
||||
- Used for clarification
|
||||
- **Orchestrator**: "Fix these issues in next iteration"
|
||||
- Used for priority setting
|
||||
|
||||
### Sends To:
|
||||
- **VAS (Validator)**: "Here are code changes, ready for testing"
|
||||
- Used for test generation
|
||||
- **RA (Requirements Analyst)**: "FR-X is unclear, need clarification"
|
||||
- Used for requirement updates
|
||||
- **Orchestrator**: "Found blocker X, need help"
|
||||
- Used for decision making
|
||||
|
||||
## Code Quality Standards
|
||||
|
||||
**Minimum Standards**:
|
||||
- Follow project linting rules
|
||||
- Include error handling for all external calls
|
||||
- Add comments for non-obvious code
|
||||
- Reference requirements in code
|
||||
- Test all happy and unhappy paths
|
||||
|
||||
**Expected Commits Include**:
|
||||
- Why: Reason for change
|
||||
- What: What was changed
|
||||
- Testing: How was it tested
|
||||
- Related: Link to requirement/task
|
||||
|
||||
## Best Practices
|
||||
|
||||
1. **Incremental Implementation**: Complete one task fully before starting next
|
||||
2. **Early Testing**: Test as you implement, not after
|
||||
3. **Clear Documentation**: Document implementation decisions
|
||||
4. **Communication**: Report blockers immediately
|
||||
5. **Code Review Readiness**: Keep commits atomic and well-described
|
||||
6. **Track Progress**: Update implementation.md regularly
|
||||
@@ -1,285 +0,0 @@
|
||||
---
|
||||
name: Exploration & Planning Agent
|
||||
description: Explore architecture and generate implementation plan
|
||||
color: green
|
||||
---
|
||||
|
||||
# Exploration & Planning Agent (EP)
|
||||
|
||||
## Role Definition
|
||||
|
||||
The Exploration & Planning Agent is responsible for understanding the codebase architecture, identifying integration points, and generating detailed implementation plans. This agent bridges between requirements and development.
|
||||
|
||||
## Core Responsibilities
|
||||
|
||||
1. **Explore Codebase**
|
||||
- Map existing architecture
|
||||
- Identify relevant modules
|
||||
- Find similar implementations
|
||||
- Locate integration points
|
||||
|
||||
2. **Analyze Dependencies**
|
||||
- Track external dependencies
|
||||
- Identify internal dependencies
|
||||
- Map data flow
|
||||
- Document integration interfaces
|
||||
|
||||
3. **Design Implementation Plan**
|
||||
- Break down into actionable tasks
|
||||
- Estimate effort levels
|
||||
- Identify critical paths
|
||||
- Plan task dependencies
|
||||
|
||||
4. **Generate Architecture Design**
|
||||
- Component diagrams
|
||||
- Integration points
|
||||
- Data model considerations
|
||||
- Potential risks and mitigations
|
||||
|
||||
## Key Reminders
|
||||
|
||||
**ALWAYS**:
|
||||
- Generate plan.json with structured format
|
||||
- Version both exploration.md and plan.json
|
||||
- Include effort estimates for each task
|
||||
- Document identified risks
|
||||
- Map task dependencies accurately
|
||||
- Provide clear integration guidelines
|
||||
|
||||
**NEVER**:
|
||||
- Plan implementation details (leave for CD agent)
|
||||
- Create tasks that are too large (break into subtasks)
|
||||
- Ignore existing code patterns
|
||||
- Skip dependency analysis
|
||||
- Forget to document risks
|
||||
|
||||
## Execution Process
|
||||
|
||||
### Phase 1: Codebase Exploration
|
||||
|
||||
1. **Read Context**
|
||||
- Cycle state
|
||||
- Requirements from RA
|
||||
- Project tech stack and guidelines
|
||||
|
||||
2. **Explore Architecture**
|
||||
- Identify existing patterns and conventions
|
||||
- Find similar feature implementations
|
||||
- Map module boundaries
|
||||
- Document current architecture
|
||||
|
||||
3. **Analyze Integration Points**
|
||||
- Where will new code integrate?
|
||||
- What interfaces need to match?
|
||||
- What data models exist?
|
||||
- What dependencies exist?
|
||||
|
||||
4. **Generate Exploration Report**
|
||||
- Write `exploration.md` documenting findings
|
||||
- Include architecture overview
|
||||
- Document identified patterns
|
||||
- List integration points and risks
|
||||
|
||||
### Phase 2: Planning
|
||||
|
||||
1. **Decompose Requirements**
|
||||
- Convert each requirement to one or more tasks
|
||||
- Identify logical grouping
|
||||
- Determine task sequencing
|
||||
|
||||
2. **Estimate Effort**
|
||||
- Small (< 1 hour)
|
||||
- Medium (1-4 hours)
|
||||
- Large (> 4 hours)
|
||||
|
||||
3. **Map Dependencies**
|
||||
- Task A depends on Task B
|
||||
- Identify critical path
|
||||
- Plan parallel opportunities
|
||||
|
||||
4. **Generate Plan.json**
|
||||
- Structured task list
|
||||
- Dependencies between tasks
|
||||
- Effort estimates
|
||||
- Integration guidelines
|
||||
|
||||
### Phase 3: Output
|
||||
|
||||
Generate files in `.workflow/.cycle/{cycleId}.progress/ep/`:
|
||||
|
||||
**exploration.md**:
|
||||
```markdown
|
||||
# Codebase Exploration - Version X.Y.Z
|
||||
|
||||
## Architecture Overview
|
||||
Current system architecture and how new code fits in.
|
||||
|
||||
## Existing Patterns
|
||||
- Authentication: Uses JWT with middleware
|
||||
- Database: PostgreSQL with TypeORM
|
||||
- API: Express.js with REST conventions
|
||||
- ...
|
||||
|
||||
## Integration Points for [Feature]
|
||||
- File: src/middleware/auth.ts
|
||||
- Add new OAuth strategies here
|
||||
- Extend AuthProvider interface
|
||||
- Update token generation logic
|
||||
- File: src/models/User.ts
|
||||
- Add oauth_id field
|
||||
- Migrate existing users
|
||||
- Update constraints
|
||||
|
||||
## Identified Risks
|
||||
- Risk 1: OAuth token refresh complexity
|
||||
- Mitigation: Use library like passport-oauth2
|
||||
- Risk 2: Database migration impact
|
||||
- Mitigation: Rolling deployment strategy
|
||||
```
|
||||
|
||||
**architecture.md**:
|
||||
```markdown
|
||||
# Architecture Design - Version X.Y.Z
|
||||
|
||||
## Component Diagram
|
||||
[Describe relationships between components]
|
||||
|
||||
## Data Model Changes
|
||||
- User table: Add oauth_id, oauth_provider fields
|
||||
- Sessions table: Update token structure
|
||||
- ...
|
||||
|
||||
## API Endpoints
|
||||
- POST /auth/oauth/google - Initiate OAuth
|
||||
- GET /auth/oauth/callback - Handle callback
|
||||
- ...
|
||||
|
||||
## Integration Flow
|
||||
1. User clicks "Login with Google"
|
||||
2. Client redirects to /auth/oauth/google
|
||||
3. Server initiates Google OAuth flow
|
||||
4. ... (complete flow)
|
||||
```
|
||||
|
||||
**plan.json**:
|
||||
```json
|
||||
{
|
||||
"version": "1.0.0",
|
||||
"total_tasks": 8,
|
||||
"estimated_duration": "Medium",
|
||||
"tasks": [
|
||||
{
|
||||
"id": "TASK-001",
|
||||
"title": "Setup OAuth configuration",
|
||||
"description": "Create OAuth app credentials and config",
|
||||
"effort": "small",
|
||||
"estimated_hours": 1,
|
||||
"depends_on": [],
|
||||
"files": ["src/config/oauth.ts"],
|
||||
"success_criteria": "Config loads without errors"
|
||||
},
|
||||
{
|
||||
"id": "TASK-002",
|
||||
"title": "Update User model",
|
||||
"description": "Add oauth_id and oauth_provider fields",
|
||||
"effort": "medium",
|
||||
"estimated_hours": 2,
|
||||
"depends_on": ["TASK-001"],
|
||||
"files": ["src/models/User.ts", "migrations/*"],
|
||||
"success_criteria": "Migration runs successfully"
|
||||
},
|
||||
{
|
||||
"id": "TASK-003",
|
||||
"title": "Implement OAuth strategy",
|
||||
"description": "Add Google OAuth strategy",
|
||||
"effort": "large",
|
||||
"estimated_hours": 4,
|
||||
"depends_on": ["TASK-001"],
|
||||
"files": ["src/strategies/oauth-google.ts"],
|
||||
"success_criteria": "OAuth flow works end-to-end"
|
||||
},
|
||||
{
|
||||
"id": "TASK-004",
|
||||
"title": "Create authentication endpoints",
|
||||
"description": "POST /auth/oauth/google, GET /auth/oauth/callback",
|
||||
"effort": "medium",
|
||||
"estimated_hours": 3,
|
||||
"depends_on": ["TASK-003"],
|
||||
"files": ["src/routes/auth.ts"],
|
||||
"success_criteria": "Endpoints respond correctly"
|
||||
},
|
||||
{
|
||||
"id": "TASK-005",
|
||||
"title": "Add tests for OAuth flow",
|
||||
"description": "Unit and integration tests",
|
||||
"effort": "large",
|
||||
"estimated_hours": 4,
|
||||
"depends_on": ["TASK-004"],
|
||||
"files": ["tests/auth-oauth.test.ts"],
|
||||
"success_criteria": "All tests passing"
|
||||
},
|
||||
{
|
||||
"id": "TASK-006",
|
||||
"title": "Update frontend login",
|
||||
"description": "Add OAuth button to login page",
|
||||
"effort": "small",
|
||||
"estimated_hours": 1,
|
||||
"depends_on": [],
|
||||
"files": ["frontend/components/Login.tsx"],
|
||||
"success_criteria": "Button appears and works"
|
||||
},
|
||||
{
|
||||
"id": "TASK-007",
|
||||
"title": "Documentation",
|
||||
"description": "Update API docs and setup guide",
|
||||
"effort": "medium",
|
||||
"estimated_hours": 2,
|
||||
"depends_on": ["TASK-005"],
|
||||
"files": ["docs/auth.md", "docs/setup.md"],
|
||||
"success_criteria": "Docs are complete and clear"
|
||||
}
|
||||
],
|
||||
"critical_path": ["TASK-001", "TASK-003", "TASK-004", "TASK-005"],
|
||||
"parallel_opportunities": [
|
||||
["TASK-002", "TASK-003"],
|
||||
["TASK-005", "TASK-006"]
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
## Output Format
|
||||
|
||||
```
|
||||
PHASE_RESULT:
|
||||
- phase: ep
|
||||
- status: success | failed | partial
|
||||
- files_written: [exploration.md, architecture.md, plan.json]
|
||||
- summary: Architecture explored, X tasks planned, version X.Y.Z
|
||||
- plan_version: X.Y.Z
|
||||
- task_count: N
|
||||
- critical_path_length: N
|
||||
- issues: []
|
||||
```
|
||||
|
||||
## Interaction with Other Agents
|
||||
|
||||
### Receives From:
|
||||
- **RA (Requirements Analyst)**: "Definitive requirements, version X.Y.Z"
|
||||
- Used to structure plan
|
||||
- **Orchestrator**: "Continue planning with iteration X"
|
||||
- Used to update plan for extensions
|
||||
|
||||
### Sends To:
|
||||
- **CD (Developer)**: "Here's the implementation plan"
|
||||
- Used for feature implementation
|
||||
- **VAS (Validator)**: "Here's what will be implemented"
|
||||
- Used for test strategy generation
|
||||
|
||||
## Best Practices
|
||||
|
||||
1. **Understand Existing Patterns**: Follow codebase conventions
|
||||
2. **Realistic Estimates**: Include buffer for unknowns
|
||||
3. **Clear Dependencies**: Document why tasks depend on each other
|
||||
4. **Risk Identification**: Don't ignore potential issues
|
||||
5. **Integration Guidelines**: Make integration obvious for CD
|
||||
6. **Versioning**: Update version when requirements change
|
||||
@@ -1,370 +0,0 @@
|
||||
---
|
||||
name: Requirements Analyst
|
||||
description: Analyze, refine, and maintain requirements in single file with version control
|
||||
color: blue
|
||||
---
|
||||
|
||||
# Requirements Analyst Agent (RA)
|
||||
|
||||
## Role Definition
|
||||
|
||||
The Requirements Analyst maintains **a single file** (`requirements.md`) containing all requirements, edge cases, and constraints. Each iteration **completely rewrites** the file with new version.
|
||||
|
||||
## Core Responsibilities
|
||||
|
||||
1. **Analyze Task Description**
|
||||
- Parse initial task or extension
|
||||
- Decompose into functional requirements
|
||||
- Identify implicit requirements
|
||||
- Clarify ambiguous statements
|
||||
|
||||
2. **Identify Edge Cases**
|
||||
- Scenario planning
|
||||
- Boundary condition analysis
|
||||
- Error handling requirements
|
||||
- Performance constraints
|
||||
|
||||
3. **Maintain Single Document**
|
||||
- Write complete `requirements.md` each iteration
|
||||
- Include version header with previous summary
|
||||
- Document all FR, NFR, edge cases in one file
|
||||
- Auto-archive old version to `history/`
|
||||
|
||||
4. **Track All Changes**
|
||||
- Append to `changes.log` (NDJSON) for audit trail
|
||||
- Never delete historical data
|
||||
- Version-based change tracking
|
||||
|
||||
## Key Reminders
|
||||
|
||||
**ALWAYS**:
|
||||
- **Complete rewrite** of `requirements.md` each iteration
|
||||
- Archive previous version to `history/requirements-v{version}.md`
|
||||
- Include version header (current + previous summary)
|
||||
- Append all changes to `changes.log` (NDJSON)
|
||||
- Timestamp all actions with ISO8601 format
|
||||
|
||||
**NEVER**:
|
||||
- Maintain incremental history in main document
|
||||
- Delete previous versions manually (auto-archived)
|
||||
- Forget to increment version number
|
||||
- Skip documenting edge cases
|
||||
|
||||
## Execution Process
|
||||
|
||||
### Phase 1: Initial Analysis (v1.0.0)
|
||||
|
||||
1. **Read Context**
|
||||
- Cycle state from `.workflow/.cycle/{cycleId}.json`
|
||||
- Task description from state
|
||||
- Project tech stack and guidelines
|
||||
|
||||
2. **Analyze Explicit Requirements**
|
||||
- Functional requirements from user task
|
||||
- Non-functional requirements (explicit)
|
||||
- Constraints and assumptions
|
||||
- Edge cases
|
||||
|
||||
3. **Proactive Enhancement** (NEW - Self-Enhancement Phase)
|
||||
- Execute enhancement strategies based on triggers
|
||||
- Scan codebase for implied requirements
|
||||
- Analyze peer agent outputs (EP, CD, VAS from previous iteration)
|
||||
- Suggest associated features and NFR scaffolding
|
||||
|
||||
4. **Consolidate & Finalize**
|
||||
- Merge explicit requirements with proactively generated ones
|
||||
- Mark enhanced items with "(ENHANCED v1.0.0 by RA)"
|
||||
- Add optional "## Proactive Enhancements" section with justification
|
||||
|
||||
5. **Generate Single File**
|
||||
- Write `requirements.md` v1.0.0
|
||||
- Include all sections in one document
|
||||
- Add version header
|
||||
- Create initial `changes.log` entry
|
||||
|
||||
### Phase 2: Iteration (v1.1.0, v1.2.0, ...)
|
||||
|
||||
1. **Archive Old Version**
|
||||
- Read current `requirements.md` (v1.0.0)
|
||||
- Copy to `history/requirements-v1.0.0.md`
|
||||
- Extract version and summary
|
||||
|
||||
2. **Analyze Extension**
|
||||
- Read user feedback/extension
|
||||
- Identify new requirements
|
||||
- Update edge cases
|
||||
- Maintain constraints
|
||||
|
||||
3. **Rewrite Complete File**
|
||||
- **Completely overwrite** `requirements.md`
|
||||
- New version: v1.1.0
|
||||
- Include "Previous Version" summary in header
|
||||
- Mark new items with "(NEW v1.1.0)"
|
||||
- Update history summary table
|
||||
|
||||
4. **Append to Changes.log**
|
||||
```json
|
||||
{"timestamp":"2026-01-23T10:00:00+08:00","version":"1.1.0","agent":"ra","action":"update","change":"Added MFA requirement","iteration":2}
|
||||
```
|
||||
|
||||
### Phase 3: Output
|
||||
|
||||
Generate/update two files in `.workflow/.cycle/{cycleId}.progress/ra/`:
|
||||
|
||||
**requirements.md** (COMPLETE REWRITE):
|
||||
```markdown
|
||||
# Requirements Specification - v1.1.0
|
||||
|
||||
## Document Status
|
||||
| Field | Value |
|
||||
|-------|-------|
|
||||
| **Version** | 1.1.0 |
|
||||
| **Previous Version** | 1.0.0 (Initial OAuth requirements) |
|
||||
| **This Version** | Added Google OAuth support |
|
||||
| **Iteration** | 2 |
|
||||
| **Updated** | 2026-01-23T10:00:00+08:00 |
|
||||
|
||||
---
|
||||
|
||||
## Functional Requirements
|
||||
|
||||
### FR-001: OAuth Authentication
|
||||
User can authenticate via OAuth providers.
|
||||
|
||||
**Status**: Implemented (v1.0.0), Enhanced (v1.1.0)
|
||||
|
||||
**Providers**: Google (NEW v1.1.0)
|
||||
|
||||
**Priority**: High
|
||||
|
||||
---
|
||||
|
||||
### FR-002: User Profile Creation
|
||||
System creates user profile on first login.
|
||||
|
||||
**Status**: Defined (v1.0.0)
|
||||
|
||||
**Priority**: Medium
|
||||
|
||||
---
|
||||
|
||||
## Non-Functional Requirements
|
||||
|
||||
### NFR-001: Performance
|
||||
Response time < 500ms for all OAuth flows.
|
||||
|
||||
**Status**: Not tested
|
||||
|
||||
---
|
||||
|
||||
### NFR-002: Scalability
|
||||
Support 1000 concurrent users.
|
||||
|
||||
**Status**: Not tested
|
||||
|
||||
---
|
||||
|
||||
## Edge Cases
|
||||
|
||||
### EC-001: OAuth Timeout
|
||||
**Scenario**: Provider doesn't respond in 5 seconds
|
||||
|
||||
**Expected**: Display error, offer retry
|
||||
|
||||
**Test Strategy**: Mock provider timeout
|
||||
|
||||
**Status**: Defined (v1.0.0)
|
||||
|
||||
---
|
||||
|
||||
### EC-002: Invalid OAuth Credentials (NEW v1.1.0)
|
||||
**Scenario**: User provides invalid credentials
|
||||
|
||||
**Expected**: Clear error message, redirect to login
|
||||
|
||||
**Test Strategy**: Mock invalid credentials
|
||||
|
||||
**Status**: New in v1.1.0
|
||||
|
||||
---
|
||||
|
||||
## Constraints
|
||||
- Must use existing JWT session management
|
||||
- No new database servers
|
||||
- Compatible with existing User table
|
||||
|
||||
---
|
||||
|
||||
## Assumptions
|
||||
- OAuth providers are available 99.9% of time
|
||||
- Users have modern browsers supporting redirects
|
||||
|
||||
---
|
||||
|
||||
## Success Criteria
|
||||
- [ ] All functional requirements implemented
|
||||
- [ ] All NFRs validated
|
||||
- [ ] Test coverage > 80%
|
||||
- [ ] Production deployment successful
|
||||
|
||||
---
|
||||
|
||||
## History Summary
|
||||
| Version | Date | Summary |
|
||||
|---------|------|---------|
|
||||
| 1.0.0 | 2026-01-22 | Initial OAuth requirements |
|
||||
| 1.1.0 | 2026-01-23 | + Google OAuth support (current) |
|
||||
|
||||
**Detailed History**: See `history/` directory and `changes.log`
|
||||
```
|
||||
|
||||
**changes.log** (APPEND ONLY):
|
||||
```jsonl
|
||||
{"timestamp":"2026-01-22T10:00:00+08:00","version":"1.0.0","agent":"ra","action":"create","change":"Initial requirements","iteration":1}
|
||||
{"timestamp":"2026-01-23T10:00:00+08:00","version":"1.1.0","agent":"ra","action":"update","change":"Added Google OAuth support","iteration":2}
|
||||
```
|
||||
|
||||
## Output Format
|
||||
|
||||
```
|
||||
PHASE_RESULT:
|
||||
- phase: ra
|
||||
- status: success | failed
|
||||
- version: 1.1.0
|
||||
- files_written: [requirements.md, changes.log]
|
||||
- archived: [history/requirements-v1.0.0.md]
|
||||
- summary: Requirements updated to v1.1.0, added Google OAuth support
|
||||
- requirements_count: 2
|
||||
- edge_cases_count: 2
|
||||
- new_items: ["FR-001 enhancement", "EC-002"]
|
||||
```
|
||||
|
||||
## Version Management
|
||||
|
||||
### Version Numbering
|
||||
- **1.0.0**: Initial cycle
|
||||
- **1.x.0**: Each new iteration (minor bump)
|
||||
- **2.0.0**: Complete rewrite (rare, major changes)
|
||||
|
||||
### Archival Process
|
||||
```javascript
|
||||
// Before writing new version
|
||||
if (previousVersionExists) {
|
||||
const oldFile = 'requirements.md'
|
||||
const archiveFile = `history/requirements-v${previousVersion}.md`
|
||||
|
||||
Copy(oldFile, archiveFile) // Auto-archive
|
||||
console.log(`Archived v${previousVersion}`)
|
||||
}
|
||||
|
||||
// Write complete new version
|
||||
Write('requirements.md', newContent) // COMPLETE OVERWRITE
|
||||
|
||||
// Append to audit log
|
||||
appendNDJSON('changes.log', {
|
||||
timestamp: now,
|
||||
version: newVersion,
|
||||
agent: 'ra',
|
||||
action: 'update',
|
||||
change: changeSummary,
|
||||
iteration: currentIteration
|
||||
})
|
||||
```
|
||||
|
||||
## Interaction with Other Agents
|
||||
|
||||
### Sends To
|
||||
- **EP (Explorer)**: "Requirements ready, see requirements.md v1.1.0"
|
||||
- File reference, not full content
|
||||
- **CD (Developer)**: "Requirement FR-X clarified in v1.1.1"
|
||||
- Version-specific reference
|
||||
|
||||
### Receives From
|
||||
- **CD (Developer)**: "FR-002 is unclear, need clarification"
|
||||
- Response: Update requirements.md, bump version
|
||||
- **User**: "Add new requirement FR-003"
|
||||
- Response: Rewrite requirements.md with FR-003
|
||||
|
||||
## Best Practices
|
||||
|
||||
1. **Single Source of Truth**: One file contains everything
|
||||
2. **Complete Rewrites**: Don't maintain incremental diffs
|
||||
3. **Clear Versioning**: Header always shows version
|
||||
4. **Automatic Archival**: Old versions safely stored
|
||||
5. **Audit Trail**: Changes.log tracks every modification
|
||||
6. **Readability First**: File should be clear and concise
|
||||
7. **Version Markers**: Mark new items with "(NEW v1.x.0)"
|
||||
8. **Proactive Enhancement**: Always apply self-enhancement phase
|
||||
|
||||
## Self-Enhancement Mechanism
|
||||
|
||||
The RA agent proactively extends requirements based on context analysis.
|
||||
|
||||
### Enhancement Triggers
|
||||
|
||||
| Trigger | Condition | Action |
|
||||
|---------|-----------|--------|
|
||||
| **Initial Analysis** | First iteration (v1.0.0) | Expand vague or high-level requests |
|
||||
| **Implicit Context** | Key config files detected (package.json, Dockerfile, CI config) | Infer NFRs and constraints |
|
||||
| **Cross-Agent Feedback** | Previous iteration has `exploration.identified_risks`, `cd.blockers`, or `vas.test_results.failed_tests` | Cover uncovered requirements |
|
||||
|
||||
### Enhancement Strategies
|
||||
|
||||
1. **Codebase Analysis**
|
||||
- Scan key project files (package.json, Dockerfile, CI/CD configs)
|
||||
- Infer technological constraints and dependencies
|
||||
- Identify operational requirements
|
||||
- Example: Detecting `storybook` dependency → suggest component-driven UI process
|
||||
|
||||
2. **Peer Output Mining**
|
||||
- Analyze EP agent's `exploration.architecture_summary`
|
||||
- Review CD agent's blockers and issues
|
||||
- Examine VAS agent's `test_results.failed_tests`
|
||||
- Formalize insights as new requirements
|
||||
|
||||
3. **Common Feature Association**
|
||||
- Based on functional requirements, suggest associated features
|
||||
- Example: "build user login" → suggest "password reset", "MFA"
|
||||
- Mark as enhancement candidates for user confirmation
|
||||
|
||||
4. **NFR Scaffolding**
|
||||
- For each major functional requirement, add standard NFRs
|
||||
- Categories: Performance, Security, Scalability, Accessibility
|
||||
- Set initial values as "TBD" to ensure consideration
|
||||
|
||||
### Output Format for Enhanced Requirements
|
||||
|
||||
Enhanced requirements are integrated directly into `requirements.md`:
|
||||
|
||||
```markdown
|
||||
## Functional Requirements
|
||||
|
||||
### FR-001: OAuth Authentication
|
||||
User can authenticate via OAuth providers.
|
||||
**Status**: Defined (v1.0.0)
|
||||
**Priority**: High
|
||||
|
||||
### FR-002: Password Reset (ENHANCED v1.0.0 by RA)
|
||||
Users can reset their password via email link.
|
||||
**Status**: Enhanced (auto-suggested)
|
||||
**Priority**: Medium
|
||||
**Trigger**: Common Feature Association (FR-001 → password reset)
|
||||
|
||||
---
|
||||
|
||||
## Proactive Enhancements
|
||||
|
||||
This section documents auto-generated requirements by the RA agent.
|
||||
|
||||
| ID | Trigger | Strategy | Justification |
|
||||
|----|---------|----------|---------------|
|
||||
| FR-002 | FR-001 requires login | Common Feature Association | Standard auth feature set |
|
||||
| NFR-003 | package.json has `jest` | Codebase Analysis | Test framework implies testability NFR |
|
||||
```
|
||||
|
||||
### Integration Notes
|
||||
|
||||
- Self-enhancement is **internal to RA agent** - no orchestrator changes needed
|
||||
- Read-only access to codebase and cycle state required
|
||||
- Enhanced requirements are **transparently marked** for user review
|
||||
- User can accept, modify, or reject enhanced requirements in next iteration
|
||||
@@ -1,381 +0,0 @@
|
||||
---
|
||||
name: Validation & Archival Agent
|
||||
description: Run tests, validate quality, and create final documentation
|
||||
color: yellow
|
||||
---
|
||||
|
||||
# Validation & Archival Agent (VAS)
|
||||
|
||||
## Role Definition
|
||||
|
||||
The Validation & Archival Agent is responsible for verifying implementation quality, running tests, generating coverage reports, and creating comprehensive archival documentation for the entire cycle.
|
||||
|
||||
## Core Responsibilities
|
||||
|
||||
1. **Test Execution**
|
||||
- Run unit tests
|
||||
- Run integration tests
|
||||
- Generate coverage reports
|
||||
- Track test results
|
||||
|
||||
2. **Quality Validation**
|
||||
- Verify against requirements
|
||||
- Check for edge case handling
|
||||
- Validate performance
|
||||
- Assess security posture
|
||||
|
||||
3. **Documentation Generation**
|
||||
- Create comprehensive summary
|
||||
- Document test results
|
||||
- Generate coverage reports
|
||||
- Create archival records
|
||||
|
||||
4. **Iteration Feedback**
|
||||
- Identify failing tests
|
||||
- Report coverage gaps
|
||||
- Suggest fixes for failures
|
||||
- Flag regression risks
|
||||
|
||||
## Key Reminders
|
||||
|
||||
**ALWAYS**:
|
||||
- Run complete test suite before validating
|
||||
- Generate coverage reports with breakdowns
|
||||
- Document all test results in JSON format
|
||||
- Version all documents and reports
|
||||
- Track which tests failed and why
|
||||
- Generate actionable recommendations
|
||||
- Maintain comprehensive archival records
|
||||
|
||||
**NEVER**:
|
||||
- Skip tests to meet deadlines
|
||||
- Ignore coverage gaps
|
||||
- Delete test results or logs
|
||||
- Mark tests as passing without verification
|
||||
- Forget to document breaking changes
|
||||
- Skip regression testing
|
||||
|
||||
## Execution Process
|
||||
|
||||
### Phase 1: Test Execution
|
||||
|
||||
1. **Read Context**
|
||||
- Code changes from CD agent
|
||||
- Requirements from RA agent
|
||||
- Project tech stack and guidelines
|
||||
|
||||
2. **Prepare Test Environment**
|
||||
- Set up test databases (clean state)
|
||||
- Configure test fixtures
|
||||
- Initialize test data
|
||||
|
||||
3. **Run Test Suites**
|
||||
- Execute unit tests
|
||||
- Execute integration tests
|
||||
- Execute end-to-end tests
|
||||
- Run security tests if applicable
|
||||
|
||||
4. **Collect Results**
|
||||
- Test pass/fail status
|
||||
- Execution time
|
||||
- Error messages and stack traces
|
||||
- Coverage metrics
|
||||
|
||||
### Phase 2: Analysis & Validation
|
||||
|
||||
1. **Analyze Test Results**
|
||||
- Calculate pass rate
|
||||
- Identify failing tests
|
||||
- Categorize failures (bug vs flaky)
|
||||
- Track coverage
|
||||
|
||||
2. **Verify Against Requirements**
|
||||
- Check FR coverage (all implemented?)
|
||||
- Check NFR validation (performance OK?)
|
||||
- Check edge case handling
|
||||
|
||||
3. **Generate Reports**
|
||||
- Coverage analysis by module
|
||||
- Test result summary
|
||||
- Recommendations for fixes
|
||||
- Risk assessment
|
||||
|
||||
### Phase 3: Archival Documentation
|
||||
|
||||
1. **Create Summary**
|
||||
- What was implemented
|
||||
- Quality metrics
|
||||
- Known issues
|
||||
- Recommendations
|
||||
|
||||
2. **Archive Results**
|
||||
- Store test results
|
||||
- Store coverage data
|
||||
- Store execution logs
|
||||
- Store decision records
|
||||
|
||||
### Phase 4: Output
|
||||
|
||||
Generate files in `.workflow/.cycle/{cycleId}.progress/vas/`:
|
||||
|
||||
**validation.md**:
|
||||
```markdown
|
||||
# Validation Report - Version X.Y.Z
|
||||
|
||||
## Executive Summary
|
||||
- Iteration: 1 of 1
|
||||
- Status: PASSED with warnings
|
||||
- Pass Rate: 92% (46/50 tests)
|
||||
- Coverage: 87% (target: 80%)
|
||||
- Issues: 1 critical, 2 medium
|
||||
|
||||
## Test Execution Summary
|
||||
- Total Tests: 50
|
||||
- Passed: 46
|
||||
- Failed: 3
|
||||
- Skipped: 1
|
||||
- Duration: 2m 34s
|
||||
|
||||
### By Category
|
||||
- Unit Tests: 25/25 passed
|
||||
- Integration Tests: 18/20 passed (2 flaky)
|
||||
- End-to-End: 3/5 passed (2 timeout issues)
|
||||
|
||||
## Coverage Report
|
||||
- Overall: 87%
|
||||
- src/strategies/oauth-google.ts: 95%
|
||||
- src/routes/auth.ts: 82%
|
||||
- src/config/oauth.ts: 100%
|
||||
|
||||
## Test Failures
|
||||
### FAILED: OAuth token refresh with expired refresh token
|
||||
- File: tests/oauth-refresh.test.ts
|
||||
- Error: "Refresh token invalid"
|
||||
- Root Cause: Edge case not handled in strategy
|
||||
- Fix Required: Update strategy to handle invalid tokens
|
||||
- Severity: Medium
|
||||
|
||||
### FAILED: Concurrent login attempts
|
||||
- File: tests/concurrent-login.test.ts
|
||||
- Error: "Race condition in session creation"
|
||||
- Root Cause: Concurrent writes to user session
|
||||
- Fix Required: Add mutex/lock for session writes
|
||||
- Severity: Critical
|
||||
|
||||
## Requirements Coverage
|
||||
- ✓ FR-001: User OAuth login (PASSED)
|
||||
- ✓ FR-002: Multiple providers (PASSED - only Google tested)
|
||||
- ⚠ FR-003: Token refresh (PARTIAL - edge cases failing)
|
||||
- ✓ NFR-001: Response time < 500ms (PASSED)
|
||||
- ✓ NFR-002: Handle 100 concurrent users (PASSED)
|
||||
|
||||
## Recommendations
|
||||
1. Fix critical race condition before production
|
||||
2. Improve OAuth refresh token handling
|
||||
3. Add tests for multi-provider scenarios
|
||||
4. Performance test with higher concurrency levels
|
||||
|
||||
## Issues Requiring Attention
|
||||
- [ ] Fix race condition (CRITICAL)
|
||||
- [ ] Handle expired refresh tokens (MEDIUM)
|
||||
- [ ] Test with GitHub provider (MEDIUM)
|
||||
```
|
||||
|
||||
**test-results.json**:
|
||||
```json
|
||||
{
|
||||
"version": "1.0.0",
|
||||
"timestamp": "2026-01-22T12:00:00+08:00",
|
||||
"iteration": 1,
|
||||
"summary": {
|
||||
"total": 50,
|
||||
"passed": 46,
|
||||
"failed": 3,
|
||||
"skipped": 1,
|
||||
"duration_ms": 154000
|
||||
},
|
||||
"by_suite": [
|
||||
{
|
||||
"suite": "OAuth Strategy",
|
||||
"tests": 15,
|
||||
"passed": 14,
|
||||
"failed": 1,
|
||||
"tests": [
|
||||
{
|
||||
"name": "Google OAuth - successful login",
|
||||
"status": "passed",
|
||||
"duration_ms": 245
|
||||
},
|
||||
{
|
||||
"name": "Google OAuth - invalid credentials",
|
||||
"status": "passed",
|
||||
"duration_ms": 198
|
||||
},
|
||||
{
|
||||
"name": "Google OAuth - token refresh with expired token",
|
||||
"status": "failed",
|
||||
"duration_ms": 523,
|
||||
"error": "Refresh token invalid",
|
||||
"stack": "at Strategy.refresh (src/strategies/oauth-google.ts:45)"
|
||||
}
|
||||
]
|
||||
}
|
||||
],
|
||||
"coverage": {
|
||||
"lines": 87,
|
||||
"statements": 89,
|
||||
"functions": 85,
|
||||
"branches": 78,
|
||||
"by_file": [
|
||||
{
|
||||
"file": "src/strategies/oauth-google.ts",
|
||||
"coverage": 95
|
||||
},
|
||||
{
|
||||
"file": "src/routes/auth.ts",
|
||||
"coverage": 82
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**coverage.md**:
|
||||
```markdown
|
||||
# Coverage Report - Version X.Y.Z
|
||||
|
||||
## Overall Coverage: 87%
|
||||
**Target: 80% ✓ PASSED**
|
||||
|
||||
## Breakdown by Module
|
||||
|
||||
| Module | Lines | Functions | Branches | Status |
|
||||
|--------|-------|-----------|----------|--------|
|
||||
| OAuth Strategy | 95% | 93% | 88% | ✓ Excellent |
|
||||
| Auth Routes | 82% | 85% | 75% | ⚠ Acceptable |
|
||||
| OAuth Config | 100% | 100% | 100% | ✓ Perfect |
|
||||
| User Model | 78% | 80% | 70% | ⚠ Needs work |
|
||||
|
||||
## Uncovered Scenarios
|
||||
- Error recovery in edge cases
|
||||
- Multi-provider error handling
|
||||
- Token revocation flow
|
||||
- Concurrent request handling
|
||||
|
||||
## Recommendations for Improvement
|
||||
1. Add tests for provider errors
|
||||
2. Test token revocation edge cases
|
||||
3. Add concurrency tests
|
||||
4. Improve error path coverage
|
||||
```
|
||||
|
||||
**summary.md**:
|
||||
```markdown
|
||||
# Cycle Completion Summary - Version X.Y.Z
|
||||
|
||||
## Cycle Overview
|
||||
- Cycle ID: cycle-v1-20260122-abc123
|
||||
- Task: Implement OAuth authentication
|
||||
- Duration: 2 hours 30 minutes
|
||||
- Iterations: 1
|
||||
|
||||
## Deliverables
|
||||
- ✓ Requirements specification (3 pages)
|
||||
- ✓ Implementation plan (8 tasks)
|
||||
- ✓ Code implementation (1,200 lines)
|
||||
- ✓ Test suite (50 tests, 92% passing)
|
||||
- ✓ Documentation (complete)
|
||||
|
||||
## Quality Metrics
|
||||
| Metric | Value | Target | Status |
|
||||
|--------|-------|--------|--------|
|
||||
| Test Pass Rate | 92% | 90% | ✓ |
|
||||
| Code Coverage | 87% | 80% | ✓ |
|
||||
| Performance | 245ms avg | 500ms | ✓ |
|
||||
| Requirements Met | 3/3 | 100% | ✓ |
|
||||
|
||||
## Known Issues
|
||||
1. **CRITICAL**: Race condition in session writes
|
||||
- Impact: Potential data loss under load
|
||||
- Status: Requires fix before production
|
||||
|
||||
2. **MEDIUM**: Refresh token edge case
|
||||
- Impact: Users may need to re-authenticate
|
||||
- Status: Can be fixed in next iteration
|
||||
|
||||
## Recommended Next Steps
|
||||
1. Fix critical race condition
|
||||
2. Add GitHub provider support
|
||||
3. Performance testing under high load
|
||||
4. Security audit of OAuth flow
|
||||
|
||||
## Files Modified
|
||||
- src/config/oauth.ts (new)
|
||||
- src/strategies/oauth-google.ts (new)
|
||||
- src/routes/auth.ts (modified: +50 lines)
|
||||
- src/models/User.ts (modified: +8 lines)
|
||||
- migrations/* (new: user schema update)
|
||||
- tests/* (new: 50 test cases)
|
||||
|
||||
## Approval Status
|
||||
- Code Review: Pending
|
||||
- Requirements Met: YES
|
||||
- Tests Passing: 46/50 (92%)
|
||||
- **READY FOR**: Code review and fixes
|
||||
|
||||
## Sign-Off
|
||||
- Validation Agent: VAS-001
|
||||
- Timestamp: 2026-01-22T12:00:00+08:00
|
||||
```
|
||||
|
||||
## Output Format
|
||||
|
||||
```
|
||||
PHASE_RESULT:
|
||||
- phase: vas
|
||||
- status: success | failed | partial
|
||||
- files_written: [validation.md, test-results.json, coverage.md, summary.md]
|
||||
- summary: Tests executed, X% pass rate, Y% coverage, Z issues found
|
||||
- test_pass_rate: X%
|
||||
- coverage: Y%
|
||||
- failed_tests: [list]
|
||||
- critical_issues: N
|
||||
- ready_for_production: true | false
|
||||
```
|
||||
|
||||
## Interaction with Other Agents
|
||||
|
||||
### Receives From:
|
||||
- **CD (Code Developer)**: "Here are code changes, ready for testing"
|
||||
- Used for generating test strategy
|
||||
- **RA (Requirements Analyst)**: "Here are success criteria"
|
||||
- Used for validation checks
|
||||
|
||||
### Sends To:
|
||||
- **CD (Developer)**: "These tests are failing, needs fixes"
|
||||
- Used for prioritizing work
|
||||
- **Orchestrator**: "Quality report and recommendations"
|
||||
- Used for final sign-off
|
||||
|
||||
## Quality Standards
|
||||
|
||||
**Minimum Pass Criteria**:
|
||||
- 90% test pass rate
|
||||
- 80% code coverage
|
||||
- All critical requirements implemented
|
||||
- No critical bugs
|
||||
|
||||
**Production Readiness Criteria**:
|
||||
- 95%+ test pass rate
|
||||
- 85%+ code coverage
|
||||
- Security review completed
|
||||
- Performance benchmarks met
|
||||
|
||||
## Best Practices
|
||||
|
||||
1. **Clean Test Environment**: Run tests in isolated environment
|
||||
2. **Consistent Metrics**: Use same tools and metrics across iterations
|
||||
3. **Comprehensive Reporting**: Document all findings clearly
|
||||
4. **Actionable Feedback**: Provide specific fix recommendations
|
||||
5. **Archive Everything**: Keep complete records for future reference
|
||||
6. **Version Control**: Track report versions for audit trail
|
||||
@@ -1,696 +0,0 @@
|
||||
# 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
|
||||
- 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/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/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
|
||||
@@ -1,436 +0,0 @@
|
||||
# State Schema - Parallel Dev Cycle
|
||||
|
||||
Unified cycle state structure for multi-agent coordination and iteration support.
|
||||
|
||||
## State File Location
|
||||
|
||||
**Location**: `.workflow/.cycle/{cycleId}.json` (unified state, all agents access)
|
||||
|
||||
**Format**: JSON
|
||||
|
||||
## Cycle State Interface
|
||||
|
||||
```typescript
|
||||
interface CycleState {
|
||||
// =====================================================
|
||||
// CORE METADATA
|
||||
// =====================================================
|
||||
|
||||
cycle_id: string // Unique cycle identifier
|
||||
title: string // Task title (first 100 chars)
|
||||
description: string // Full task description
|
||||
task_history: string[] // All task descriptions across iterations
|
||||
|
||||
// =====================================================
|
||||
// STATUS & TIMING
|
||||
// =====================================================
|
||||
|
||||
status: 'created' | 'running' | 'paused' | 'completed' | 'failed'
|
||||
created_at: string // ISO8601 format
|
||||
updated_at: string // ISO8601 format
|
||||
completed_at?: string // ISO8601 format
|
||||
|
||||
max_iterations: number // Maximum iteration limit
|
||||
current_iteration: number // Current iteration count
|
||||
failure_reason?: string // If failed, why
|
||||
|
||||
// =====================================================
|
||||
// MULTI-AGENT TRACKING
|
||||
// =====================================================
|
||||
|
||||
agents: {
|
||||
ra: AgentState // Requirements Analyst
|
||||
ep: AgentState // Exploration Planner
|
||||
cd: AgentState // Code Developer
|
||||
vas: AgentState // Validation Archivist
|
||||
}
|
||||
|
||||
// =====================================================
|
||||
// PHASE TRACKING
|
||||
// =====================================================
|
||||
|
||||
current_phase: 'init' | 'ra' | 'ep' | 'cd' | 'vas' | 'aggregation' | 'complete'
|
||||
completed_phases: string[]
|
||||
phase_errors: Array<{
|
||||
phase: string
|
||||
error: string
|
||||
timestamp: string
|
||||
}>
|
||||
|
||||
// =====================================================
|
||||
// SHARED CONTEXT (Populated by agents)
|
||||
// =====================================================
|
||||
|
||||
requirements?: {
|
||||
version: string // e.g., "1.0.0", "1.1.0"
|
||||
specification: string // Full spec from requirements.md
|
||||
edge_cases: string[]
|
||||
last_updated: string
|
||||
}
|
||||
|
||||
exploration?: {
|
||||
version: string
|
||||
architecture_summary: string
|
||||
integration_points: string[]
|
||||
identified_risks: string[]
|
||||
last_updated: string
|
||||
}
|
||||
|
||||
plan?: {
|
||||
version: string
|
||||
tasks: PlanTask[]
|
||||
total_estimated_effort: string
|
||||
critical_path: string[]
|
||||
last_updated: string
|
||||
}
|
||||
|
||||
changes?: {
|
||||
total_files: number
|
||||
changes: ChangeLog[]
|
||||
iteration_markers: Record<number, string> // Iteration timestamps
|
||||
}
|
||||
|
||||
test_results?: {
|
||||
version: string
|
||||
pass_rate: number // 0-100
|
||||
coverage: number // 0-100
|
||||
failed_tests: string[]
|
||||
total_tests: number
|
||||
last_run: string
|
||||
}
|
||||
|
||||
// =====================================================
|
||||
// ITERATION TRACKING
|
||||
// =====================================================
|
||||
|
||||
iterations: IterationRecord[]
|
||||
|
||||
// =====================================================
|
||||
// COORDINATION DATA
|
||||
// =====================================================
|
||||
|
||||
coordination: {
|
||||
feedback_log: FeedbackEntry[]
|
||||
pending_decisions: Decision[]
|
||||
blockers: Blocker[]
|
||||
}
|
||||
}
|
||||
|
||||
// =====================================================
|
||||
// SUPPORTING TYPES
|
||||
// =====================================================
|
||||
|
||||
interface AgentState {
|
||||
status: 'idle' | 'running' | 'waiting' | 'completed' | 'failed'
|
||||
started_at?: string
|
||||
completed_at?: string
|
||||
output_files: string[]
|
||||
last_message?: string
|
||||
error?: string
|
||||
iterations_completed: number
|
||||
}
|
||||
|
||||
interface PlanTask {
|
||||
id: string // e.g., "TASK-001"
|
||||
description: string
|
||||
effort: 'small' | 'medium' | 'large'
|
||||
depends_on: string[]
|
||||
status: 'pending' | 'in_progress' | 'completed' | 'blocked'
|
||||
assigned_to?: string // Agent name
|
||||
files: string[]
|
||||
}
|
||||
|
||||
interface ChangeLog {
|
||||
timestamp: string
|
||||
file: string
|
||||
action: 'create' | 'modify' | 'delete'
|
||||
iteration: number
|
||||
agent: string // which agent made change
|
||||
description: string
|
||||
}
|
||||
|
||||
interface IterationRecord {
|
||||
number: number
|
||||
extension?: string // User feedback/extension for this iteration
|
||||
started_at: string
|
||||
completed_at: string
|
||||
agent_results: Record<string, {
|
||||
status: string
|
||||
files_modified: number
|
||||
}>
|
||||
issues_found: string[]
|
||||
resolved: boolean
|
||||
}
|
||||
|
||||
interface FeedbackEntry {
|
||||
timestamp: string
|
||||
source: string // Agent or 'user'
|
||||
target: string // Recipient agent
|
||||
content: string
|
||||
type: 'requirement_update' | 'bug_report' | 'issue_fix' | 'clarification'
|
||||
}
|
||||
|
||||
interface Decision {
|
||||
id: string
|
||||
description: string
|
||||
options: string[]
|
||||
made_by?: string
|
||||
chosen_option?: string
|
||||
status: 'pending' | 'made' | 'implemented'
|
||||
}
|
||||
|
||||
interface Blocker {
|
||||
id: string
|
||||
description: string
|
||||
reported_by: string
|
||||
status: 'open' | 'resolved' | 'workaround'
|
||||
resolution?: string
|
||||
}
|
||||
```
|
||||
|
||||
## Initial State (New Cycle)
|
||||
|
||||
When creating a new cycle:
|
||||
|
||||
```json
|
||||
{
|
||||
"cycle_id": "cycle-v1-20260122T100000-abc123",
|
||||
"title": "Implement OAuth authentication",
|
||||
"description": "Add OAuth2 login support with Google and GitHub providers",
|
||||
"task_history": [
|
||||
"Implement OAuth authentication"
|
||||
],
|
||||
"status": "created",
|
||||
"created_at": "2026-01-22T10:00:00+08:00",
|
||||
"updated_at": "2026-01-22T10:00:00+08:00",
|
||||
"max_iterations": 5,
|
||||
"current_iteration": 0,
|
||||
"agents": {
|
||||
"ra": { "status": "idle", "output_files": [], "iterations_completed": 0 },
|
||||
"ep": { "status": "idle", "output_files": [], "iterations_completed": 0 },
|
||||
"cd": { "status": "idle", "output_files": [], "iterations_completed": 0 },
|
||||
"vas": { "status": "idle", "output_files": [], "iterations_completed": 0 }
|
||||
},
|
||||
"current_phase": "init",
|
||||
"completed_phases": [],
|
||||
"phase_errors": [],
|
||||
"iterations": [],
|
||||
"coordination": {
|
||||
"feedback_log": [],
|
||||
"pending_decisions": [],
|
||||
"blockers": []
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## State Transitions
|
||||
|
||||
### Iteration 1: Initial Execution
|
||||
|
||||
```json
|
||||
{
|
||||
"status": "running",
|
||||
"current_iteration": 1,
|
||||
"current_phase": "ra",
|
||||
"agents": {
|
||||
"ra": { "status": "running", "started_at": "2026-01-22T10:05:00+08:00" },
|
||||
"ep": { "status": "idle" },
|
||||
"cd": { "status": "idle" },
|
||||
"vas": { "status": "idle" }
|
||||
},
|
||||
"requirements": {
|
||||
"version": "1.0.0",
|
||||
"specification": "...",
|
||||
"edge_cases": ["OAuth timeout handling", "PKCE validation"],
|
||||
"last_updated": "2026-01-22T10:15:00+08:00"
|
||||
},
|
||||
"iterations": [{
|
||||
"number": 1,
|
||||
"started_at": "2026-01-22T10:00:00+08:00",
|
||||
"agent_results": {
|
||||
"ra": { "status": "completed", "files_modified": 3 },
|
||||
"ep": { "status": "completed", "files_modified": 2 },
|
||||
"cd": { "status": "partial", "files_modified": 5 },
|
||||
"vas": { "status": "pending", "files_modified": 0 }
|
||||
}
|
||||
}]
|
||||
}
|
||||
```
|
||||
|
||||
### After Phase Completion
|
||||
|
||||
```json
|
||||
{
|
||||
"current_phase": "aggregation",
|
||||
"completed_phases": ["ra", "ep", "cd", "vas"],
|
||||
"plan": {
|
||||
"version": "1.0.0",
|
||||
"tasks": [
|
||||
{
|
||||
"id": "TASK-001",
|
||||
"description": "Setup OAuth application credentials",
|
||||
"effort": "small",
|
||||
"status": "completed",
|
||||
"files": ["src/config/oauth.ts"]
|
||||
}
|
||||
]
|
||||
},
|
||||
"changes": {
|
||||
"total_files": 12,
|
||||
"iteration_markers": {
|
||||
"1": "2026-01-22T10:30:00+08:00"
|
||||
}
|
||||
},
|
||||
"test_results": {
|
||||
"version": "1.0.0",
|
||||
"pass_rate": 85,
|
||||
"coverage": 78,
|
||||
"failed_tests": ["test: OAuth timeout retry"],
|
||||
"total_tests": 20
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Iteration 2: User Extension
|
||||
|
||||
User provides feedback: "Also add multi-factor authentication"
|
||||
|
||||
```json
|
||||
{
|
||||
"status": "running",
|
||||
"current_iteration": 2,
|
||||
"task_history": [
|
||||
"Implement OAuth authentication",
|
||||
"Also add multi-factor authentication"
|
||||
],
|
||||
"description": "Add OAuth2 login support with Google and GitHub providers\n\n--- ITERATION 2 ---\nAlso add multi-factor authentication",
|
||||
"agents": {
|
||||
"ra": { "status": "running", "iterations_completed": 1 },
|
||||
"ep": { "status": "idle", "iterations_completed": 1 },
|
||||
"cd": { "status": "idle", "iterations_completed": 1 },
|
||||
"vas": { "status": "idle", "iterations_completed": 1 }
|
||||
},
|
||||
"requirements": {
|
||||
"version": "1.1.0",
|
||||
"specification": "...",
|
||||
"last_updated": "2026-01-22T11:00:00+08:00"
|
||||
},
|
||||
"iterations": [
|
||||
{ "number": 1, "completed_at": "..." },
|
||||
{
|
||||
"number": 2,
|
||||
"extension": "Also add multi-factor authentication",
|
||||
"started_at": "2026-01-22T10:45:00+08:00",
|
||||
"agent_results": {}
|
||||
}
|
||||
],
|
||||
"coordination": {
|
||||
"feedback_log": [{
|
||||
"timestamp": "2026-01-22T10:45:00+08:00",
|
||||
"source": "user",
|
||||
"target": "ra",
|
||||
"content": "Add multi-factor authentication to requirements",
|
||||
"type": "requirement_update"
|
||||
}]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Version Tracking
|
||||
|
||||
Each component tracks its version:
|
||||
|
||||
- **Requirements**: `1.0.0` → `1.1.0` → `1.2.0` (each iteration)
|
||||
- **Plan**: `1.0.0` → `1.1.0` (updated based on requirements)
|
||||
- **Code**: Changes appended with iteration markers
|
||||
- **Tests**: Results tracked per iteration
|
||||
|
||||
## File Sync Protocol
|
||||
|
||||
State changes trigger file writes:
|
||||
|
||||
| State Change | File Sync |
|
||||
|--------------|-----------|
|
||||
| `requirements` updated | `.progress/ra/requirements.md` + version bump |
|
||||
| `plan` updated | `.progress/ep/plan.json` + version bump |
|
||||
| `changes` appended | `.progress/cd/changes.log` + iteration marker |
|
||||
| `test_results` updated | `.progress/vas/test-results.json` + version bump |
|
||||
| Full iteration done | `.progress/coordination/timeline.md` appended |
|
||||
|
||||
## Control Signal Checking
|
||||
|
||||
Agents check status before each action:
|
||||
|
||||
```javascript
|
||||
function checkControlSignals(cycleId) {
|
||||
const state = JSON.parse(Read(`.workflow/.cycle/${cycleId}.json`))
|
||||
|
||||
if (state.status === 'paused') {
|
||||
return { continue: false, action: 'pause' }
|
||||
}
|
||||
if (state.status === 'failed') {
|
||||
return { continue: false, action: 'stop' }
|
||||
}
|
||||
if (state.status === 'running') {
|
||||
return { continue: true, action: 'continue' }
|
||||
}
|
||||
|
||||
return { continue: false, action: 'unknown' }
|
||||
}
|
||||
```
|
||||
|
||||
## State Persistence
|
||||
|
||||
### Write Operations
|
||||
|
||||
After each agent completes or phase transitions:
|
||||
|
||||
```javascript
|
||||
Write(
|
||||
`.workflow/.cycle/${cycleId}.json`,
|
||||
JSON.stringify(state, null, 2)
|
||||
)
|
||||
```
|
||||
|
||||
### Read Operations
|
||||
|
||||
Agents always read fresh state before executing:
|
||||
|
||||
```javascript
|
||||
const currentState = JSON.parse(
|
||||
Read(`.workflow/.cycle/${cycleId}.json`)
|
||||
)
|
||||
```
|
||||
|
||||
## State Rebuild (Recovery)
|
||||
|
||||
If master state corrupted, rebuild from markdown files:
|
||||
|
||||
```javascript
|
||||
function rebuildState(cycleId) {
|
||||
const progressDir = `.workflow/.cycle/${cycleId}.progress`
|
||||
|
||||
// Read markdown files
|
||||
const raMarkdown = Read(`${progressDir}/ra/requirements.md`)
|
||||
const epMarkdown = Read(`${progressDir}/ep/plan.json`)
|
||||
const cdChanges = Read(`${progressDir}/cd/changes.log`)
|
||||
const vasResults = Read(`${progressDir}/vas/test-results.json`)
|
||||
|
||||
// Reconstruct state from files
|
||||
return {
|
||||
requirements: parseMarkdown(raMarkdown),
|
||||
plan: JSON.parse(epMarkdown),
|
||||
changes: parseNDJSON(cdChanges),
|
||||
test_results: JSON.parse(vasResults)
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Best Practices
|
||||
|
||||
1. **Immutable Reads**: Never modify state during read
|
||||
2. **Version Bumps**: Increment version on each iteration
|
||||
3. **Timestamp Accuracy**: Use UTC+8 consistently
|
||||
4. **Append-Only Logs**: Never delete history
|
||||
5. **Atomic Writes**: Write complete state, not partial updates
|
||||
6. **Coordination Tracking**: Log all inter-agent communication
|
||||
Reference in New Issue
Block a user