mirror of
https://github.com/catlog22/Claude-Code-Workflow.git
synced 2026-02-05 01:50:27 +08:00
386 lines
11 KiB
Markdown
386 lines
11 KiB
Markdown
# 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
|
|
|
|
```bash
|
|
/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"
|
|
|
|
```bash
|
|
/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)
|
|
|
|
```bash
|
|
/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:
|
|
|
|
```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","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
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```javascript
|
|
// 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:
|
|
|
|
```javascript
|
|
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:
|
|
|
|
```javascript
|
|
// 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
|
|
|
|
```bash
|
|
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
|