codex-ride-spec

name	codex-ride-spec
description	Use when the user wants to start or continue a codex-ride workflow, write a spec, or says '/codex-ride-spec'. Guides spec drafting, resume, and adversarial review.

启动 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 已记录
• 用户已明确批准