Claude-Code-Workflow/.codex/skills/parallel-dev-cycle/README.md

Parallel Dev Cycle Skill

Multi-agent parallel development cycle using Codex subagent pattern with continuous iteration support.

Overview

This skill implements a single-file-per-agent development workflow:

• RA: requirements.md (all requirements + edge cases + history)
• EP: exploration.md, architecture.md, plan.json (codebase exploration + architecture + structured tasks)
• CD: implementation.md (progress + files + decisions + testing)
• VAS: summary.md (validation + test results + recommendations)

Each file is completely rewritten on each iteration, with old versions auto-archived to history/.

Installation

Files are in .codex/skills/parallel-dev-cycle/:

.codex/skills/parallel-dev-cycle/
├── SKILL.md                        # Main skill definition
├── README.md                       # This file
├── phases/
│   ├── orchestrator.md             # Multi-agent coordination
│   ├── state-schema.md             # Unified state structure
│   └── agents/
│       ├── requirements-analyst.md # RA role
│       ├── exploration-planner.md  # EP role
│       ├── code-developer.md       # CD role
│       └── validation-archivist.md # VAS role
└── specs/
    ├── coordination-protocol.md    # Agent communication
    └── versioning-strategy.md      # Version management

Quick Start

Launch New Cycle

/parallel-dev-cycle TASK="Implement OAuth authentication"

Creates:

.workflow/.cycle/cycle-v1-20260122-abc123.progress/
├── ra/
│   ├── requirements.md (v1.0.0)
│   └── changes.log (NDJSON)
├── ep/
│   ├── exploration.md (v1.0.0)
│   ├── architecture.md (v1.0.0)
│   ├── plan.json (v1.0.0)
│   └── changes.log (NDJSON)
├── cd/
│   ├── implementation.md (v1.0.0)
│   └── changes.log (NDJSON)
└── vas/
    ├── summary.md (v1.0.0)
    └── changes.log (NDJSON)

Continue With Extension (XX-1 Pattern)

User adds requirement: "Also support Google OAuth"

/parallel-dev-cycle --cycle-id=cycle-v1-20260122-abc123 --extend="Add Google OAuth"

Automatically:

1. Archives old requirements.md (v1.0.0) → history/requirements-v1.0.0.md
2. Rewrites requirements.md (v1.1.0) - complete file replacement
3. Appends change to changes.log (NDJSON audit trail)

Next Iteration (XX-2)

/parallel-dev-cycle --cycle-id=cycle-v1-20260122-abc123 --extend="Add GitHub provider"

All files update to v1.2.0, previous versions archived.

Execution Flow

Phase 1: Parallel Agent Execution

Time  RA              EP              CD              VAS
────  ──              ──              ──              ──
0ms   [spawned]       [spawned]       [spawned]       [spawned]
      ↓               ↓               ↓               ↓
      Analyzing       Exploring       Reading plan    Waiting
      task            codebase        from EP...
                                      ↓
5min  Outputs req.    Outputs plan    Requirements
      v1.0.0 ✓        v1.0.0 ✓        unclear - BLOCKED

10min Clarifies req   Updates plan    ✓ Ready
      v1.0.1 ✓        v1.0.1 ✓        Implementing...
                                      ↓
15min ✓ Complete      ✓ Complete      ✓ Code done      [waiting for CD]

20min                                                 [starts tests]
                                                      ↓
25min                                                 Outputs summary
                                                      v1.0.0 ✓

Phase 2: Version Transition

When iteration completes, next extends to v1.1.0:

Current State (v1.0.0)
├── requirements.md (v1.0.0)
├── plan.json (v1.0.0)
├── implementation.md (v1.0.0)
└── summary.md (v1.0.0)

User: "Add GitHub provider"
         ↓
Archive Old                    Write New
├── history/requirements-v1.0.0.md  → requirements.md (v1.1.0) - REWRITTEN
├── history/plan-v1.0.0.json        → plan.json (v1.1.0) - REWRITTEN
├── history/impl-v1.0.0.md          → implementation.md (v1.1.0) - REWRITTEN
└── history/summary-v1.0.0.md       → summary.md (v1.1.0) - REWRITTEN
                                       ↓
                                 Append to changes.log (NDJSON)

Session Files

.workflow/.cycle/{cycleId}.progress/

ra/ - Requirements Analyst
├── requirements.md           # v1.2.0 (current, complete rewrite)
├── changes.log              # NDJSON audit trail
└── history/
    ├── requirements-v1.0.0.md
    └── requirements-v1.1.0.md

ep/ - Exploration & Planning
├── exploration.md           # v1.2.0 (codebase exploration)
├── architecture.md          # v1.2.0 (architecture design)
├── plan.json                # v1.2.0 (structured task list, current)
├── changes.log              # NDJSON audit trail
└── history/
    ├── plan-v1.0.0.json
    └── plan-v1.1.0.json

cd/ - Code Developer
├── implementation.md        # v1.2.0 (current)
├── changes.log              # NDJSON audit trail
└── history/
    ├── implementation-v1.0.0.md
    └── implementation-v1.1.0.md

vas/ - Validation & Archival
├── summary.md               # v1.2.0 (current)
├── changes.log              # NDJSON audit trail
└── history/
    ├── summary-v1.0.0.md
    └── summary-v1.1.0.md

Versioning Strategy

