parallel-dev-cycle

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Parallel Dev Cycle

多Agent并行开发周期

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.

采用Codex子Agent模式的多Agent并行开发周期，包含4个专业化的工作Agent：

需求分析与扩展（RA）- 需求分析与自我增强
探索与规划（EP）- 代码库探索与实现规划
代码开发（CD）- 支持调试策略的代码开发
验证与归档总结（VAS）- 验证与归档总结

编排逻辑（阶段管理、状态更新、反馈协调）在主流程中内联运行——不会生成独立的编排Agent，仅分配4个工作Agent。

每个Agent维护一份主文档（例如requirements.md、plan.json、implementation.md），每次迭代会完全重写该文档，同时维护附加日志（changes.log、debug-log.ndjson），日志采用追加写入模式。

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             │
              └──────────────────────────────┘

┌─────────────────────────────────────────────────────────────┐
│                    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

主文档+附加日志：每个Agent维护一份主文档（每次迭代重写）和附加日志（追加写入）
基于版本的覆盖：主文档每次迭代完全重写；日志仅追加
自动归档：旧版本主文档自动归档至
```
history/
```
目录
完整审计追踪：Changes.log（NDJSON格式）保留所有变更历史
并行协调：4个Agent同时启动；通过共享状态和内联主流程进行协调
文件引用：使用短文件路径而非传递内容
自我增强：RA Agent会根据上下文主动扩展需求
共享发现看板：所有Agent通过
```
discoveries.ndjson
```
共享探索成果——启动时读取，探索时写入，消除重复的代码库探索

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)

参数	是否必填	描述
TASK	TASK或--cycle-id二选一	任务描述（用于新周期，与--cycle-id互斥）
--cycle-id	TASK或--cycle-id二选一	要继续的现有周期ID（来自API或之前的会话）
--extend	否	扩展描述（仅与--cycle-id配合有效）
--auto	否	自动周期模式（按顺序运行所有阶段，无需用户确认）
--parallel	否	并行Agent数量（默认：4，最大值：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.

当启用

--auto

参数时：按顺序运行所有阶段，迭代之间无需用户确认。所有决策使用推荐默认值。自动继续迭代循环，直到测试通过或达到最大迭代次数。

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.

当

{projectRoot}/.workflow/.cycle/prep-package.json

文件存在时，阶段1会读取该文件以：

使用优化后的任务描述替代原始TASK
应用自动迭代配置（收敛标准、阶段门限）
注入每次迭代的Agent聚焦指令（从0到1 vs 从1到100）

预准备包由交互式提示符

/prompts:prep-cycle

生成。详见phases/00-prep-checklist.md中的 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

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

阶段参考文档（仅当该阶段即将执行时才读取）：

阶段	文档	用途
1	phases/01-session-init.md	会话创建/恢复与状态初始化
2	phases/02-agent-execution.md	并行Agent启动与执行
3	phases/03-result-aggregation.md	结果解析、反馈生成、迭代处理
4	phases/04-completion-summary.md	最终总结生成与清理

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

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

{projectRoot}/.workflow/.cycle/
├── {cycleId}.json                                 # 主状态文件
├── {cycleId}.progress/
    ├── ra/
    │   ├── requirements.md                        # 当前版本（完全重写）
    │   ├── changes.log                            # NDJSON格式完整历史（追加写入）
    │   └── history/                               # 归档快照
    ├── ep/
    │   ├── exploration.md                         # 代码库探索报告
    │   ├── architecture.md                        # 架构设计
    │   ├── plan.json                              # 结构化任务列表（当前版本）
    │   ├── changes.log                            # NDJSON格式完整历史
    │   └── history/
    ├── cd/
    │   ├── implementation.md                      # 当前版本
    │   ├── debug-log.ndjson                       # 调试假设追踪
    │   ├── changes.log                            # NDJSON格式完整历史
    │   └── history/
    ├── vas/
    │   ├── summary.md                             # 当前版本
    │   ├── changes.log                            # NDJSON格式完整历史
    │   └── history/
    └── coordination/
        ├── discoveries.ndjson                     # 共享发现看板（所有Agent追加内容）
        ├── timeline.md                            # 执行时间线
        └── decisions.log                          # 决策日志

State Management

状态管理

Master state file:

{projectRoot}/.workflow/.cycle/{cycleId}.json

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.

主状态文件：

{projectRoot}/.workflow/.cycle/{cycleId}.json

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": [] }
}

恢复机制：如果状态文件损坏，可从

.progress/

目录下的Markdown文件和changes.log重建。

TodoWrite Pattern

TodoWrite模式

Phase-Level Tracking (Tasks Attached)

阶段级追踪（任务附加）

json

[
  {"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"}
]

json

