parallel-dev-cycle

并行开发周期

使用 Codex 子 Agent 模式的多 Agent 并行开发周期，包含四个专用工作者：

1. 需求分析与扩展（RA）- 需求分析与自我增强
2. 探索与规划（EP）- 代码库探索与实施规划
3. 代码开发（CD）- 代码开发，并提供调试策略支持
4. 验证与归档摘要（VAS）- 验证与归档摘要

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

每个 Agent 维护一份主文档（例如 requirements.md、plan.json、implementation.md），每次迭代都会完全重写；另有仅追加的辅助日志（changes.log、debug-log.ndjson）。

架构概览

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

关键设计原则

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

参数

Arg	必填	描述
TASK	TASK 或 --cycle-id 二选一	任务描述（用于新周期，不能与 --cycle-id 同时使用）
--cycle-id	TASK 或 --cycle-id 二选一	要继续的现有周期 ID（来自 API 或先前会话）
--extend	否	扩展描述（仅在使用 --cycle-id 时有效）
--auto	否	自动周期模式（按顺序运行所有阶段，无需用户确认）
--parallel	否	并行 Agent 数量（默认：4，最多：4）

自动模式

使用 --auto 时：按顺序运行所有阶段，迭代之间无需用户确认。所有决策均使用建议的默认值。自动持续迭代，直到测试通过或达到最大迭代次数。

Prep Package 集成

当 {projectRoot}/.workflow/.cycle/prep-package.json 存在时，Phase 1 会使用它来：

• 使用经过优化的任务描述，而非原始 TASK
• 应用自动迭代配置（收敛标准、阶段门控）
• 注入每次迭代的 Agent 重点指示（0→1 对比 1→100）

Prep package 由交互式提示词 /prompts:prep-cycle 生成。架构请参阅 phases/00-prep-checklist.md。

执行流程

Input Parsing:
   └─ Parse arguments (TASK | --cycle-id + --extend)
   └─ Convert to structured context (cycleId, state, progressDir)
   └─ Initialize progress tracking: functions.update_plan([...phases])

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 followup_task, 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	生成最终摘要并清理

数据流

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

会话结构

{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

{
  "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 重建。

进度跟踪

初始化（必须）

// Initialize progress tracking after input parsing
functions.update_plan([
  { id: "phase-1", title: "Phase 1: Session Initialization", status: "in_progress" },
  { id: "phase-2", title: "Phase 2: Agent Execution", status: "pending" },
  { id: "phase-3", title: "Phase 3: Result Aggregation", status: "pending" },
  { id: "phase-4", title: "Phase 4: Completion & Summary", status: "pending" }
])

阶段转换

// After Phase 1 completes
functions.update_plan([
  { id: "phase-1", status: "completed" },
  { id: "phase-2", status: "in_progress" }
])

// After Phase 2 completes
functions.update_plan([
  { id: "phase-2", status: "completed" },
  { id: "phase-3", status: "in_progress" }
])

// After Phase 3 — iterate or complete
// If iterating back to Phase 2:
functions.update_plan([
  { id: "phase-3", status: "completed" },
  { id: "phase-2", title: "Phase 2: Agent Execution (Iteration N)", status: "in_progress" }
])
// If proceeding to Phase 4:
functions.update_plan([
  { id: "phase-3", status: "completed" },
  { id: "phase-4", status: "in_progress" }
])

// After Phase 4 completes
functions.update_plan([{ id: "phase-4", status: "completed" }])

版本管理

• 1.0.0：初始周期 → 1.x.0：每次迭代（次版本号递增）
• 每次迭代：归档旧内容 → 完全重写 → 追加到 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 输出	重写（每次迭代）	仅追加
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

协调协议

执行顺序：RA → EP → CD → VAS（依赖链，全部并行启动，但会等待依赖项）

共享探索看板

所有 Agent 共用实时探索看板 coordination/discoveries.ndjson。每个 Agent 启动时都会读取看板，并在工作期间追加发现内容。这可以避免重复探索代码库。

生命周期：

• 由首个写入探索发现的 Agent 创建（文件最初可能不存在）
• 在各次迭代间保留，不会清空或重新创建
• Agent 使用 Bash echo '...' >> discoveries.ndjson 追加条目

格式：NDJSON，每行都是独立的 JSON，包含必需的顶层字段 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"}}

探索发现类型：

type	去重键	写入者	读取者	data 必需字段
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（可选）、coverage（可选）
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

协议规则：

1. 先读取看板，再自行探索 → 跳过已覆盖的区域（如果文件不存在，则跳过）
2. 立即通过 Bash echo >> 写入探索发现 → 不要批量写入
3. 去重——检查已有条目；如果相同的 type 和去重键值已存在，则跳过
4. 仅追加——绝不修改或删除已有行

Agent → 主流程通信

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

主流程 → Agent 通信

通过 followup_task 提供反馈（文件引用 + 问题摘要，绝不提供完整内容）：

## FEEDBACK FROM [Source]
[Issue summary with file:line references]
## Reference
- File: .progress/vas/test-results.json (v1.0.0)
## Actions Required
1. [Specific fix]

规则：只有主流程可以写入状态文件。Agent 读取状态，只能写入自己的 .progress/{agent}/ 目录。

核心规则

1. 立即开始：第一个操作是初始化 functions.update_plan，然后执行阶段 1
2. 逐步加载阶段内容：仅在即将执行某个阶段时读取该阶段的文档
3. 解析每项输出：从每个 Agent 提取 PHASE_RESULT 数据，供下一阶段使用
4. 自动继续：每个阶段结束后，自动执行下一个待处理阶段
5. 跟踪进度：在每次阶段转换时更新 functions.update_plan
6. 单一写入者：只有主流程可以写入主状态文件；Agent 通过 PHASE_RESULT 报告
7. 文件引用：在 Agent 之间传递文件路径，而非内容
8. 不得停止：持续执行，直至所有阶段完成或达到最大迭代次数

错误处理

错误类型	恢复方式
Agent 超时	请求 followup_task 进行收敛，然后重试
状态损坏	根据进度 Markdown 文件和 changes.log 重新构建
Agent 失败	使用先前的上下文重新启动 Agent
结果冲突	主流程发送协调请求
文件缺失	RA/EP Agent 识别问题并请求澄清
达到最大迭代次数	生成摘要，并记录剩余问题

协调器检查清单（主流程）

每个阶段开始前

• 阅读阶段参考文档
• 检查当前状态中的依赖项
• 使用阶段状态更新 functions.update_plan

每个阶段结束后

• 解析 Agent 输出（PHASE_RESULT）
• 更新主状态文件
• 更新 functions.update_plan 中的阶段完成状态
• 确定下一步操作（继续 / 迭代 / 完成）

参考文档

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

用法

# 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"