mirror of
https://github.com/catlog22/Claude-Code-Workflow.git
synced 2026-02-10 02:24:35 +08:00
437 lines
12 KiB
Markdown
437 lines
12 KiB
Markdown
# 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
|