easy-codex-writing-plans

name	easy-codex-writing-plans
description	当已有经用户批准的规格说明，需要在实现前编写分阶段实现计划、阶段拆解、文件影响、测试计划和执行交接文档时使用。

Easy Codex 编写实现计划

把已批准规格写成可执行计划。只在规格指定 worktree 内改计划文档。

用户选择

• “选择功能”指：可点击选择可用时必须用控件；工具不可用时用文本降级，给每个选项编号，列 2-3 个互斥选项，推荐项第一，要求用户回复编号数字、完整选项名或 其他: <自定义>；开放答案用“其他”，并允许用户直接输入自定义内容；禁止要求用户输入关键词或技能名。

强制门禁

规格未获批准前，禁止写计划。必须在规格记录的绝对 worktree 路径内工作；禁止在 main worktree 写入。计划阶段只能写/改 docs/plans/；禁止实现、改源文件、改测试或脚手架。必须用 sub-agent 审核计划；没有子代理能力则停止。计划完成、审核处理并经用户批准后，才能进入 $easy-codex-executing-plans 或 $easy-codex-review。

前置条件

• 已有用户批准规格，通常在 docs/specs/。
• 规格未批准：返回 $easy-codex-spec。
• 规格必须记录 主项目根、绝对 worktree 路径 和 显示路径；缺失或绝对路径字段是相对路径时，返回 $easy-codex-spec 补齐。
• 用 realpath 验证：绝对 worktree 路径必须等于 <主项目根>/<显示路径>，必须不是 main worktree，且必须出现在 git worktree list --porcelain。
• 规格必须记录 基准: <main HEAD SHA>、规格批准记录、审核状态、下一阶段许可；缺失则返回 $easy-codex-spec 补齐。
• 计划必须继承规格 基准，禁止改写。
• 多独立子系统：拆成多个可独立交付/验证的计划。
• 可并行任务：写入同一计划的并行组；不能证明写集独立时保持串行。

工作流

1. 声明使用本技能。
2. 读取规格字段 绝对 worktree 路径；相对路径直接阻塞。用 realpath 和 git worktree list --porcelain 验证后切入；git status --short。
3. 读规格、相关代码、测试、文档、配置。
4. 列预计创建/修改/测试文件和职责。
5. 按最小可验证增量拆阶段；每个阶段是执行期一次提交边界。可并行阶段必须记录并行组、依赖、写集和独立验证命令。
6. 写到 docs/plans/YYYY-MM-DD-<slug>.md。
7. 自检修正：规格覆盖、占位符、命名一致、命令可跑、顺序正确。
8. 派子代理审核；按“审核规则”处理。
9. 汇报路径、审核结论、剩余风险；用选择功能请求下一步：开始实现、先审计划、停止。

计划格式

# <功能名> 实现计划

- 目标：
- 架构：
- 技术栈：
- 规格来源：`docs/specs/<文件名>.md`
- 主项目根：
- 绝对 worktree 路径：
- 显示路径：`worktrees/<name>`
- 基准：`<继承规格基准，不可改写>`

## 流程状态
- 计划状态：草稿
- 计划批准记录：未批准
- 审核状态：未审核
- 下一阶段许可：未许可

## 文件结构
- 创建：`path/to/new-file`
- 修改：`path/to/existing-file`
- 测试：`path/to/test-file`

## 执行拓扑
- 默认：串行
- 并行组：`无` 或 `P1: 阶段 2, 阶段 3`
- 依赖：`阶段 4 依赖 P1 完成`
- 写集冲突检查：`无冲突` / `保持串行：<原因>`

## 阶段 1：<组件或行为>
- 并行组：无
- 依赖：无
- 写集：`path/to/file`
- 文件：
- [ ] 计划失败测试：代码或精确说明
- [ ] 确认失败：`<命令>`，预期 `<失败原因>`
- [ ] 计划最小实现：关键片段或精确说明
- [ ] 验证：`<命令>`，预期通过
- 提交信息：`<短提交信息>`

## 风险与回滚
- 风险：
- 缓解：
- 回滚：

## 最终验证
- [ ] `<命令>`：预期通过
- [ ] 手工检查：

## 对抗性审核
- 审核者：
- 结论：
- 已修正问题：
- 剩余风险：
- 用户处理决定：

规则