Semantic Versioning

• 1.0.0: Initial cycle
• 1.1.0: User extends with new requirement
• 1.2.0: Another iteration with more requirements

What Gets Versioned

✅ Main Document File

• Completely rewritten each iteration
• Auto-archived to history/
• No inline version history (stays clean)

✅ Changes.log (NDJSON)

• Append-only (never deleted)
• Complete audit trail of all changes
• Used to trace requirement origins

✅ Historical Snapshots

• Auto-created in history/ directory
• Keep last N versions (default: 5)
• For reference when needed

Key Principle

主文档简洁清晰 ← Agent 只关注当前版本

完整历史记录 ← Changes.log 保留每个变更

版本快照归档 ← History/ 备份旧版本

File Maintenance

Each Agent

Agent	File	Contains	Size
RA	requirements.md	All FR, NFR, edge cases, history summary	~2-5KB
EP	exploration.md + architecture.md + plan.json	Codebase exploration, architecture design, structured task list	~5-10KB total
CD	implementation.md	Completed tasks, files changed, decisions, tests	~4-10KB
VAS	summary.md	Test results, coverage, issues, recommendations	~5-12KB

Changes.log (Shared)

NDJSON format - one line per change:

{"timestamp":"2026-01-22T10:00:00+08:00","version":"1.0.0","agent":"ra","action":"create","change":"Initial requirements","iteration":1}
{"timestamp":"2026-01-22T11:00:00+08:00","version":"1.1.0","agent":"ra","action":"update","change":"Added Google OAuth","iteration":2}
{"timestamp":"2026-01-22T12:00:00+08:00","version":"1.2.0","agent":"ra","action":"update","change":"Added GitHub, MFA","iteration":3}

Accessing History

Current Version

# View latest requirements
cat .workflow/.cycle/cycle-xxx.progress/ra/requirements.md

# Quick check - version is in header
head -5 requirements.md  # "# Requirements Specification - v1.2.0"

Version History

# View previous version
cat .workflow/.cycle/cycle-xxx.progress/ra/history/requirements-v1.1.0.md

# Audit trail - all changes
cat .workflow/.cycle/cycle-xxx.progress/ra/changes.log | jq .

# Changes in specific iteration
cat changes.log | jq 'select(.iteration==2)'

# Trace requirement history
cat changes.log | jq 'select(.change | contains("OAuth"))'

Codex Pattern Implementation

Multi-Agent Parallel

// Create 4 agents in parallel
const agents = {
  ra: spawn_agent({ message: raRoleAndTask }),
  ep: spawn_agent({ message: epRoleAndTask }),
  cd: spawn_agent({ message: cdRoleAndTask }),
  vas: spawn_agent({ message: vasRoleAndTask })
}

// Wait for all 4 in parallel
const results = wait({ ids: [agents.ra, agents.ep, agents.cd, agents.vas] })

Role Path Passing

Each agent reads its own role definition:

spawn_agent({
  message: `
## MANDATORY FIRST STEPS
1. Read role: ~/.codex/agents/requirements-analyst.md
2. Read: .workflow/project-tech.json
3. Read: .workflow/project-guidelines.json

## TASK
${taskDescription}
`
})

Deep Interaction

Use send_input for iteration refinement:

// First output
const initial = wait({ ids: [agent] })

// User feedback
send_input({
  id: agent,
  message: `
## Feedback

${feedback}

## Next Steps
Update ${filename} based on feedback. Increment version.
Output PHASE_RESULT when complete.
`
})

// Updated output
const revised = wait({ ids: [agent] })

// Only close when done
close_agent({ id: agent })

Error Handling

Situation	Recovery
Agent timeout	send_input requesting convergence or retry
State corrupted	Rebuild from changes.log NDJSON
Version mismatch	Agent checks version in state before reading
Blocked dependency	Orchestrator sends updated file path

Best Practices

1. Let agents rewrite - Don't maintain incremental history in main doc
2. Trust changes.log - NDJSON is the source of truth for history
3. Archive on version bump - Automatic, no manual versioning needed
4. Keep files focused - Each file should be readable in 5 minutes
5. Version header always present - Makes version obvious at a glance

Integration

This skill works standalone or integrated with:

• Dashboard Loop Monitor (API triggers)
• CCW workflow system
• Custom orchestration

API Trigger

POST /api/cycles/start
{
  "task": "Implement OAuth",
  "mode": "auto"
}
→ Returns cycle_id

GET /api/cycles/{cycle_id}/status
→ Returns agents status and progress

Architecture Diagram

User Task
    ↓
Orchestrator (main coordinator)
    ├─→ spawn_agent(RA)
    ├─→ spawn_agent(EP)
    ├─→ spawn_agent(CD)
    └─→ spawn_agent(VAS)
           ↓
        wait({ ids: [all 4] })
           ↓
      All write to:
      - requirements.md (v1.x.0)
      - exploration.md, architecture.md, plan.json (v1.x.0)
      - implementation.md (v1.x.0)
      - summary.md (v1.x.0)
      - changes.log (NDJSON append)
           ↓
      [Automatic archival]
      - history/requirements-v1.{x-1}.0.md
      - history/plan-v1.{x-1}.0.json
      - etc...
           ↓
      Orchestrator: Next iteration?
      - Yes: send_input with feedback
      - No: close_agent, report summary

License

MIT