name: parallel-dev-cycle description: 使用需求分析、探索规划、代码开发和验证的多代理并行开发周期。编排内联在主流程中运行（无单独编排器代理）。支持带Markdown进度文档的持续迭代。触发条件为"parallel-dev-cycle"。 allowed-tools: spawn_agent, wait, send_input, close_agent, AskUserQuestion, Read, Write, Edit, Bash, Glob, Grep
平行开发周期
使用Codex子代理模式的多代理并行开发周期，包含四个专门工作代理：
- 需求分析与扩展 (RA) - 需求分析和自我增强
- 探索与规划 (EP) - 代码库探索和实现规划
- 代码开发 (CD) - 带调试策略支持的代码开发
- 验证与归档摘要 (VAS) - 验证和归档摘要
编排逻辑（阶段管理、状态更新、反馈协调）内联在主流程中运行 — 不产生单独编排器代理。只分配4个工作代理。
每个代理维护一个主文档（如requirements.md、plan.json、implementation.md），每次迭代完全重写，以及辅助日志（changes.log、debug-log.ndjson），它们是仅追加的。
架构概述
┌─────────────────────────────────────────────────────────────┐
│ 用户输入（任务） │
└────────────────────────────┬────────────────────────────────┘
│
v
┌──────────────────────────────┐
│ 主流程（内联编排） │
│ 阶段1 → 2 → 3 → 4 │
└──────────────────────────────┘
│
┌────────────────────┼────────────────────┐
│ │ │
v v v
┌────────┐ ┌────────┐ ┌────────┐
│ RA │ │ EP │ │ CD │
│代理 │ │代理 │ │代理 │
└────────┘ └────────┘ └────────┘
│ │ │
└────────────────────┼────────────────────┘
│
v
┌────────┐
│ VAS │
│ 代理 │
└────────┘
│
v
┌──────────────────────────────┐
│ 摘要报告 │
│ 和Markdown文档 │
└──────────────────────────────┘
关键设计原则
- 主文档 + 辅助日志：每个代理维护一个主文档（每次迭代重写）和辅助日志（仅追加）
- 基于版本的重写：每次迭代完全重写主文档；日志仅追加
- 自动归档：旧主文档版本自动归档到
history/目录 - 完整审计追踪：Changes.log (NDJSON) 保存所有变更历史
- 平行协调：同时启动四个代理；通过共享状态和内联主流程协调
- 文件引用：使用短文件路径而不是内容传递
- 自我增强：RA代理基于上下文主动扩展需求
- 共享发现板：所有代理通过
discoveries.ndjson共享探索发现 — 启动时读取，发现时写入，消除冗余代码库探索
参数
| 参数 | 必需 | 描述 |
|---|---|---|
| TASK | TASK或–cycle-id之一 | 任务描述（用于新周期，与–cycle-id互斥） |
| –cycle-id | TASK或–cycle-id之一 | 继续现有周期ID（来自API或先前会话） |
| –extend | 否 | 扩展描述（仅与–cycle-id有效） |
| –auto | 否 | 自动模式（顺序运行所有阶段，无需用户确认） |
| –parallel | 否 | 并行代理数量（默认：4，最大：4） |
自动模式
当使用--auto时：顺序运行所有阶段，无需用户确认迭代。对所有决策使用推荐默认值。自动继续迭代循环，直到测试通过或达到最大迭代次数。
预备包集成
当prep-package.json存在于{projectRoot}/.workflow/.cycle/prep-package.json时，阶段1使用它以：
- 使用精炼的任务描述代替原始TASK
- 应用自动迭代配置（收敛标准、阶段门控）
- 注入每迭代代理焦点指令（0→1 vs 1→100）
预备包由交互式提示/prompts:prep-cycle生成。参见phases/00-prep-checklist.md获取模式。
执行流程
输入解析：
└─ 解析参数（TASK | --cycle-id + --extend）
└─ 转换为结构化上下文（cycleId, state, progressDir）
阶段1：会话初始化
└─ 参考：phases/01-session-init.md
├─ 创建新周期或恢复现有周期
├─ 初始化状态文件和目录结构
└─ 输出：cycleId, state, progressDir
阶段2：代理执行（并行）
└─ 参考：phases/02-agent-execution.md
├─ 附加任务：生成RA → 生成EP → 生成CD → 生成VAS → 等待所有
├─ 并行生成RA、EP、CD、VAS代理
├─ 等待所有代理，含超时处理
└─ 输出：agentOutputs（4个代理结果）
阶段3：结果聚合与迭代
└─ 参考：phases/03-result-aggregation.md
├─ 从每个代理解析PHASE_RESULT
├─ 检测问题（测试失败、阻塞）
├─ 决策：发现问题且迭代 < 最大迭代？
│ ├─ 是 → 通过send_input发送反馈，循环回阶段2
│ └─ 否 → 继续到阶段4
└─ 输出：parsedResults, iteration status
阶段4：完成与摘要
└─ 参考：phases/04-completion-summary.md
├─ 生成统一摘要报告
├─ 更新最终状态
├─ 关闭所有代理
└─ 输出：最终周期报告，含继续说明
阶段参考文档（阶段执行时按需读取）：
| 阶段 | 文档 | 目的 |
|---|---|---|
| 1 | phases/01-session-init.md | 会话创建/恢复和状态初始化 |
| 2 | phases/02-agent-execution.md | 并行代理生成和执行 |
| 3 | phases/03-result-aggregation.md | 结果解析、反馈生成、迭代处理 |
| 4 | phases/04-completion-summary.md | 最终摘要生成和清理 |
数据流
用户输入（TASK | --cycle-id + --extend）
↓
[解析参数]
↓ cycleId, state, progressDir
阶段1：会话初始化
↓ cycleId, state, progressDir（初始化/恢复）
阶段2：代理执行
├─ 所有代理启动时读取coordination/discoveries.ndjson
├─ 每个代理探索 → 写入新发现到发现板
├─ 后续完成代理受益于先前代理的发现
↓ agentOutputs {ra, ep, cd, vas} + 共享discoveries.ndjson
阶段3：结果聚合
↓ parsedResults, hasIssues, 迭代计数
↓ [如果发现问题且迭代 < 最大，循环回阶段2]
↓（discoveries.ndjson跨迭代传递）
阶段4：完成与摘要
↓ finalState, summaryReport
返回：cycle_id, iterations, final_state
会话结构
{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 # 共享发现板（所有代理追加）
├── timeline.md # 执行时间线
└── decisions.log # 决策日志
状态管理
主状态文件：{projectRoot}/.workflow/.cycle/{cycleId}.json
{
"cycle_id": "cycle-v1-20260122T100000-abc123",
"title": "任务标题",
"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模式
阶段级追踪（附加任务）
[
{"content": "阶段1：会话初始化", "status": "completed"},
{"content": "阶段2：代理执行", "status": "in_progress"},
{"content": " → 生成RA代理", "status": "completed"},
{"content": " → 生成EP代理", "status": "completed"},
{"content": " → 生成CD代理", "status": "in_progress"},
{"content": " → 生成VAS代理", "status": "pending"},
{"content": "阶段3：结果聚合", "status": "pending"},
{"content": "阶段4：完成与摘要", "status": "pending"}
]
阶段级追踪（折叠）
[
{"content": "阶段1：会话初始化", "status": "completed"},
{"content": "阶段2：代理执行（4个代理完成）", "status": "completed"},
{"content": "阶段3：结果聚合", "status": "in_progress"},
{"content": "阶段4：完成与摘要", "status": "pending"}
]
迭代循环追踪
[
{"content": "阶段1：会话初始化", "status": "completed"},
{"content": "迭代1：代理执行 + 聚合", "status": "completed"},
{"content": "迭代2：反馈 → 重新执行 → 聚合", "status": "in_progress"},
{"content": "阶段4：完成与摘要", "status": "pending"}
]
版本控制
- 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":"..."}
| 代理输出 | 重写（每次迭代） | 仅追加 |
|---|---|---|
| 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（依赖链，所有并行生成但依赖阻塞）
共享发现板
所有代理共享实时发现板在coordination/discoveries.ndjson。每个代理启动时读取并在工作中追加发现。这消除冗余代码库探索。
生命周期：
- 由第一个写入发现的代理创建（文件可能初始不存在）
- 跨迭代传递 — 永不清除或重新创建
- 代理使用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(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 |
协议规则：
- 探索前读取发现板 → 跳过覆盖区域（如果文件不存在，跳过）
- 通过Bash
echo >>立即写入发现 → 不批处理 - 去重 — 检查现有条目；如果相同
type+ 去重键值已存在，跳过 - 仅追加 — 永不修改或删除现有行
代理 → 主流程通信
PHASE_RESULT:
- phase: ra | ep | cd | vas
- status: success | failed | partial
- files_written: [列表]
- summary: 一行摘要
- issues: []
主流程 → 代理通信
通过send_input反馈（文件引用 + 问题摘要，非完整内容）：
## 来自 [来源] 的反馈
[文件:行引用的问题摘要]
## 参考
- 文件：.progress/vas/test-results.json (v1.0.0)
## 必需行动
1. [具体修复]
规则：只有主流程写入状态文件。代理读取状态，只写入自己的.progress/{agent}/目录。
核心规则
- 立即开始：第一动作是TodoWrite初始化，然后执行阶段1
- 渐进阶段加载：仅当阶段即将执行时读取阶段文档
- 解析所有输出：从每个代理提取PHASE_RESULT数据供下一阶段使用
- 自动继续：每个阶段后，自动执行下一待定阶段
- 追踪进度：使用附加/折叠模式动态更新TodoWrite
- 单写入者：只有主流程写入主状态文件；代理通过PHASE_RESULT报告
- 文件引用：在代理间传递文件路径，非内容
- 不要停止：连续执行，直到所有阶段完成或达到最大迭代
错误处理
| 错误类型 | 恢复 |
|---|---|
| 代理超时 | send_input请求收敛，然后重试 |
| 状态损坏 | 从进度Markdown文件和changes.log重建 |
| 代理失败 | 用先前上下文重新生成代理 |
| 冲突结果 | 主流程发送协调请求 |
| 缺失文件 | RA/EP代理识别并请求澄清 |
| 最大迭代达到 | 生成摘要，记录剩余问题 |
协调者清单（主流程）
每个阶段前
- [ ] 读取阶段参考文档
- [ ] 检查当前状态的依赖
- [ ] 更新TodoWrite带阶段任务
每个阶段后
- [ ] 解析代理输出（PHASE_RESULT）
- [ ] 更新主状态文件
- [ ] 折叠TodoWrite子任务
- [ ] 决定下一步行动（继续 / 迭代 / 完成）
参考文档
| 文档 | 目的 |
|---|---|
| roles/ | 代理角色定义（RA, EP, CD, VAS） |
使用
# 开始新周期
/parallel-dev-cycle TASK="实施实时通知"
# 继续周期
/parallel-dev-cycle --cycle-id=cycle-v1-20260122-abc123
# 带扩展的迭代
/parallel-dev-cycle --cycle-id=cycle-v1-20260122-abc123 --extend="也添加邮件通知"
# 自动模式
/parallel-dev-cycle --auto TASK="添加OAuth认证"