---
name: parallel-dev-cycle
description: Multi-agent parallel development cycle with requirement analysis, exploration planning, code development, and validation. Supports continuous iteration with markdown progress documentation. Triggers on "parallel-dev-cycle".
allowed-tools: Task, AskUserQuestion, TodoWrite, Read, Write, Edit, Bash, Glob, Grep
---

# Parallel Dev Cycle

Multi-agent parallel development cycle using Codex subagent pattern with four specialized workers:
1. **Requirements Analysis & Extension** (RA) - Requirement analysis and self-enhancement
2. **Exploration & Planning** (EP) - Codebase exploration and implementation planning
3. **Code Development** (CD) - Code development with debug strategy support
4. **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.

## Architecture Overview

```
┌─────────────────────────────────────────────────────────────┐
│                    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

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

## 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 without user confirmation) |
| --parallel | No | Number of parallel agents (default: 4, max: 4) |

## Auto Mode

When `--auto`: Run all phases sequentially without user confirmation between iterations. Use recommended defaults for all decisions. Automatically continue iteration loop until tests pass or max iterations reached.

## Execution Flow

```
Input Parsing:
   └─ Parse arguments (TASK | --cycle-id + --extend)
   └─ Convert to structured context (cycleId, state, progressDir)

Phase 1: Session Initialization
   └─ Ref: phases/01-session-init.md
      ├─ Create new cycle OR resume existing cycle
      ├─ Initialize state file and directory structure
      └─ Output: cycleId, state, progressDir

Phase 2: Agent Execution (Parallel)
   └─ Ref: phases/02-agent-execution.md
      ├─ Tasks attached: Spawn RA → Spawn EP → Spawn CD → Spawn VAS → Wait all
      ├─ Spawn RA, EP, CD, VAS agents in parallel
      ├─ Wait for all agents with timeout handling
      └─ Output: agentOutputs (4 agent results)

Phase 3: Result Aggregation & Iteration
   └─ Ref: phases/03-result-aggregation.md
      ├─ Parse PHASE_RESULT from each agent
      ├─ Detect issues (test failures, blockers)
      ├─ Decision: Issues found AND iteration < max?
      │   ├─ Yes → Send feedback via send_input, loop back to Phase 2
      │   └─ No → Proceed to Phase 4
      └─ Output: parsedResults, iteration status

Phase 4: Completion & Summary
   └─ Ref: phases/04-completion-summary.md
      ├─ Generate unified summary report
      ├─ Update final state
      ├─ Close all agents
      └─ Output: final cycle report with continuation instructions
```

**Phase Reference Documents** (read on-demand when phase executes):

| Phase | Document | Purpose |
|-------|----------|---------|
| 1 | [phases/01-session-init.md](phases/01-session-init.md) | Session creation/resume and state initialization |
| 2 | [phases/02-agent-execution.md](phases/02-agent-execution.md) | Parallel agent spawning and execution |
| 3 | [phases/03-result-aggregation.md](phases/03-result-aggregation.md) | Result parsing, feedback generation, iteration handling |
| 4 | [phases/04-completion-summary.md](phases/04-completion-summary.md) | Final summary generation and cleanup |

## Data Flow

```
User Input (TASK | --cycle-id + --extend)
    ↓
[Parse Arguments]
    ↓ cycleId, state, progressDir

Phase 1: Session Initialization
    ↓ cycleId, state, progressDir (initialized/resumed)

Phase 2: Agent Execution
    ↓ agentOutputs {ra, ep, cd, vas}

Phase 3: Result Aggregation
    ↓ parsedResults, hasIssues, iteration count
    ↓ [Loop back to Phase 2 if issues and iteration < max]

Phase 4: Completion & Summary
    ↓ finalState, summaryReport