• 计划阶段只能在选定 worktree 内写/改 docs/plans/；不改源文件、测试、配置或脚手架。
• 禁止占位符：“待定”“稍后实现”“添加适当处理”“写相关测试”“类似任务 N”。
• 涉代码步骤必须给出足以执行的路径、命令、验收方式或关键接口；不要求提前写完整实现细节。
• 路径、命令、预期结果必须足以让实现子代理推进；可在实现中自然发现和修正的细节不阻塞。
• 阶段优先测试驱动：先计划测试，再计划实现，再计划验证；每阶段必须有提交信息。
• 目标和验收标准必须映射到阶段。
• 可并行阶段必须满足：写集不重叠、不共享迁移/配置/生成文件、无顺序依赖、验证命令可独立运行；否则保持串行并写明原因。
• 并行组内每个阶段必须列 并行组、依赖、写集 和独立验证。
• 风险、验证、回滚必须明确。
• 不主动扩大规格；发现规格缺口时，只有实现前必须由用户决策才回 $easy-codex-spec，否则记录为非阻塞建议。
• 计划审核以能否执行并支撑规格落地为目标；不要把计划审成完整实现设计。
• 派审前先按自检清单补齐常见缺口：必填字段、流程状态、目标/验收到阶段映射、每阶段验证、提交信息、路径命名一致性、占位符。
• 格式、字段、明显缺漏由控制器自动修正后再派审；只有影响阶段边界、范围或验证结论的问题才询问用户。
• 计划阶段的子代理只用于计划文档审核/修正，不是 $easy-codex-executing-plans 的写代码实现子代理；不得跨阶段保留或复用。

审核规则

自检后派新子代理审查。只给计划路径和规格路径，不给预期答案。计划审核子代理用完就关闭：返回后读完结果必须立即 close_agent；重审派新子代理。

要求子代理先判断计划能否执行并让规格落地：目标/验收覆盖、范围、阶段边界、并行证据、验证、路径/命令一致性是否足以开工。默认不阻塞，举证才阻塞；未发现明确阻塞问题时，结论必须为 通过；建议只能进入非阻塞建议。

只有以下问题才算阻塞：

• 阶段缺失导致规格目标或验收完全无法覆盖。
• 步骤、路径或命令缺失到实现子代理无法开始工作。
• 验证标准无法判断通过/失败。
• 违反明确流程门禁：worktree、基准、批准状态、下一阶段许可。
• 存在具体且不可逆的数据破坏、迁移失败、兼容破坏或安全风险，且计划未给处理边界。
• 存在实现前必须由用户决策的产品/范围问题。

以下不得算阻塞：

• 只是希望补更多背景、细节、示例或完整代码设计。
• 可在实现阶段自然拆解的技术步骤。
• 可通过默认假设推进，且假设错误影响已写明。
• 轻微范围漂移、测试补强建议、非关键边界条件、低概率异常、风格偏好。
• reviewer 无法指出具体失败模式的问题。

阻塞问题必须说明：如果不修正，会导致什么具体无法执行、错误实现或无法验收。不能说明具体失败模式时，降级为非阻塞建议。非阻塞建议不得阻止进入下一阶段。

子代理输出必须包含：

• 通过 或 需要修改
• 阻塞问题：每项含影响、明确建议、2-3 个备选处理方案、推荐选择
• 非阻塞建议：每项含收益、代价、可忽略条件
• 最小修正方向：指出计划章节或阶段

只有明确阻塞问题才允许输出 需要修改。若 需要修改，先分类处理：格式、字段、明显缺漏由控制器自动修正；真正阻塞问题才展示并请求选择。每个阻塞问题带建议、2-3 个备选方案、推荐选择，再用选择功能询问：

• 选择 再审一轮：按用户确认方向更新计划，再派新子代理审核。
• 选择 接受现状：把剩余风险和用户处理决定写入计划，视为风险已接受。
• 选择 停止计划：停止，不进入实现或 review。

同时提供“其他”输入入口；若用户自定义内容改变规格，返回 $easy-codex-spec。

执行交接

计划通过审核，或用户明确接受剩余风险后，用选择功能提供：

• 开始实现：使用 $easy-codex-executing-plans 用子代理按计划实现。
• 先审计划：使用 $easy-codex-review 做计划审查。
• 停止：不继续。

选择开始实现前，必须把 计划批准记录、审核状态、下一阶段许可 写入计划；否则 $easy-codex-executing-plans 必须阻塞。