codex-ride-spec

# 启动 Spec Workflow 这是 `codex-ride` workflow 的用户入口。用户要新开 workflow、写 spec、或直接说 `/codex-ride-spec` 时，用这个 skill。 ## 核心规则 - 这是 spec 阶段入口，不直接进入 planning 或 execution - 只用 `codex-ride` CLI 操作 workflow state，不要直接编辑 `.codex-ride/session.json` 或其他 session state 文件 - spec 按 `docs/templates/spec-template.md` 的结构写 - 一次最多问一个阻塞问题；非阻塞假设写进 spec ## 流程 0. 建议用户切换模型: "建议使用高推理档位来写 spec；需要时可先切换模型。" 1. **强制 worktree gate** (避免 state 文件覆盖): - 执行 `pwd` 确认当前 CWD - 若 CWD 不在 `<project-root>/worktrees/<name>` 内 (即仍在主工作树或别处): - 询问用户 worktree 名 (新任务簇名 / 复用现有) - 新建: `git worktree add worktrees/<name> -b codex-ride/<name>` - 进入: `cd worktrees/<name>` (后续所有 `codex-ride` CLI 都在 worktree CWD 跑) - 若已在某 worktree 内: 直接继续, 该 worktree 的 `.codex-ride/session.json` 是本 spec 的独立 state - **关键**: `codex-ride` state 文件按 CWD 存; 不切 worktree 直接在主仓 init 新 spec, 会用 `--force` 覆盖既有 workflow state 2. 检测已有 workflow: 执行 `codex-ride state:get` - 如果已有 workflow 且 `spec_approved == true`: - 提示用户: "已有已批准的 workflow <workflow_id>, spec 在 <spec_path>。用 /codex-ride-run 继续执行。" - 停止, 不重复 init - 如果已有 workflow 且 `spec_approved == false` 且 `spec_path` 非空: - 提示用户: "发现未完成的 workflow <workflow_id>, spec 在 <spec_path>。" - 问用户: "继续编辑这个 spec, 还是放弃重开?" - 用户选继续 -> 跳到步骤 4, 读已有 spec 继续改 - 用户选重开 -> 执行 `codex-ride init --slug <slug> --force`, 走正常新建流程 - 如果没有 workflow (state:get 报错或 workflow_id 为空): - 确认或和用户约定 workflow slug, 执行 `codex-ride init --slug <slug>` 3. 执行 `codex-ride state:get`, 读取 `workflow_id` 4. 和用户一起按 `docs/templates/spec-template.md` 起草 spec。spec 必须包含： - 目标 - 非目标 - 约束 - 成功标准 - 架构与边界 - phase 假设 - 测试与验证预期 - 开放问题 5. 将 spec 落盘到 `docs/specs/<workflow-id>.md` 6. 执行 `codex-ride state:set --set spec_path=docs/specs/<workflow-id>.md` 7. 派 codex-worker 做对抗式 review：`codex-ride dispatch --job specAdversarialReview` 8. 如果 review 结果是 `pass`： - 向用户总结 review 结论 - **单独汇报外部依赖风险**: 从 review 文档读取 `external_dependency_risks` 段 - 若非 `none`, 逐条朗读给用户, 格式 `<依赖>: <风险> - 建议: <缓解>` - 明确告知用户: "以下风险不阻塞批准, 但建议知情; 最终报告会再次汇总。" - 若为 `none`, 简短告知 "无外部依赖风险记录" - 询问用户是否批准 spec - 用户批准后执行 `codex-ride state:set --set spec_approved=true --set spec_review_passed=true` - 明确提示用户：`spec 已批准。用 /codex-ride-run 启动执行。` 9. 如果 review 结果是 `revise`： - 总结关键问题、隐含假设、建议修改 - 和用户一起改 spec - 重新执行 `codex-ride dispatch --job specAdversarialReview` - **强制上限: 连续 2 轮 revise 后, 必须停止自动循环, 向用户展示累积问题清单, 让用户决定:** - 继续修改 spec 再审一轮 - override 剩余问题, 接受当前 spec - 放弃本次 workflow 10. 如果用户明确要求 override： - 记录 override 原因、范围、被跳过的 review 问题 - 把 override 写进 spec 的 `Override 记录` - 继续 review / approval 流程 ## 审查要求 - review 必须是对抗式，不是走过场 - 重点检查（critical 级）: 行为歧义、隐藏依赖、不可测成功标准（内部）、内部路径失败处理缺失、scope 大到无法 phase 化 - **外部依赖** (第三方 API / 外部服务) 的错误处理和测试覆盖单独归入 `external_dependency_risks`, 不进 critical, 不触发 revise - `开放问题` 不能留空；没有就写 `none` - `外部依赖风险` 不能留空；没有就写 `none` ## 退出条件 - `docs/specs/<workflow-id>.md` 已写好 - `spec_path` 已通过 `codex-ride state:set` 写回 state - spec review 已通过，或 override 已记录 - 用户已明确批准