diff --git a/.codex/skills/parallel-dev-cycle/README.md b/.codex/skills/parallel-dev-cycle/README.md new file mode 100644 index 00000000..cc16a290 --- /dev/null +++ b/.codex/skills/parallel-dev-cycle/README.md @@ -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 diff --git a/.codex/skills/parallel-dev-cycle/SKILL.md b/.codex/skills/parallel-dev-cycle/SKILL.md new file mode 100644 index 00000000..16118509 --- /dev/null +++ b/.codex/skills/parallel-dev-cycle/SKILL.md @@ -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="" [--cycle-id=] [--auto] [--parallel=] +--- + +# 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) | 版本管理 | diff --git a/.codex/skills/parallel-dev-cycle/phases/agents/code-developer.md b/.codex/skills/parallel-dev-cycle/phases/agents/code-developer.md new file mode 100644 index 00000000..7ee76c84 --- /dev/null +++ b/.codex/skills/parallel-dev-cycle/phases/agents/code-developer.md @@ -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 diff --git a/.codex/skills/parallel-dev-cycle/phases/agents/exploration-planner.md b/.codex/skills/parallel-dev-cycle/phases/agents/exploration-planner.md new file mode 100644 index 00000000..c032b75a --- /dev/null +++ b/.codex/skills/parallel-dev-cycle/phases/agents/exploration-planner.md @@ -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 diff --git a/.codex/skills/parallel-dev-cycle/phases/agents/requirements-analyst.md b/.codex/skills/parallel-dev-cycle/phases/agents/requirements-analyst.md new file mode 100644 index 00000000..49904138 --- /dev/null +++ b/.codex/skills/parallel-dev-cycle/phases/agents/requirements-analyst.md @@ -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)" diff --git a/.codex/skills/parallel-dev-cycle/phases/agents/validation-archivist.md b/.codex/skills/parallel-dev-cycle/phases/agents/validation-archivist.md new file mode 100644 index 00000000..e87e9139 --- /dev/null +++ b/.codex/skills/parallel-dev-cycle/phases/agents/validation-archivist.md @@ -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 diff --git a/.codex/skills/parallel-dev-cycle/phases/orchestrator.md b/.codex/skills/parallel-dev-cycle/phases/orchestrator.md new file mode 100644 index 00000000..356be9a4 --- /dev/null +++ b/.codex/skills/parallel-dev-cycle/phases/orchestrator.md @@ -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 diff --git a/.codex/skills/parallel-dev-cycle/phases/state-schema.md b/.codex/skills/parallel-dev-cycle/phases/state-schema.md new file mode 100644 index 00000000..bc7a7407 --- /dev/null +++ b/.codex/skills/parallel-dev-cycle/phases/state-schema.md @@ -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 // 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 + 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 diff --git a/.codex/skills/parallel-dev-cycle/specs/communication-optimization.md b/.codex/skills/parallel-dev-cycle/specs/communication-optimization.md new file mode 100644 index 00000000..83268336 --- /dev/null +++ b/.codex/skills/parallel-dev-cycle/specs/communication-optimization.md @@ -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 从引用路径自动读取所需文件。 + +### 第四步: 测试版本检测 + +确保版本不匹配时有警告。 diff --git a/.codex/skills/parallel-dev-cycle/specs/coordination-protocol.md b/.codex/skills/parallel-dev-cycle/specs/coordination-protocol.md new file mode 100644 index 00000000..782d36db --- /dev/null +++ b/.codex/skills/parallel-dev-cycle/specs/coordination-protocol.md @@ -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 +``` diff --git a/.codex/skills/parallel-dev-cycle/specs/versioning-strategy.md b/.codex/skills/parallel-dev-cycle/specs/versioning-strategy.md new file mode 100644 index 00000000..d48df98c --- /dev/null +++ b/.codex/skills/parallel-dev-cycle/specs/versioning-strategy.md @@ -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 友好），又保留了完整历史（审计友好）。