Return: cycle_id, iterations, final_state
```

## Session Structure

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

## State Management

Master state file: `.workflow/.cycle/{cycleId}.json`

```json
{
  "cycle_id": "cycle-v1-20260122T100000-abc123",
  "title": "Task title",
  "description": "Full task description",
  "status": "created | running | paused | completed | failed",
  "created_at": "ISO8601", "updated_at": "ISO8601",
  "max_iterations": 5, "current_iteration": 0,
  "agents": {
    "ra":  { "status": "idle | running | completed | failed", "output_files": [] },
    "ep":  { "status": "idle", "output_files": [] },
    "cd":  { "status": "idle", "output_files": [] },
    "vas": { "status": "idle", "output_files": [] }
  },
  "current_phase": "init | ra | ep | cd | vas | aggregation | complete",
  "completed_phases": [],
  "requirements": null, "plan": null, "changes": [], "test_results": null,
  "coordination": { "feedback_log": [], "blockers": [] }
}
```

**Recovery**: If state corrupted, rebuild from `.progress/` markdown files and changes.log.

## TodoWrite Pattern

### Phase-Level Tracking (Tasks Attached)

```json
[
  {"content": "Phase 1: Session Initialization", "status": "completed"},
  {"content": "Phase 2: Agent Execution", "status": "in_progress"},
  {"content": "  → Spawn RA Agent", "status": "completed"},
  {"content": "  → Spawn EP Agent", "status": "completed"},
  {"content": "  → Spawn CD Agent", "status": "in_progress"},
  {"content": "  → Spawn VAS Agent", "status": "pending"},
  {"content": "Phase 3: Result Aggregation", "status": "pending"},
  {"content": "Phase 4: Completion & Summary", "status": "pending"}
]
```

### Phase-Level Tracking (Collapsed)

```json
[
  {"content": "Phase 1: Session Initialization", "status": "completed"},
  {"content": "Phase 2: Agent Execution (4 agents completed)", "status": "completed"},
  {"content": "Phase 3: Result Aggregation", "status": "in_progress"},
  {"content": "Phase 4: Completion & Summary", "status": "pending"}
]
```

### Iteration Loop Tracking

```json
[
  {"content": "Phase 1: Session Initialization", "status": "completed"},
  {"content": "Iteration 1: Agent Execution + Aggregation", "status": "completed"},
  {"content": "Iteration 2: Feedback → Re-execution → Aggregation", "status": "in_progress"},
  {"content": "Phase 4: Completion & Summary", "status": "pending"}
]
```

## Versioning

- **1.0.0**: Initial cycle → **1.x.0**: Each iteration (minor bump)
- Each iteration: archive old → complete rewrite → append changes.log

```
Archive: copy requirements.md → history/requirements-v1.0.0.md
Rewrite: overwrite requirements.md with v1.1.0 (complete new content)
Append:  changes.log ← {"timestamp","version":"1.1.0","action":"update","description":"..."}
```

| Agent Output | Rewrite (per iteration) | Append-only |
|-------------|------------------------|-------------|
| RA | requirements.md | changes.log |
| EP | exploration.md, architecture.md, plan.json | changes.log |
| CD | implementation.md, issues.md | changes.log, debug-log.ndjson |
| VAS | summary.md, test-results.json | changes.log |

## Coordination Protocol

**Execution Order**: RA → EP → CD → VAS (dependency chain, all spawned in parallel but block on dependencies)

**Agent → Orchestrator**: Each agent outputs `PHASE_RESULT:` block:
```
PHASE_RESULT:
- phase: ra | ep | cd | vas
- status: success | failed | partial
- files_written: [list]
- summary: one-line summary
- issues: []
```

**Orchestrator → Agent**: Feedback via `send_input` (file refs + issue summary, never full content):
```
## FEEDBACK FROM [Source]
[Issue summary with file:line references]
## Reference
- File: .progress/vas/test-results.json (v1.0.0)
## Actions Required
1. [Specific fix]
```

**Rules**: Only orchestrator writes state file. Agents read state, write to own `.progress/{agent}/` directory only.

## Core Rules

1. **Start Immediately**: First action is TodoWrite initialization, then Phase 1 execution
2. **Progressive Phase Loading**: Read phase docs ONLY when that phase is about to execute
3. **Parse Every Output**: Extract PHASE_RESULT data from each agent for next phase
4. **Auto-Continue**: After each phase, execute next pending phase automatically
5. **Track Progress**: Update TodoWrite dynamically with attachment/collapse pattern
6. **Single Writer**: Only orchestrator writes to master state file; agents report via PHASE_RESULT
7. **File References**: Pass file paths between agents, not content
8. **DO NOT STOP**: Continuous execution until all phases complete or max iterations reached

## Error Handling

| Error Type | Recovery |
|------------|----------|
| Agent timeout | send_input requesting convergence, then retry |
| State corrupted | Rebuild from progress markdown files and changes.log |
| Agent failed | Re-spawn agent with previous context |
| Conflicting results | Orchestrator sends reconciliation request |
| Missing files | RA/EP agents identify and request clarification |
| Max iterations reached | Generate summary with remaining issues documented |

## Coordinator Checklist

### Before Each Phase

- [ ] Read phase reference document
- [ ] Check current state for dependencies
- [ ] Update TodoWrite with phase tasks

### After Each Phase

- [ ] Parse agent outputs (PHASE_RESULT)
- [ ] Update master state file
- [ ] Collapse TodoWrite sub-tasks
- [ ] Determine next action (continue / iterate / complete)

## Reference Documents

| Document | Purpose |
|----------|---------|
| [roles/](roles/) | Agent role definitions (RA, EP, CD, VAS) |

## 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"
```