feat: Update documentation and file references for changes.log in parallel development cycle

.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/requirements-v1.0.0.md  → requirements.md (v1.1.0) - REWRITTEN
-├── history/plan-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    → plan.md (v1.1.0) - REWRITTEN
+├── history/impl-v1.0.0.md          → implementation.md (v1.1.0) - REWRITTEN
-└── history/summary-v1.0.0.md → implementation.md (v1.1.0) - REWRITTEN
+└── history/summary-v1.0.0.md       → summary.md (v1.1.0) - REWRITTEN
-                               → summary.md (v1.1.0) - REWRITTEN
+                                       ↓
-                                  ↓
+                                 Append to changes.log (NDJSON)
-                           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.0.0.json
-    └── plan-v1.1.0.md
+    └── 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?

.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="<task description>" [--cycle-id=<id>] [--auto] [--parallel=<count>]
+argument-hint: TASK="<task description>" | --cycle-id=<id> [--extend="<extension>"] [--auto] [--parallel=<count>]
 ---
 
 # 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) |
+| TASK | One of TASK or --cycle-id | Task description (for new cycle, mutually exclusive with --cycle-id) |
-| --cycle-id | No | Existing cycle ID to continue (from API or previous session) |
+| --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)
+1. **Main Document + Auxiliary Logs**: Each agent maintains one main document (rewritten per iteration) and auxiliary logs (append-only)
-2. **Version-Based Overwrite**: Each version completely rewrites the main file
+2. **Version-Based Overwrite**: Main documents completely rewritten per version; logs append-only
-3. **Automatic Archival**: Old versions automatically archived to `history/` directory
+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.0.0.json
-    |       +-- plan-v1.1.0.md
+    |       +-- 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
 ```

.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

.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

.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

.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

.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
+// Agent outputs PHASE_RESULT (reports to orchestrator, NOT writes directly)
-Write(`.workflow/.cycle/${cycleId}.json`, JSON.stringify(state, null, 2))
+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)
+- Only orchestrator writes to state file (no concurrent writes, no lock needed)
-- Timestamp all updates with ISO8601 format
+- 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 |
+| Agent | Main Documents (Rewrite) | Logs (Append-Only) |
-|-------|-------|
+|-------|--------------------------|-------------------|
-| RA | requirements.md, edge-cases.md, changes.log |
+| RA | requirements.md | changes.log |
-| EP | exploration.md, architecture.md, plan.json |
+| EP | exploration.md, architecture.md, plan.json | changes.log |
-| CD | implementation.md, code-changes.log, issues.md |
+| CD | implementation.md, issues.md | changes.log, debug-log.ndjson |
-| VAS | validation.md, test-results.json, coverage.md, summary.md |
+| VAS | validation.md, summary.md, test-results.json | changes.log |
 
 **Protocol**:
-- Append-only pattern (no overwrites)
+- **Main documents**: Complete rewrite per iteration, archived to `history/`
-- Version each document independently
+- **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

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