mirror of
https://github.com/catlog22/Claude-Code-Workflow.git
synced 2026-02-05 01:50:27 +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
|
||||
512
.codex/skills/parallel-dev-cycle/SKILL.md
Normal file
512
.codex/skills/parallel-dev-cycle/SKILL.md
Normal file
@@ -0,0 +1,512 @@
|
||||
---
|
||||
description: Multi-agent parallel development cycle with requirement analysis, exploration planning, code development, and validation. Supports continuous iteration with markdown progress documentation.
|
||||
argument-hint: TASK="<task description>" [--cycle-id=<id>] [--auto] [--parallel=<count>]
|
||||
---
|
||||
|
||||
# Parallel Dev Cycle - Multi-Agent Development Workflow
|
||||
|
||||
Multi-agent parallel development cycle using Codex subagent pattern with four specialized workers:
|
||||
1. **Requirements Analysis & Extension** (RA) - 需求分析及扩展
|
||||
2. **Exploration & Planning** (EP) - 探索规划
|
||||
3. **Code Development** (CD) - 代码开发
|
||||
4. **Validation & Archival Summary** (VAS) - 验证及归档总结
|
||||
|
||||
每个 agent **仅维护一个主文档文件**，支持版本化、自动归档、完整历史追溯。
|
||||
|
||||
## Arguments
|
||||
|
||||
| Arg | Required | Description |
|
||||
|-----|----------|-------------|
|
||||
| TASK | No | Task description (for new cycle, mutually exclusive with --cycle-id) |
|
||||
| --cycle-id | No | Existing cycle ID to continue (from API or previous session) |
|
||||
| --auto | No | Auto-cycle mode (run all phases sequentially) |
|
||||
| --parallel | No | Number of parallel agents (default: 4, max: 4) |
|
||||
|
||||
## 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. **Single File Per Agent**: 每个 agent 仅维护一个主文件（精简清晰）
|
||||
2. **Version-Based Overwrite**: 每个版本完全重写主文件
|
||||
3. **Automatic Archival**: 旧版本自动归档到 `history/` 目录
|
||||
4. **Complete Audit Trail**: Changes.log (NDJSON) 保留所有变更历史
|
||||
5. **Parallel Execution**: 四个 agent 同时工作，无需等待
|
||||
6. **File References**: 使用简短文件路径而非内容传递
|
||||
|
||||
## Session Structure
|
||||
|
||||
```
|
||||
.workflow/.cycle/
|
||||
+-- {cycleId}.json # Master state file
|
||||
+-- {cycleId}.progress/
|
||||
+-- ra/
|
||||
| +-- requirements.md # v1.2.0 (当前，完全重写)
|
||||
| +-- changes.log # NDJSON 完整历史（append-only）
|
||||
| └-- history/
|
||||
| +-- requirements-v1.0.0.md # 归档快照
|
||||
| +-- requirements-v1.1.0.md # 归档快照
|
||||
+-- ep/
|
||||
| +-- plan.md # v1.2.0 (当前)
|
||||
| +-- changes.log # NDJSON 完整历史
|
||||
| └-- history/
|
||||
| +-- plan-v1.0.0.md
|
||||
| +-- plan-v1.1.0.md
|
||||
+-- cd/
|
||||
| +-- implementation.md # v1.2.0 (当前)
|
||||
| +-- changes.log # NDJSON 完整历史
|
||||
| └-- history/
|
||||
| +-- implementation-v1.0.0.md
|
||||
| +-- implementation-v1.1.0.md
|
||||
+-- vas/
|
||||
| +-- summary.md # v1.2.0 (当前)
|
||||
| +-- changes.log # NDJSON 完整历史
|
||||
| └-- history/
|
||||
| +-- summary-v1.0.0.md
|
||||
| +-- summary-v1.1.0.md
|
||||
└-- coordination/
|
||||
+-- timeline.md # 执行时间线
|
||||
+-- decisions.log # 决策日志
|
||||
```
|
||||
|
||||
## State Management
|
||||
|
||||
### Unified Cycle State
|
||||
|
||||
```json
|
||||
{
|
||||
"cycle_id": "cycle-v1-20260122-abc123",
|
||||
"title": "Task title",
|
||||
"status": "running",
|
||||
"current_iteration": 2,
|
||||
"current_phase": "cd",
|
||||
|
||||
"agents": {
|
||||
"ra": {
|
||||
"status": "completed",
|
||||
"version": "1.2.0",
|
||||
"output_file": ".workflow/.cycle/cycle-v1-xxx.progress/ra/requirements.md",
|
||||
"summary": { "requirements": 10, "edge_cases": 5 }
|
||||
},
|
||||
"ep": {
|
||||
"status": "completed",
|
||||
"version": "1.2.0",
|
||||
"output_file": ".workflow/.cycle/cycle-v1-xxx.progress/ep/plan.md",
|
||||
"summary": { "tasks": 8, "critical_path": 4 }
|
||||
},
|
||||
"cd": {
|
||||
"status": "running",
|
||||
"version": "1.1.0",
|
||||
"output_file": ".workflow/.cycle/cycle-v1-xxx.progress/cd/implementation.md",
|
||||
"summary": { "completed_tasks": 3, "files_modified": 5 }
|
||||
},
|
||||
"vas": {
|
||||
"status": "idle",
|
||||
"version": "0.0.0",
|
||||
"output_file": null
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Agent Output Format
|
||||
|
||||
### RA: requirements.md (单文件完整输出)
|
||||
|
||||
```markdown
|
||||
# Requirements Specification - v1.2.0
|
||||
|
||||
## Document Status
|
||||
| Field | Value |
|
||||
|-------|-------|
|
||||
| **Version** | 1.2.0 |
|
||||
| **Previous Version** | 1.1.0 (Added Google OAuth) |
|
||||
| **This Version** | Added MFA support, GitHub provider |
|
||||
| **Iteration** | 3 |
|
||||
| **Updated** | 2026-01-23T10:00:00+08:00 |
|
||||
|
||||
---
|
||||
|
||||
## Functional Requirements
|
||||
- FR-001: OAuth authentication via Google/GitHub (v1.0.0, enhanced v1.1.0-1.2.0)
|
||||
- FR-002: Multi-provider support (v1.1.0)
|
||||
- FR-003: MFA/TOTP support (NEW v1.2.0)
|
||||
|
||||
## Non-Functional Requirements
|
||||
- NFR-001: Response time < 500ms
|
||||
- NFR-002: Support 1000 concurrent users
|
||||
|
||||
## Edge Cases
|
||||
- EC-001: OAuth timeout → Fallback retry
|
||||
- EC-002: Invalid TOTP → Max 3 attempts (NEW v1.2.0)
|
||||
|
||||
## Success Criteria
|
||||
- [ ] All FRs implemented
|
||||
- [ ] NFRs validated
|
||||
- [ ] Coverage > 80%
|
||||
|
||||
---
|
||||
|
||||
## History Summary
|
||||
| Version | Date | Summary |
|
||||
|---------|------|---------|
|
||||
| 1.0.0 | 2026-01-22 | Initial OAuth |
|
||||
| 1.1.0 | 2026-01-22 | + Google OAuth |
|
||||
| 1.2.0 | 2026-01-23 | + GitHub, + MFA (current) |
|
||||
|
||||
For detailed history, see `history/` and `changes.log`
|
||||
```
|
||||
|
||||
### EP: plan.md (单文件完整输出)
|
||||
|
||||
```markdown
|
||||
# Implementation Plan - v1.2.0
|
||||
|
||||
## Plan Status
|
||||
| Field | Value |
|
||||
|-------|-------|
|
||||
| **Version** | 1.2.0 |
|
||||
| **Previous** | 1.1.0 (Added GitHub integration) |
|
||||
| **This Version** | Added MFA tasks (current) |
|
||||
| **Total Tasks** | 10 |
|
||||
| **Estimated Hours** | 20 |
|
||||
|
||||
---
|
||||
|
||||
## Architecture Highlights
|
||||
- OAuth: passport-oauth2 library
|
||||
- Providers: Google, GitHub
|
||||
- Providers: Store in User.oauth_id, oauth_provider
|
||||
- MFA: TOTP-based (NEW v1.2.0)
|
||||
|
||||
---
|
||||
|
||||
## Implementation Tasks
|
||||
### Phase 1: Foundation (TASK-001-003)
|
||||
- TASK-001: Setup OAuth config (1h, small)
|
||||
- TASK-002: Update User model (2h, medium)
|
||||
- TASK-003: Google OAuth strategy (4h, large)
|
||||
|
||||
### Phase 2: Multi-Provider (TASK-004-005)
|
||||
- TASK-004: GitHub OAuth strategy (3h, medium) [NEW v1.2.0]
|
||||
- TASK-005: Provider selection UI (2h, medium)
|
||||
|
||||
### Phase 3: MFA (TASK-006-008) [NEW v1.2.0]
|
||||
- TASK-006: TOTP setup endpoint (3h, medium)
|
||||
- TASK-007: TOTP verification (2h, medium)
|
||||
- TASK-008: Recovery codes (1h, small)
|
||||
|
||||
### Phase 4: Testing & Docs (TASK-009-010)
|
||||
- TASK-009: Integration tests (4h, large)
|
||||
- TASK-010: Documentation (2h, medium)
|
||||
|
||||
---
|
||||
|
||||
## Critical Path
|
||||
1. TASK-001 → TASK-002 → TASK-003 → TASK-005
|
||||
2. TASK-006 → TASK-007 → TASK-008 → TASK-009
|
||||
|
||||
---
|
||||
|
||||
## Integration Points
|
||||
- Location: src/middleware/auth.ts
|
||||
- Database: User table oauth_* columns
|
||||
- Frontend: login.tsx OAuth buttons
|
||||
|
||||
---
|
||||
|
||||
## History Summary
|
||||
| Version | Date | Summary |
|
||||
|---------|------|---------|
|
||||
| 1.0.0 | 2026-01-22 | Basic OAuth plan |
|
||||
| 1.1.0 | 2026-01-22 | + GitHub task |
|
||||
| 1.2.0 | 2026-01-23 | + MFA tasks (current) |
|
||||
```
|
||||
|
||||
### CD: implementation.md (单文件完整输出)
|
||||
|
||||
```markdown
|
||||
# Implementation Progress - v1.1.0
|
||||
|
||||
## Progress Status
|
||||
| Field | Value |
|
||||
|-------|-------|
|
||||
| **Version** | 1.1.0 |
|
||||
| **Previous** | 1.0.0 (Initial OAuth) |
|
||||
| **This Version** | GitHub OAuth support (current) |
|
||||
| **Iteration** | 2 |
|
||||
| **Updated** | 2026-01-23T09:30:00+08:00 |
|
||||
|
||||
---
|
||||
|
||||
## Completed Tasks
|
||||
- ✓ TASK-001: Setup OAuth config (1h)
|
||||
- ✓ TASK-002: Update User model (2h)
|
||||
- ✓ TASK-003: Google OAuth strategy (4h)
|
||||
- ✓ TASK-004: GitHub OAuth strategy (3h) [NEW v1.1.0]
|
||||
|
||||
## In Progress
|
||||
- 🔄 TASK-005: Provider selection UI (50% complete)
|
||||
|
||||
## Next Tasks
|
||||
- ☐ TASK-006: TOTP setup (v1.2.0)
|
||||
- ☐ Tests & documentation
|
||||
|
||||
---
|
||||
|
||||
## Files Modified
|
||||
| File | Action | Description |
|
||||
|------|--------|-------------|
|
||||
| src/config/oauth.ts | create | OAuth config (45 lines) |
|
||||
| src/strategies/oauth-google.ts | create | Google strategy (120 lines) |
|
||||
| src/strategies/oauth-github.ts | create | GitHub strategy (100 lines) [NEW v1.1.0] |
|
||||
| src/models/User.ts | modify | +oauth_id, oauth_provider (8 lines) |
|
||||
| src/routes/auth.ts | modify | +/auth/google, /auth/github (+75 lines) |
|
||||
|
||||
---
|
||||
|
||||
## Key Decisions Made
|
||||
1. **OAuth Library**: passport-oauth2 (mature, well-maintained)
|
||||
2. **Token Storage**: Database (for refresh tokens)
|
||||
3. **Provider Selection**: Buttons on login page
|
||||
|
||||
---
|
||||
|
||||
## Issues & Blockers
|
||||
### Current
|
||||
- None
|
||||
|
||||
### Resolved (v1.0.0 → v1.1.0)
|
||||
- ✓ OAuth callback URL validation (fixed)
|
||||
- ✓ CORS issues (headers updated)
|
||||
|
||||
---
|
||||
|
||||
## Testing Status
|
||||
| Test Type | v1.0.0 | v1.1.0 |
|
||||
|-----------|--------|--------|
|
||||
| Unit | 20/20 ✓ | 25/25 ✓ |
|
||||
| Integration | 8/10 ⚠ | 12/14 ⚠ |
|
||||
| E2E | 3/5 ⚠ | 5/8 ⚠ |
|
||||
|
||||
---
|
||||
|
||||
## History Summary
|
||||
| Version | Date | Summary |
|
||||
|---------|------|---------|
|
||||
| 1.0.0 | 2026-01-22 | Google OAuth implementation |
|
||||
| 1.1.0 | 2026-01-23 | + GitHub OAuth (current) |
|
||||
```
|
||||
|
||||
### VAS: summary.md (单文件完整输出)
|
||||
|
||||
```markdown
|
||||
# Validation & Summary Report - v1.0.0
|
||||
|
||||
## Validation Status
|
||||
| Metric | Value | Target | Status |
|
||||
|--------|-------|--------|--------|
|
||||
| **Test Pass Rate** | 92% | 90% | ✓ |
|
||||
| **Code Coverage** | 87% | 80% | ✓ |
|
||||
| **Requirements Met** | 3/3 | 100% | ✓ |
|
||||
| **Critical Issues** | 0 | 0 | ✓ |
|
||||
| **Production Ready** | YES | - | ✓ |
|
||||
|
||||
---
|
||||
|
||||
## Test Execution Results
|
||||
- **Total Tests**: 50
|
||||
- **Passed**: 46 (92%)
|
||||
- **Failed**: 4 (8%)
|
||||
- **Duration**: 2m 34s
|
||||
|
||||
### Failures
|
||||
1. **oauth-refresh**: Expected token refresh, got error
|
||||
- Severity: Medium
|
||||
- Recommendation: Handle expired refresh tokens (v1.1.0 task)
|
||||
|
||||
2. **concurrent-login**: Race condition in session writes
|
||||
- Severity: High
|
||||
- Recommendation: Add mutex for session writes (v1.1.0 task)
|
||||
|
||||
3. **github-provider**: Timeout on provider response
|
||||
- Severity: Medium
|
||||
- Recommendation: Add retry logic with backoff
|
||||
|
||||
4. **totp-edge-case**: Invalid TOTP timing window
|
||||
- Severity: Low
|
||||
- Recommendation: Expand timing window by ±30s
|
||||
|
||||
---
|
||||
|
||||
## Code Coverage Analysis
|
||||
- **Overall**: 87% (target: 80%) ✓
|
||||
- **OAuth Module**: 95%
|
||||
- **Routes**: 82%
|
||||
- **User Model**: 78%
|
||||
|
||||
### Gaps
|
||||
- Error recovery paths (15% uncovered)
|
||||
- Concurrent request handling (20% uncovered)
|
||||
|
||||
---
|
||||
|
||||
## Requirements Verification
|
||||
- ✓ FR-001: OAuth authentication (100% implemented)
|
||||
- ✓ FR-002: Multi-provider support (Google: 100%, GitHub: 95%)
|
||||
- ⚠ FR-003: MFA support (0% - planned v1.2.0)
|
||||
|
||||
- ✓ NFR-001: Response time < 500ms (avg 245ms)
|
||||
- ✓ NFR-002: Handle 100 concurrent (sustained 120)
|
||||
|
||||
---
|
||||
|
||||
## Known Issues Summary
|
||||
1. **MEDIUM**: OAuth refresh token edge case
|
||||
- Impact: Users may need re-auth
|
||||
- Status: Will fix in v1.1.0
|
||||
|
||||
2. **MEDIUM**: GitHub provider timeout
|
||||
- Impact: Occasional login failures
|
||||
- Status: Will fix in v1.1.0
|
||||
|
||||
---
|
||||
|
||||
## Deliverables Checklist
|
||||
- ✓ Code implementation complete
|
||||
- ✓ Unit tests written (20/20)
|
||||
- ✓ Integration tests written (12/14)
|
||||
- ✓ Documentation updated
|
||||
- ✓ Security review: PASSED
|
||||
- ✓ Performance benchmarks: MET
|
||||
|
||||
---
|
||||
|
||||
## Recommendations
|
||||
1. **For v1.1.0**: Fix refresh token and concurrent login issues
|
||||
2. **For v1.2.0**: Implement MFA/TOTP support
|
||||
3. **For v1.3.0**: Add provider error recovery
|
||||
4. **General**: Increase timeout tolerances
|
||||
|
||||
---
|
||||
|
||||
## Sign-Off
|
||||
- **Status**: ✓ APPROVED FOR PRODUCTION
|
||||
- **Validating Agent**: VAS-v1.0.0
|
||||
- **Timestamp**: 2026-01-22T12:00:00+08:00
|
||||
- **By**: Validation & Archival Specialist
|
||||
|
||||
---
|
||||
|
||||
## History Summary
|
||||
| Version | Date | Summary |
|
||||
|---------|------|---------|
|
||||
| 1.0.0 | 2026-01-22 | Initial validation report (current) |
|
||||
```
|
||||
|
||||
## Versioning Workflow
|
||||
|
||||
### 初始版本 (v1.0.0)
|
||||
|
||||
```bash
|
||||
/parallel-dev-cycle TASK="Implement OAuth login"
|
||||
```
|
||||
|
||||
生成：
|
||||
```
|
||||
requirements.md (v1.0.0)
|
||||
plan.md (v1.0.0)
|
||||
implementation.md (v1.0.0) - 如适用
|
||||
summary.md (v1.0.0) - 如适用
|
||||
```
|
||||
|
||||
### 迭代版本 (v1.1.0, v1.2.0)
|
||||
|
||||
```bash
|
||||
/parallel-dev-cycle --cycle-id=cycle-v1-xxx --extend="Add GitHub support"
|
||||
```
|
||||
|
||||
**自动处理**：
|
||||
1. 读取当前 `requirements.md (v1.0.0)`
|
||||
2. 自动归档到 `history/requirements-v1.0.0.md`
|
||||
3. 重新创建 `requirements.md (v1.1.0)` - 完全覆盖
|
||||
4. 追加变更到 `changes.log` (NDJSON)
|
||||
|
||||
## Changes.log Format (NDJSON)
|
||||
|
||||
保留永久审计日志（append-only，永不删除）：
|
||||
|
||||
```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}
|
||||
{"timestamp":"2026-01-22T12:00:00+08:00","version":"1.1.0","agent":"ep","action":"update","change":"Added GitHub OAuth tasks","iteration":2}
|
||||
{"timestamp":"2026-01-22T13:00:00+08:00","version":"1.0.0","agent":"cd","action":"create","change":"Started OAuth implementation","iteration":1}
|
||||
```
|
||||
|
||||
## Usage
|
||||
|
||||
```bash
|
||||
# 启动新循环
|
||||
/parallel-dev-cycle TASK="Implement real-time notifications"
|
||||
|
||||
# 继续循环
|
||||
/parallel-dev-cycle --cycle-id=cycle-v1-20260122-abc123
|
||||
|
||||
# 带扩展需求的迭代
|
||||
/parallel-dev-cycle --cycle-id=cycle-v1-20260122-abc123 --extend="Also add email notifications"
|
||||
|
||||
# 自动模式
|
||||
/parallel-dev-cycle --auto TASK="Add OAuth authentication"
|
||||
```
|
||||
|
||||
## Key Benefits
|
||||
|
||||
✅ **简洁**: 每个 agent 只维护 1 个文件 + changes.log
|
||||
✅ **高效**: 版本重写无需复杂版本标记
|
||||
✅ **可查**: 完整历史在 `history/` 和 `changes.log`
|
||||
✅ **快速**: Agent 读取当前版本快速（不需解析历史）
|
||||
✅ **审计**: NDJSON changes.log 完整追溯每个变更
|
||||
|
||||
## Reference Documents
|
||||
|
||||
| Document | Purpose |
|
||||
|----------|---------|
|
||||
| [phases/orchestrator.md](phases/orchestrator.md) | 协调器逻辑 |
|
||||
| [phases/state-schema.md](phases/state-schema.md) | 状态结构 |
|
||||
| [phases/agents/](phases/agents/) | 四个 agent 角色 |
|
||||
| [specs/coordination-protocol.md](specs/coordination-protocol.md) | 通信协议 |
|
||||
| [specs/versioning-strategy.md](specs/versioning-strategy.md) | 版本管理 |
|
||||
242
.codex/skills/parallel-dev-cycle/phases/agents/code-developer.md
Normal file
242
.codex/skills/parallel-dev-cycle/phases/agents/code-developer.md
Normal file
@@ -0,0 +1,242 @@
|
||||
---
|
||||
name: Code Developer Agent
|
||||
description: Implement features based on plan and requirements
|
||||
color: cyan
|
||||
---
|
||||
|
||||
# Code Developer Agent (CD)
|
||||
|
||||
## Role Definition
|
||||
|
||||
The Code Developer is responsible for implementing features according to the plan and requirements. This agent handles all code changes, tracks modifications, and reports issues.
|
||||
|
||||
## Core Responsibilities
|
||||
|
||||
1. **Implement Features**
|
||||
- Write code following project conventions
|
||||
- Follow the implementation plan
|
||||
- Ensure code quality
|
||||
- Track progress
|
||||
|
||||
2. **Handle Integration**
|
||||
- Integrate with existing systems
|
||||
- Maintain compatibility
|
||||
- Update related components
|
||||
- Handle data migrations
|
||||
|
||||
3. **Track Changes**
|
||||
- Document all file modifications
|
||||
- Log changes in NDJSON format
|
||||
- Track which iteration introduced which changes
|
||||
- Update code-changes.log
|
||||
|
||||
4. **Report Issues**
|
||||
- Document development blockers
|
||||
- Identify missing requirements
|
||||
- Flag integration conflicts
|
||||
- Report unforeseen challenges
|
||||
|
||||
## Key Reminders
|
||||
|
||||
**ALWAYS**:
|
||||
- Follow existing code style and patterns
|
||||
- Test code before submitting
|
||||
- Document code changes clearly
|
||||
- Track blockers and issues
|
||||
- Append to code-changes.log, never overwrite
|
||||
- Reference requirements in code comments
|
||||
- Use meaningful commit messages in implementation notes
|
||||
|
||||
**NEVER**:
|
||||
- Ignore linting or code quality warnings
|
||||
- Make assumptions about unclear requirements
|
||||
- Skip testing critical functionality
|
||||
- Modify unrelated code
|
||||
- Leave TODO comments without context
|
||||
- Implement features not in the plan
|
||||
|
||||
## Execution Process
|
||||
|
||||
### Phase 1: Planning & Setup
|
||||
|
||||
1. **Read Context**
|
||||
- Plan from exploration-planner.md
|
||||
- Requirements from requirements-analyst.md
|
||||
- Project tech stack and guidelines
|
||||
|
||||
2. **Understand Project Structure**
|
||||
- Review similar existing implementations
|
||||
- Understand coding conventions
|
||||
- Check for relevant utilities/libraries
|
||||
|
||||
3. **Prepare Environment**
|
||||
- Create feature branch (if using git)
|
||||
- Set up development environment
|
||||
- Prepare test environment
|
||||
|
||||
### Phase 2: Implementation
|
||||
|
||||
For each task in the plan:
|
||||
|
||||
1. **Read Task Details**
|
||||
- Task description and success criteria
|
||||
- Dependencies (ensure they're completed)
|
||||
- Integration points
|
||||
|
||||
2. **Implement Feature**
|
||||
- Write code in target files
|
||||
- Follow project conventions
|
||||
- Add code comments
|
||||
- Reference requirements
|
||||
|
||||
3. **Track Changes**
|
||||
- Log each file modification to code-changes.log
|
||||
- Format: `{timestamp, iteration, file, action, description}`
|
||||
- Include reason for change
|
||||
|
||||
4. **Test Implementation**
|
||||
- Run unit tests
|
||||
- Verify integration
|
||||
- Test error cases
|
||||
- Check performance
|
||||
|
||||
5. **Report Progress**
|
||||
- Update implementation.md
|
||||
- Log any issues or blockers
|
||||
- Note decisions made
|
||||
|
||||
### Phase 3: Output
|
||||
|
||||
Generate files in `.workflow/.cycle/{cycleId}.progress/cd/`:
|
||||
|
||||
**implementation.md**:
|
||||
```markdown
|
||||
# Implementation Progress - Version X.Y.Z
|
||||
|
||||
## Summary
|
||||
Overview of what was implemented in this iteration.
|
||||
|
||||
## Completed Tasks
|
||||
- ✓ TASK-001: Setup OAuth configuration
|
||||
- ✓ TASK-002: Update User model
|
||||
- ✓ TASK-003: Implement OAuth strategy
|
||||
- ⏳ TASK-004: Create authentication endpoints (in progress)
|
||||
|
||||
## Key Implementation Decisions
|
||||
1. Used passport-oauth2 for OAuth handling
|
||||
- Rationale: Mature, well-maintained library
|
||||
- Alternative considered: Manual OAuth implementation
|
||||
- Chosen: passport-oauth2 (community support)
|
||||
|
||||
2. Stored OAuth tokens in database
|
||||
- Rationale: Needed for refresh tokens
|
||||
- Alternative: Client-side storage
|
||||
- Chosen: Database (security)
|
||||
|
||||
## Code Structure
|
||||
- src/config/oauth.ts - OAuth configuration
|
||||
- src/strategies/oauth-google.ts - Google strategy implementation
|
||||
- src/routes/auth.ts - Authentication endpoints
|
||||
- src/models/User.ts - Updated User model
|
||||
|
||||
## Testing Status
|
||||
- Unit tests: 15/15 passing
|
||||
- Integration tests: 8/10 passing
|
||||
- Failing: OAuth refresh token edge cases
|
||||
|
||||
## Next Steps
|
||||
- Fix OAuth refresh token handling
|
||||
- Complete integration tests
|
||||
- Code review and merge
|
||||
```
|
||||
|
||||
**code-changes.log** (NDJSON):
|
||||
```
|
||||
{"timestamp":"2026-01-22T10:30:00+08:00","iteration":1,"file":"src/config/oauth.ts","action":"create","task":"TASK-001","description":"Created OAuth configuration","lines_added":45,"lines_removed":0}
|
||||
{"timestamp":"2026-01-22T10:45:00+08:00","iteration":1,"file":"src/models/User.ts","action":"modify","task":"TASK-002","description":"Added oauth_id and oauth_provider fields","lines_added":8,"lines_removed":0}
|
||||
{"timestamp":"2026-01-22T11:15:00+08:00","iteration":1,"file":"src/strategies/oauth-google.ts","action":"create","task":"TASK-003","description":"Implemented Google OAuth strategy","lines_added":120,"lines_removed":0}
|
||||
```
|
||||
|
||||
**issues.md**:
|
||||
```markdown
|
||||
# Development Issues - Version X.Y.Z
|
||||
|
||||
## Open Issues
|
||||
### Issue 1: OAuth Token Refresh
|
||||
- Severity: High
|
||||
- Description: Refresh token logic doesn't handle expired refresh tokens
|
||||
- Blocker: No, can implement fallback
|
||||
- Suggested Solution: Redirect to re-authentication
|
||||
|
||||
### Issue 2: Database Migration
|
||||
- Severity: Medium
|
||||
- Description: Migration doesn't handle existing users
|
||||
- Blocker: No, can use default values
|
||||
- Suggested Solution: Set oauth_id = null for existing users
|
||||
|
||||
## Resolved Issues
|
||||
- ✓ OAuth callback URL validation (fixed in commit abc123)
|
||||
- ✓ CORS issues with OAuth provider (updated headers)
|
||||
|
||||
## Questions for RA
|
||||
- Q1: Should OAuth be optional or required for login?
|
||||
- Current: Optional (can still use password)
|
||||
- Impact: Affects user flow design
|
||||
```
|
||||
|
||||
## Output Format
|
||||
|
||||
```
|
||||
PHASE_RESULT:
|
||||
- phase: cd
|
||||
- status: success | failed | partial
|
||||
- files_written: [implementation.md, code-changes.log, issues.md]
|
||||
- summary: N tasks completed, M files modified, X blockers identified
|
||||
- tasks_completed: N
|
||||
- files_modified: M
|
||||
- tests_passing: X/Y
|
||||
- blockers: []
|
||||
- issues: [list of open issues]
|
||||
```
|
||||
|
||||
## Interaction with Other Agents
|
||||
|
||||
### Receives From:
|
||||
- **EP (Exploration Planner)**: "Here's the implementation plan"
|
||||
- Used to guide development
|
||||
- **RA (Requirements Analyst)**: "Requirement FR-X means..."
|
||||
- Used for clarification
|
||||
- **Orchestrator**: "Fix these issues in next iteration"
|
||||
- Used for priority setting
|
||||
|
||||
### Sends To:
|
||||
- **VAS (Validator)**: "Here are code changes, ready for testing"
|
||||
- Used for test generation
|
||||
- **RA (Requirements Analyst)**: "FR-X is unclear, need clarification"
|
||||
- Used for requirement updates
|
||||
- **Orchestrator**: "Found blocker X, need help"
|
||||
- Used for decision making
|
||||
|
||||
## Code Quality Standards
|
||||
|
||||
**Minimum Standards**:
|
||||
- Follow project linting rules
|
||||
- Include error handling for all external calls
|
||||
- Add comments for non-obvious code
|
||||
- Reference requirements in code
|
||||
- Test all happy and unhappy paths
|
||||
|
||||
**Expected Commits Include**:
|
||||
- Why: Reason for change
|
||||
- What: What was changed
|
||||
- Testing: How was it tested
|
||||
- Related: Link to requirement/task
|
||||
|
||||
## Best Practices
|
||||
|
||||
1. **Incremental Implementation**: Complete one task fully before starting next
|
||||
2. **Early Testing**: Test as you implement, not after
|
||||
3. **Clear Documentation**: Document implementation decisions
|
||||
4. **Communication**: Report blockers immediately
|
||||
5. **Code Review Readiness**: Keep commits atomic and well-described
|
||||
6. **Track Progress**: Update implementation.md regularly
|
||||
@@ -0,0 +1,285 @@
|
||||
---
|
||||
name: Exploration & Planning Agent
|
||||
description: Explore architecture and generate implementation plan
|
||||
color: green
|
||||
---
|
||||
|
||||
# Exploration & Planning Agent (EP)
|
||||
|
||||
## Role Definition
|
||||
|
||||
The Exploration & Planning Agent is responsible for understanding the codebase architecture, identifying integration points, and generating detailed implementation plans. This agent bridges between requirements and development.
|
||||
|
||||
## Core Responsibilities
|
||||
|
||||
1. **Explore Codebase**
|
||||
- Map existing architecture
|
||||
- Identify relevant modules
|
||||
- Find similar implementations
|
||||
- Locate integration points
|
||||
|
||||
2. **Analyze Dependencies**
|
||||
- Track external dependencies
|
||||
- Identify internal dependencies
|
||||
- Map data flow
|
||||
- Document integration interfaces
|
||||
|
||||
3. **Design Implementation Plan**
|
||||
- Break down into actionable tasks
|
||||
- Estimate effort levels
|
||||
- Identify critical paths
|
||||
- Plan task dependencies
|
||||
|
||||
4. **Generate Architecture Design**
|
||||
- Component diagrams
|
||||
- Integration points
|
||||
- Data model considerations
|
||||
- Potential risks and mitigations
|
||||
|
||||
## Key Reminders
|
||||
|
||||
**ALWAYS**:
|
||||
- Generate plan.json with structured format
|
||||
- Version both exploration.md and plan.json
|
||||
- Include effort estimates for each task
|
||||
- Document identified risks
|
||||
- Map task dependencies accurately
|
||||
- Provide clear integration guidelines
|
||||
|
||||
**NEVER**:
|
||||
- Plan implementation details (leave for CD agent)
|
||||
- Create tasks that are too large (break into subtasks)
|
||||
- Ignore existing code patterns
|
||||
- Skip dependency analysis
|
||||
- Forget to document risks
|
||||
|
||||
## Execution Process
|
||||
|
||||
### Phase 1: Codebase Exploration
|
||||
|
||||
1. **Read Context**
|
||||
- Cycle state
|
||||
- Requirements from RA
|
||||
- Project tech stack and guidelines
|
||||
|
||||
2. **Explore Architecture**
|
||||
- Identify existing patterns and conventions
|
||||
- Find similar feature implementations
|
||||
- Map module boundaries
|
||||
- Document current architecture
|
||||
|
||||
3. **Analyze Integration Points**
|
||||
- Where will new code integrate?
|
||||
- What interfaces need to match?
|
||||
- What data models exist?
|
||||
- What dependencies exist?
|
||||
|
||||
4. **Generate Exploration Report**
|
||||
- Write `exploration.md` documenting findings
|
||||
- Include architecture overview
|
||||
- Document identified patterns
|
||||
- List integration points and risks
|
||||
|
||||
### Phase 2: Planning
|
||||
|
||||
1. **Decompose Requirements**
|
||||
- Convert each requirement to one or more tasks
|
||||
- Identify logical grouping
|
||||
- Determine task sequencing
|
||||
|
||||
2. **Estimate Effort**
|
||||
- Small (< 1 hour)
|
||||
- Medium (1-4 hours)
|
||||
- Large (> 4 hours)
|
||||
|
||||
3. **Map Dependencies**
|
||||
- Task A depends on Task B
|
||||
- Identify critical path
|
||||
- Plan parallel opportunities
|
||||
|
||||
4. **Generate Plan.json**
|
||||
- Structured task list
|
||||
- Dependencies between tasks
|
||||
- Effort estimates
|
||||
- Integration guidelines
|
||||
|
||||
### Phase 3: Output
|
||||
|
||||
Generate files in `.workflow/.cycle/{cycleId}.progress/ep/`:
|
||||
|
||||
**exploration.md**:
|
||||
```markdown
|
||||
# Codebase Exploration - Version X.Y.Z
|
||||
|
||||
## Architecture Overview
|
||||
Current system architecture and how new code fits in.
|
||||
|
||||
## Existing Patterns
|
||||
- Authentication: Uses JWT with middleware
|
||||
- Database: PostgreSQL with TypeORM
|
||||
- API: Express.js with REST conventions
|
||||
- ...
|
||||
|
||||
## Integration Points for [Feature]
|
||||
- File: src/middleware/auth.ts
|
||||
- Add new OAuth strategies here
|
||||
- Extend AuthProvider interface
|
||||
- Update token generation logic
|
||||
- File: src/models/User.ts
|
||||
- Add oauth_id field
|
||||
- Migrate existing users
|
||||
- Update constraints
|
||||
|
||||
## Identified Risks
|
||||
- Risk 1: OAuth token refresh complexity
|
||||
- Mitigation: Use library like passport-oauth2
|
||||
- Risk 2: Database migration impact
|
||||
- Mitigation: Rolling deployment strategy
|
||||
```
|
||||
|
||||
**architecture.md**:
|
||||
```markdown
|
||||
# Architecture Design - Version X.Y.Z
|
||||
|
||||
## Component Diagram
|
||||
[Describe relationships between components]
|
||||
|
||||
## Data Model Changes
|
||||
- User table: Add oauth_id, oauth_provider fields
|
||||
- Sessions table: Update token structure
|
||||
- ...
|
||||
|
||||
## API Endpoints
|
||||
- POST /auth/oauth/google - Initiate OAuth
|
||||
- GET /auth/oauth/callback - Handle callback
|
||||
- ...
|
||||
|
||||
## Integration Flow
|
||||
1. User clicks "Login with Google"
|
||||
2. Client redirects to /auth/oauth/google
|
||||
3. Server initiates Google OAuth flow
|
||||
4. ... (complete flow)
|
||||
```
|
||||
|
||||
**plan.json**:
|
||||
```json
|
||||
{
|
||||
"version": "1.0.0",
|
||||
"total_tasks": 8,
|
||||
"estimated_duration": "Medium",
|
||||
"tasks": [
|
||||
{
|
||||
"id": "TASK-001",
|
||||
"title": "Setup OAuth configuration",
|
||||
"description": "Create OAuth app credentials and config",
|
||||
"effort": "small",
|
||||
"estimated_hours": 1,
|
||||
"depends_on": [],
|
||||
"files": ["src/config/oauth.ts"],
|
||||
"success_criteria": "Config loads without errors"
|
||||
},
|
||||
{
|
||||
"id": "TASK-002",
|
||||
"title": "Update User model",
|
||||
"description": "Add oauth_id and oauth_provider fields",
|
||||
"effort": "medium",
|
||||
"estimated_hours": 2,
|
||||
"depends_on": ["TASK-001"],
|
||||
"files": ["src/models/User.ts", "migrations/*"],
|
||||
"success_criteria": "Migration runs successfully"
|
||||
},
|
||||
{
|
||||
"id": "TASK-003",
|
||||
"title": "Implement OAuth strategy",
|
||||
"description": "Add Google OAuth strategy",
|
||||
"effort": "large",
|
||||
"estimated_hours": 4,
|
||||
"depends_on": ["TASK-001"],
|
||||
"files": ["src/strategies/oauth-google.ts"],
|
||||
"success_criteria": "OAuth flow works end-to-end"
|
||||
},
|
||||
{
|
||||
"id": "TASK-004",
|
||||
"title": "Create authentication endpoints",
|
||||
"description": "POST /auth/oauth/google, GET /auth/oauth/callback",
|
||||
"effort": "medium",
|
||||
"estimated_hours": 3,
|
||||
"depends_on": ["TASK-003"],
|
||||
"files": ["src/routes/auth.ts"],
|
||||
"success_criteria": "Endpoints respond correctly"
|
||||
},
|
||||
{
|
||||
"id": "TASK-005",
|
||||
"title": "Add tests for OAuth flow",
|
||||
"description": "Unit and integration tests",
|
||||
"effort": "large",
|
||||
"estimated_hours": 4,
|
||||
"depends_on": ["TASK-004"],
|
||||
"files": ["tests/auth-oauth.test.ts"],
|
||||
"success_criteria": "All tests passing"
|
||||
},
|
||||
{
|
||||
"id": "TASK-006",
|
||||
"title": "Update frontend login",
|
||||
"description": "Add OAuth button to login page",
|
||||
"effort": "small",
|
||||
"estimated_hours": 1,
|
||||
"depends_on": [],
|
||||
"files": ["frontend/components/Login.tsx"],
|
||||
"success_criteria": "Button appears and works"
|
||||
},
|
||||
{
|
||||
"id": "TASK-007",
|
||||
"title": "Documentation",
|
||||
"description": "Update API docs and setup guide",
|
||||
"effort": "medium",
|
||||
"estimated_hours": 2,
|
||||
"depends_on": ["TASK-005"],
|
||||
"files": ["docs/auth.md", "docs/setup.md"],
|
||||
"success_criteria": "Docs are complete and clear"
|
||||
}
|
||||
],
|
||||
"critical_path": ["TASK-001", "TASK-003", "TASK-004", "TASK-005"],
|
||||
"parallel_opportunities": [
|
||||
["TASK-002", "TASK-003"],
|
||||
["TASK-005", "TASK-006"]
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
## Output Format
|
||||
|
||||
```
|
||||
PHASE_RESULT:
|
||||
- phase: ep
|
||||
- status: success | failed | partial
|
||||
- files_written: [exploration.md, architecture.md, plan.json]
|
||||
- summary: Architecture explored, X tasks planned, version X.Y.Z
|
||||
- plan_version: X.Y.Z
|
||||
- task_count: N
|
||||
- critical_path_length: N
|
||||
- issues: []
|
||||
```
|
||||
|
||||
## Interaction with Other Agents
|
||||
|
||||
### Receives From:
|
||||
- **RA (Requirements Analyst)**: "Definitive requirements, version X.Y.Z"
|
||||
- Used to structure plan
|
||||
- **Orchestrator**: "Continue planning with iteration X"
|
||||
- Used to update plan for extensions
|
||||
|
||||
### Sends To:
|
||||
- **CD (Developer)**: "Here's the implementation plan"
|
||||
- Used for feature implementation
|
||||
- **VAS (Validator)**: "Here's what will be implemented"
|
||||
- Used for test strategy generation
|
||||
|
||||
## Best Practices
|
||||
|
||||
1. **Understand Existing Patterns**: Follow codebase conventions
|
||||
2. **Realistic Estimates**: Include buffer for unknowns
|
||||
3. **Clear Dependencies**: Document why tasks depend on each other
|
||||
4. **Risk Identification**: Don't ignore potential issues
|
||||
5. **Integration Guidelines**: Make integration obvious for CD
|
||||
6. **Versioning**: Update version when requirements change
|
||||
@@ -0,0 +1,285 @@
|
||||
---
|
||||
name: Requirements Analyst
|
||||
description: Analyze, refine, and maintain requirements in single file with version control
|
||||
color: blue
|
||||
---
|
||||
|
||||
# Requirements Analyst Agent (RA)
|
||||
|
||||
## Role Definition
|
||||
|
||||
The Requirements Analyst maintains **a single file** (`requirements.md`) containing all requirements, edge cases, and constraints. Each iteration **completely rewrites** the file with new version.
|
||||
|
||||
## Core Responsibilities
|
||||
|
||||
1. **Analyze Task Description**
|
||||
- Parse initial task or extension
|
||||
- Decompose into functional requirements
|
||||
- Identify implicit requirements
|
||||
- Clarify ambiguous statements
|
||||
|
||||
2. **Identify Edge Cases**
|
||||
- Scenario planning
|
||||
- Boundary condition analysis
|
||||
- Error handling requirements
|
||||
- Performance constraints
|
||||
|
||||
3. **Maintain Single Document**
|
||||
- Write complete `requirements.md` each iteration
|
||||
- Include version header with previous summary
|
||||
- Document all FR, NFR, edge cases in one file
|
||||
- Auto-archive old version to `history/`
|
||||
|
||||
4. **Track All Changes**
|
||||
- Append to `changes.log` (NDJSON) for audit trail
|
||||
- Never delete historical data
|
||||
- Version-based change tracking
|
||||
|
||||
## Key Reminders
|
||||
|
||||
**ALWAYS**:
|
||||
- **Complete rewrite** of `requirements.md` each iteration
|
||||
- Archive previous version to `history/requirements-v{version}.md`
|
||||
- Include version header (current + previous summary)
|
||||
- Append all changes to `changes.log` (NDJSON)
|
||||
- Timestamp all actions with ISO8601 format
|
||||
|
||||
**NEVER**:
|
||||
- Maintain incremental history in main document
|
||||
- Delete previous versions manually (auto-archived)
|
||||
- Forget to increment version number
|
||||
- Skip documenting edge cases
|
||||
|
||||
## Execution Process
|
||||
|
||||
### Phase 1: Initial Analysis (v1.0.0)
|
||||
|
||||
1. **Read Context**
|
||||
- Cycle state from `.workflow/.cycle/{cycleId}.json`
|
||||
- Task description from state
|
||||
- Project tech stack and guidelines
|
||||
|
||||
2. **Analyze Requirements**
|
||||
- Functional requirements
|
||||
- Non-functional requirements
|
||||
- Constraints and assumptions
|
||||
- Edge cases
|
||||
|
||||
3. **Generate Single File**
|
||||
- Write `requirements.md` v1.0.0
|
||||
- Include all sections in one document
|
||||
- Add version header
|
||||
- Create initial `changes.log` entry
|
||||
|
||||
### Phase 2: Iteration (v1.1.0, v1.2.0, ...)
|
||||
|
||||
1. **Archive Old Version**
|
||||
- Read current `requirements.md` (v1.0.0)
|
||||
- Copy to `history/requirements-v1.0.0.md`
|
||||
- Extract version and summary
|
||||
|
||||
2. **Analyze Extension**
|
||||
- Read user feedback/extension
|
||||
- Identify new requirements
|
||||
- Update edge cases
|
||||
- Maintain constraints
|
||||
|
||||
3. **Rewrite Complete File**
|
||||
- **Completely overwrite** `requirements.md`
|
||||
- New version: v1.1.0
|
||||
- Include "Previous Version" summary in header
|
||||
- Mark new items with "(NEW v1.1.0)"
|
||||
- Update history summary table
|
||||
|
||||
4. **Append to Changes.log**
|
||||
```json
|
||||
{"timestamp":"2026-01-23T10:00:00+08:00","version":"1.1.0","agent":"ra","action":"update","change":"Added MFA requirement","iteration":2}
|
||||
```
|
||||
|
||||
### Phase 3: Output
|
||||
|
||||
Generate/update two files in `.workflow/.cycle/{cycleId}.progress/ra/`:
|
||||
|
||||
**requirements.md** (COMPLETE REWRITE):
|
||||
```markdown
|
||||
# Requirements Specification - v1.1.0
|
||||
|
||||
## Document Status
|
||||
| Field | Value |
|
||||
|-------|-------|
|
||||
| **Version** | 1.1.0 |
|
||||
| **Previous Version** | 1.0.0 (Initial OAuth requirements) |
|
||||
| **This Version** | Added Google OAuth support |
|
||||
| **Iteration** | 2 |
|
||||
| **Updated** | 2026-01-23T10:00:00+08:00 |
|
||||
|
||||
---
|
||||
|
||||
## Functional Requirements
|
||||
|
||||
### FR-001: OAuth Authentication
|
||||
User can authenticate via OAuth providers.
|
||||
|
||||
**Status**: Implemented (v1.0.0), Enhanced (v1.1.0)
|
||||
|
||||
**Providers**: Google (NEW v1.1.0)
|
||||
|
||||
**Priority**: High
|
||||
|
||||
---
|
||||
|
||||
### FR-002: User Profile Creation
|
||||
System creates user profile on first login.
|
||||
|
||||
**Status**: Defined (v1.0.0)
|
||||
|
||||
**Priority**: Medium
|
||||
|
||||
---
|
||||
|
||||
## Non-Functional Requirements
|
||||
|
||||
### NFR-001: Performance
|
||||
Response time < 500ms for all OAuth flows.
|
||||
|
||||
**Status**: Not tested
|
||||
|
||||
---
|
||||
|
||||
### NFR-002: Scalability
|
||||
Support 1000 concurrent users.
|
||||
|
||||
**Status**: Not tested
|
||||
|
||||
---
|
||||
|
||||
## Edge Cases
|
||||
|
||||
### EC-001: OAuth Timeout
|
||||
**Scenario**: Provider doesn't respond in 5 seconds
|
||||
|
||||
**Expected**: Display error, offer retry
|
||||
|
||||
**Test Strategy**: Mock provider timeout
|
||||
|
||||
**Status**: Defined (v1.0.0)
|
||||
|
||||
---
|
||||
|
||||
### EC-002: Invalid OAuth Credentials (NEW v1.1.0)
|
||||
**Scenario**: User provides invalid credentials
|
||||
|
||||
**Expected**: Clear error message, redirect to login
|
||||
|
||||
**Test Strategy**: Mock invalid credentials
|
||||
|
||||
**Status**: New in v1.1.0
|
||||
|
||||
---
|
||||
|
||||
## Constraints
|
||||
- Must use existing JWT session management
|
||||
- No new database servers
|
||||
- Compatible with existing User table
|
||||
|
||||
---
|
||||
|
||||
## Assumptions
|
||||
- OAuth providers are available 99.9% of time
|
||||
- Users have modern browsers supporting redirects
|
||||
|
||||
---
|
||||
|
||||
## Success Criteria
|
||||
- [ ] All functional requirements implemented
|
||||
- [ ] All NFRs validated
|
||||
- [ ] Test coverage > 80%
|
||||
- [ ] Production deployment successful
|
||||
|
||||
---
|
||||
|
||||
## History Summary
|
||||
| Version | Date | Summary |
|
||||
|---------|------|---------|
|
||||
| 1.0.0 | 2026-01-22 | Initial OAuth requirements |
|
||||
| 1.1.0 | 2026-01-23 | + Google OAuth support (current) |
|
||||
|
||||
**Detailed History**: See `history/` directory and `changes.log`
|
||||
```
|
||||
|
||||
**changes.log** (APPEND ONLY):
|
||||
```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-23T10:00:00+08:00","version":"1.1.0","agent":"ra","action":"update","change":"Added Google OAuth support","iteration":2}
|
||||
```
|
||||
|
||||
## Output Format
|
||||
|
||||
```
|
||||
PHASE_RESULT:
|
||||
- phase: ra
|
||||
- status: success | failed
|
||||
- version: 1.1.0
|
||||
- files_written: [requirements.md, changes.log]
|
||||
- archived: [history/requirements-v1.0.0.md]
|
||||
- summary: Requirements updated to v1.1.0, added Google OAuth support
|
||||
- requirements_count: 2
|
||||
- edge_cases_count: 2
|
||||
- new_items: ["FR-001 enhancement", "EC-002"]
|
||||
```
|
||||
|
||||
## Version Management
|
||||
|
||||
### Version Numbering
|
||||
- **1.0.0**: Initial cycle
|
||||
- **1.x.0**: Each new iteration (minor bump)
|
||||
- **2.0.0**: Complete rewrite (rare, major changes)
|
||||
|
||||
### Archival Process
|
||||
```javascript
|
||||
// Before writing new version
|
||||
if (previousVersionExists) {
|
||||
const oldFile = 'requirements.md'
|
||||
const archiveFile = `history/requirements-v${previousVersion}.md`
|
||||
|
||||
Copy(oldFile, archiveFile) // Auto-archive
|
||||
console.log(`Archived v${previousVersion}`)
|
||||
}
|
||||
|
||||
// Write complete new version
|
||||
Write('requirements.md', newContent) // COMPLETE OVERWRITE
|
||||
|
||||
// Append to audit log
|
||||
appendNDJSON('changes.log', {
|
||||
timestamp: now,
|
||||
version: newVersion,
|
||||
agent: 'ra',
|
||||
action: 'update',
|
||||
change: changeSummary,
|
||||
iteration: currentIteration
|
||||
})
|
||||
```
|
||||
|
||||
## Interaction with Other Agents
|
||||
|
||||
### Sends To
|
||||
- **EP (Explorer)**: "Requirements ready, see requirements.md v1.1.0"
|
||||
- File reference, not full content
|
||||
- **CD (Developer)**: "Requirement FR-X clarified in v1.1.1"
|
||||
- Version-specific reference
|
||||
|
||||
### Receives From
|
||||
- **CD (Developer)**: "FR-002 is unclear, need clarification"
|
||||
- Response: Update requirements.md, bump version
|
||||
- **User**: "Add new requirement FR-003"
|
||||
- Response: Rewrite requirements.md with FR-003
|
||||
|
||||
## Best Practices
|
||||
|
||||
1. **Single Source of Truth**: One file contains everything
|
||||
2. **Complete Rewrites**: Don't maintain incremental diffs
|
||||
3. **Clear Versioning**: Header always shows version
|
||||
4. **Automatic Archival**: Old versions safely stored
|
||||
5. **Audit Trail**: Changes.log tracks every modification
|
||||
6. **Readability First**: File should be clear and concise
|
||||
7. **Version Markers**: Mark new items with "(NEW v1.x.0)"
|
||||
@@ -0,0 +1,381 @@
|
||||
---
|
||||
name: Validation & Archival Agent
|
||||
description: Run tests, validate quality, and create final documentation
|
||||
color: yellow
|
||||
---
|
||||
|
||||
# Validation & Archival Agent (VAS)
|
||||
|
||||
## Role Definition
|
||||
|
||||
The Validation & Archival Agent is responsible for verifying implementation quality, running tests, generating coverage reports, and creating comprehensive archival documentation for the entire cycle.
|
||||
|
||||
## Core Responsibilities
|
||||
|
||||
1. **Test Execution**
|
||||
- Run unit tests
|
||||
- Run integration tests
|
||||
- Generate coverage reports
|
||||
- Track test results
|
||||
|
||||
2. **Quality Validation**
|
||||
- Verify against requirements
|
||||
- Check for edge case handling
|
||||
- Validate performance
|
||||
- Assess security posture
|
||||
|
||||
3. **Documentation Generation**
|
||||
- Create comprehensive summary
|
||||
- Document test results
|
||||
- Generate coverage reports
|
||||
- Create archival records
|
||||
|
||||
4. **Iteration Feedback**
|
||||
- Identify failing tests
|
||||
- Report coverage gaps
|
||||
- Suggest fixes for failures
|
||||
- Flag regression risks
|
||||
|
||||
## Key Reminders
|
||||
|
||||
**ALWAYS**:
|
||||
- Run complete test suite before validating
|
||||
- Generate coverage reports with breakdowns
|
||||
- Document all test results in JSON format
|
||||
- Version all documents and reports
|
||||
- Track which tests failed and why
|
||||
- Generate actionable recommendations
|
||||
- Maintain comprehensive archival records
|
||||
|
||||
**NEVER**:
|
||||
- Skip tests to meet deadlines
|
||||
- Ignore coverage gaps
|
||||
- Delete test results or logs
|
||||
- Mark tests as passing without verification
|
||||
- Forget to document breaking changes
|
||||
- Skip regression testing
|
||||
|
||||
## Execution Process
|
||||
|
||||
### Phase 1: Test Execution
|
||||
|
||||
1. **Read Context**
|
||||
- Code changes from CD agent
|
||||
- Requirements from RA agent
|
||||
- Project tech stack and guidelines
|
||||
|
||||
2. **Prepare Test Environment**
|
||||
- Set up test databases (clean state)
|
||||
- Configure test fixtures
|
||||
- Initialize test data
|
||||
|
||||
3. **Run Test Suites**
|
||||
- Execute unit tests
|
||||
- Execute integration tests
|
||||
- Execute end-to-end tests
|
||||
- Run security tests if applicable
|
||||
|
||||
4. **Collect Results**
|
||||
- Test pass/fail status
|
||||
- Execution time
|
||||
- Error messages and stack traces
|
||||
- Coverage metrics
|
||||
|
||||
### Phase 2: Analysis & Validation
|
||||
|
||||
1. **Analyze Test Results**
|
||||
- Calculate pass rate
|
||||
- Identify failing tests
|
||||
- Categorize failures (bug vs flaky)
|
||||
- Track coverage
|
||||
|
||||
2. **Verify Against Requirements**
|
||||
- Check FR coverage (all implemented?)
|
||||
- Check NFR validation (performance OK?)
|
||||
- Check edge case handling
|
||||
|
||||
3. **Generate Reports**
|
||||
- Coverage analysis by module
|
||||
- Test result summary
|
||||
- Recommendations for fixes
|
||||
- Risk assessment
|
||||
|
||||
### Phase 3: Archival Documentation
|
||||
|
||||
1. **Create Summary**
|
||||
- What was implemented
|
||||
- Quality metrics
|
||||
- Known issues
|
||||
- Recommendations
|
||||
|
||||
2. **Archive Results**
|
||||
- Store test results
|
||||
- Store coverage data
|
||||
- Store execution logs
|
||||
- Store decision records
|
||||
|
||||
### Phase 4: Output
|
||||
|
||||
Generate files in `.workflow/.cycle/{cycleId}.progress/vas/`:
|
||||
|
||||
**validation.md**:
|
||||
```markdown
|
||||
# Validation Report - Version X.Y.Z
|
||||
|
||||
## Executive Summary
|
||||
- Iteration: 1 of 1
|
||||
- Status: PASSED with warnings
|
||||
- Pass Rate: 92% (46/50 tests)
|
||||
- Coverage: 87% (target: 80%)
|
||||
- Issues: 1 critical, 2 medium
|
||||
|
||||
## Test Execution Summary
|
||||
- Total Tests: 50
|
||||
- Passed: 46
|
||||
- Failed: 3
|
||||
- Skipped: 1
|
||||
- Duration: 2m 34s
|
||||
|
||||
### By Category
|
||||
- Unit Tests: 25/25 passed
|
||||
- Integration Tests: 18/20 passed (2 flaky)
|
||||
- End-to-End: 3/5 passed (2 timeout issues)
|
||||
|
||||
## Coverage Report
|
||||
- Overall: 87%
|
||||
- src/strategies/oauth-google.ts: 95%
|
||||
- src/routes/auth.ts: 82%
|
||||
- src/config/oauth.ts: 100%
|
||||
|
||||
## Test Failures
|
||||
### FAILED: OAuth token refresh with expired refresh token
|
||||
- File: tests/oauth-refresh.test.ts
|
||||
- Error: "Refresh token invalid"
|
||||
- Root Cause: Edge case not handled in strategy
|
||||
- Fix Required: Update strategy to handle invalid tokens
|
||||
- Severity: Medium
|
||||
|
||||
### FAILED: Concurrent login attempts
|
||||
- File: tests/concurrent-login.test.ts
|
||||
- Error: "Race condition in session creation"
|
||||
- Root Cause: Concurrent writes to user session
|
||||
- Fix Required: Add mutex/lock for session writes
|
||||
- Severity: Critical
|
||||
|
||||
## Requirements Coverage
|
||||
- ✓ FR-001: User OAuth login (PASSED)
|
||||
- ✓ FR-002: Multiple providers (PASSED - only Google tested)
|
||||
- ⚠ FR-003: Token refresh (PARTIAL - edge cases failing)
|
||||
- ✓ NFR-001: Response time < 500ms (PASSED)
|
||||
- ✓ NFR-002: Handle 100 concurrent users (PASSED)
|
||||
|
||||
## Recommendations
|
||||
1. Fix critical race condition before production
|
||||
2. Improve OAuth refresh token handling
|
||||
3. Add tests for multi-provider scenarios
|
||||
4. Performance test with higher concurrency levels
|
||||
|
||||
## Issues Requiring Attention
|
||||
- [ ] Fix race condition (CRITICAL)
|
||||
- [ ] Handle expired refresh tokens (MEDIUM)
|
||||
- [ ] Test with GitHub provider (MEDIUM)
|
||||
```
|
||||
|
||||
**test-results.json**:
|
||||
```json
|
||||
{
|
||||
"version": "1.0.0",
|
||||
"timestamp": "2026-01-22T12:00:00+08:00",
|
||||
"iteration": 1,
|
||||
"summary": {
|
||||
"total": 50,
|
||||
"passed": 46,
|
||||
"failed": 3,
|
||||
"skipped": 1,
|
||||
"duration_ms": 154000
|
||||
},
|
||||
"by_suite": [
|
||||
{
|
||||
"suite": "OAuth Strategy",
|
||||
"tests": 15,
|
||||
"passed": 14,
|
||||
"failed": 1,
|
||||
"tests": [
|
||||
{
|
||||
"name": "Google OAuth - successful login",
|
||||
"status": "passed",
|
||||
"duration_ms": 245
|
||||
},
|
||||
{
|
||||
"name": "Google OAuth - invalid credentials",
|
||||
"status": "passed",
|
||||
"duration_ms": 198
|
||||
},
|
||||
{
|
||||
"name": "Google OAuth - token refresh with expired token",
|
||||
"status": "failed",
|
||||
"duration_ms": 523,
|
||||
"error": "Refresh token invalid",
|
||||
"stack": "at Strategy.refresh (src/strategies/oauth-google.ts:45)"
|
||||
}
|
||||
]
|
||||
}
|
||||
],
|
||||
"coverage": {
|
||||
"lines": 87,
|
||||
"statements": 89,
|
||||
"functions": 85,
|
||||
"branches": 78,
|
||||
"by_file": [
|
||||
{
|
||||
"file": "src/strategies/oauth-google.ts",
|
||||
"coverage": 95
|
||||
},
|
||||
{
|
||||
"file": "src/routes/auth.ts",
|
||||
"coverage": 82
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**coverage.md**:
|
||||
```markdown
|
||||
# Coverage Report - Version X.Y.Z
|
||||
|
||||
## Overall Coverage: 87%
|
||||
**Target: 80% ✓ PASSED**
|
||||
|
||||
## Breakdown by Module
|
||||
|
||||
| Module | Lines | Functions | Branches | Status |
|
||||
|--------|-------|-----------|----------|--------|
|
||||
| OAuth Strategy | 95% | 93% | 88% | ✓ Excellent |
|
||||
| Auth Routes | 82% | 85% | 75% | ⚠ Acceptable |
|
||||
| OAuth Config | 100% | 100% | 100% | ✓ Perfect |
|
||||
| User Model | 78% | 80% | 70% | ⚠ Needs work |
|
||||
|
||||
## Uncovered Scenarios
|
||||
- Error recovery in edge cases
|
||||
- Multi-provider error handling
|
||||
- Token revocation flow
|
||||
- Concurrent request handling
|
||||
|
||||
## Recommendations for Improvement
|
||||
1. Add tests for provider errors
|
||||
2. Test token revocation edge cases
|
||||
3. Add concurrency tests
|
||||
4. Improve error path coverage
|
||||
```
|
||||
|
||||
**summary.md**:
|
||||
```markdown
|
||||
# Cycle Completion Summary - Version X.Y.Z
|
||||
|
||||
## Cycle Overview
|
||||
- Cycle ID: cycle-v1-20260122-abc123
|
||||
- Task: Implement OAuth authentication
|
||||
- Duration: 2 hours 30 minutes
|
||||
- Iterations: 1
|
||||
|
||||
## Deliverables
|
||||
- ✓ Requirements specification (3 pages)
|
||||
- ✓ Implementation plan (8 tasks)
|
||||
- ✓ Code implementation (1,200 lines)
|
||||
- ✓ Test suite (50 tests, 92% passing)
|
||||
- ✓ Documentation (complete)
|
||||
|
||||
## Quality Metrics
|
||||
| Metric | Value | Target | Status |
|
||||
|--------|-------|--------|--------|
|
||||
| Test Pass Rate | 92% | 90% | ✓ |
|
||||
| Code Coverage | 87% | 80% | ✓ |
|
||||
| Performance | 245ms avg | 500ms | ✓ |
|
||||
| Requirements Met | 3/3 | 100% | ✓ |
|
||||
|
||||
## Known Issues
|
||||
1. **CRITICAL**: Race condition in session writes
|
||||
- Impact: Potential data loss under load
|
||||
- Status: Requires fix before production
|
||||
|
||||
2. **MEDIUM**: Refresh token edge case
|
||||
- Impact: Users may need to re-authenticate
|
||||
- Status: Can be fixed in next iteration
|
||||
|
||||
## Recommended Next Steps
|
||||
1. Fix critical race condition
|
||||
2. Add GitHub provider support
|
||||
3. Performance testing under high load
|
||||
4. Security audit of OAuth flow
|
||||
|
||||
## Files Modified
|
||||
- src/config/oauth.ts (new)
|
||||
- src/strategies/oauth-google.ts (new)
|
||||
- src/routes/auth.ts (modified: +50 lines)
|
||||
- src/models/User.ts (modified: +8 lines)
|
||||
- migrations/* (new: user schema update)
|
||||
- tests/* (new: 50 test cases)
|
||||
|
||||
## Approval Status
|
||||
- Code Review: Pending
|
||||
- Requirements Met: YES
|
||||
- Tests Passing: 46/50 (92%)
|
||||
- **READY FOR**: Code review and fixes
|
||||
|
||||
## Sign-Off
|
||||
- Validation Agent: VAS-001
|
||||
- Timestamp: 2026-01-22T12:00:00+08:00
|
||||
```
|
||||
|
||||
## Output Format
|
||||
|
||||
```
|
||||
PHASE_RESULT:
|
||||
- phase: vas
|
||||
- status: success | failed | partial
|
||||
- files_written: [validation.md, test-results.json, coverage.md, summary.md]
|
||||
- summary: Tests executed, X% pass rate, Y% coverage, Z issues found
|
||||
- test_pass_rate: X%
|
||||
- coverage: Y%
|
||||
- failed_tests: [list]
|
||||
- critical_issues: N
|
||||
- ready_for_production: true | false
|
||||
```
|
||||
|
||||
## Interaction with Other Agents
|
||||
|
||||
### Receives From:
|
||||
- **CD (Code Developer)**: "Here are code changes, ready for testing"
|
||||
- Used for generating test strategy
|
||||
- **RA (Requirements Analyst)**: "Here are success criteria"
|
||||
- Used for validation checks
|
||||
|
||||
### Sends To:
|
||||
- **CD (Developer)**: "These tests are failing, needs fixes"
|
||||
- Used for prioritizing work
|
||||
- **Orchestrator**: "Quality report and recommendations"
|
||||
- Used for final sign-off
|
||||
|
||||
## Quality Standards
|
||||
|
||||
**Minimum Pass Criteria**:
|
||||
- 90% test pass rate
|
||||
- 80% code coverage
|
||||
- All critical requirements implemented
|
||||
- No critical bugs
|
||||
|
||||
**Production Readiness Criteria**:
|
||||
- 95%+ test pass rate
|
||||
- 85%+ code coverage
|
||||
- Security review completed
|
||||
- Performance benchmarks met
|
||||
|
||||
## Best Practices
|
||||
|
||||
1. **Clean Test Environment**: Run tests in isolated environment
|
||||
2. **Consistent Metrics**: Use same tools and metrics across iterations
|
||||
3. **Comprehensive Reporting**: Document all findings clearly
|
||||
4. **Actionable Feedback**: Provide specific fix recommendations
|
||||
5. **Archive Everything**: Keep complete records for future reference
|
||||
6. **Version Control**: Track report versions for audit trail
|
||||
696
.codex/skills/parallel-dev-cycle/phases/orchestrator.md
Normal file
696
.codex/skills/parallel-dev-cycle/phases/orchestrator.md
Normal file
@@ -0,0 +1,696 @@
|
||||
# Orchestrator - Multi-Agent Coordination (Codex Pattern)
|
||||
|
||||
Orchestrate parallel dev cycle using Codex subagent pattern with continuous iteration support.
|
||||
|
||||
## Role
|
||||
|
||||
Coordinate four specialized agents → Manage state → Support continuous iteration → Generate unified documentation.
|
||||
|
||||
## Codex Pattern Overview
|
||||
|
||||
```
|
||||
Main Orchestrator Flow:
|
||||
|
||||
┌─── spawn_agent (orchestrator role) ────────────────────────────┐
|
||||
│ │
|
||||
│ Phase 1: INIT (Check control signals) │
|
||||
│ ↓ │
|
||||
│ wait() → Parse cycle state │
|
||||
│ ↓ │
|
||||
│ Phase 2: AGENT ORCHESTRATION │
|
||||
│ ↓ │
|
||||
│ spawn_agent(RA) | spawn_agent(EP) │
|
||||
│ spawn_agent(CD) | spawn_agent(VAS) │
|
||||
│ ↓ │
|
||||
│ wait({ ids: [RA, EP, CD, VAS] }) → Collect all results │
|
||||
│ ↓ │
|
||||
│ Phase 3: ITERATION HANDLING │
|
||||
│ ↓ │
|
||||
│ [If extension needed] │
|
||||
│ send_input to affected agents │
|
||||
│ wait() for updated results │
|
||||
│ ↓ │
|
||||
│ Phase 4: AGGREGATION │
|
||||
│ ↓ │
|
||||
│ Merge all outputs → Generate unified documentation │
|
||||
│ ↓ │
|
||||
│ Update cycle state │
|
||||
│ ↓ │
|
||||
│ [Loop if more iterations] │
|
||||
│ ↓ │
|
||||
│ close_agent() when complete │
|
||||
│ │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
## State Management
|
||||
|
||||
### Read Cycle State
|
||||
|
||||
```javascript
|
||||
const getUtc8ISOString = () => new Date(Date.now() + 8 * 60 * 60 * 1000).toISOString()
|
||||
|
||||
function readCycleState(cycleId) {
|
||||
const stateFile = `.workflow/.cycle/${cycleId}.json`
|
||||
if (!fs.existsSync(stateFile)) {
|
||||
return null
|
||||
}
|
||||
return JSON.parse(Read(stateFile))
|
||||
}
|
||||
```
|
||||
|
||||
### Create New Cycle State
|
||||
|
||||
```javascript
|
||||
function createCycleState(cycleId, taskDescription) {
|
||||
const stateFile = `.workflow/.cycle/${cycleId}.json`
|
||||
const now = getUtc8ISOString()
|
||||
|
||||
const state = {
|
||||
// Metadata
|
||||
cycle_id: cycleId,
|
||||
title: taskDescription.substring(0, 100),
|
||||
description: taskDescription,
|
||||
max_iterations: 5,
|
||||
status: 'running',
|
||||
created_at: now,
|
||||
updated_at: now,
|
||||
|
||||
// Agent tracking
|
||||
agents: {
|
||||
ra: { status: 'idle', output_files: [] },
|
||||
ep: { status: 'idle', output_files: [] },
|
||||
cd: { status: 'idle', output_files: [] },
|
||||
vas: { status: 'idle', output_files: [] }
|
||||
},
|
||||
|
||||
// Phase tracking
|
||||
current_phase: 'init',
|
||||
completed_phases: [],
|
||||
current_iteration: 0,
|
||||
|
||||
// Shared context (populated by agents)
|
||||
requirements: null,
|
||||
exploration: null,
|
||||
plan: null,
|
||||
changes: [],
|
||||
test_results: null
|
||||
}
|
||||
|
||||
// Create directories
|
||||
mkdir -p `.workflow/.cycle/${cycleId}.progress/{ra,ep,cd,vas,coordination}`
|
||||
|
||||
Write(stateFile, JSON.stringify(state, null, 2))
|
||||
return state
|
||||
}
|
||||
```
|
||||
|
||||
## Main Execution Flow (Codex Subagent)
|
||||
|
||||
```javascript
|
||||
async function runOrchestrator(options = {}) {
|
||||
const { cycleId: existingCycleId, task, mode = 'interactive', extension } = options
|
||||
|
||||
console.log('=== Parallel Dev Cycle Orchestrator Started ===')
|
||||
|
||||
// 1. Determine cycleId and initial state
|
||||
let cycleId
|
||||
let state
|
||||
|
||||
if (existingCycleId) {
|
||||
// Continue existing cycle
|
||||
cycleId = existingCycleId
|
||||
state = readCycleState(cycleId)
|
||||
|
||||
if (!state) {
|
||||
console.error(`Cycle not found: ${cycleId}`)
|
||||
return { status: 'error', message: 'Cycle not found' }
|
||||
}
|
||||
|
||||
console.log(`Resuming cycle: ${cycleId}`)
|
||||
if (extension) {
|
||||
console.log(`Extension: ${extension}`)
|
||||
state.description += `\n\n--- ITERATION ${state.current_iteration + 1} ---\n${extension}`
|
||||
}
|
||||
|
||||
} else if (task) {
|
||||
// Create new cycle
|
||||
const timestamp = getUtc8ISOString().replace(/[-:]/g, '').split('.')[0]
|
||||
const random = Math.random().toString(36).substring(2, 10)
|
||||
cycleId = `cycle-v1-${timestamp}-${random}`
|
||||
|
||||
console.log(`Creating new cycle: ${cycleId}`)
|
||||
state = createCycleState(cycleId, task)
|
||||
|
||||
} else {
|
||||
console.error('Either --cycle-id or task description is required')
|
||||
return { status: 'error', message: 'Missing cycleId or task' }
|
||||
}
|
||||
|
||||
const progressDir = `.workflow/.cycle/${cycleId}.progress`
|
||||
|
||||
// 2. Main orchestration loop
|
||||
let iteration = state.current_iteration || 0
|
||||
const maxIterations = state.max_iterations || 5
|
||||
let continueLoop = true
|
||||
|
||||
while (continueLoop && iteration < maxIterations) {
|
||||
iteration++
|
||||
state.current_iteration = iteration
|
||||
|
||||
console.log(`\n========== ITERATION ${iteration} ==========`)
|
||||
|
||||
// 3. Spawn four agents in parallel
|
||||
console.log('Spawning agents...')
|
||||
|
||||
const agents = {
|
||||
ra: spawnRAAgent(cycleId, state, progressDir),
|
||||
ep: spawnEPAgent(cycleId, state, progressDir),
|
||||
cd: spawnCDAgent(cycleId, state, progressDir),
|
||||
vas: spawnVASAgent(cycleId, state, progressDir)
|
||||
}
|
||||
|
||||
// 4. Wait for all agents to complete
|
||||
console.log('Waiting for all agents...')
|
||||
const results = wait({
|
||||
ids: [agents.ra, agents.ep, agents.cd, agents.vas],
|
||||
timeout_ms: 1800000 // 30 minutes
|
||||
})
|
||||
|
||||
if (results.timed_out) {
|
||||
console.log('Some agents timed out, sending convergence request...')
|
||||
Object.entries(agents).forEach(([name, id]) => {
|
||||
if (!results.status[id].completed) {
|
||||
send_input({
|
||||
id: id,
|
||||
message: `
|
||||
## TIMEOUT NOTIFICATION
|
||||
|
||||
Execution timeout reached. Please:
|
||||
1. Output current progress to markdown file
|
||||
2. Save all state updates
|
||||
3. Return completion status
|
||||
`
|
||||
})
|
||||
}
|
||||
})
|
||||
continue
|
||||
}
|
||||
|
||||
// 5. Collect all agent outputs
|
||||
const agentOutputs = {
|
||||
ra: results.status[agents.ra].completed,
|
||||
ep: results.status[agents.ep].completed,
|
||||
cd: results.status[agents.cd].completed,
|
||||
vas: results.status[agents.vas].completed
|
||||
}
|
||||
|
||||
// 6. Parse and aggregate results
|
||||
const parsedResults = parseAgentOutputs(agentOutputs)
|
||||
|
||||
// Update state with agent results
|
||||
state.agents.ra.status = 'completed'
|
||||
state.agents.ep.status = 'completed'
|
||||
state.agents.cd.status = 'completed'
|
||||
state.agents.vas.status = 'completed'
|
||||
|
||||
state.requirements = parsedResults.ra.requirements
|
||||
state.exploration = parsedResults.ep.exploration
|
||||
state.plan = parsedResults.ep.plan
|
||||
state.changes = parsedResults.cd.changes
|
||||
state.test_results = parsedResults.vas.test_results
|
||||
|
||||
state.completed_phases.push(...['ra', 'ep', 'cd', 'vas'])
|
||||
state.updated_at = getUtc8ISOString()
|
||||
|
||||
// Save state
|
||||
Write(`.workflow/.cycle/${cycleId}.json`, JSON.stringify(state, null, 2))
|
||||
|
||||
// 7. Check for issues and determine next iteration
|
||||
const hasIssues = parsedResults.vas.test_results?.passed === false ||
|
||||
parsedResults.cd.issues?.length > 0
|
||||
|
||||
if (hasIssues && iteration < maxIterations) {
|
||||
console.log('Issues detected, preparing for next iteration...')
|
||||
|
||||
// Generate feedback for agents
|
||||
const feedback = generateFeedback(parsedResults)
|
||||
|
||||
// Send feedback to relevant agents
|
||||
if (feedback.ra) {
|
||||
send_input({
|
||||
id: agents.ra,
|
||||
message: feedback.ra
|
||||
})
|
||||
}
|
||||
|
||||
if (feedback.cd) {
|
||||
send_input({
|
||||
id: agents.cd,
|
||||
message: feedback.cd
|
||||
})
|
||||
}
|
||||
|
||||
// Wait for updates
|
||||
const updatedResults = wait({
|
||||
ids: [agents.ra, agents.cd].filter(Boolean),
|
||||
timeout_ms: 900000
|
||||
})
|
||||
|
||||
console.log('Agents updated, continuing...')
|
||||
|
||||
} else if (!hasIssues) {
|
||||
console.log('All phases completed successfully')
|
||||
continueLoop = false
|
||||
|
||||
} else if (iteration >= maxIterations) {
|
||||
console.log(`Reached maximum iterations (${maxIterations})`)
|
||||
continueLoop = false
|
||||
}
|
||||
}
|
||||
|
||||
// 8. Generate unified summary
|
||||
console.log('Generating final summary...')
|
||||
generateFinalSummary(cycleId, state)
|
||||
|
||||
// 9. Update final state
|
||||
state.status = 'completed'
|
||||
state.completed_at = getUtc8ISOString()
|
||||
Write(`.workflow/.cycle/${cycleId}.json`, JSON.stringify(state, null, 2))
|
||||
|
||||
// 10. Cleanup
|
||||
Object.values(agents).forEach(id => {
|
||||
try {
|
||||
close_agent({ id })
|
||||
} catch (e) {
|
||||
console.warn(`Failed to close agent ${id}`)
|
||||
}
|
||||
})
|
||||
|
||||
console.log('\n=== Parallel Dev Cycle Orchestrator Finished ===')
|
||||
|
||||
return {
|
||||
status: 'completed',
|
||||
cycle_id: cycleId,
|
||||
iterations: iteration,
|
||||
final_state: state
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Agent Spawning Functions
|
||||
|
||||
### Spawn RA Agent
|
||||
|
||||
```javascript
|
||||
function spawnRAAgent(cycleId, state, progressDir) {
|
||||
return spawn_agent({
|
||||
message: `
|
||||
## TASK ASSIGNMENT
|
||||
|
||||
### MANDATORY FIRST STEPS (Agent Execute)
|
||||
1. **Read role definition**: ~/.codex/agents/requirements-analyst.md
|
||||
2. Read: .workflow/project-tech.json (if exists)
|
||||
3. Read: .workflow/project-guidelines.json (if exists)
|
||||
4. Read: .workflow/.cycle/${cycleId}.progress/coordination/feedback.md (if exists)
|
||||
|
||||
---
|
||||
|
||||
## CYCLE CONTEXT
|
||||
|
||||
- **Cycle ID**: ${cycleId}
|
||||
- **Progress Dir**: ${progressDir}/ra/
|
||||
- **Current Iteration**: ${state.current_iteration}
|
||||
- **Task Description**: ${state.description}
|
||||
|
||||
## CURRENT REQUIREMENTS STATE
|
||||
|
||||
${state.requirements ? JSON.stringify(state.requirements, null, 2) : 'No previous requirements'}
|
||||
|
||||
## YOUR ROLE
|
||||
|
||||
Requirements Analyst - Analyze and refine requirements throughout the cycle.
|
||||
|
||||
## RESPONSIBILITIES
|
||||
|
||||
1. Analyze initial task description
|
||||
2. Generate comprehensive requirements specification
|
||||
3. Identify edge cases and implicit requirements
|
||||
4. Track requirement changes across iterations
|
||||
5. Maintain requirements.md and changes.log
|
||||
|
||||
## DELIVERABLES
|
||||
|
||||
Write files to ${progressDir}/ra/:
|
||||
- requirements.md: Full requirements specification
|
||||
- edge-cases.md: Edge case analysis
|
||||
- changes.log: NDJSON format change tracking
|
||||
|
||||
## OUTPUT FORMAT
|
||||
|
||||
\`\`\`
|
||||
PHASE_RESULT:
|
||||
- phase: ra
|
||||
- status: success | failed
|
||||
- files_written: [list]
|
||||
- summary: one-line summary
|
||||
- issues: []
|
||||
\`\`\`
|
||||
`
|
||||
})
|
||||
}
|
||||
```
|
||||
|
||||
### Spawn EP Agent
|
||||
|
||||
```javascript
|
||||
function spawnEPAgent(cycleId, state, progressDir) {
|
||||
return spawn_agent({
|
||||
message: `
|
||||
## TASK ASSIGNMENT
|
||||
|
||||
### MANDATORY FIRST STEPS (Agent Execute)
|
||||
1. **Read role definition**: ~/.codex/agents/exploration-planner.md
|
||||
2. Read: .workflow/project-tech.json
|
||||
3. Read: .workflow/project-guidelines.json
|
||||
4. Read: ${progressDir}/ra/requirements.md
|
||||
|
||||
---
|
||||
|
||||
## CYCLE CONTEXT
|
||||
|
||||
- **Cycle ID**: ${cycleId}
|
||||
- **Progress Dir**: ${progressDir}/ep/
|
||||
- **Requirements**: See requirements.md
|
||||
- **Current Plan**: ${state.plan ? 'Existing' : 'None - first iteration'}
|
||||
|
||||
## YOUR ROLE
|
||||
|
||||
Exploration & Planning Agent - Explore architecture and generate implementation plan.
|
||||
|
||||
## RESPONSIBILITIES
|
||||
|
||||
1. Explore codebase architecture
|
||||
2. Map integration points
|
||||
3. Design implementation approach
|
||||
4. Generate plan.json with task breakdown
|
||||
5. Update or iterate on existing plan
|
||||
|
||||
## DELIVERABLES
|
||||
|
||||
Write files to ${progressDir}/ep/:
|
||||
- exploration.md: Codebase exploration findings
|
||||
- architecture.md: Architecture design
|
||||
- plan.json: Implementation plan (structured)
|
||||
|
||||
## OUTPUT FORMAT
|
||||
|
||||
\`\`\`
|
||||
PHASE_RESULT:
|
||||
- phase: ep
|
||||
- status: success | failed
|
||||
- files_written: [list]
|
||||
- summary: one-line summary
|
||||
- plan_version: X.Y.Z
|
||||
\`\`\`
|
||||
`
|
||||
})
|
||||
}
|
||||
```
|
||||
|
||||
### Spawn CD Agent
|
||||
|
||||
```javascript
|
||||
function spawnCDAgent(cycleId, state, progressDir) {
|
||||
return spawn_agent({
|
||||
message: `
|
||||
## TASK ASSIGNMENT
|
||||
|
||||
### MANDATORY FIRST STEPS (Agent Execute)
|
||||
1. **Read role definition**: ~/.codex/agents/code-developer.md
|
||||
2. Read: ${progressDir}/ep/plan.json
|
||||
3. Read: ${progressDir}/ra/requirements.md
|
||||
|
||||
---
|
||||
|
||||
## CYCLE CONTEXT
|
||||
|
||||
- **Cycle ID**: ${cycleId}
|
||||
- **Progress Dir**: ${progressDir}/cd/
|
||||
- **Plan Version**: ${state.plan?.version || 'N/A'}
|
||||
- **Previous Changes**: ${state.changes?.length || 0} files
|
||||
|
||||
## YOUR ROLE
|
||||
|
||||
Code Developer - Implement features based on plan and requirements.
|
||||
|
||||
## RESPONSIBILITIES
|
||||
|
||||
1. Implement features from plan
|
||||
2. Track code changes
|
||||
3. Handle integration issues
|
||||
4. Maintain code quality
|
||||
5. Report implementation progress and issues
|
||||
|
||||
## DELIVERABLES
|
||||
|
||||
Write files to ${progressDir}/cd/:
|
||||
- implementation.md: Implementation progress and decisions
|
||||
- code-changes.log: NDJSON format, each line: {file, action, timestamp}
|
||||
- issues.md: Development issues and blockers
|
||||
|
||||
## OUTPUT FORMAT
|
||||
|
||||
\`\`\`
|
||||
PHASE_RESULT:
|
||||
- phase: cd
|
||||
- status: success | failed | partial
|
||||
- files_changed: [count]
|
||||
- summary: one-line summary
|
||||
- blockers: []
|
||||
\`\`\`
|
||||
`
|
||||
})
|
||||
}
|
||||
```
|
||||
|
||||
### Spawn VAS Agent
|
||||
|
||||
```javascript
|
||||
function spawnVASAgent(cycleId, state, progressDir) {
|
||||
return spawn_agent({
|
||||
message: `
|
||||
## TASK ASSIGNMENT
|
||||
|
||||
### MANDATORY FIRST STEPS (Agent Execute)
|
||||
1. **Read role definition**: ~/.codex/agents/validation-archivist.md
|
||||
2. Read: ${progressDir}/cd/code-changes.log
|
||||
|
||||
---
|
||||
|
||||
## CYCLE CONTEXT
|
||||
|
||||
- **Cycle ID**: ${cycleId}
|
||||
- **Progress Dir**: ${progressDir}/vas/
|
||||
- **Changes Count**: ${state.changes?.length || 0}
|
||||
- **Iteration**: ${state.current_iteration}
|
||||
|
||||
## YOUR ROLE
|
||||
|
||||
Validation & Archival Specialist - Validate quality and create documentation.
|
||||
|
||||
## RESPONSIBILITIES
|
||||
|
||||
1. Run tests on implemented features
|
||||
2. Generate coverage reports
|
||||
3. Create archival documentation
|
||||
4. Summarize cycle results
|
||||
5. Generate version history
|
||||
|
||||
## DELIVERABLES
|
||||
|
||||
Write files to ${progressDir}/vas/:
|
||||
- validation.md: Test validation results
|
||||
- test-results.json: Detailed test results
|
||||
- coverage.md: Coverage report
|
||||
- summary.md: Cycle summary and recommendations
|
||||
|
||||
## OUTPUT FORMAT
|
||||
|
||||
\`\`\`
|
||||
PHASE_RESULT:
|
||||
- phase: vas
|
||||
- status: success | failed
|
||||
- test_pass_rate: X%
|
||||
- coverage: X%
|
||||
- issues: []
|
||||
\`\`\`
|
||||
`
|
||||
})
|
||||
}
|
||||
```
|
||||
|
||||
## Result Parsing
|
||||
|
||||
```javascript
|
||||
function parseAgentOutputs(agentOutputs) {
|
||||
const results = {
|
||||
ra: parseOutput(agentOutputs.ra, 'ra'),
|
||||
ep: parseOutput(agentOutputs.ep, 'ep'),
|
||||
cd: parseOutput(agentOutputs.cd, 'cd'),
|
||||
vas: parseOutput(agentOutputs.vas, 'vas')
|
||||
}
|
||||
return results
|
||||
}
|
||||
|
||||
function parseOutput(output, agent) {
|
||||
const result = {
|
||||
agent: agent,
|
||||
status: 'unknown',
|
||||
data: {}
|
||||
}
|
||||
|
||||
// Parse PHASE_RESULT block
|
||||
const match = output.match(/PHASE_RESULT:\s*([\s\S]*?)(?:\n\n|$)/)
|
||||
if (match) {
|
||||
const lines = match[1].split('\n')
|
||||
for (const line of lines) {
|
||||
const m = line.match(/^-\s*(\w+):\s*(.+)$/)
|
||||
if (m) {
|
||||
result[m[1]] = m[2].trim()
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
return result
|
||||
}
|
||||
```
|
||||
|
||||
## Feedback Generation
|
||||
|
||||
```javascript
|
||||
function generateFeedback(parsedResults) {
|
||||
const feedback = {}
|
||||
|
||||
// Check VAS results
|
||||
if (parsedResults.vas.test_pass_rate < 100) {
|
||||
feedback.cd = `
|
||||
## FEEDBACK FROM VALIDATION
|
||||
|
||||
Test pass rate: ${parsedResults.vas.test_pass_rate}%
|
||||
|
||||
## ISSUES TO FIX
|
||||
|
||||
${parsedResults.vas.data.issues || 'See test-results.json for details'}
|
||||
|
||||
## NEXT STEP
|
||||
|
||||
Fix failing tests and update implementation.md with resolution.
|
||||
`
|
||||
}
|
||||
|
||||
// Check CD blockers
|
||||
if (parsedResults.cd.blockers?.length > 0) {
|
||||
feedback.ra = `
|
||||
## FEEDBACK FROM DEVELOPMENT
|
||||
|
||||
Blockers encountered:
|
||||
${parsedResults.cd.blockers.map(b => `- ${b}`).join('\n')}
|
||||
|
||||
## NEXT STEP
|
||||
|
||||
Clarify requirements or identify alternative approaches.
|
||||
Update requirements.md if needed.
|
||||
`
|
||||
}
|
||||
|
||||
return feedback
|
||||
}
|
||||
```
|
||||
|
||||
## Summary Generation
|
||||
|
||||
```javascript
|
||||
function generateFinalSummary(cycleId, state) {
|
||||
const summaryFile = `.workflow/.cycle/${cycleId}.progress/coordination/summary.md`
|
||||
|
||||
const summary = `# Cycle Summary - ${cycleId}
|
||||
|
||||
## Metadata
|
||||
- Cycle ID: ${cycleId}
|
||||
- Started: ${state.created_at}
|
||||
- Completed: ${state.completed_at}
|
||||
- Iterations: ${state.current_iteration}
|
||||
- Status: ${state.status}
|
||||
|
||||
## Phase Results
|
||||
- Requirements Analysis: ✓ Completed
|
||||
- Exploration & Planning: ✓ Completed
|
||||
- Code Development: ✓ Completed
|
||||
- Validation & Archival: ✓ Completed
|
||||
|
||||
## Key Deliverables
|
||||
- Requirements: ${state.requirements ? '✓' : '✗'}
|
||||
- Architecture Plan: ${state.plan ? '✓' : '✗'}
|
||||
- Code Changes: ${state.changes?.length || 0} files
|
||||
- Test Results: ${state.test_results?.pass_rate || '0'}% passing
|
||||
|
||||
## Generated Files
|
||||
- .workflow/.cycle/${cycleId}.progress/ra/requirements.md
|
||||
- .workflow/.cycle/${cycleId}.progress/ep/plan.json
|
||||
- .workflow/.cycle/${cycleId}.progress/cd/code-changes.log
|
||||
- .workflow/.cycle/${cycleId}.progress/vas/summary.md
|
||||
|
||||
## Continuation Instructions
|
||||
|
||||
To extend this cycle:
|
||||
|
||||
\`\`\`bash
|
||||
/parallel-dev-cycle --cycle-id=${cycleId} --extend="New requirement or feedback"
|
||||
\`\`\`
|
||||
|
||||
This will spawn agents for iteration ${state.current_iteration + 1}.
|
||||
`
|
||||
|
||||
Write(summaryFile, summary)
|
||||
}
|
||||
```
|
||||
|
||||
## Control Signal Checking
|
||||
|
||||
```javascript
|
||||
function checkControlSignals(cycleId) {
|
||||
const state = readCycleState(cycleId)
|
||||
|
||||
switch (state?.status) {
|
||||
case 'paused':
|
||||
return { continue: false, action: 'pause_exit' }
|
||||
case 'failed':
|
||||
return { continue: false, action: 'stop_exit' }
|
||||
case 'running':
|
||||
return { continue: true, action: 'continue' }
|
||||
default:
|
||||
return { continue: false, action: 'stop_exit' }
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Error Recovery Strategies
|
||||
|
||||
| Error Type | Recovery |
|
||||
|------------|----------|
|
||||
| Agent timeout | send_input requesting convergence |
|
||||
| State corrupted | Rebuild from progress markdown files |
|
||||
| Agent failed | Re-spawn agent with previous context |
|
||||
| Conflicting results | Orchestrator sends reconciliation request |
|
||||
| Missing files | RA/EP agents identify and request clarification |
|
||||
|
||||
## Codex Best Practices Applied
|
||||
|
||||
1. **Single Orchestrator**: One main agent manages all phases
|
||||
2. **Parallel Workers**: Four specialized agents execute simultaneously
|
||||
3. **Batch wait()**: Wait for all agents with `wait({ ids: [...] })`
|
||||
4. **Deep Interaction**: Use send_input for iteration and refinement
|
||||
5. **Delayed close_agent**: Only after all phases and iterations complete
|
||||
6. **Role Path Passing**: Each agent reads its own role definition
|
||||
7. **Persistent Context**: Cycle state shared across all agents
|
||||
436
.codex/skills/parallel-dev-cycle/phases/state-schema.md
Normal file
436
.codex/skills/parallel-dev-cycle/phases/state-schema.md
Normal file
@@ -0,0 +1,436 @@
|
||||
# State Schema - Parallel Dev Cycle
|
||||
|
||||
Unified cycle state structure for multi-agent coordination and iteration support.
|
||||
|
||||
## State File Location
|
||||
|
||||
**Location**: `.workflow/.cycle/{cycleId}.json` (unified state, all agents access)
|
||||
|
||||
**Format**: JSON
|
||||
|
||||
## Cycle State Interface
|
||||
|
||||
```typescript
|
||||
interface CycleState {
|
||||
// =====================================================
|
||||
// CORE METADATA
|
||||
// =====================================================
|
||||
|
||||
cycle_id: string // Unique cycle identifier
|
||||
title: string // Task title (first 100 chars)
|
||||
description: string // Full task description
|
||||
task_history: string[] // All task descriptions across iterations
|
||||
|
||||
// =====================================================
|
||||
// STATUS & TIMING
|
||||
// =====================================================
|
||||
|
||||
status: 'created' | 'running' | 'paused' | 'completed' | 'failed'
|
||||
created_at: string // ISO8601 format
|
||||
updated_at: string // ISO8601 format
|
||||
completed_at?: string // ISO8601 format
|
||||
|
||||
max_iterations: number // Maximum iteration limit
|
||||
current_iteration: number // Current iteration count
|
||||
failure_reason?: string // If failed, why
|
||||
|
||||
// =====================================================
|
||||
// MULTI-AGENT TRACKING
|
||||
// =====================================================
|
||||
|
||||
agents: {
|
||||
ra: AgentState // Requirements Analyst
|
||||
ep: AgentState // Exploration Planner
|
||||
cd: AgentState // Code Developer
|
||||
vas: AgentState // Validation Archivist
|
||||
}
|
||||
|
||||
// =====================================================
|
||||
// PHASE TRACKING
|
||||
// =====================================================
|
||||
|
||||
current_phase: 'init' | 'ra' | 'ep' | 'cd' | 'vas' | 'aggregation' | 'complete'
|
||||
completed_phases: string[]
|
||||
phase_errors: Array<{
|
||||
phase: string
|
||||
error: string
|
||||
timestamp: string
|
||||
}>
|
||||
|
||||
// =====================================================
|
||||
// SHARED CONTEXT (Populated by agents)
|
||||
// =====================================================
|
||||
|
||||
requirements?: {
|
||||
version: string // e.g., "1.0.0", "1.1.0"
|
||||
specification: string // Full spec from requirements.md
|
||||
edge_cases: string[]
|
||||
last_updated: string
|
||||
}
|
||||
|
||||
exploration?: {
|
||||
version: string
|
||||
architecture_summary: string
|
||||
integration_points: string[]
|
||||
identified_risks: string[]
|
||||
last_updated: string
|
||||
}
|
||||
|
||||
plan?: {
|
||||
version: string
|
||||
tasks: PlanTask[]
|
||||
total_estimated_effort: string
|
||||
critical_path: string[]
|
||||
last_updated: string
|
||||
}
|
||||
|
||||
changes?: {
|
||||
total_files: number
|
||||
changes: ChangeLog[]
|
||||
iteration_markers: Record<number, string> // Iteration timestamps
|
||||
}
|
||||
|
||||
test_results?: {
|
||||
version: string
|
||||
pass_rate: number // 0-100
|
||||
coverage: number // 0-100
|
||||
failed_tests: string[]
|
||||
total_tests: number
|
||||
last_run: string
|
||||
}
|
||||
|
||||
// =====================================================
|
||||
// ITERATION TRACKING
|
||||
// =====================================================
|
||||
|
||||
iterations: IterationRecord[]
|
||||
|
||||
// =====================================================
|
||||
// COORDINATION DATA
|
||||
// =====================================================
|
||||
|
||||
coordination: {
|
||||
feedback_log: FeedbackEntry[]
|
||||
pending_decisions: Decision[]
|
||||
blockers: Blocker[]
|
||||
}
|
||||
}
|
||||
|
||||
// =====================================================
|
||||
// SUPPORTING TYPES
|
||||
// =====================================================
|
||||
|
||||
interface AgentState {
|
||||
status: 'idle' | 'running' | 'waiting' | 'completed' | 'failed'
|
||||
started_at?: string
|
||||
completed_at?: string
|
||||
output_files: string[]
|
||||
last_message?: string
|
||||
error?: string
|
||||
iterations_completed: number
|
||||
}
|
||||
|
||||
interface PlanTask {
|
||||
id: string // e.g., "TASK-001"
|
||||
description: string
|
||||
effort: 'small' | 'medium' | 'large'
|
||||
depends_on: string[]
|
||||
status: 'pending' | 'in_progress' | 'completed' | 'blocked'
|
||||
assigned_to?: string // Agent name
|
||||
files: string[]
|
||||
}
|
||||
|
||||
interface ChangeLog {
|
||||
timestamp: string
|
||||
file: string
|
||||
action: 'create' | 'modify' | 'delete'
|
||||
iteration: number
|
||||
agent: string // which agent made change
|
||||
description: string
|
||||
}
|
||||
|
||||
interface IterationRecord {
|
||||
number: number
|
||||
extension?: string // User feedback/extension for this iteration
|
||||
started_at: string
|
||||
completed_at: string
|
||||
agent_results: Record<string, {
|
||||
status: string
|
||||
files_modified: number
|
||||
}>
|
||||
issues_found: string[]
|
||||
resolved: boolean
|
||||
}
|
||||
|
||||
interface FeedbackEntry {
|
||||
timestamp: string
|
||||
source: string // Agent or 'user'
|
||||
target: string // Recipient agent
|
||||
content: string
|
||||
type: 'requirement_update' | 'bug_report' | 'issue_fix' | 'clarification'
|
||||
}
|
||||
|
||||
interface Decision {
|
||||
id: string
|
||||
description: string
|
||||
options: string[]
|
||||
made_by?: string
|
||||
chosen_option?: string
|
||||
status: 'pending' | 'made' | 'implemented'
|
||||
}
|
||||
|
||||
interface Blocker {
|
||||
id: string
|
||||
description: string
|
||||
reported_by: string
|
||||
status: 'open' | 'resolved' | 'workaround'
|
||||
resolution?: string
|
||||
}
|
||||
```
|
||||
|
||||
## Initial State (New Cycle)
|
||||
|
||||
When creating a new cycle:
|
||||
|
||||
```json
|
||||
{
|
||||
"cycle_id": "cycle-v1-20260122T100000-abc123",
|
||||
"title": "Implement OAuth authentication",
|
||||
"description": "Add OAuth2 login support with Google and GitHub providers",
|
||||
"task_history": [
|
||||
"Implement OAuth authentication"
|
||||
],
|
||||
"status": "created",
|
||||
"created_at": "2026-01-22T10:00:00+08:00",
|
||||
"updated_at": "2026-01-22T10:00:00+08:00",
|
||||
"max_iterations": 5,
|
||||
"current_iteration": 0,
|
||||
"agents": {
|
||||
"ra": { "status": "idle", "output_files": [], "iterations_completed": 0 },
|
||||
"ep": { "status": "idle", "output_files": [], "iterations_completed": 0 },
|
||||
"cd": { "status": "idle", "output_files": [], "iterations_completed": 0 },
|
||||
"vas": { "status": "idle", "output_files": [], "iterations_completed": 0 }
|
||||
},
|
||||
"current_phase": "init",
|
||||
"completed_phases": [],
|
||||
"phase_errors": [],
|
||||
"iterations": [],
|
||||
"coordination": {
|
||||
"feedback_log": [],
|
||||
"pending_decisions": [],
|
||||
"blockers": []
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## State Transitions
|
||||
|
||||
### Iteration 1: Initial Execution
|
||||
|
||||
```json
|
||||
{
|
||||
"status": "running",
|
||||
"current_iteration": 1,
|
||||
"current_phase": "ra",
|
||||
"agents": {
|
||||
"ra": { "status": "running", "started_at": "2026-01-22T10:05:00+08:00" },
|
||||
"ep": { "status": "idle" },
|
||||
"cd": { "status": "idle" },
|
||||
"vas": { "status": "idle" }
|
||||
},
|
||||
"requirements": {
|
||||
"version": "1.0.0",
|
||||
"specification": "...",
|
||||
"edge_cases": ["OAuth timeout handling", "PKCE validation"],
|
||||
"last_updated": "2026-01-22T10:15:00+08:00"
|
||||
},
|
||||
"iterations": [{
|
||||
"number": 1,
|
||||
"started_at": "2026-01-22T10:00:00+08:00",
|
||||
"agent_results": {
|
||||
"ra": { "status": "completed", "files_modified": 3 },
|
||||
"ep": { "status": "completed", "files_modified": 2 },
|
||||
"cd": { "status": "partial", "files_modified": 5 },
|
||||
"vas": { "status": "pending", "files_modified": 0 }
|
||||
}
|
||||
}]
|
||||
}
|
||||
```
|
||||
|
||||
### After Phase Completion
|
||||
|
||||
```json
|
||||
{
|
||||
"current_phase": "aggregation",
|
||||
"completed_phases": ["ra", "ep", "cd", "vas"],
|
||||
"plan": {
|
||||
"version": "1.0.0",
|
||||
"tasks": [
|
||||
{
|
||||
"id": "TASK-001",
|
||||
"description": "Setup OAuth application credentials",
|
||||
"effort": "small",
|
||||
"status": "completed",
|
||||
"files": ["src/config/oauth.ts"]
|
||||
}
|
||||
]
|
||||
},
|
||||
"changes": {
|
||||
"total_files": 12,
|
||||
"iteration_markers": {
|
||||
"1": "2026-01-22T10:30:00+08:00"
|
||||
}
|
||||
},
|
||||
"test_results": {
|
||||
"version": "1.0.0",
|
||||
"pass_rate": 85,
|
||||
"coverage": 78,
|
||||
"failed_tests": ["test: OAuth timeout retry"],
|
||||
"total_tests": 20
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Iteration 2: User Extension
|
||||
|
||||
User provides feedback: "Also add multi-factor authentication"
|
||||
|
||||
```json
|
||||
{
|
||||
"status": "running",
|
||||
"current_iteration": 2,
|
||||
"task_history": [
|
||||
"Implement OAuth authentication",
|
||||
"Also add multi-factor authentication"
|
||||
],
|
||||
"description": "Add OAuth2 login support with Google and GitHub providers\n\n--- ITERATION 2 ---\nAlso add multi-factor authentication",
|
||||
"agents": {
|
||||
"ra": { "status": "running", "iterations_completed": 1 },
|
||||
"ep": { "status": "idle", "iterations_completed": 1 },
|
||||
"cd": { "status": "idle", "iterations_completed": 1 },
|
||||
"vas": { "status": "idle", "iterations_completed": 1 }
|
||||
},
|
||||
"requirements": {
|
||||
"version": "1.1.0",
|
||||
"specification": "...",
|
||||
"last_updated": "2026-01-22T11:00:00+08:00"
|
||||
},
|
||||
"iterations": [
|
||||
{ "number": 1, "completed_at": "..." },
|
||||
{
|
||||
"number": 2,
|
||||
"extension": "Also add multi-factor authentication",
|
||||
"started_at": "2026-01-22T10:45:00+08:00",
|
||||
"agent_results": {}
|
||||
}
|
||||
],
|
||||
"coordination": {
|
||||
"feedback_log": [{
|
||||
"timestamp": "2026-01-22T10:45:00+08:00",
|
||||
"source": "user",
|
||||
"target": "ra",
|
||||
"content": "Add multi-factor authentication to requirements",
|
||||
"type": "requirement_update"
|
||||
}]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Version Tracking
|
||||
|
||||
Each component tracks its version:
|
||||
|
||||
- **Requirements**: `1.0.0` → `1.1.0` → `1.2.0` (each iteration)
|
||||
- **Plan**: `1.0.0` → `1.1.0` (updated based on requirements)
|
||||
- **Code**: Changes appended with iteration markers
|
||||
- **Tests**: Results tracked per iteration
|
||||
|
||||
## File Sync Protocol
|
||||
|
||||
State changes trigger file writes:
|
||||
|
||||
| State Change | File Sync |
|
||||
|--------------|-----------|
|
||||
| `requirements` updated | `.progress/ra/requirements.md` + version bump |
|
||||
| `plan` updated | `.progress/ep/plan.json` + version bump |
|
||||
| `changes` appended | `.progress/cd/code-changes.log` + iteration marker |
|
||||
| `test_results` updated | `.progress/vas/test-results.json` + version bump |
|
||||
| Full iteration done | `.progress/coordination/timeline.md` appended |
|
||||
|
||||
## Control Signal Checking
|
||||
|
||||
Agents check status before each action:
|
||||
|
||||
```javascript
|
||||
function checkControlSignals(cycleId) {
|
||||
const state = JSON.parse(Read(`.workflow/.cycle/${cycleId}.json`))
|
||||
|
||||
if (state.status === 'paused') {
|
||||
return { continue: false, action: 'pause' }
|
||||
}
|
||||
if (state.status === 'failed') {
|
||||
return { continue: false, action: 'stop' }
|
||||
}
|
||||
if (state.status === 'running') {
|
||||
return { continue: true, action: 'continue' }
|
||||
}
|
||||
|
||||
return { continue: false, action: 'unknown' }
|
||||
}
|
||||
```
|
||||
|
||||
## State Persistence
|
||||
|
||||
### Write Operations
|
||||
|
||||
After each agent completes or phase transitions:
|
||||
|
||||
```javascript
|
||||
Write(
|
||||
`.workflow/.cycle/${cycleId}.json`,
|
||||
JSON.stringify(state, null, 2)
|
||||
)
|
||||
```
|
||||
|
||||
### Read Operations
|
||||
|
||||
Agents always read fresh state before executing:
|
||||
|
||||
```javascript
|
||||
const currentState = JSON.parse(
|
||||
Read(`.workflow/.cycle/${cycleId}.json`)
|
||||
)
|
||||
```
|
||||
|
||||
## State Rebuild (Recovery)
|
||||
|
||||
If master state corrupted, rebuild from markdown files:
|
||||
|
||||
```javascript
|
||||
function rebuildState(cycleId) {
|
||||
const progressDir = `.workflow/.cycle/${cycleId}.progress`
|
||||
|
||||
// Read markdown files
|
||||
const raMarkdown = Read(`${progressDir}/ra/requirements.md`)
|
||||
const epMarkdown = Read(`${progressDir}/ep/plan.json`)
|
||||
const cdChanges = Read(`${progressDir}/cd/code-changes.log`)
|
||||
const vasResults = Read(`${progressDir}/vas/test-results.json`)
|
||||
|
||||
// Reconstruct state from files
|
||||
return {
|
||||
requirements: parseMarkdown(raMarkdown),
|
||||
plan: JSON.parse(epMarkdown),
|
||||
changes: parseNDJSON(cdChanges),
|
||||
test_results: JSON.parse(vasResults)
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Best Practices
|
||||
|
||||
1. **Immutable Reads**: Never modify state during read
|
||||
2. **Version Bumps**: Increment version on each iteration
|
||||
3. **Timestamp Accuracy**: Use UTC+8 consistently
|
||||
4. **Append-Only Logs**: Never delete history
|
||||
5. **Atomic Writes**: Write complete state, not partial updates
|
||||
6. **Coordination Tracking**: Log all inter-agent communication
|
||||
@@ -0,0 +1,423 @@
|
||||
# Agent Communication Optimization
|
||||
|
||||
优化 agent 通信机制：使用简短的产出文件引用而不是内容传递。
|
||||
|
||||
## 背景
|
||||
|
||||
在多 agent 系统中，传递完整的文件内容会导致：
|
||||
- 消息体积过大
|
||||
- 上下文使用量增加
|
||||
- 通信效率低下
|
||||
- 容易引入上下文断层
|
||||
|
||||
**优化方案**: 使用文件路径引用，让 agent 自动读取需要的文件。
|
||||
|
||||
## 优化原则
|
||||
|
||||
### 原则 1: 文件引用而非内容传递
|
||||
|
||||
❌ **错误做法**（传递内容）:
|
||||
```javascript
|
||||
send_input({
|
||||
id: agents.cd,
|
||||
message: `
|
||||
Requirements:
|
||||
${requirements_content} // 完整内容 - 浪费空间
|
||||
|
||||
Plan:
|
||||
${plan_json} // 完整 JSON - 重复信息
|
||||
`
|
||||
})
|
||||
```
|
||||
|
||||
✅ **正确做法**（引用文件）:
|
||||
```javascript
|
||||
send_input({
|
||||
id: agents.cd,
|
||||
message: `
|
||||
## Feedback from Validation
|
||||
|
||||
Test failures found. Review these outputs:
|
||||
|
||||
## Reference
|
||||
- Requirements: .workflow/.cycle/${cycleId}.progress/ra/requirements.md (v1.0.0)
|
||||
- Plan: .workflow/.cycle/${cycleId}.progress/ep/plan.json (v1.0.0)
|
||||
- Test Results: .workflow/.cycle/${cycleId}.progress/vas/test-results.json
|
||||
|
||||
## Issues Found
|
||||
${summary_of_issues} // 只传递摘要
|
||||
|
||||
## Actions Required
|
||||
1. Fix OAuth token refresh (test line 45)
|
||||
2. Update implementation.md with fixes
|
||||
`
|
||||
})
|
||||
```
|
||||
|
||||
### 原则 2: 摘要而非全文
|
||||
|
||||
❌ **错误**：
|
||||
```javascript
|
||||
// 传递所有文件内容
|
||||
RA输出: "requirements.md (2000 lines) + edge-cases.md (1000 lines) + changes.log (500 lines)"
|
||||
|
||||
EP读取: 全文解析所有内容（浪费token）
|
||||
```
|
||||
|
||||
✅ **正确**：
|
||||
```javascript
|
||||
// 只传递关键摘要
|
||||
RA输出:
|
||||
- 10个功能需求
|
||||
- 5个非功能需求
|
||||
- 8个边界场景
|
||||
- 文件路径用于完整查看
|
||||
|
||||
EP读取: 读取摘要 + 需要时查看完整文件（高效）
|
||||
```
|
||||
|
||||
### 原则 3: 文件版本跟踪
|
||||
|
||||
每个引用必须包含版本:
|
||||
|
||||
```javascript
|
||||
send_input({
|
||||
id: agents.cd,
|
||||
message: `
|
||||
Requirements: .workflow/.cycle/${cycleId}.progress/ra/requirements.md (v1.1.0)
|
||||
^^^^^^^ 版本号
|
||||
|
||||
Plan: .workflow/.cycle/${cycleId}.progress/ep/plan.json (v1.0.0)
|
||||
^^^^^^^ 版本号
|
||||
`
|
||||
})
|
||||
```
|
||||
|
||||
**好处**:
|
||||
- 避免使用过期信息
|
||||
- 自动检测版本不匹配
|
||||
- 支持多版本迭代
|
||||
|
||||
## 实现模式
|
||||
|
||||
### Pattern 1: 通知 + 引用
|
||||
|
||||
Agent 向其他 agent 通知输出，而非传递内容：
|
||||
|
||||
```javascript
|
||||
// RA 输出摘要
|
||||
const raSummary = {
|
||||
requirements_count: 10,
|
||||
edge_cases_count: 8,
|
||||
version: "1.0.0",
|
||||
output_file: ".workflow/.cycle/${cycleId}.progress/ra/requirements.md",
|
||||
key_requirements: [
|
||||
"FR-001: OAuth authentication",
|
||||
"FR-002: Multi-provider support",
|
||||
"..." // 只列出标题，不传递完整内容
|
||||
]
|
||||
}
|
||||
|
||||
// 更新状态，让其他 agent 读取
|
||||
state.requirements = {
|
||||
version: raSummary.version,
|
||||
output_file: raSummary.output_file,
|
||||
summary: raSummary.key_requirements
|
||||
}
|
||||
|
||||
// EP agent 从状态读取
|
||||
const requiredDetails = state.requirements
|
||||
const outputFile = requiredDetails.output_file
|
||||
const requirements = JSON.parse(Read(outputFile)) // EP 自己读取完整文件
|
||||
```
|
||||
|
||||
### Pattern 2: 反馈通知
|
||||
|
||||
Orchestrator 发送反馈时只传递摘要和行号：
|
||||
|
||||
```javascript
|
||||
// ❌ 错误：传递完整测试结果
|
||||
send_input({
|
||||
id: agents.cd,
|
||||
message: `
|
||||
Test Results:
|
||||
${entire_test_results_json} // 完整 JSON - 太大
|
||||
`
|
||||
})
|
||||
|
||||
// ✅ 正确：引用文件 + 问题摘要
|
||||
send_input({
|
||||
id: agents.cd,
|
||||
message: `
|
||||
## Test Failures
|
||||
|
||||
Full results: .workflow/.cycle/${cycleId}.progress/vas/test-results.json (v1.0.0)
|
||||
|
||||
## Quick Summary
|
||||
- Failed: oauth-refresh (line 45, expected token refresh)
|
||||
- Failed: concurrent-login (line 78, race condition)
|
||||
|
||||
## Fix Instructions
|
||||
1. Review test cases at referenced lines
|
||||
2. Fix implementation
|
||||
3. Re-run tests
|
||||
4. Update implementation.md
|
||||
|
||||
Reference previous file paths if you need full details.
|
||||
`
|
||||
})
|
||||
```
|
||||
|
||||
### Pattern 3: 依赖链路
|
||||
|
||||
Agent 通过文件引用获取依赖：
|
||||
|
||||
```javascript
|
||||
// EP agent: 从状态读取 RA 输出路径
|
||||
const raOutputPath = state.requirements?.output_file
|
||||
if (raOutputPath && exists(raOutputPath)) {
|
||||
const requirements = Read(raOutputPath)
|
||||
// 使用 requirements 生成计划
|
||||
}
|
||||
|
||||
// CD agent: 从状态读取 EP 输出路径
|
||||
const epPlanPath = state.plan?.output_file
|
||||
if (epPlanPath && exists(epPlanPath)) {
|
||||
const plan = JSON.parse(Read(epPlanPath))
|
||||
// 根据 plan 实现功能
|
||||
}
|
||||
|
||||
// VAS agent: 从状态读取 CD 输出路径
|
||||
const cdChangesPath = state.changes?.output_file
|
||||
if (cdChangesPath && exists(cdChangesPath)) {
|
||||
const changes = readNDJSON(cdChangesPath)
|
||||
// 根据 changes 生成测试
|
||||
}
|
||||
```
|
||||
|
||||
## 状态文件引用结构
|
||||
|
||||
优化后的状态文件应该包含文件路径而不是内容：
|
||||
|
||||
```json
|
||||
{
|
||||
"cycle_id": "cycle-v1-20260122-abc123",
|
||||
|
||||
"requirements": {
|
||||
"version": "1.0.0",
|
||||
"output_files": {
|
||||
"specification": ".workflow/.cycle/cycle-v1-20260122-abc123.progress/ra/requirements.md",
|
||||
"edge_cases": ".workflow/.cycle/cycle-v1-20260122-abc123.progress/ra/edge-cases.md",
|
||||
"changes_log": ".workflow/.cycle/cycle-v1-20260122-abc123.progress/ra/changes.log"
|
||||
},
|
||||
"summary": {
|
||||
"functional_requirements": 10,
|
||||
"edge_cases": 8,
|
||||
"constraints": 5
|
||||
}
|
||||
},
|
||||
|
||||
"exploration": {
|
||||
"version": "1.0.0",
|
||||
"output_files": {
|
||||
"exploration": ".workflow/.cycle/cycle-v1-20260122-abc123.progress/ep/exploration.md",
|
||||
"architecture": ".workflow/.cycle/cycle-v1-20260122-abc123.progress/ep/architecture.md"
|
||||
},
|
||||
"summary": {
|
||||
"key_components": ["Auth Module", "User Service"],
|
||||
"integration_points": 5,
|
||||
"identified_risks": 3
|
||||
}
|
||||
},
|
||||
|
||||
"plan": {
|
||||
"version": "1.0.0",
|
||||
"output_file": ".workflow/.cycle/cycle-v1-20260122-abc123.progress/ep/plan.json",
|
||||
"summary": {
|
||||
"total_tasks": 8,
|
||||
"critical_path": ["TASK-001", "TASK-003", "TASK-004"],
|
||||
"estimated_hours": 16
|
||||
}
|
||||
},
|
||||
|
||||
"implementation": {
|
||||
"version": "1.0.0",
|
||||
"output_files": {
|
||||
"progress": ".workflow/.cycle/cycle-v1-20260122-abc123.progress/cd/implementation.md",
|
||||
"changes": ".workflow/.cycle/cycle-v1-20260122-abc123.progress/cd/code-changes.log",
|
||||
"issues": ".workflow/.cycle/cycle-v1-20260122-abc123.progress/cd/issues.md"
|
||||
},
|
||||
"summary": {
|
||||
"tasks_completed": 3,
|
||||
"files_modified": 5,
|
||||
"blockers": 0
|
||||
}
|
||||
},
|
||||
|
||||
"validation": {
|
||||
"version": "1.0.0",
|
||||
"output_files": {
|
||||
"validation": ".workflow/.cycle/cycle-v1-20260122-abc123.progress/vas/validation.md",
|
||||
"test_results": ".workflow/.cycle/cycle-v1-20260122-abc123.progress/vas/test-results.json",
|
||||
"coverage": ".workflow/.cycle/cycle-v1-20260122-abc123.progress/vas/coverage.md"
|
||||
},
|
||||
"summary": {
|
||||
"pass_rate": 92,
|
||||
"coverage": 87,
|
||||
"failures": 4
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Agent 通信模板优化
|
||||
|
||||
### 优化前: 完整内容传递
|
||||
|
||||
```javascript
|
||||
send_input({
|
||||
id: agents.cd,
|
||||
message: `
|
||||
## Requirements (Complete Content)
|
||||
|
||||
${fs.readFileSync(requirementsFile, 'utf8')} // 2000+ lines
|
||||
|
||||
## Plan (Complete JSON)
|
||||
|
||||
${fs.readFileSync(planFile, 'utf8')} // 1000+ lines
|
||||
|
||||
## Test Results (Complete)
|
||||
|
||||
${fs.readFileSync(testResultsFile, 'utf8')} // 500+ lines
|
||||
|
||||
## Your Task
|
||||
|
||||
Fix the implementation...
|
||||
` // 总消息体: 4000+ 行
|
||||
})
|
||||
```
|
||||
|
||||
### 优化后: 文件引用 + 摘要
|
||||
|
||||
```javascript
|
||||
send_input({
|
||||
id: agents.cd,
|
||||
message: `
|
||||
## Test Failures - Action Required
|
||||
|
||||
Full Test Report: .workflow/.cycle/${cycleId}.progress/vas/test-results.json (v1.0.0)
|
||||
|
||||
## Summary of Failures
|
||||
- oauth-refresh: Expected token refresh, got error (test line 45)
|
||||
- concurrent-login: Race condition in session writes (test line 78)
|
||||
|
||||
## Implementation Reference
|
||||
- Current Code: .workflow/.cycle/${cycleId}.progress/cd/implementation.md (v1.0.0)
|
||||
- Code Changes: .workflow/.cycle/${cycleId}.progress/cd/code-changes.log (v1.0.0)
|
||||
|
||||
## Action Required
|
||||
1. Review failing tests in referenced test results file
|
||||
2. Fix root causes (race condition, token handling)
|
||||
3. Update implementation.md with fixes
|
||||
4. Re-run tests
|
||||
|
||||
## Context
|
||||
- Requirement: .workflow/.cycle/${cycleId}.progress/ra/requirements.md (v1.0.0)
|
||||
- Plan: .workflow/.cycle/${cycleId}.progress/ep/plan.json (v1.0.0)
|
||||
|
||||
Output PHASE_RESULT when complete.
|
||||
` // 总消息体: <500 行，高效传递
|
||||
})
|
||||
```
|
||||
|
||||
## 版本控制最佳实践
|
||||
|
||||
### 版本不匹配检测
|
||||
|
||||
```javascript
|
||||
function validateVersionConsistency(state) {
|
||||
const versions = {
|
||||
ra: state.requirements?.version,
|
||||
ep: state.plan?.version,
|
||||
cd: state.implementation?.version,
|
||||
vas: state.validation?.version
|
||||
}
|
||||
|
||||
// 检查版本一致性
|
||||
const allVersions = Object.values(versions).filter(v => v)
|
||||
const unique = new Set(allVersions)
|
||||
|
||||
if (unique.size > 1) {
|
||||
console.warn('Version mismatch detected:')
|
||||
console.warn(versions)
|
||||
// 返回版本差异，让 orchestrator 决定是否继续
|
||||
}
|
||||
|
||||
return unique.size === 1
|
||||
}
|
||||
```
|
||||
|
||||
### 文件存在性检查
|
||||
|
||||
```javascript
|
||||
function validateReferences(state, cycleId) {
|
||||
const checks = []
|
||||
|
||||
// 检查所有引用的文件是否存在
|
||||
for (const [agent, data] of Object.entries(state)) {
|
||||
if (data?.output_files) {
|
||||
for (const [name, path] of Object.entries(data.output_files)) {
|
||||
if (!fs.existsSync(path)) {
|
||||
checks.push({
|
||||
agent: agent,
|
||||
file: name,
|
||||
path: path,
|
||||
status: 'missing'
|
||||
})
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
return checks
|
||||
}
|
||||
```
|
||||
|
||||
## 好处总结
|
||||
|
||||
| 方面 | 改进 |
|
||||
|------|------|
|
||||
| 消息体积 | 减少 80-90% |
|
||||
| Token 使用 | 减少 60-70% |
|
||||
| 读取速度 | 无需解析冗余内容 |
|
||||
| 版本控制 | 清晰的版本跟踪 |
|
||||
| 上下文清晰 | 不会混淆版本 |
|
||||
| 可维护性 | 文件变更不需要修改消息 |
|
||||
|
||||
## 迁移建议
|
||||
|
||||
### 第一步: 更新状态结构
|
||||
|
||||
```json
|
||||
// 从这样:
|
||||
"requirements": "完整内容"
|
||||
|
||||
// 改为这样:
|
||||
"requirements": {
|
||||
"version": "1.0.0",
|
||||
"output_file": "path/to/file",
|
||||
"summary": {...}
|
||||
}
|
||||
```
|
||||
|
||||
### 第二步: 更新通信模板
|
||||
|
||||
所有 `send_input` 消息改为引用路径。
|
||||
|
||||
### 第三步: Agent 自动读取
|
||||
|
||||
Agent 从引用路径自动读取所需文件。
|
||||
|
||||
### 第四步: 测试版本检测
|
||||
|
||||
确保版本不匹配时有警告。
|
||||
391
.codex/skills/parallel-dev-cycle/specs/coordination-protocol.md
Normal file
391
.codex/skills/parallel-dev-cycle/specs/coordination-protocol.md
Normal file
@@ -0,0 +1,391 @@
|
||||
# Coordination Protocol - Multi-Agent Communication
|
||||
|
||||
Inter-agent communication protocols and patterns for parallel-dev-cycle skill.
|
||||
|
||||
## Overview
|
||||
|
||||
The coordination protocol enables four parallel agents (RA, EP, CD, VAS) to communicate efficiently while maintaining clear responsibilities and avoiding conflicts.
|
||||
|
||||
## Communication Channels
|
||||
|
||||
### 1. Shared State File (Primary)
|
||||
|
||||
**Location**: `.workflow/.cycle/{cycleId}.json`
|
||||
|
||||
All agents read from and write to the unified state file:
|
||||
|
||||
```javascript
|
||||
// Every agent: Read fresh state at action start
|
||||
const state = JSON.parse(Read(`.workflow/.cycle/${cycleId}.json`))
|
||||
|
||||
// Every agent: Write updated state at action end
|
||||
Write(`.workflow/.cycle/${cycleId}.json`, JSON.stringify(state, null, 2))
|
||||
```
|
||||
|
||||
**Protocol**:
|
||||
- Read-Update-Write pattern (no lock needed, orchestrator serializes)
|
||||
- Timestamp all updates with ISO8601 format
|
||||
- Never delete existing data, only append
|
||||
|
||||
### 2. Progress Markdown Files (Async Log)
|
||||
|
||||
**Location**: `.workflow/.cycle/{cycleId}.progress/{agent}/`
|
||||
|
||||
Each agent writes progress to dedicated markdown files:
|
||||
|
||||
| Agent | Files |
|
||||
|-------|-------|
|
||||
| RA | requirements.md, edge-cases.md, changes.log |
|
||||
| EP | exploration.md, architecture.md, plan.json |
|
||||
| CD | implementation.md, code-changes.log, issues.md |
|
||||
| VAS | validation.md, test-results.json, coverage.md, summary.md |
|
||||
|
||||
**Protocol**:
|
||||
- Append-only pattern (no overwrites)
|
||||
- Version each document independently
|
||||
- Include timestamp on each update
|
||||
- Maintain backward compatibility
|
||||
|
||||
### 3. Orchestrator send_input (Synchronous)
|
||||
|
||||
**When**: Orchestrator needs to send feedback or corrections
|
||||
|
||||
```javascript
|
||||
// Example: CD agent receives test failure feedback
|
||||
send_input({
|
||||
id: agents.cd,
|
||||
message: `
|
||||
## FEEDBACK FROM VALIDATION
|
||||
|
||||
Test failures detected: ${failures}
|
||||
|
||||
## REQUIRED ACTION
|
||||
|
||||
Fix the following:
|
||||
${actionItems}
|
||||
|
||||
## NEXT STEP
|
||||
Update implementation.md with fixes, then re-run tests.
|
||||
Output PHASE_RESULT when complete.
|
||||
`
|
||||
})
|
||||
```
|
||||
|
||||
**Protocol**:
|
||||
- Only orchestrator initiates send_input
|
||||
- Clear action items and expected output
|
||||
- Single message per iteration (no rapid-fire sends)
|
||||
|
||||
### 4. Coordination Log
|
||||
|
||||
**Location**: `.workflow/.cycle/{cycleId}.progress/coordination/`
|
||||
|
||||
Centralized log for inter-agent decisions and communication:
|
||||
|
||||
**feedback.md**:
|
||||
```markdown
|
||||
# Feedback & Coordination Log - Version X.Y.Z
|
||||
|
||||
## Timeline
|
||||
- [10:00:00] Orchestrator: Created cycle
|
||||
- [10:05:00] RA: Requirements analysis started
|
||||
- [10:10:00] RA: Requirements completed, v1.0.0
|
||||
- [10:10:01] EP: Starting exploration (depends on RA output)
|
||||
- [10:15:00] EP: Architecture designed, plan.json v1.0.0
|
||||
- [10:15:01] CD: Starting implementation (depends on EP plan)
|
||||
- [10:30:00] CD: Implementation progressing, found blocker
|
||||
- [10:31:00] RA: Clarified requirement after CD blocker
|
||||
- [10:31:01] CD: Continuing with clarification
|
||||
- [10:40:00] CD: Implementation complete
|
||||
- [10:40:01] VAS: Starting validation
|
||||
- [10:45:00] VAS: Testing complete, found failures
|
||||
- [10:45:01] Orchestrator: Sending feedback to CD
|
||||
- [10:46:00] CD: Fixed issues
|
||||
- [10:50:00] VAS: Re-validation, all passing
|
||||
- [10:50:01] Orchestrator: Cycle complete
|
||||
|
||||
## Decision Records
|
||||
- [10:31:00] RA Clarification: OAuth optional vs required?
|
||||
- Decision: Optional (can use password)
|
||||
- Rationale: More flexible for users
|
||||
- Impact: Affects FR-003 implementation
|
||||
|
||||
## Blockers & Resolutions
|
||||
- [10:30:00] Blocker: Database migration for existing users
|
||||
- Reported by: CD
|
||||
- Resolution: Set oauth_id = null for existing users
|
||||
- Status: Resolved
|
||||
|
||||
## Cross-Agent Dependencies
|
||||
- EP depends on: RA requirements (v1.0.0)
|
||||
- CD depends on: EP plan (v1.0.0)
|
||||
- VAS depends on: CD code changes
|
||||
```
|
||||
|
||||
## Message Formats
|
||||
|
||||
### Agent Status Update
|
||||
|
||||
Each agent updates state with its status:
|
||||
|
||||
```json
|
||||
{
|
||||
"agents": {
|
||||
"ra": {
|
||||
"status": "completed",
|
||||
"started_at": "2026-01-22T10:05:00+08:00",
|
||||
"completed_at": "2026-01-22T10:15:00+08:00",
|
||||
"output_files": [
|
||||
".workflow/.cycle/cycle-xxx.progress/ra/requirements.md",
|
||||
".workflow/.cycle/cycle-xxx.progress/ra/edge-cases.md",
|
||||
".workflow/.cycle/cycle-xxx.progress/ra/changes.log"
|
||||
],
|
||||
"iterations_completed": 1
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Feedback Message Format
|
||||
|
||||
When orchestrator sends feedback via send_input:
|
||||
|
||||
```text
|
||||
## FEEDBACK FROM [Agent Name]
|
||||
|
||||
[Summary of findings or issues]
|
||||
|
||||
## REFERENCED OUTPUT
|
||||
File: [path to agent output]
|
||||
Version: [X.Y.Z]
|
||||
|
||||
## REQUIRED ACTION
|
||||
|
||||
1. [Action 1 with specific details]
|
||||
2. [Action 2 with specific details]
|
||||
|
||||
## SUCCESS CRITERIA
|
||||
|
||||
- [ ] Item 1
|
||||
- [ ] Item 2
|
||||
|
||||
## NEXT STEP
|
||||
[What agent should do next]
|
||||
Output PHASE_RESULT when complete.
|
||||
|
||||
## CONTEXT
|
||||
|
||||
Previous iteration: [N]
|
||||
Current iteration: [N+1]
|
||||
```
|
||||
|
||||
### Phase Result Format
|
||||
|
||||
Every agent outputs PHASE_RESULT:
|
||||
|
||||
```text
|
||||
PHASE_RESULT:
|
||||
- phase: [ra|ep|cd|vas]
|
||||
- status: success | failed | partial
|
||||
- files_written: [list of files]
|
||||
- summary: [one-line summary]
|
||||
- [agent-specific fields]
|
||||
- issues: [list of issues if any]
|
||||
|
||||
PHASE_DETAILS:
|
||||
[Additional details or metrics]
|
||||
```
|
||||
|
||||
## Dependency Resolution
|
||||
|
||||
### Build Order (Default)
|
||||
|
||||
```
|
||||
RA (Requirements) → EP (Planning) → CD (Development) → VAS (Validation)
|
||||
↓ ↓ ↓ ↓
|
||||
Block EP Block CD Block VAS Block completion
|
||||
```
|
||||
|
||||
### Parallel Opportunities
|
||||
|
||||
Some phases can run in parallel:
|
||||
|
||||
```
|
||||
RA + FrontendCode (independent)
|
||||
EP + RA (not blocking)
|
||||
CD.Task1 + CD.Task2 (if no dependencies)
|
||||
```
|
||||
|
||||
### Dependency Tracking
|
||||
|
||||
State file tracks dependencies:
|
||||
|
||||
```json
|
||||
{
|
||||
"agents": {
|
||||
"ep": {
|
||||
"depends_on": ["ra"],
|
||||
"ready": true, // RA completed
|
||||
"can_start": true
|
||||
},
|
||||
"cd": {
|
||||
"depends_on": ["ep"],
|
||||
"ready": true, // EP completed
|
||||
"can_start": true
|
||||
},
|
||||
"vas": {
|
||||
"depends_on": ["cd"],
|
||||
"ready": false, // CD not yet complete
|
||||
"can_start": false
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Iteration Flow with Communication
|
||||
|
||||
### Iteration 1: Initial Execution
|
||||
|
||||
```
|
||||
Time Agent Action State Update
|
||||
──────────────────────────────────────────────────────
|
||||
10:00 Init Create cycle status: running
|
||||
10:05 RA Start analysis agents.ra.status: running
|
||||
10:10 RA Complete (v1.0.0) agents.ra.status: completed
|
||||
10:10 EP Start planning agents.ep.status: running
|
||||
(depends on RA completion)
|
||||
10:15 EP Complete (v1.0.0) agents.ep.status: completed
|
||||
10:15 CD Start development agents.cd.status: running
|
||||
(depends on EP completion)
|
||||
10:30 CD Found blocker coordination.blockers.add()
|
||||
10:31 RA Clarify blocker requirements.v1.1.0 created
|
||||
10:35 CD Continue (with fix) agents.cd.status: running
|
||||
10:40 CD Complete agents.cd.status: completed
|
||||
10:40 VAS Start validation agents.vas.status: running
|
||||
(depends on CD completion)
|
||||
10:45 VAS Tests failing coordination.feedback_log.add()
|
||||
10:45 Orch Send feedback agents.cd.message: "Fix these tests"
|
||||
10:46 CD Resume (send_input) agents.cd.status: running
|
||||
10:48 CD Fix complete agents.cd.status: completed
|
||||
10:50 VAS Re-validate agents.vas.status: running
|
||||
10:55 VAS All pass agents.vas.status: completed
|
||||
11:00 Orch Complete cycle status: completed
|
||||
```
|
||||
|
||||
## Conflict Resolution
|
||||
|
||||
### Conflict Type 1: Unclear Requirement
|
||||
|
||||
**Scenario**: CD needs clarification on FR-X
|
||||
|
||||
**Resolution Flow**:
|
||||
1. CD reports blocker in issues.md
|
||||
2. Orchestrator extracts blocker
|
||||
3. Orchestrator sends message to RA
|
||||
4. RA updates requirements with clarification
|
||||
5. RA outputs new requirements.md (v1.1.0)
|
||||
6. Orchestrator sends message to CD with clarification
|
||||
7. CD resumes and continues
|
||||
|
||||
### Conflict Type 2: Test Failure
|
||||
|
||||
**Scenario**: VAS finds test failures
|
||||
|
||||
**Resolution Flow**:
|
||||
1. VAS reports failures in validation.md
|
||||
2. VAS outputs test-results.json with details
|
||||
3. Orchestrator extracts failure details
|
||||
4. Orchestrator categorizes failures
|
||||
5. If blocker: Orchestrator sends to CD/RA for fixes
|
||||
6. CD/RA fix and report completion
|
||||
7. Orchestrator sends CD/VAS to retry
|
||||
8. VAS re-validates
|
||||
|
||||
### Conflict Type 3: Plan Mismatch
|
||||
|
||||
**Scenario**: CD realizes plan tasks are incomplete
|
||||
|
||||
**Resolution Flow**:
|
||||
1. CD reports in issues.md
|
||||
2. Orchestrator extracts issue
|
||||
3. Orchestrator sends to EP to revise plan
|
||||
4. EP updates plan.json (v1.1.0)
|
||||
5. EP adds new tasks or dependencies
|
||||
6. Orchestrator sends to CD with updated plan
|
||||
7. CD implements remaining tasks
|
||||
|
||||
## Escalation Path
|
||||
|
||||
For issues that block resolution:
|
||||
|
||||
```
|
||||
Agent Issue
|
||||
↓
|
||||
Agent reports blocker
|
||||
↓
|
||||
Orchestrator analyzes
|
||||
↓
|
||||
Can fix automatically?
|
||||
├─ Yes: send_input to agent with fix
|
||||
└─ No: Escalate to user
|
||||
↓
|
||||
User provides guidance
|
||||
↓
|
||||
Orchestrator applies guidance
|
||||
↓
|
||||
Resume agents
|
||||
```
|
||||
|
||||
## Communication Best Practices
|
||||
|
||||
1. **Clear Timestamps**: All events timestamped ISO8601 format
|
||||
2. **Structured Messages**: Use consistent format for feedback
|
||||
3. **Version Tracking**: Always include version numbers
|
||||
4. **Audit Trail**: Maintain complete log of decisions
|
||||
5. **No Direct Agent Communication**: All communication via orchestrator
|
||||
6. **Document Decisions**: Record why decisions were made
|
||||
7. **Append-Only Logs**: Never delete history
|
||||
|
||||
## State Consistency Rules
|
||||
|
||||
1. **Single Writer Per Field**: Only one agent updates each field
|
||||
- RA writes: requirements, edge_cases
|
||||
- EP writes: exploration, plan
|
||||
- CD writes: changes, implementation
|
||||
- VAS writes: test_results, summary
|
||||
|
||||
2. **Read-Write Serialization**: Orchestrator ensures no conflicts
|
||||
|
||||
3. **Version Synchronization**: All versions increment together
|
||||
- v1.0.0 → v1.1.0 (all docs updated)
|
||||
|
||||
4. **Timestamp Consistency**: All timestamps in state file UTC+8
|
||||
|
||||
## Monitoring & Debugging
|
||||
|
||||
### State Inspection
|
||||
|
||||
```javascript
|
||||
// Check agent status
|
||||
const state = JSON.parse(Read(`.workflow/.cycle/${cycleId}.json`))
|
||||
console.log(state.agents) // See status of all agents
|
||||
|
||||
// Check for blockers
|
||||
console.log(state.coordination.blockers)
|
||||
|
||||
// Check feedback history
|
||||
console.log(state.coordination.feedback_log)
|
||||
```
|
||||
|
||||
### Log Analysis
|
||||
|
||||
```bash
|
||||
# Check RA progress
|
||||
tail .workflow/.cycle/cycle-xxx.progress/ra/changes.log
|
||||
|
||||
# Check CD changes
|
||||
grep "TASK-001" .workflow/.cycle/cycle-xxx.progress/cd/code-changes.log
|
||||
|
||||
# Check coordination timeline
|
||||
tail -50 .workflow/.cycle/cycle-xxx.progress/coordination/feedback.md
|
||||
```
|
||||
330
.codex/skills/parallel-dev-cycle/specs/versioning-strategy.md
Normal file
330
.codex/skills/parallel-dev-cycle/specs/versioning-strategy.md
Normal file
@@ -0,0 +1,330 @@
|
||||
# Document Versioning Strategy
|
||||
|
||||
文档版本管理策略：重新创建 vs 增量更新
|
||||
|
||||
## 推荐方案：重新创建 + 归档历史
|
||||
|
||||
每次迭代，**完全重写**主文档，旧版本自动归档到 `history/` 目录。
|
||||
|
||||
### 文件结构
|
||||
|
||||
```
|
||||
.workflow/.cycle/cycle-v1-20260122-abc123.progress/
|
||||
├── ra/
|
||||
│ ├── requirements.md # v1.2.0 (当前版本，重新创建)
|
||||
│ ├── edge-cases.md # v1.2.0 (当前版本，重新创建)
|
||||
│ ├── changes.log # NDJSON 完整变更历史（append-only）
|
||||
│ └── history/
|
||||
│ ├── requirements-v1.0.0.md (归档)
|
||||
│ ├── requirements-v1.1.0.md (归档)
|
||||
│ ├── edge-cases-v1.0.0.md (归档)
|
||||
│ └── edge-cases-v1.1.0.md (归档)
|
||||
├── ep/
|
||||
│ ├── exploration.md # v1.2.0 (当前)
|
||||
│ ├── architecture.md # v1.2.0 (当前)
|
||||
│ ├── plan.json # v1.2.0 (当前)
|
||||
│ └── history/
|
||||
│ ├── plan-v1.0.0.json
|
||||
│ └── plan-v1.1.0.json
|
||||
├── cd/
|
||||
│ ├── implementation.md # v1.2.0 (当前)
|
||||
│ ├── code-changes.log # NDJSON 完整历史
|
||||
│ ├── issues.md # 当前未解决问题
|
||||
│ └── history/
|
||||
│ ├── implementation-v1.0.0.md
|
||||
│ └── implementation-v1.1.0.md
|
||||
└── vas/
|
||||
├── validation.md # v1.2.0 (当前)
|
||||
├── test-results.json # v1.2.0 (当前)
|
||||
├── summary.md # v1.2.0 (当前)
|
||||
└── history/
|
||||
├── validation-v1.0.0.md
|
||||
└── test-results-v1.0.0.json
|
||||
```
|
||||
|
||||
## 文档模板优化
|
||||
|
||||
### Requirements.md (重新创建版本)
|
||||
|
||||
```markdown
|
||||
# Requirements Specification - v1.2.0
|
||||
|
||||
## Document Metadata
|
||||
| Field | Value |
|
||||
|-------|-------|
|
||||
| Version | 1.2.0 |
|
||||
| Previous | 1.1.0 (Added Google OAuth) |
|
||||
| Changes | Added MFA, GitHub provider |
|
||||
| Date | 2026-01-23T10:00:00+08:00 |
|
||||
| Cycle | cycle-v1-20260122-abc123 |
|
||||
| Iteration | 3 |
|
||||
|
||||
---
|
||||
|
||||
## Functional Requirements
|
||||
|
||||
### FR-001: OAuth Authentication
|
||||
**Description**: Users can log in using OAuth providers.
|
||||
|
||||
**Supported Providers**: Google, GitHub
|
||||
|
||||
**Priority**: High
|
||||
|
||||
**Status**: ✓ Implemented (v1.0.0), Enhanced (v1.1.0, v1.2.0)
|
||||
|
||||
**Success Criteria**:
|
||||
- User can click provider button
|
||||
- Redirect to provider
|
||||
- Return with valid token
|
||||
- Session created
|
||||
|
||||
---
|
||||
|
||||
### FR-002: Multi-Provider Support
|
||||
**Description**: System supports multiple OAuth providers simultaneously.
|
||||
|
||||
**Providers**:
|
||||
- Google (v1.1.0)
|
||||
- GitHub (v1.2.0)
|
||||
|
||||
**Priority**: High
|
||||
|
||||
**Status**: ✓ Implemented
|
||||
|
||||
---
|
||||
|
||||
### FR-003: Multi-Factor Authentication
|
||||
**Description**: Optional MFA for enhanced security.
|
||||
|
||||
**Method**: TOTP (Time-based One-Time Password)
|
||||
|
||||
**Priority**: Medium
|
||||
|
||||
**Status**: 🆕 New in v1.2.0
|
||||
|
||||
**Success Criteria**:
|
||||
- User can enable MFA in settings
|
||||
- TOTP QR code generated
|
||||
- Verification on login
|
||||
|
||||
---
|
||||
|
||||
## Non-Functional Requirements
|
||||
|
||||
### NFR-001: Performance
|
||||
Response time < 500ms for all OAuth flows.
|
||||
|
||||
**Status**: ✓ Met (v1.0.0)
|
||||
|
||||
---
|
||||
|
||||
## Edge Cases
|
||||
|
||||
### EC-001: OAuth Provider Timeout
|
||||
**Scenario**: Provider doesn't respond in 5 seconds
|
||||
|
||||
**Expected**: Display error, offer retry
|
||||
|
||||
**Status**: ✓ Handled
|
||||
|
||||
---
|
||||
|
||||
### EC-002: Invalid MFA Code (NEW v1.2.0)
|
||||
**Scenario**: User enters incorrect TOTP code
|
||||
|
||||
**Expected**: Display error, max 3 attempts, lock after
|
||||
|
||||
**Status**: 🔄 To be implemented
|
||||
|
||||
---
|
||||
|
||||
## Constraints
|
||||
- Must use existing JWT session management
|
||||
- No new database servers
|
||||
- Compatible with existing user table
|
||||
|
||||
---
|
||||
|
||||
## Assumptions
|
||||
- Users have access to authenticator app for MFA
|
||||
- OAuth providers are always available
|
||||
|
||||
---
|
||||
|
||||
## Version History Summary
|
||||
|
||||
| Version | Date | Summary |
|
||||
|---------|------|---------|
|
||||
| 1.0.0 | 2026-01-22 | Initial OAuth login (Google only implicit) |
|
||||
| 1.1.0 | 2026-01-22 | + Explicit Google OAuth support |
|
||||
| 1.2.0 | 2026-01-23 | + GitHub provider, + MFA (current) |
|
||||
|
||||
**Detailed History**: See `history/` directory and `changes.log`
|
||||
```
|
||||
|
||||
### Changes.log (NDJSON - 完整历史)
|
||||
|
||||
```jsonl
|
||||
{"timestamp":"2026-01-22T10:00:00+08:00","iteration":1,"version":"1.0.0","action":"create","type":"requirement","id":"FR-001","description":"Initial OAuth requirement"}
|
||||
{"timestamp":"2026-01-22T10:05:00+08:00","iteration":1,"version":"1.0.0","action":"create","type":"requirement","id":"NFR-001","description":"Performance requirement"}
|
||||
{"timestamp":"2026-01-22T11:00:00+08:00","iteration":2,"version":"1.1.0","action":"update","type":"requirement","id":"FR-001","description":"Clarified Google OAuth support"}
|
||||
{"timestamp":"2026-01-22T11:05:00+08:00","iteration":2,"version":"1.1.0","action":"create","type":"requirement","id":"FR-002","description":"Multi-provider support"}
|
||||
{"timestamp":"2026-01-23T10:00:00+08:00","iteration":3,"version":"1.2.0","action":"create","type":"requirement","id":"FR-003","description":"MFA requirement"}
|
||||
{"timestamp":"2026-01-23T10:05:00+08:00","iteration":3,"version":"1.2.0","action":"update","type":"requirement","id":"FR-002","description":"Added GitHub provider"}
|
||||
```
|
||||
|
||||
## 实现流程
|
||||
|
||||
### Agent 工作流（RA 为例）
|
||||
|
||||
```javascript
|
||||
// ==================== RA Agent 迭代流程 ====================
|
||||
|
||||
// 读取当前状态
|
||||
const state = JSON.parse(Read(`.workflow/.cycle/${cycleId}.json`))
|
||||
const currentVersion = state.requirements?.version || "0.0.0"
|
||||
const iteration = state.current_iteration
|
||||
|
||||
// 如果是迭代（已有旧版本）
|
||||
if (currentVersion !== "0.0.0") {
|
||||
// 1. 归档旧版本
|
||||
const oldFile = `.workflow/.cycle/${cycleId}.progress/ra/requirements.md`
|
||||
const archiveFile = `.workflow/.cycle/${cycleId}.progress/ra/history/requirements-v${currentVersion}.md`
|
||||
|
||||
Copy(oldFile, archiveFile) // 归档
|
||||
|
||||
// 2. 读取旧版本（可选，用于理解上下文）
|
||||
const oldRequirements = Read(oldFile)
|
||||
|
||||
// 3. 读取变更历史
|
||||
const changesLog = readNDJSON(`.workflow/.cycle/${cycleId}.progress/ra/changes.log`)
|
||||
}
|
||||
|
||||
// 4. 生成新版本号
|
||||
const newVersion = bumpVersion(currentVersion, 'minor') // 1.1.0 -> 1.2.0
|
||||
|
||||
// 5. 生成新文档（完全重写）
|
||||
const newRequirements = generateRequirements({
|
||||
version: newVersion,
|
||||
previousVersion: currentVersion,
|
||||
previousSummary: "Added Google OAuth support",
|
||||
currentChanges: "Added MFA and GitHub provider",
|
||||
iteration: iteration,
|
||||
taskDescription: state.description,
|
||||
changesLog: changesLog // 用于理解历史
|
||||
})
|
||||
|
||||
// 6. 写入新文档（覆盖旧的）
|
||||
Write(`.workflow/.cycle/${cycleId}.progress/ra/requirements.md`, newRequirements)
|
||||
|
||||
// 7. 追加变更到 changes.log
|
||||
appendNDJSON(`.workflow/.cycle/${cycleId}.progress/ra/changes.log`, {
|
||||
timestamp: getUtc8ISOString(),
|
||||
iteration: iteration,
|
||||
version: newVersion,
|
||||
action: "create",
|
||||
type: "requirement",
|
||||
id: "FR-003",
|
||||
description: "Added MFA requirement"
|
||||
})
|
||||
|
||||
// 8. 更新状态
|
||||
state.requirements = {
|
||||
version: newVersion,
|
||||
output_file: `.workflow/.cycle/${cycleId}.progress/ra/requirements.md`,
|
||||
summary: {
|
||||
functional_requirements: 3,
|
||||
edge_cases: 2,
|
||||
constraints: 3
|
||||
}
|
||||
}
|
||||
|
||||
Write(`.workflow/.cycle/${cycleId}.json`, JSON.stringify(state, null, 2))
|
||||
```
|
||||
|
||||
## 优势对比
|
||||
|
||||
| 方面 | 增量更新 | 重新创建 + 归档 |
|
||||
|------|----------|----------------|
|
||||
| **文档简洁性** | ❌ 越来越长 | ✅ 始终简洁 |
|
||||
| **Agent 解析** | ❌ 需要解析历史 | ✅ 只看当前版本 |
|
||||
| **维护复杂度** | ❌ 高（版本标记） | ✅ 低（直接重写） |
|
||||
| **文件大小** | ❌ 膨胀 | ✅ 固定 |
|
||||
| **历史追溯** | ✅ 在主文档 | ✅ 在 history/ + changes.log |
|
||||
| **人类可读** | ❌ 需要跳过历史 | ✅ 直接看当前 |
|
||||
| **Token 使用** | ❌ 多（读取完整历史） | ✅ 少（只读当前） |
|
||||
|
||||
## 归档策略
|
||||
|
||||
### 自动归档触发时机
|
||||
|
||||
```javascript
|
||||
function shouldArchive(currentVersion, state) {
|
||||
// 每次版本更新时归档
|
||||
return currentVersion !== state.requirements?.version
|
||||
}
|
||||
|
||||
function archiveOldVersion(cycleId, agent, filename, currentVersion) {
|
||||
const currentFile = `.workflow/.cycle/${cycleId}.progress/${agent}/${filename}`
|
||||
const archiveDir = `.workflow/.cycle/${cycleId}.progress/${agent}/history`
|
||||
const archiveFile = `${archiveDir}/${filename.replace('.', `-v${currentVersion}.`)}`
|
||||
|
||||
// 确保归档目录存在
|
||||
mkdir -p ${archiveDir}
|
||||
|
||||
// 复制（不是移动，保持当前文件直到新版本写入）
|
||||
Copy(currentFile, archiveFile)
|
||||
|
||||
console.log(`Archived ${filename} v${currentVersion} to history/`)
|
||||
}
|
||||
```
|
||||
|
||||
### 清理策略（可选）
|
||||
|
||||
保留最近 N 个版本，删除更老的归档：
|
||||
|
||||
```javascript
|
||||
function cleanupArchives(cycleId, agent, keepVersions = 3) {
|
||||
const historyDir = `.workflow/.cycle/${cycleId}.progress/${agent}/history`
|
||||
const archives = listFiles(historyDir)
|
||||
|
||||
// 按版本号排序
|
||||
archives.sort((a, b) => compareVersions(extractVersion(a), extractVersion(b)))
|
||||
|
||||
// 删除最老的版本（保留最近 N 个）
|
||||
if (archives.length > keepVersions) {
|
||||
const toDelete = archives.slice(0, archives.length - keepVersions)
|
||||
toDelete.forEach(file => Delete(`${historyDir}/${file}`))
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Changes.log 的重要性
|
||||
|
||||
虽然主文档重新创建，但 **changes.log (NDJSON) 永久保留完整历史**：
|
||||
|
||||
```bash
|
||||
# 查看所有变更
|
||||
cat .workflow/.cycle/cycle-xxx.progress/ra/changes.log | jq .
|
||||
|
||||
# 查看某个需求的历史
|
||||
cat .workflow/.cycle/cycle-xxx.progress/ra/changes.log | jq 'select(.id=="FR-001")'
|
||||
|
||||
# 按迭代查看变更
|
||||
cat .workflow/.cycle/cycle-xxx.progress/ra/changes.log | jq 'select(.iteration==2)'
|
||||
```
|
||||
|
||||
这样：
|
||||
- **主文档**: 清晰简洁（当前状态）
|
||||
- **Changes.log**: 完整追溯（所有历史）
|
||||
- **History/**: 快照备份（按需查看）
|
||||
|
||||
## 推荐实施
|
||||
|
||||
1. ✅ 采用"重新创建"策略
|
||||
2. ✅ 主文档只保留"上一版本简要说明"
|
||||
3. ✅ 自动归档到 `history/` 目录
|
||||
4. ✅ Changes.log (NDJSON) 保留完整历史
|
||||
5. ✅ 可选：保留最近 3-5 个历史版本
|
||||
|
||||
这样既保持了文档简洁（Agent 友好），又保留了完整历史（审计友好）。
|
||||
Reference in New Issue
Block a user