mirror of
https://github.com/catlog22/Claude-Code-Workflow.git
synced 2026-02-11 02:33:51 +08:00
feat: Add communication optimization and coordination protocol for multi-agent system
- Introduced a new specification for agent communication optimization focusing on file references instead of content transfer to enhance efficiency and reduce message size. - Established a coordination protocol detailing communication channels, message formats, and dependency resolution strategies among agents (RA, EP, CD, VAS). - Created a unified progress format specification for all agents, standardizing documentation structure and versioning practices.
This commit is contained in:
catlog22
382
.codex/skills/parallel-dev-cycle/README.md
Normal file
382
.codex/skills/parallel-dev-cycle/README.md
Normal file
@@ -0,0 +1,382 @@
|
||||
# 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**: `plan.md` (architecture + tasks + integration points)
|
||||
- **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/
|
||||
│ ├── plan.md (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.md (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
|
||||
├── history/plan-v1.0.0.md → requirements.md (v1.1.0) - REWRITTEN
|
||||
├── history/impl-v1.0.0.md → plan.md (v1.1.0) - REWRITTEN
|
||||
└── history/summary-v1.0.0.md → implementation.md (v1.1.0) - REWRITTEN
|
||||
→ 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
|
||||
├── plan.md # v1.2.0 (current)
|
||||
├── changes.log # NDJSON audit trail
|
||||
└── history/
|
||||
├── plan-v1.0.0.md
|
||||
└── plan-v1.1.0.md
|
||||
|
||||
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** | plan.md | Architecture, all tasks, critical path, history | ~3-8KB |
|
||||
| **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)
|
||||
- plan.md (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.md
|
||||
- etc...
|
||||
↓
|
||||
Orchestrator: Next iteration?
|
||||
- Yes: send_input with feedback
|
||||
- No: close_agent, report summary
|
||||
```
|
||||
|
||||
## License
|
||||
|
||||
MIT
|
||||
Reference in New Issue
Block a user