easy-codex-spec

name	easy-codex-spec
description	当用户希望在实现前澄清需求、编写规格说明、设计说明或需求文档，定义范围、非目标、验收标准、验证计划和风险，或任务模糊且直接实现容易跑偏时使用。

Easy Codex 规格说明

把模糊或高风险任务写成可实现、可验证的规格。除创建/选择工作树外，只改规格文档。

用户选择

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

强制门禁

从规格阶段开始必须使用 git worktree。工作树必须位于主项目根目录 worktrees/<name>；禁止在 main worktree 写入项目文件。设计未获批准前，禁止实现、改源文件、改测试或脚手架。必须用 sub-agent 审核规格；没有子代理能力则停止。规格完成、审核处理并经用户批准后，才能进入 $easy-codex-writing-plans。

工作树门禁

• 先用 git rev-parse --show-toplevel 和 git worktree list --porcelain 找主项目根目录。
• 根据用户需求推荐 2-3 个安全的 worktree name，用选择功能让用户选；同时提供“其他”输入入口。
• worktree name 必须匹配 ^[a-z0-9][a-z0-9._-]{0,63}$；拒绝 /、..、绝对路径和空白。
• 先 canonicalize <主项目根>；mkdir -p <主项目根>/worktrees 是 main worktree 唯一允许的管理写入；再 canonicalize worktrees 父目录。
• 目标不存在时先用 git worktree add <主项目根>/worktrees/<name> 创建专用分支；创建后再 realpath 目标，确认仍在 <主项目根>/worktrees/ 下。
• 目标已存在且是已注册 git worktree：展示 git status --short，用选择功能确认复用、换名或停止；脏 worktree 必须明确选择继续、换名或停止。
• 目标已存在但不是已注册 git worktree：阻塞，用选择功能选择换名或停止。
• 基准 必须在创建/复用 worktree 时立即写入 main worktree 当前 HEAD SHA，后续只能继承，禁止执行后补写或改写。
• 创建后切到该 worktree 写 docs/specs/；main worktree 除 worktree 管理命令和创建 worktrees/ 父目录外，不改项目文件。

路由

• 用：规格/设计/需求/验收；范围不清；影响多文件、接口、流程、数据。
• 不用：执行已批准且审核已处理的计划 -> $easy-codex-executing-plans；审查 -> $easy-codex-review；交付 -> $easy-codex-ship。

工作流

1. git status --short。
2. 推荐并选择 worktree name，创建/切换到绝对 worktree 路径。
3. 在选定 worktree 读相关代码、测试、README、文档、配置；事实自己查。
4. 一问一答澄清，只问最高影响问题；有限候选答案必须用选择功能。
5. 清楚后提出 2-3 个方案、取舍、推荐方案。
6. 展示设计摘要，用选择功能获批：批准设计、调整设计、停止规格。
7. 评估规格规模和预计计划阶段数；规模过大、跨多子系统或预计需要很多阶段时，先建议拆分规格，从最小可交付项开始。
8. 写到 docs/specs/YYYY-MM-DD-<slug>.md。
9. 自检修正：占位符、矛盾、歧义、范围过大、不可测试验收。
10. 派子代理审核；按“审核规则”处理。
11. 汇报 worktree、路径、假设、开放问题、审核结论；用选择功能请求下一步：进入实现计划、继续修改规格、停止。

文档格式

# <任务名称> 规格说明

## 背景
- 问题：
- 事实：

## 工作树
- 主项目根：
- 绝对 worktree 路径：
- 显示路径：`worktrees/<name>`
- 分支：
- 基准：`<main HEAD SHA>`

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

## 目标
-

## 非目标
-

## 范围
- 包含：
- 不包含：

## 方案
- 推荐方案：
- 备选方案 1：
- 备选方案 2：
- 取舍：

## 影响面
- 文件/模块：
- 接口/数据契约：
- 兼容性：

## 验收标准
- [ ] 标准 1
- [ ] 标准 2

## 验证计划
- 自动化验证：
- 手工验证：
- 不验证项及原因：

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

## 开放问题
- [ ] 问题 / 影响 / 假设

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

规则

• 规格阶段只在选定 worktree 内改规格文档；不改源文件、测试、配置或脚手架。
• 已有相关规格说明时优先更新，不重复创建。
• 会改变实现方向的问题先用选择功能决策；开放问题不能替代关键验收。
• 默认假设要标明错误影响。
• 验收标准必须可测试或可人工明确判断。
• 规格审核只保证目标、边界、验收和验证足以进入计划；不要把规格审成完整设计。
• 规格过大或预计实现计划会拆出很多阶段时，必须建议拆分规格；用选择功能提供：拆分规格、保留单规格、停止。
• 派审前先按自检清单补齐常见缺口：必填字段、流程状态、目标/范围/验收/验证映射、风险、开放问题、占位符、路径和命名一致性。
• 格式、字段、明显缺漏由控制器自动修正后再派审；只有影响设计方向、范围或验收的问题才询问用户。
• 规格阶段的子代理只用于规格文档审核/修正，不是 $easy-codex-executing-plans 的写代码实现子代理；不得跨阶段保留或复用。
• 选择进入实现计划前，必须把 规格状态 更新为已批准，把 规格批准记录 写入用户批准时间/方式，把 审核状态 写为通过或风险已接受，把 下一阶段许可 写为允许进入 $easy-codex-writing-plans；否则 $easy-codex-writing-plans 必须阻塞。

审核规则

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

要求子代理先判断规格能否落地：目标、非目标、范围、验收、验证、风险和方案比较是否足以进入计划。默认不阻塞，举证才阻塞；未发现明确阻塞问题时，结论必须为 通过；建议只能进入非阻塞建议。

只有以下问题才算阻塞：

• 会导致两个合理实现产生不同的用户可见行为、数据结果或 API 契约。
• 验收标准无法判断通过/失败。
• 违反明确流程门禁：worktree、基准、批准状态、下一阶段许可。
• 存在具体且不可逆的数据破坏、迁移失败、兼容破坏或安全风险，且规格未给处理边界。
• 存在实现前必须由用户决策的产品/范围问题。

以下不得算阻塞：

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

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

子代理输出必须包含：

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

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

• 选择 再审一轮：按用户确认方向更新规格，再派新子代理审核。
• 选择 接受现状：把用户接受的剩余风险写入 对抗性审核，继续请求规格批准。
• 选择 完全拒绝：停止，不进入 $easy-codex-writing-plans、实现或 review。

同时提供“其他”输入入口；若用户自定义内容改变设计、范围或验收标准，更新规格说明并重新审核。