claude-code-workflow 6.3.37 → 6.3.39

package/.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