diff --git a/.codex/skills/parallel-dev-cycle/README.md b/.codex/skills/parallel-dev-cycle/README.md index cc16a290..4d9d0730 100644 --- a/.codex/skills/parallel-dev-cycle/README.md +++ b/.codex/skills/parallel-dev-cycle/README.md @@ -7,7 +7,7 @@ Multi-agent parallel development cycle using Codex subagent pattern with continu 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) +- **EP**: `exploration.md`, `architecture.md`, `plan.json` (codebase exploration + architecture + structured tasks) - **CD**: `implementation.md` (progress + files + decisions + testing) - **VAS**: `summary.md` (validation + test results + recommendations) @@ -49,7 +49,9 @@ Creates: │ ├── requirements.md (v1.0.0) │ └── changes.log (NDJSON) ├── ep/ -│ ├── plan.md (v1.0.0) +│ ├── exploration.md (v1.0.0) +│ ├── architecture.md (v1.0.0) +│ ├── plan.json (v1.0.0) │ └── changes.log (NDJSON) ├── cd/ │ ├── implementation.md (v1.0.0) @@ -113,20 +115,19 @@ When iteration completes, next extends to v1.1.0: ``` Current State (v1.0.0) ├── requirements.md (v1.0.0) -├── plan.md (v1.0.0) +├── plan.json (v1.0.0) ├── implementation.md (v1.0.0) └── summary.md (v1.0.0) User: "Add GitHub provider" ↓ Archive Old Write New -├── history/requirements-v1.0.0.md -├── 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) +├── history/requirements-v1.0.0.md → requirements.md (v1.1.0) - REWRITTEN +├── history/plan-v1.0.0.json → plan.json (v1.1.0) - REWRITTEN +├── history/impl-v1.0.0.md → implementation.md (v1.1.0) - REWRITTEN +└── history/summary-v1.0.0.md → summary.md (v1.1.0) - REWRITTEN + ↓ + Append to changes.log (NDJSON) ``` ## Session Files @@ -142,11 +143,13 @@ ra/ - Requirements Analyst └── requirements-v1.1.0.md ep/ - Exploration & Planning -├── plan.md # v1.2.0 (current) +├── exploration.md # v1.2.0 (codebase exploration) +├── architecture.md # v1.2.0 (architecture design) +├── plan.json # v1.2.0 (structured task list, current) ├── changes.log # NDJSON audit trail └── history/ - ├── plan-v1.0.0.md - └── plan-v1.1.0.md + ├── plan-v1.0.0.json + └── plan-v1.1.0.json cd/ - Code Developer ├── implementation.md # v1.2.0 (current) @@ -203,7 +206,7 @@ vas/ - Validation & Archival | 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 | +| **EP** | exploration.md + architecture.md + plan.json | Codebase exploration, architecture design, structured task list | ~5-10KB total | | **CD** | implementation.md | Completed tasks, files changed, decisions, tests | ~4-10KB | | **VAS** | summary.md | Test results, coverage, issues, recommendations | ~5-12KB | @@ -362,14 +365,14 @@ Orchestrator (main coordinator) ↓ All write to: - requirements.md (v1.x.0) - - plan.md (v1.x.0) + - exploration.md, architecture.md, plan.json (v1.x.0) - implementation.md (v1.x.0) - summary.md (v1.x.0) - changes.log (NDJSON append) ↓ [Automatic archival] - history/requirements-v1.{x-1}.0.md - - history/plan-v1.{x-1}.0.md + - history/plan-v1.{x-1}.0.json - etc... ↓ Orchestrator: Next iteration? diff --git a/.codex/skills/parallel-dev-cycle/SKILL.md b/.codex/skills/parallel-dev-cycle/SKILL.md index d30dd85b..f0cfc776 100644 --- a/.codex/skills/parallel-dev-cycle/SKILL.md +++ b/.codex/skills/parallel-dev-cycle/SKILL.md @@ -1,7 +1,7 @@ --- name: Parallel Dev Cycle 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=] +argument-hint: TASK="" | --cycle-id= [--extend=""] [--auto] [--parallel=] --- # Parallel Dev Cycle - Multi-Agent Development Workflow @@ -12,14 +12,15 @@ Multi-agent parallel development cycle using Codex subagent pattern with four sp 3. **Code Development** (CD) - Code development with debug strategy support 4. **Validation & Archival Summary** (VAS) - Validation and archival summary -Each agent **maintains only one main document file**, supporting versioning, automatic archival, and complete history tracking. +Each agent **maintains one main document** (e.g., requirements.md, plan.json, implementation.md) that is completely rewritten per iteration, plus auxiliary logs (changes.log, debug-log.ndjson) that are append-only. Supports versioning, automatic archival, and complete history tracking. ## 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) | +| TASK | One of TASK or --cycle-id | Task description (for new cycle, mutually exclusive with --cycle-id) | +| --cycle-id | One of TASK or --cycle-id | Existing cycle ID to continue (from API or previous session) | +| --extend | No | Extension description (only valid with --cycle-id) | | --auto | No | Auto-cycle mode (run all phases sequentially) | | --parallel | No | Number of parallel agents (default: 4, max: 4) | @@ -61,11 +62,11 @@ Each agent **maintains only one main document file**, supporting versioning, aut ## Key Design Principles -1. **Single File Per Agent**: Each agent maintains only one main file (clean and simple) -2. **Version-Based Overwrite**: Each version completely rewrites the main file -3. **Automatic Archival**: Old versions automatically archived to `history/` directory +1. **Main Document + Auxiliary Logs**: Each agent maintains one main document (rewritten per iteration) and auxiliary logs (append-only) +2. **Version-Based Overwrite**: Main documents completely rewritten per version; logs append-only +3. **Automatic Archival**: Old main document versions automatically archived to `history/` directory 4. **Complete Audit Trail**: Changes.log (NDJSON) preserves all change history -5. **Parallel Execution**: Four agents work simultaneously, no waiting +5. **Parallel Coordination**: Four agents launched simultaneously; coordination via shared state and orchestrator 6. **File References**: Use short file paths instead of content passing 7. **Self-Enhancement**: RA agent proactively extends requirements based on context @@ -82,11 +83,13 @@ Each agent **maintains only one main document file**, supporting versioning, aut | +-- requirements-v1.0.0.md # Archived snapshot | +-- requirements-v1.1.0.md # Archived snapshot +-- ep/ - | +-- plan.md # Current version + | +-- exploration.md # Codebase exploration report + | +-- architecture.md # Architecture design + | +-- plan.json # Structured task list (current version) | +-- changes.log # NDJSON complete history | └-- history/ - | +-- plan-v1.0.0.md - | +-- plan-v1.1.0.md + | +-- plan-v1.0.0.json + | +-- plan-v1.1.0.json +-- cd/ | +-- implementation.md # Current version | +-- debug-log.ndjson # Debug hypothesis tracking @@ -125,7 +128,9 @@ State schema is defined in [phases/state-schema.md](phases/state-schema.md). The Generates: ``` requirements.md (v1.0.0) -plan.md (v1.0.0) +exploration.md (v1.0.0) +architecture.md (v1.0.0) +plan.json (v1.0.0) implementation.md (v1.0.0) - if applicable summary.md (v1.0.0) - if applicable ``` diff --git a/.codex/skills/parallel-dev-cycle/phases/agents/code-developer.md b/.codex/skills/parallel-dev-cycle/phases/agents/code-developer.md index 662316a7..0f124113 100644 --- a/.codex/skills/parallel-dev-cycle/phases/agents/code-developer.md +++ b/.codex/skills/parallel-dev-cycle/phases/agents/code-developer.md @@ -28,7 +28,7 @@ The Code Developer is responsible for implementing features according to the pla - Document all file modifications - Log changes in NDJSON format - Track which iteration introduced which changes - - Update code-changes.log + - Update changes.log 4. **Report Issues** - Document development blockers @@ -43,7 +43,7 @@ The Code Developer is responsible for implementing features according to the pla - Test code before submitting - Document code changes clearly - Track blockers and issues -- Append to code-changes.log, never overwrite +- Append to changes.log, never overwrite - Reference requirements in code comments - Use meaningful commit messages in implementation notes @@ -90,7 +90,7 @@ For each task in the plan: - Reference requirements 3. **Track Changes** - - Log each file modification to code-changes.log + - Log each file modification to changes.log - Format: `{timestamp, iteration, file, action, description}` - Include reason for change @@ -150,7 +150,7 @@ When tests fail during implementation, the CD agent MUST initiate the hypothesis 6. **Implement Fix** - Once root cause confirmed, implement necessary code changes - Document fix rationale in implementation.md - - Log fix in code-changes.log + - Log fix in changes.log 7. **Verify Fix** - Run all relevant tests to ensure fix is effective @@ -180,7 +180,7 @@ Outcome values: `confirmed | refuted | inconclusive` ### Hypothesis Priority Order 1. **Direct Error Messages/Stack Traces**: Most reliable starting point -2. **Recent Changes**: Check `code-changes.log` for recent modifications +2. **Recent Changes**: Check `changes.log` for recent modifications 3. **Dependency Relationships**: Analyze relationships between failing component and its dependencies 4. **Edge Cases**: Review `edge-cases.md` for documented edge cases @@ -234,7 +234,7 @@ Overview of what was implemented in this iteration. - Code review and merge ``` -**code-changes.log** (NDJSON): +**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} @@ -274,7 +274,7 @@ Overview of what was implemented in this iteration. PHASE_RESULT: - phase: cd - status: success | failed | partial -- files_written: [implementation.md, code-changes.log, debug-log.ndjson (if debug executed), issues.md] +- files_written: [implementation.md, changes.log, debug-log.ndjson (if debug executed), issues.md] - summary: N tasks completed, M files modified, X blockers identified - tasks_completed: N - files_modified: M diff --git a/.codex/skills/parallel-dev-cycle/phases/orchestrator.md b/.codex/skills/parallel-dev-cycle/phases/orchestrator.md index 356be9a4..c28aa491 100644 --- a/.codex/skills/parallel-dev-cycle/phases/orchestrator.md +++ b/.codex/skills/parallel-dev-cycle/phases/orchestrator.md @@ -456,7 +456,7 @@ Code Developer - Implement features based on plan and requirements. Write files to ${progressDir}/cd/: - implementation.md: Implementation progress and decisions -- code-changes.log: NDJSON format, each line: {file, action, timestamp} +- changes.log: NDJSON format, each line: {file, action, timestamp} - issues.md: Development issues and blockers ## OUTPUT FORMAT @@ -484,7 +484,7 @@ function spawnVASAgent(cycleId, state, progressDir) { ### MANDATORY FIRST STEPS (Agent Execute) 1. **Read role definition**: ~/.codex/agents/validation-archivist.md -2. Read: ${progressDir}/cd/code-changes.log +2. Read: ${progressDir}/cd/changes.log --- @@ -638,7 +638,7 @@ function generateFinalSummary(cycleId, state) { ## 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/cd/changes.log - .workflow/.cycle/${cycleId}.progress/vas/summary.md ## Continuation Instructions diff --git a/.codex/skills/parallel-dev-cycle/phases/state-schema.md b/.codex/skills/parallel-dev-cycle/phases/state-schema.md index bc7a7407..613bfcc1 100644 --- a/.codex/skills/parallel-dev-cycle/phases/state-schema.md +++ b/.codex/skills/parallel-dev-cycle/phases/state-schema.md @@ -353,7 +353,7 @@ State changes trigger file writes: |--------------|-----------| | `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 | +| `changes` appended | `.progress/cd/changes.log` + iteration marker | | `test_results` updated | `.progress/vas/test-results.json` + version bump | | Full iteration done | `.progress/coordination/timeline.md` appended | @@ -413,7 +413,7 @@ function rebuildState(cycleId) { // 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 cdChanges = Read(`${progressDir}/cd/changes.log`) const vasResults = Read(`${progressDir}/vas/test-results.json`) // Reconstruct state from files diff --git a/.codex/skills/parallel-dev-cycle/specs/communication-optimization.md b/.codex/skills/parallel-dev-cycle/specs/communication-optimization.md index 83268336..ab18381a 100644 --- a/.codex/skills/parallel-dev-cycle/specs/communication-optimization.md +++ b/.codex/skills/parallel-dev-cycle/specs/communication-optimization.md @@ -244,7 +244,7 @@ if (cdChangesPath && exists(cdChangesPath)) { "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", + "changes": ".workflow/.cycle/cycle-v1-20260122-abc123.progress/cd/changes.log", "issues": ".workflow/.cycle/cycle-v1-20260122-abc123.progress/cd/issues.md" }, "summary": { @@ -313,7 +313,7 @@ Full Test Report: .workflow/.cycle/${cycleId}.progress/vas/test-results.json (v1 ## 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) +- Code Changes: .workflow/.cycle/${cycleId}.progress/cd/changes.log (v1.0.0) ## Action Required 1. Review failing tests in referenced test results file diff --git a/.codex/skills/parallel-dev-cycle/specs/coordination-protocol.md b/.codex/skills/parallel-dev-cycle/specs/coordination-protocol.md index 782d36db..7376283d 100644 --- a/.codex/skills/parallel-dev-cycle/specs/coordination-protocol.md +++ b/.codex/skills/parallel-dev-cycle/specs/coordination-protocol.md @@ -12,19 +12,26 @@ The coordination protocol enables four parallel agents (RA, EP, CD, VAS) to comm **Location**: `.workflow/.cycle/{cycleId}.json` -All agents read from and write to the unified state file: +**Access Pattern**: +- **Agents**: READ ONLY - check dependencies and status +- **Orchestrator**: READ-WRITE - updates state after each phase ```javascript -// Every agent: Read fresh state at action start +// Every agent: Read state to check dependencies const state = JSON.parse(Read(`.workflow/.cycle/${cycleId}.json`)) +const canProceed = checkDependencies(state) -// Every agent: Write updated state at action end -Write(`.workflow/.cycle/${cycleId}.json`, JSON.stringify(state, null, 2)) +// Agent outputs PHASE_RESULT (reports to orchestrator, NOT writes directly) +console.log("PHASE_RESULT: ...") + +// Only Orchestrator writes to state file after receiving PHASE_RESULT +// Write(`.workflow/.cycle/${cycleId}.json`, JSON.stringify(updatedState, null, 2)) ``` **Protocol**: -- Read-Update-Write pattern (no lock needed, orchestrator serializes) -- Timestamp all updates with ISO8601 format +- Only orchestrator writes to state file (no concurrent writes, no lock needed) +- Agents read state to understand dependencies +- Timestamp all orchestrator updates with ISO8601 format - Never delete existing data, only append ### 2. Progress Markdown Files (Async Log) @@ -33,18 +40,18 @@ Write(`.workflow/.cycle/${cycleId}.json`, JSON.stringify(state, null, 2)) 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 | +| Agent | Main Documents (Rewrite) | Logs (Append-Only) | +|-------|--------------------------|-------------------| +| RA | requirements.md | changes.log | +| EP | exploration.md, architecture.md, plan.json | changes.log | +| CD | implementation.md, issues.md | changes.log, debug-log.ndjson | +| VAS | validation.md, summary.md, test-results.json | changes.log | **Protocol**: -- Append-only pattern (no overwrites) -- Version each document independently +- **Main documents**: Complete rewrite per iteration, archived to `history/` +- **Log files**: Append-only (changes.log, debug-log.ndjson) - never delete +- **Version synchronization**: All main documents share same version (e.g., all v1.1.0 in iteration 2) - Include timestamp on each update -- Maintain backward compatibility ### 3. Orchestrator send_input (Synchronous) @@ -198,6 +205,8 @@ PHASE_DETAILS: ## Dependency Resolution +**Execution Model**: All four agents are spawned in parallel, but execution blocks based on dependencies. Orchestrator manages dependency resolution via shared state. + ### Build Order (Default) ``` @@ -206,6 +215,12 @@ RA (Requirements) → EP (Planning) → CD (Development) → VAS (Validation) Block EP Block CD Block VAS Block completion ``` +**Explanation**: +- All agents spawned simultaneously +- Each agent checks dependencies in shared state before proceeding +- Blocked agents wait for dependency completion +- Orchestrator uses `send_input` to notify dependent agents when ready + ### Parallel Opportunities Some phases can run in parallel: @@ -384,7 +399,7 @@ console.log(state.coordination.feedback_log) tail .workflow/.cycle/cycle-xxx.progress/ra/changes.log # Check CD changes -grep "TASK-001" .workflow/.cycle/cycle-xxx.progress/cd/code-changes.log +grep "TASK-001" .workflow/.cycle/cycle-xxx.progress/cd/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 index 4b960633..2fa0335d 100644 --- a/.codex/skills/parallel-dev-cycle/specs/versioning-strategy.md +++ b/.codex/skills/parallel-dev-cycle/specs/versioning-strategy.md @@ -28,7 +28,7 @@ For each iteration, **completely rewrite** the main document, and automatically │ └── plan-v1.1.0.json ├── cd/ │ ├── implementation.md # v1.2.0 (current) -│ ├── code-changes.log # NDJSON complete history +│ ├── changes.log # NDJSON complete history │ ├── debug-log.ndjson # Debug hypothesis tracking │ ├── issues.md # Current unresolved issues │ └── history/