菜单
Drive YorZ spec docs through plan / tasks / execute stages with deterministic state updates.
用 Codex 或 Claude 帮你安装 复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。
| name | yorz-spec |
| description | Drive YorZ spec docs through plan / tasks / execute stages with deterministic state updates. |
将单个 YorZ spec 文档作为状态机执行，围绕 plan / tasks / execute 三阶段推进，全部任务完成后进入终止态 done，把状态持续写回文档。md 是单一真相；Agent 持续推进直至阻塞（待确认项、决策、Review）或收尾为 done 才退出。
本 skill 文档结构精简为 3 个文件；每次接到 spec 任务时，按以下顺序按需 Read：
mermaid.md 与 references/ 目录仅按需 Read：只有在判断当前阶段需要输出 mermaid 图表「升维」时才加载，纯状态推进任务不必读取，以节省 context。plan 阶段的「图形化补充」收尾子步骤（见 stages.md）会针对 现状分析/技术方案 两节强制加载 mermaid.md 补图；补图须遵循其核心原则**「图优先、精确信息折叠」**——表层给图，精确细节折叠进 <details> 精确层。
当 Agent 以
mode=review/mode=git-ops启动时，按 review.md 执行；该路径不进入 plan/tasks/execute 状态机，也不修改 spec.md 的 frontmatter。
spec_path：可选，目标 spec 文档路径。
docs/specs/*.md 或 .yorz/specs/<id>/spec.md，直接更新该 spec。.yorz/specs，可由 <ProjectRoot>/.yorz/config.json 的 specsDir 字段覆盖。mode：可选，plan|tasks|execute|auto，默认 auto。！！！每个 spec md 顶部必须有 YAML frontmatter：
---
stage: plan # plan | tasks | execute | done
last_action: 简述上一次动作
updated_at: '2026-06-14 15:42:07' # 本地秒级字符串
summary: 一句话概要，≤ 200 字符
---
stage → last_action → updated_at → summary，每个字段独占一行，禁止嵌套与额外字段。updated_at 使用本地秒级 YYYY-MM-DD HH:mm:ss 字符串。npx prettier --write <spec_path>）；未配置则跳过。- [ ] / - [x]，避免缩进与嵌套。## / ### 出现顺序重新编号。## N. 标题（N 从 1 起）；三级标题 ### N.M 标题（M 在所属二级下从 1 起）。# ）。mode=auto 时，严格按顺序判定，命中即停：
spec_path 缺省：从 session 上下文恢复 spec 路径；恢复失败进入 新建 spec 流程 并以 plan 起步。## 追加任务 中是否存在 [open] 条目：存在即视为"新输入"信号，进入 plan（重开流程）。plan（重开流程）。！！！ 批注，进入 tasks。## 待确认项 下存在有效条目（非空态 _暂无_），停止推进并等待人工批注。stage 已是 done 且上述 1–5 均未命中（无新输入/批注/待确认项），直接停止：终止态不再自动推进。[manual] 任务（- [ ] 且非 - [ ] [manual]），进入 execute。[open]/新需求/批注/待确认项）：将 stage 置为 done 并停止推进（终止态）。## 技术实现方案 为空或明显不完整，进入 plan。章节名
## 待确认项为新名，parser/lint 兼容旧名## 待确认问题；存量 spec 保留旧名仍可识别，新建/重写一律用待确认项。待确认项判定：章节内存在任一
###三级标题即视为未决；仅有_暂无_或整章为空即视为无未决条目；存在未决条目时禁止进入 execute。
done判定忽略- [ ] [manual]人工确认项：即使 manual 项仍未勾选，只要其余任务全部完成、且无待确认项/批注/[open]，即可收尾为done。
初始化 spec 时建议创建以下章节（## 追加任务 ## 用户批注 为可选，由用户触发追加时懒插入）：
## 现状分析 / ## 技术实现方案 / ## 待确认项 / ## 任务清单 / ## 执行记录lint 不再强制校验章节齐全；但 routing 按章节名查找时，章节不存在视为空态。
触发条件：
stage 切回 plan，last_action 记录"变更重开流程"。## 追加任务 存在 - [open] [feat|refct|fix] ... 条目时，将 stage 切回 plan。重开后必须做的事：
plan → tasks → execute。[open] 状态标记。任何阶段完成对 spec.md / review.md 的写入后，Agent 必须通过 Bash 运行 yorz lint <path> --format json，并 parse stdout。
errorCount === 0 时视为通过。severity: error 时按 ruleId + message + line 定位并修改，然后重新运行 lint。## 待确认项 条目写入 spec.md 后退出，等待人工干预。warn 级 finding 不阻断推进，但应尽力消除。Agent 在 plan / tasks / execute 任意阶段，只允许因以下"合法阻塞"退出当轮：
## 待确认项 章节存在非 暂无 条目；！！！ 批注；plan；显式禁止以下"元确认"行为：
替代约定：tasks/execute 阶段若产生新疑问，必须作为新条目写回 ## 待确认项 并按变更重开流程退出。
兜底：对外部世界有副作用、不可逆的命令（如 git push、git reset --hard、rm -rf、修改 CI 配置等破坏性操作）仍按系统默认安全准则处理。
spec_path 即可。！！！ 批注，再由 CLI / Service 重新拉起 Agent 继续执行。