Parallel Dev Cycle - Multi-Agent Development Workflow

Multi-agent parallel development cycle using Codex subagent pattern with four specialized workers:

•Requirements Analysis & Extension (RA) - Requirement analysis and self-enhancement
•Exploration & Planning (EP) - Exploration and planning
•Code Development (CD) - Code development with debug strategy support
•Validation & Archival Summary (VAS) - Validation and archival summary

Each agent maintains one main document (e.g., requirements.md, plan.json, implementation.md) that is completely rewritten per iteration, plus auxiliary logs (changes.log, debug-log.ndjson) that are append-only. Supports versioning, automatic archival, and complete history tracking.

Arguments

Arg	Required	Description
TASK	One of TASK or --cycle-id	Task description (for new cycle, mutually exclusive with --cycle-id)
--cycle-id	One of TASK or --cycle-id	Existing cycle ID to continue (from API or previous session)
--extend	No	Extension description (only valid with --cycle-id)
--auto	No	Auto-cycle mode (run all phases sequentially)
--parallel	No	Number of parallel agents (default: 4, max: 4)

Architecture Overview

code

┌─────────────────────────────────────────────────────────────┐
│                    User Input (Task)                        │
└────────────────────────────┬────────────────────────────────┘
                             │
                             v
                  ┌──────────────────────┐
                  │  Orchestrator Agent  │  (Coordinator)
                  │  (spawned once)      │
                  └──────────────────────┘
                             │
        ┌────────────────────┼────────────────────┐
        │                    │                    │
        v                    v                    v
    ┌────────┐         ┌────────┐         ┌────────┐
    │  RA    │         │  EP    │         │  CD    │
    │Agent   │         │Agent   │         │Agent   │
    └────────┘         └────────┘         └────────┘
        │                    │                    │
        └────────────────────┼────────────────────┘
                             │
                             v
                         ┌────────┐
                         │  VAS   │
                         │ Agent  │
                         └────────┘
                             │
                             v
                  ┌──────────────────────┐
                  │    Summary Report    │
                  │  & Markdown Docs     │
                  └──────────────────────┘

Key Design Principles

•Main Document + Auxiliary Logs: Each agent maintains one main document (rewritten per iteration) and auxiliary logs (append-only)
•Version-Based Overwrite: Main documents completely rewritten per version; logs append-only
•Automatic Archival: Old main document versions automatically archived to history/ directory
•Complete Audit Trail: Changes.log (NDJSON) preserves all change history
•Parallel Coordination: Four agents launched simultaneously; coordination via shared state and orchestrator
•File References: Use short file paths instead of content passing
•Self-Enhancement: RA agent proactively extends requirements based on context

Session Structure

code

.workflow/.cycle/
+-- {cycleId}.json                                 # Master state file
+-- {cycleId}.progress/
    +-- ra/
    |   +-- requirements.md                        # Current version (complete rewrite)
    |   +-- changes.log                            # NDJSON complete history (append-only)
    |   └-- history/
    |       +-- requirements-v1.0.0.md             # Archived snapshot
    |       +-- requirements-v1.1.0.md             # Archived snapshot
    +-- ep/
    |   +-- exploration.md                         # Codebase exploration report
    |   +-- architecture.md                        # Architecture design
    |   +-- plan.json                              # Structured task list (current version)
    |   +-- changes.log                            # NDJSON complete history
    |   └-- history/
    |       +-- plan-v1.0.0.json
    |       +-- plan-v1.1.0.json
    +-- cd/
    |   +-- implementation.md                      # Current version
    |   +-- debug-log.ndjson                       # Debug hypothesis tracking
    |   +-- changes.log                            # NDJSON complete history
    |   └-- history/
    |       +-- implementation-v1.0.0.md
    |       +-- implementation-v1.1.0.md
    +-- vas/
    |   +-- summary.md                             # Current version
    |   +-- changes.log                            # NDJSON complete history
    |   └-- history/
    |       +-- summary-v1.0.0.md
    |       +-- summary-v1.1.0.md
    └-- coordination/
        +-- timeline.md                            # Execution timeline
        +-- decisions.log                          # Decision log

State Management

State schema is defined in phases/state-schema.md. The master state file ({cycleId}.json) tracks:

•Cycle metadata (id, title, status, iterations)
•Agent states (status, output files, version)
•Shared context (requirements, plan, changes, test results)
•Coordination data (feedback log, decisions, blockers)

Versioning Workflow

Initial Version (v1.0.0)

bash

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

Generates:

code

requirements.md (v1.0.0)
exploration.md (v1.0.0)
architecture.md (v1.0.0)
plan.json (v1.0.0)
implementation.md (v1.0.0) - if applicable
summary.md (v1.0.0) - if applicable

Iteration Versions (v1.1.0, v1.2.0)

bash

/parallel-dev-cycle --cycle-id=cycle-v1-xxx --extend="Add GitHub support"

Automatic handling:

•Read current requirements.md (v1.0.0)
•Auto-archive to history/requirements-v1.0.0.md
•Recreate requirements.md (v1.1.0) - complete overwrite
•Append changes to changes.log (NDJSON)

Changes.log Format (NDJSON)

Permanent audit log (append-only, never deleted):

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-22T11:00:00+08:00","version":"1.1.0","agent":"ra","action":"update","change":"Added Google OAuth requirement","iteration":2}
{"timestamp":"2026-01-22T11:30:00+08:00","version":"1.0.0","agent":"ep","action":"create","change":"Initial implementation plan","iteration":1}

Usage

bash

# Start new cycle
/parallel-dev-cycle TASK="Implement real-time notifications"

# Continue cycle
/parallel-dev-cycle --cycle-id=cycle-v1-20260122-abc123

# Iteration with extension
/parallel-dev-cycle --cycle-id=cycle-v1-20260122-abc123 --extend="Also add email notifications"

# Auto mode
/parallel-dev-cycle --auto TASK="Add OAuth authentication"

Key Benefits

•Simple: Each agent maintains only 1 file + changes.log
•Efficient: Version rewrite without complex version marking
•Traceable: Complete history in history/ and changes.log
•Fast: Agent reads current version quickly (no history parsing needed)
•Auditable: NDJSON changes.log fully traces every change
•Self-Enhancing: RA agent proactively extends requirements
•Debug-Ready: CD agent supports hypothesis-driven debugging

Reference Documents

Document	Purpose
phases/orchestrator.md	Orchestrator logic
phases/state-schema.md	State structure definition
phases/agents/	Four agent role definitions
specs/coordination-protocol.md	Communication protocol
specs/versioning-strategy.md	Version management