| 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
流程
- 建议用户切换模型: "建议使用高推理档位来写 spec；需要时可先切换模型。"
- 强制 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
- 检测已有 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>
- 执行
codex-ride state:get, 读取 workflow_id
- 和用户一起按
docs/templates/spec-template.md 起草 spec。spec 必须包含：
- 目标
- 非目标
- 约束
- 成功标准
- 架构与边界
- phase 假设
- 测试与验证预期
- 开放问题
- 将 spec 落盘到
docs/specs/<workflow-id>.md
- 执行
codex-ride state:set --set spec_path=docs/specs/<workflow-id>.md
- 派 codex-worker 做对抗式 review：
codex-ride dispatch --job specAdversarialReview
- 如果 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 启动执行。
- 如果 review 结果是
revise：
- 总结关键问题、隐含假设、建议修改
- 和用户一起改 spec
- 重新执行
codex-ride dispatch --job specAdversarialReview
- 强制上限: 连续 2 轮 revise 后, 必须停止自动循环, 向用户展示累积问题清单, 让用户决定:
- 继续修改 spec 再审一轮
- override 剩余问题, 接受当前 spec
- 放弃本次 workflow
- 如果用户明确要求 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 已记录
- 用户已明确批准
