parallel-dev-cycle

仓库: catlog22/claude-code-workflow
安装量: 54
排名: #13784

安装

npx skills add https://github.com/catlog22/claude-code-workflow --skill parallel-dev-cycle
Parallel Dev Cycle
Multi-agent parallel development cycle using Codex subagent pattern with four specialized workers:
Requirements Analysis & Extension
(RA) - Requirement analysis and self-enhancement
Exploration & Planning
(EP) - Codebase exploration and implementation planning
Code Development
(CD) - Code development with debug strategy support
Validation & Archival Summary
(VAS) - Validation and archival summary
Orchestration logic (phase management, state updates, feedback coordination) runs
inline in the main flow
— no separate orchestrator agent is spawned. Only 4 worker agents are allocated.
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.
Architecture Overview
┌─────────────────────────────────────────────────────────────┐
│ User Input (Task) │
└────────────────────────────┬────────────────────────────────┘
│
v
┌──────────────────────────────┐
│ Main Flow (Inline Orchestration) │
│ Phase 1 → 2 → 3 → 4 │
└──────────────────────────────┘
│
┌────────────────────┼────────────────────┐
│ │ │
v v v
┌────────┐ ┌────────┐ ┌────────┐
│ RA │ │ EP │ │ CD │
│Agent │ │Agent │ │Agent │
└────────┘ └────────┘ └────────┘
│ │ │
└────────────────────┼────────────────────┘
│
v
┌────────┐
│ VAS │
│ Agent │
└────────┘
│
v
┌──────────────────────────────┐
│ Summary Report │
│ & Markdown Docs │
└──────────────────────────────┘
Key Design Principles
Main Document + Auxiliary Logs
Each agent maintains one main document (rewritten per iteration) and auxiliary logs (append-only)
Version-Based Overwrite
Main documents completely rewritten per version; logs append-only
Automatic Archival
Old main document versions automatically archived to
history/
directory
Complete Audit Trail
Changes.log (NDJSON) preserves all change history
Parallel Coordination
Four agents launched simultaneously; coordination via shared state and inline main flow
File References
Use short file paths instead of content passing
Self-Enhancement
RA agent proactively extends requirements based on context
Shared Discovery Board
All agents share exploration findings via
discoveries.ndjson
— read on start, write as you discover, eliminating redundant codebase exploration
Arguments
Arg
Required
Description
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 without user confirmation)
--parallel
No
Number of parallel agents (default: 4, max: 4)
Auto Mode
When
--auto
Run all phases sequentially without user confirmation between iterations. Use recommended defaults for all decisions. Automatically continue iteration loop until tests pass or max iterations reached.
Prep Package Integration
When
prep-package.json
exists at
{projectRoot}/.workflow/.cycle/prep-package.json
, Phase 1 consumes it to:
Use refined task description instead of raw TASK
Apply auto-iteration config (convergence criteria, phase gates)
Inject per-iteration agent focus directives (0→1 vs 1→100)
Prep packages are generated by the interactive prompt
/prompts:prep-cycle
. See
phases/00-prep-checklist.md
for schema.
Execution Flow
Input Parsing:
└─ Parse arguments (TASK | --cycle-id + --extend)
└─ Convert to structured context (cycleId, state, progressDir)
Phase 1: Session Initialization
└─ Ref: phases/01-session-init.md
├─ Create new cycle OR resume existing cycle
├─ Initialize state file and directory structure
└─ Output: cycleId, state, progressDir
Phase 2: Agent Execution (Parallel)
└─ Ref: phases/02-agent-execution.md
├─ Tasks attached: Spawn RA → Spawn EP → Spawn CD → Spawn VAS → Wait all
├─ Spawn RA, EP, CD, VAS agents in parallel
├─ Wait for all agents with timeout handling
└─ Output: agentOutputs (4 agent results)
Phase 3: Result Aggregation & Iteration
└─ Ref: phases/03-result-aggregation.md
├─ Parse PHASE_RESULT from each agent
├─ Detect issues (test failures, blockers)
├─ Decision: Issues found AND iteration < max?
│ ├─ Yes → Send feedback via send_input, loop back to Phase 2
│ └─ No → Proceed to Phase 4
└─ Output: parsedResults, iteration status
Phase 4: Completion & Summary
└─ Ref: phases/04-completion-summary.md
├─ Generate unified summary report
├─ Update final state
├─ Sync session state: $session-sync -y "Dev cycle complete: {iterations} iterations"
├─ Close all agents
└─ Output: final cycle report with continuation instructions
Phase Reference Documents
(read on-demand when phase executes):
Phase
Document
Purpose
1
phases/01-session-init.md
Session creation/resume and state initialization
2
phases/02-agent-execution.md
Parallel agent spawning and execution
3
phases/03-result-aggregation.md
Result parsing, feedback generation, iteration handling
4
phases/04-completion-summary.md
Final summary generation and cleanup
Data Flow
User Input (TASK | --cycle-id + --extend)
↓
[Parse Arguments]
↓ cycleId, state, progressDir
Phase 1: Session Initialization
↓ cycleId, state, progressDir (initialized/resumed)
Phase 2: Agent Execution
├─ All agents read coordination/discoveries.ndjson on start
├─ Each agent explores → writes new discoveries to board
├─ Later-finishing agents benefit from earlier agents' findings
↓ agentOutputs {ra, ep, cd, vas} + shared discoveries.ndjson
Phase 3: Result Aggregation
↓ parsedResults, hasIssues, iteration count
↓ [Loop back to Phase 2 if issues and iteration < max]
↓ (discoveries.ndjson carries over across iterations)
Phase 4: Completion & Summary
↓ finalState, summaryReport
Return: cycle_id, iterations, final_state
Session Structure
{projectRoot}/.workflow/.cycle/
├── {cycleId}.json # Master state file
├── {cycleId}.progress/
├── ra/
│ ├── requirements.md # Current version (complete rewrite)
│ ├── changes.log # NDJSON complete history (append-only)
│ └── history/ # Archived snapshots
├── ep/
│ ├── exploration.md # Codebase exploration report
│ ├── architecture.md # Architecture design
│ ├── plan.json # Structured task list (current version)
│ ├── changes.log # NDJSON complete history
│ └── history/
├── cd/
│ ├── implementation.md # Current version
│ ├── debug-log.ndjson # Debug hypothesis tracking
│ ├── changes.log # NDJSON complete history
│ └── history/
├── vas/
│ ├── summary.md # Current version
│ ├── changes.log # NDJSON complete history
│ └── history/
└── coordination/
├── discoveries.ndjson # Shared discovery board (all agents append)
├── timeline.md # Execution timeline
└── decisions.log # Decision log
State Management
Master state file:
{projectRoot}/.workflow/.cycle/{cycleId}.json
{
"cycle_id"
:
"cycle-v1-20260122T100000-abc123"
,
"title"
:
"Task title"
,
"description"
:
"Full task description"
,
"status"
:
"created | running | paused | completed | failed"
,
"created_at"
:
"ISO8601"
,
"updated_at"
:
"ISO8601"
,
"max_iterations"
:
5
,
"current_iteration"
:
0
,
"agents"
:
{
"ra"
:
{
"status"
:
"idle | running | completed | failed"
,
"output_files"
:
[
]
}
,
"ep"
:
{
"status"
:
"idle"
,
"output_files"
:
[
]
}
,
"cd"
:
{
"status"
:
"idle"
,
"output_files"
:
[
]
}
,
"vas"
:
{
"status"
:
"idle"
,
"output_files"
:
[
]
}
}
,
"current_phase"
:
"init | ra | ep | cd | vas | aggregation | complete"
,
"completed_phases"
:
[
]
,
"requirements"
:
null
,
"plan"
:
null
,
"changes"
:
[
]
,
"test_results"
:
null
,
"coordination"
:
{
"feedback_log"
:
[
]
,
"blockers"
:
[
]
}
}
Recovery
If state corrupted, rebuild from
.progress/
markdown files and changes.log.
TodoWrite Pattern
Phase-Level Tracking (Tasks Attached)
[
{
"content"
:
"Phase 1: Session Initialization"
,
"status"
:
"completed"
}
,
{
"content"
:
"Phase 2: Agent Execution"
,
"status"
:
"in_progress"
}
,
{
"content"
:
" → Spawn RA Agent"
,
"status"
:
"completed"
}
,
{
"content"
:
" → Spawn EP Agent"
,
"status"
:
"completed"
}
,
{
"content"
:
" → Spawn CD Agent"
,
"status"
:
"in_progress"
}
,
{
"content"
:
" → Spawn VAS Agent"
,
"status"
:
"pending"
}
,
{
"content"
:
"Phase 3: Result Aggregation"
,
"status"
:
"pending"
}
,
{
"content"
:
"Phase 4: Completion & Summary"
,
"status"
:
"pending"
}
]
Phase-Level Tracking (Collapsed)
[
{
"content"
:
"Phase 1: Session Initialization"
,
"status"
:
"completed"
}
,
{
"content"
:
"Phase 2: Agent Execution (4 agents completed)"
,
"status"
:
"completed"
}
,
{
"content"
:
"Phase 3: Result Aggregation"
,
"status"
:
"in_progress"
}
,
{
"content"
:
"Phase 4: Completion & Summary"
,
"status"
:
"pending"
}
]
Iteration Loop Tracking
[
{
"content"
:
"Phase 1: Session Initialization"
,
"status"
:
"completed"
}
,
{
"content"
:
"Iteration 1: Agent Execution + Aggregation"
,
"status"
:
"completed"
}
,
{
"content"
:
"Iteration 2: Feedback → Re-execution → Aggregation"
,
"status"
:
"in_progress"
}
,
{
"content"
:
"Phase 4: Completion & Summary"
,
"status"
:
"pending"
}
]
Versioning
1.0.0
Initial cycle →
1.x.0
Each iteration (minor bump)
Each iteration: archive old → complete rewrite → append changes.log
Archive: copy requirements.md → history/requirements-v1.0.0.md
Rewrite: overwrite requirements.md with v1.1.0 (complete new content)
Append: changes.log ←
Agent Output
Rewrite (per iteration)
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
summary.md, test-results.json
changes.log
Coordination Protocol
Execution Order
RA → EP → CD → VAS (dependency chain, all spawned in parallel but block on dependencies)
Shared Discovery Board
All agents share a real-time discovery board at
coordination/discoveries.ndjson
. Each agent reads it on start and appends findings during work. This eliminates redundant codebase exploration.
Lifecycle
:
Created by the first agent to write a discovery (file may not exist initially)
Carries over across iterations — never cleared or recreated
Agents use Bash
echo '...' >> discoveries.ndjson
to append entries
Format
NDJSON, each line is a self-contained JSON with required top-level fields ts , agent , type , data : {"ts":"2026-01-22T10:00:00+08:00","agent":"ra","type":"tech_stack","data":{"language":"TypeScript","framework":"Express","test":"Jest","build":"tsup"}} Discovery Types : type Dedup Key Writers Readers Required data Fields tech_stack singleton RA EP, CD, VAS language , framework , test , build project_config data.path RA EP, CD path , key_deps[] , scripts{} existing_feature data.name RA, EP CD name , files[] , summary architecture singleton EP CD, VAS pattern , layers[] , entry code_pattern data.name EP, CD CD, VAS name , description , example_file integration_point data.file EP CD file , description , exports[] similar_impl data.feature EP CD feature , files[] , relevance code_convention singleton CD VAS naming , imports , formatting utility data.name CD VAS name , file , usage test_command singleton CD, VAS VAS, CD unit , integration (opt), coverage (opt) test_baseline singleton VAS CD total , passing , coverage_pct , framework , config test_pattern singleton VAS CD style , naming , fixtures blocker data.issue any all issue , severity , impact Protocol Rules : Read board before own exploration → skip covered areas (if file doesn't exist, skip) Write discoveries immediately via Bash echo >> → don't batch Deduplicate — check existing entries; skip if same type + dedup key value already exists Append-only — never modify or delete existing lines Agent → Main Flow Communication PHASE_RESULT: - phase: ra | ep | cd | vas - status: success | failed | partial - files_written: [list] - summary: one-line summary - issues: [] Main Flow → Agent Communication Feedback via send_input (file refs + issue summary, never full content):

FEEDBACK FROM [Source]

[Issue summary with file:line references]

Reference

  • File: .progress/vas/test-results.json (v1.0.0)

Actions Required

  1. [Specific fix]
    Rules
    Only main flow writes state file. Agents read state, write to own
    .progress/{agent}/
    directory only.
    Core Rules
    Start Immediately
    First action is TodoWrite initialization, then Phase 1 execution
    Progressive Phase Loading
    Read phase docs ONLY when that phase is about to execute
    Parse Every Output
    Extract PHASE_RESULT data from each agent for next phase
    Auto-Continue
    After each phase, execute next pending phase automatically
    Track Progress
    Update TodoWrite dynamically with attachment/collapse pattern
    Single Writer
    Only main flow writes to master state file; agents report via PHASE_RESULT
    File References
    Pass file paths between agents, not content
    DO NOT STOP
    Continuous execution until all phases complete or max iterations reached Error Handling Error Type Recovery Agent timeout send_input requesting convergence, then retry State corrupted Rebuild from progress markdown files and changes.log Agent failed Re-spawn agent with previous context Conflicting results Main flow sends reconciliation request Missing files RA/EP agents identify and request clarification Max iterations reached Generate summary with remaining issues documented Coordinator Checklist (Main Flow) Before Each Phase Read phase reference document Check current state for dependencies Update TodoWrite with phase tasks After Each Phase Parse agent outputs (PHASE_RESULT) Update master state file Collapse TodoWrite sub-tasks Determine next action (continue / iterate / complete) Reference Documents Document Purpose roles/ Agent role definitions (RA, EP, CD, VAS) Usage

Start new cycle

/parallel-dev-cycle TASK = "Implement real-time notifications"

Continue cycle

/parallel-dev-cycle --cycle-id

cycle-v1-20260122-abc123

Iteration with extension

/parallel-dev-cycle --cycle-id

cycle-v1-20260122-abc123 --extend = "Also add email notifications"

Auto mode

/parallel-dev-cycle --auto TASK = "Add OAuth authentication"

← 返回排行榜