mirror of
https://github.com/catlog22/Claude-Code-Workflow.git
synced 2026-02-11 02:33:51 +08:00
5b48bcff64
- 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.
345 lines
14 KiB
Markdown
345 lines
14 KiB
Markdown
---
|
|
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"
|
|
```
|