easy-codex-writing-plans

# 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. 汇报路径、审核结论、剩余风险；用选择功能请求下一步：开始实现、先审计划、停止。 ## 计划格式 ````markdown # <功能名> 实现计划 - 目标： - 架构： - 技术栈： - 规格来源：`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` 必须阻塞。