[
  {"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)

阶段级追踪（折叠式）

json

[
  {"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"}
]

json

[
  {"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

迭代循环追踪

json

[
  {"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"}
]

json

[
  {"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 ← {"timestamp","version":"1.1.0","action":"update","description":"..."}

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

1.0.0：初始周期 → 1.x.0：每次迭代（次版本号递增）
每次迭代：归档旧版本 → 完全重写主文档 → 追加至changes.log

归档：将requirements.md复制到history/requirements-v1.0.0.md
重写：用v1.1.0版本内容覆盖requirements.md（全新内容）
追加：向changes.log写入{"timestamp","version":"1.1.0","action":"update","description":"..."}

Agent输出	每次迭代重写	仅追加
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)

执行顺序：RA → EP → CD → VAS（依赖链，所有Agent并行启动但会等待依赖完成）

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

jsonl

{"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共享位于

coordination/discoveries.ndjson

的实时发现看板。每个Agent启动时读取该文件，并在工作中追加发现内容。这消除了重复的代码库探索。

生命周期:

由第一个写入发现内容的Agent创建（文件初始可能不存在）
跨迭代保留——从不清除或重建
Agent使用Bash命令
```
echo '...' >> discoveries.ndjson
```
追加条目

格式：NDJSON格式，每行是独立的JSON对象，包含必填顶级字段

ts

、

agent

、

type

、

data

jsonl

{"ts":"2026-01-22T10:00:00+08:00","agent":"ra","type":"tech_stack","data":{"language":"TypeScript","framework":"Express","test":"Jest","build":"tsup"}}

发现类型:

类型	去重键	写入Agent	读取Agent	必填 `data` 字段
`tech_stack`	单例	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`	单例	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`	单例	CD	VAS	`naming` , `imports` , `formatting`
`utility`	`data.name`	CD	VAS	`name` , `file` , `usage`
`test_command`	单例	CD, VAS	VAS, CD	`unit` , `integration` (可选), `coverage` (可选)
`test_baseline`	单例	VAS	CD	`total` , `passing` , `coverage_pct` , `framework` , `config`
`test_pattern`	单例	VAS	CD	`style` , `naming` , `fixtures`
`blocker`	`data.issue`	任意	所有	`issue` , `severity` , `impact`

协议规则:

开始自身探索前先读取看板 → 跳过已覆盖的内容（如果文件不存在则跳过）
立即通过Bash命令
```
echo >>
```
写入发现内容 → 不要批量处理
去重——检查现有条目；如果相同
```
type
```
+去重键值已存在则跳过
仅追加——绝不修改或删除现有行

Agent → Main Flow Communication

Agent → 主流程通信

PHASE_RESULT:
- phase: ra | ep | cd | vas
- status: success | failed | partial
- files_written: [list]
- summary: one-line summary
- issues: []

PHASE_RESULT:
- phase: ra | ep | cd | vas
- status: success | failed | partial
- files_written: [列表]
- summary: 单行总结
- issues: []

Main Flow → Agent Communication

主流程 → Agent通信

Feedback via

send_input

(file refs + issue summary, never full content):

undefined

通过

send_input

发送反馈（仅包含文件引用+问题总结，绝不传递完整内容）：

undefined

FEEDBACK FROM [Source]

[Issue summary with file:line references]

[带file:line引用的问题总结]

Reference

参考

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

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

Actions Required

需执行的操作

[Specific fix]


**Rules**: Only main flow writes state file. Agents read state, write to own `.progress/{agent}/` directory only.

[具体修复内容]


**规则**：仅主流程可写入状态文件。Agent仅读取状态，且仅写入自身的`.progress/{agent}/`目录。

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

立即启动：第一个操作是初始化TodoWrite，然后执行阶段1
渐进式阶段加载：仅当该阶段即将执行时才读取阶段文档
解析所有输出：从每个Agent提取PHASE_RESULT数据用于下一阶段
自动继续：每个阶段完成后，自动执行下一个待处理阶段
追踪进度：使用附加/折叠模式动态更新TodoWrite
单一写入者：仅主流程可写入主状态文件；Agent通过PHASE_RESULT报告状态
文件引用：在Agent之间传递文件路径，而非内容
持续执行：持续执行直到所有阶段完成或达到最大迭代次数

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

错误类型	恢复方式
Agent超时	发送要求收敛的send_input请求，然后重试
状态损坏	从进度Markdown文件和changes.log重建
Agent执行失败	使用之前的上下文重新启动Agent
结果冲突	主流程发送协调请求
文件缺失	RA/EP Agent识别问题并请求澄清
达到最大迭代次数	生成包含未解决问题的总结报告

Coordinator Checklist (Main Flow)

主流程协调器检查清单

Before Each Phase

每个阶段执行前

Read phase reference document
Check current state for dependencies
Update TodoWrite with phase tasks

读取阶段参考文档
检查当前状态的依赖项
更新TodoWrite的阶段任务

After Each Phase

每个阶段执行后

Parse agent outputs (PHASE_RESULT)
Update master state file
Collapse TodoWrite sub-tasks
Determine next action (continue / iterate / complete)

解析Agent输出（PHASE_RESULT）
更新主状态文件
折叠TodoWrite的子任务
确定下一步操作（继续/迭代/完成）

Reference Documents

参考文档

Document	Purpose
roles/	Agent role definitions (RA, EP, CD, VAS)

文档	用途
roles/	Agent角色定义（RA、EP、CD、VAS）

Usage

使用示例

bash

undefined

bash

undefined

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"

undefined

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

undefined