mirror of
https://github.com/catlog22/Claude-Code-Workflow.git
synced 2026-02-05 01:50:27 +08:00
feat: Update documentation and file references for changes.log in parallel development cycle
This commit is contained in:
catlog22
@@ -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?
|
||||
|
||||
@@ -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) |
|
||||
| --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
|
||||
```
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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/
|
||||
|
||||
Reference in New Issue
Block a user