Openspec Driven Development

OpenSpec 驱动的开发执行闭环

把一个开发任务从「需求」一路带到「代码落地 + 事实源归档」，先有经确认的方案、再写代码、写完让事实源反映现状。

这个 skill 的价值不在某一步，而在闭环本身：跳过方案直接写码会失控，写完不归档会让事实源慢慢失真。所以它的每一步都为同一个可观察结果服务——方案、代码、事实源三者始终一致。

项目有两套事实源（视项目而定）：

• openspec/specs//spec.md 是行为事实源，靠 change 的 spec-delta/ 流转更新。
• docs/wireframes/（若项目有）是版式事实源，靠 change 的 wireframes.md（本项目扩展，按需新建）流转更新。

归档时两套事实源一起更新——spec-delta 合并回 specs/，wireframes.md 回流到 docs/wireframes/。项目级归档约定写在 openspec/changes/AGENTS.md，这个 skill 是它的执行口径。

边界（和相邻 skill 的分工）

这个 skill 只管「已在 openspec 约定下的日常开发执行」——也包括咨询口吻的开发问题（「你会如何做 / 改 X」「X 做在哪里」）和 bug 讨论（「为什么 X 不对」），这些都从步骤 1 进。碰到下面的活，交出去、别自己干：

• 项目还没有 openspec/、要从零搭 AGENTS.md + openspec 骨架 → 停下，主动提议用 project-init-docs（见步骤 0）。
• 用户要打 tag / 写 changelog / 定版本号 → 交给 release。
• 非开发任务（问答、查资料、跑一条命令）→ 不触发，正常回答即可。
• 「符合」消歧：问「代码是否符合方案 / spec / 某个 change」→ 这是步骤 6，触发；问「项目是否符合规范 / 标准 / 约定」这类泛合规审计 → 与具体改动无关，不触发。

工作流总览

步骤0 识别开发任务 + openspec 检测 + 进场路由
   ├─非开发───────────────────────────> 终止
   ├─无 openspec──────────────────────> 停下，主动提议初始化（project-init-docs）
   └─有 openspec，按开场分流：
       "实施 openspec/changes/X" ───────> 直接进 步骤5
       "实施完了，检查是否符合方案/遗漏" ─> 直接进 步骤6
       微改动 ─────────────────────────> 步骤1 快车道
       其余开发任务 / 开发问题 / bug 讨论 ─> 步骤1
   │
步骤1 采访 / 诊断澄清目标
   ├─结论：不需要改代码──> 给出诊断/解释/结论，结束
   └─结论：需要改代码────> 步骤2
   │
步骤2 聊天框出方案（字符图 / 测试用例）→ agent 自审 → 自动到步骤3
   │
步骤3 检测/切到 feature 分支（NEVER 在 main/master 写入）→ 落盘 openspec/changes//
   │
步骤4 反思方案 → ✓ plan-written（出方案 + 落盘 + 反思整体视为 plan-written 完成）
   │
步骤5 按 spec 写代码（在 feature 分支上） → ✓ code-written
   │
步骤6 反思代码符合度 ──偏差──> 回步骤5 改 ──通过──> ✓ code-verified
   │
步骤7 归档（按 openspec/changes/AGENTS.md 的「归档」节）：
       ① changes// → changes/archive/-/
       ② spec-delta 合进 openspec/specs//
       ③ 若有 wireframes.md → 回流到 docs/wireframes/pages/.md 与 flow.md
   │
步骤8 更新 AGENTS.md → git commit（feature 分支）→ 有 remote 则 push + 开 PR（body 粘 proposal.md）→ ✓ pr-opened

CREATE A TODO LIST 覆盖步骤 0-8，每步做完更新状态。MUST 在步骤 0 末把推进计划（见下节）亮给用户、把"在哪状态停"接住，再开干；除非推进计划里写了停在某个状态，否则全程自动衔接。

---

状态枚举与外部锚点（v0.5 起精简）

整条流水线只有 6 个状态枚举，给外部（用户在 prompt 里、上游 skill、流程编排）一个稳定锚点，可指定「跑到某个状态就停」或「在某个状态额外做点什么」。中间的机械动作（切分支、落盘、归档、commit、push）合并到上下游枚举里，用自然语言报告进度即可，不再单独命名。

步骤 1 采访是 HARD STOP——interviewing 必须等用户回答，agent 不能自审通过、不能替答、不能跳过。其余状态默认 agent 自审通过后自动衔接，是否要变成"等用户拍板"由步骤 0 的推进计划决定。

最后的 pr-opened 是个特殊节点：有 remote 时始终去做（push feature 分支 + gh pr create），不再"问用户要不要推"——PR 是 reviewer 的介入点，不该被绕开。但 NEVER 自己合并 PR，合并由 reviewer 拍板。

状态枚举表

| 状态 | 含义 | 覆盖步骤 | 默认行为 | |---|---|---|---| | interviewing | LLM 正在采访 / 诊断，等用户回答 | 步骤 1 进行中 | 天然等用户（HARD STOP） | | interview-confirmed | 采访结束，目标明确，进入分叉（不改代码 → end；要改代码 → 继续）| 步骤 1 末 | 自动 | | plan-written | 方案出完 + 切 feature 分支 + 落盘 openspec/changes// + 反思通过 | 步骤 2 + 3 + 4 整体 | 自动（可被指定为停） | | code-written | 按 spec 的代码（含落地测试）写完 | 步骤 5 末 | 自动（可被指定为停） | | code-verified | 代码符合度反思通过、单测绿 / AI 验证流程跑通 | 步骤 6 末 | 自动（可被指定为停） | | pr-opened | 归档（移目录 + 合 spec-delta + 必要时回流 wireframes）+ 更新 AGENTS.md + commit + 有 remote 则 push + 开 PR | 步骤 7 + 8 整体 | 有 remote 时始终走 PR；无 remote 则在 commit 后结束 |

> 为什么不区分"进行中"和"完成"两套：除了 interviewing 是 HARD STOP 必须明示外，其他过程态（出方案中、写码中、验证中）agent 持续输出工具调用和文本本身就在告诉用户它在干活，不需要枚举名再标一遍。 > 为什么把切分支 / 落盘 / 反思 / 归档 / commit / push 都合并：这些是机械动作，不会有人想"停在切分支之后"。合并掉省了一半枚举，状态机简洁很多。失败时自然会报错，用户不需要枚举名也知道哪炸了。

推进计划的显示模板

步骤 0 一定下进场点，MUST 先在对话里明示推进计划，再开干——这是给用户最后一次「指定停在哪儿 / 加事」机会。三种形态：

A. 默认（全自动衔接）：

> 推进计划（步骤 1 采访会自然停下等你回答；其余自动衔接；最后有 remote 会推 feature 分支并开 PR）： > interviewing → interview-confirmed → plan-written → code-written → code-verified → pr-opened

B. 用户指定停在某状态（例：prompt 里写「方案给我看一眼再写码」）：

> 推进计划（按你要求在 plan-written 后停下，由你拍板再写码）： > interviewing → interview-confirmed → plan-written ⏹停⏹ code-written → code-verified → pr-opened

C. 用户指定在某状态额外做事（例：「在 plan-written 时同步把方案贴到 Slack」）：

> 推进计划（在 plan-written 触发额外动作：把方案贴 Slack）： > interviewing → interview-confirmed → plan-written ⨁[贴 Slack] → code-written → code-verified → pr-opened

形态可组合（既指定停、又指定额外动作）。符号 ⏹ / ⨁ 不是硬约定——核心是把状态枚举名写清楚，让用户能精确指认是哪一步。

> 为什么默认自动而不是逐步问：原来每一步都问"要不要继续"，对一条已经达成共识的链路是冗余，最终演成"用户疯狂回车"。采访（interviewing）是 agent 没法替代的对话往返，必然停；其他节点 agent 能自审，默认就别打扰用户。需要在 plan-written / code-written / code-verified 等用户拍板的，由用户在 prompt 里显式指定即可。 > 为什么要枚举名：让外部能精确指认"在哪儿停 / 在哪儿加事"。"在第 3 步停"是脆弱的（步骤编号会随版本漂移），"在 plan-written 停"是稳定的。

---

步骤 0 · 识别 + openspec 检测 + 进场路由

先判断这是不是一个开发相关任务（要写 / 改代码，或讨论怎么开发、排查 bug）。不是（纯查询、研究、装 skill、审稿、与具体改动无关的合规审计、单独的 git 操作）→ 终止本流程，正常回应。

是开发相关，再查仓库根有没有 openspec/ 目录：

• 没有 → 停下，不要自己搭骨架，但要主动提议：当前项目还没初始化 openspec，建议先用 project-init-docs（或 openspec init）搭好 openspec/specs + openspec/changes + AGENTS.md。征得同意可引导 / 协助初始化，完成后再回来走这条流水线。
• 有 → 按开场路由进场点（穷尽，带兜底）：

| 开场判据 | 进场点 | |---|---| | 实施 openspec/changes/（spec 已写好，只差实现）| 直接进 步骤 5 | | 实施完了 / 已完成，检查是否符合方案、有无遗漏 | 直接进 步骤 6 | | 一两个文件、几行的微改动 | 步骤 1 快车道 | | 其余开发任务 / 开发问题 / bug 讨论（含「为什么 X 不对」「你会如何做 X」）| 步骤 1 | | 否则（判不准）| 先问用户一句确认意图，再决定进场点或终止 |

> 为什么停下而不自动搭骨架：搭骨架会写入大量约定文件、改变仓库结构，属于一次性脚手架决策，应由用户显式发起、且有专门的 skill 负责。这里只「提议 + 引导」，不擅自改仓库结构。 > 为什么要进场路由：真实开场常常不是从需求起步，而是「实施已写好的 change」「检查刚实施的符合度」「先讨论 / 诊断一个 bug」。硬把它们拽回步骤 1 会重复劳动或答非所问。

步骤 0 末必做：进场点定下后，在对话里明示推进计划（按上节「推进计划的显示模板」给出 A / B / C 形态之一）——把整条状态链亮出来，告诉用户哪些自动跑、哪些会停、是否带额外动作。这是给用户的最后一次「指定停在哪儿 / 加事」机会，NEVER 跳过这一步直接进入步骤 1。

---

步骤 1 · 采访澄清真实目标

> ⏸ HARD STOP：本步骤必须与用户对话。「自动推进」不覆盖这一步，agent 不能自审通过、不能替用户回答、不能一上来就出方案。

目的是找到项目 / 这次改动的真实目标，而不是照着字面需求闷头做。采访时：

• 偏向小而隔离的 spec——把大需求切成边界清晰、能独立验证的小块，别一上来就铺一张大网。
• 关键决策逼用户显式确认，不要替他默认，避免漏掉他在意的取舍。
• 最后一个问题固定是：「还有要补充的吗？」——直到用户明确说没有了，才进入步骤 2。

问题型开场（bug 讨论 / 开发问题，如「为什么 X 不对」「你会如何做 X」）进来时，步骤 1 是诊断 + 澄清你到底想要什么结果，不必非走完整的项目目标采访——先把问题定位清楚、把期望结果问明白。

采访 / 诊断完，分叉（这是给「问题型开场」留的出口，因为它不一定要改代码）：

• 结论 需要改代码 → 进入步骤 2 出方案。
• 结论 不需要改代码（就是想搞懂 / 是预期行为 / 调个配置或用法就能解决）→ 给出诊断、解释或结论，干净结束——不强行造 openspec 变更、不写代码。

快车道（小任务旁路）：如果一眼看出这是一两个文件、几行就能完成的微改动，不要走完整采访。直接问用户「这个我可以直接改，要不要我直接动手？」——确认后跳过步骤 2-3 的重型方案，直接做改动。改完的去向写死，别留白：

• 动手前同样要做步骤 3a 的分支检测：在 main 上 → 切 feature 分支再改；已在合适 feature 分支 → 复用；unrelated 分支 → 停下问。微改动也 NEVER 直接 commit 到 main。
• 仍走步骤 6（代码反思，对照用户口头需求核一遍）。
• 跳过步骤 7：微改动没有 openspec/changes 文档可归档，不强行造一个。
• 步骤 8 照走：有受影响的文档就更新 → git commit（feature 分支） → 有 remote 则推分支并开 PR；快车道没有 proposal.md，PR body 用 commit message + 一两句口头描述补充。
• 逃逸口：动手中发现改动其实不小（碰了可测逻辑、远超几行、牵动多个文件）→ 立即停下回步骤 1 走完整流程，别在快车道里硬塞。

---

步骤 2 · 在聊天框先出方案

先把方案写在对话里给用户看，不要直接落盘。方案要让一个高级程序员看明白整体逻辑即可——写哪几个文件、各自职责、业务线怎么串、有哪些测试案例——不必细到函数签名、数据结构。

两类必须附带的产物：

1. 改页面 / 有视觉版式变化 → 必须出字符图（ASCII 线框），让用户在写码前就能确认版式。落盘时进 changes//wireframes.md（不进 design.md）；基线 MUST 引用 docs/wireframes/pages/.md，NEVER 引用其他 change 的 wireframes.md。
2. 测试门槛（见下表）触发 → 必须出单元测试用例 + AI 验证流程用例（AI 验证 = 用 playwright 截图 / 手动跑一遍 / 跑命令看输出这类可由 agent 执行的验证步骤）。

方案出完后, agent 以审稿人视角自审一遍, 没问题就直接进入步骤 3 落盘; 有不确定项才问用户。聊天框方案 + 落盘 + 反思整体合成一个 plan-written 状态——除非推进计划指定停在 plan-written, 否则不需要用户单独拍板。

测试门槛

| 改动情形 | 要求 | |---|---| | 含可测逻辑（纯函数 / 数据转换 / 解析 / 状态机 / 跨文件契约）| 必须有单元测试，与行数无关——30 行的金额计算也要测 | | 单文件改动 diff > 200 行（任意类型）| 强制停下，逐文件做可测性评估，在方案里回答每块"要不要测"；若"该测却不方便测"→ 方案必须包含拆分 / 重构使其可测的设计 | | 纯展示 / HTML / CSS / 文案（哪怕 > 200 行且无逻辑）| 记录豁免理由，走 AI 验证流程即可，不强制单测 |

> 为什么"不方便测就改架构"：一段逻辑测不了，几乎总是因为它把业务逻辑和 IO / DOM / 视图耦合在了一起。正确解法是拆开让它可测，而不是给测试开后门。行数（200）只是触发这场评估的警戒线，不是"要不要测"的唯一裁判——别让 250 行的纯 CSS 被逼着写单测。

---

步骤 3 · 切到 feature 分支 + 落盘方案

这里是对仓库的第一次写入，所以要先把分支隔离做对，再落盘。

3a. 检测当前分支状态

聊天框方案 agent 自审通过后，落盘前第一件事是 git status / git branch --show-current，按下表分流：

| 当前分支 | 处理 | |---|---| | 主分支（main / master / 项目约定的主干）| git fetch origin && git checkout -b origin/main 从最新 origin/main 切出 feature 分支。NEVER 在主分支上直接写入 openspec/changes/。| | 已为本 change 准备的 feature 分支（分支名含 change-id，或本分支已有 openspec/changes// 的痕迹）| 复用，跳过建分支动作，直接进入 3b。也别为同一 change 再切一个新分支。| | unrelated feature 分支（在做别的 change，与本 change 无关）| 停下问用户：是要在当前分支上接着做（合并到那个 PR）、还是 stash 后切回 main 重开新分支？得到答复再继续，NEVER 擅自落盘。| | detached HEAD / 工作区有未提交的不相关改动 | 停下问用户怎么处理，别擅自切。|

分支命名建议：用 change-id 当后缀，例如 change/ 或 feat/——按项目既有约定优先。

> 为什么不在主分支写：openspec/changes 写入 + 后续代码改动 + spec/wireframes 归档都是 PR 的一部分；让它们全部落在 feature 分支，PR diff 就是「方案 + 实现 + 事实源更新」的完整故事，reviewer 一眼能看完。 > 为什么要检测复用：步骤 0 进场点是「实施 openspec/changes/X」时，用户大概率已经在那个 change 的分支上了——再切一次只会建出空分支或脏分支。

3b. 落盘 openspec/changes//

确认分支无误后，按 openspec 规范写：

• 变更提案（proposal）+ 设计权衡（design）+ 任务拆解（tasks）+ spec-delta。
• 方案里有字符图 → 写进 wireframes.md（本项目扩展，按需新建；多页用 ## pages/.md 小节区分）。NEVER 塞进 design.md——design 管"怎么实现/权衡/风险"，字符图是版式制品，类型不同。
• NEVER 在 tasks.md 里写「归档时回流 wireframes」这种项目级动作——归档约定写在 openspec/changes/AGENTS.md，每个 change 不重复。

保持和项目已有 openspec 约定一致的文件命名与结构。

---

步骤 4 · 反思方案 → 标记 plan-written → 进入写码阶段

落盘后，以审稿人视角重读方案找遗漏：

• 有遗漏 → 直接改方案。
• 有不确定项 → 问用户，别自己拍板。
• 没问题 / 问完了 → 整个步骤 2-4 合成的 plan-written 状态视为完成。

plan-written 后默认自动进入步骤 5，不再单独问用户「是否开始写代码？」。推进计划指定停在 plan-written 时才停下等用户口令——用户说「开始写代码」（或等价明确指令）进入步骤 5；提了别的事按新指令做，该排期的新需求记一条临时插入的 TODO别丢。

> 为什么默认不硬等：之前每次都强行问"是否开始写代码"，对一条已经走过采访 + 方案确认的链路是冗余。把"什么时候让用户介入"交给步骤 0 的推进计划——用户想看就指定停在 plan-written，不想看就不指定。

---

步骤 5 · 按 spec 写代码

> 若从步骤 0 直接进来（「实施 openspec/changes/X」）：先确认 openspec/changes// 确实存在且方案完整——它存在意味着方案此前已被确认过，可直接实现；不存在或残缺 → 回退步骤 1/2 先把方案补全、确认，再实现。

严格按 openspec/changes// 里的方案写。方案里定义了的测试用例，这一步要真正落地成可运行的测试。

---

步骤 6 · 反思代码符合度

> 若从步骤 0 直接进来（「实施完了，检查是否符合方案」）：先定位对应的 change 方案文档（在 openspec/changes/ 或已归档的 archive/）作为对照基准；找不到基准 → 问用户指明是哪个 change，别凭空判符合度。

写完后对照方案逐条核：代码是否完整实现了方案、有没有偷工或跑偏。

• 有偏差 / 遗漏 → 回步骤 5 补齐。
• 完全符合、测试通过（单测绿 / AI 验证流程跑通）→ 进入步骤 7。

---

步骤 7 · 归档（事实源回流）

闭环的收尾，不能省。本步是 openspec/changes/AGENTS.md 的「归档」节的执行口径——MUST 完成下面三步，缺一不算归档（具体顺序以项目内该文件为准）：

1. 移动 change 目录：openspec/changes// → openspec/changes/archive/-/（按项目既有归档约定）。
2. 合并 spec-delta → specs：把 spec-delta/ 下对应业务域的增删改合并进 openspec/specs//spec.md——让行为事实源反映改完之后的现状。
3. 回流 wireframes.md → docs/wireframes/（仅当本 change 有 wireframes.md 时）：把字符图回填到 docs/wireframes/pages/.md；流转变化同步进 docs/wireframes/flow.md——让版式事实源反映改完之后的现状。与第 2 步同等地位，NEVER 省略。

> 为什么必须做：openspec/specs 和 docs/wireframes/ 分别是项目的行为事实源与版式事实源。只改代码不更新它们，下一次开发就会基于过时的事实源做决策（画字符图找不到当前基线、读 spec 看到失真规则）。归档是让闭环真正闭上的那一步。 > 项目没有 docs/wireframes/ 或本 change 没有 wireframes.md → 第 3 步天然跳过；不要为不需要回流的 change 强造一个 wireframes.md。

---

步骤 8 · 更新文档 + commit + 提 PR

• 更新 AGENTS.md 里受这次改动影响的部分（模块职责、约定、入口等）。
• git add + git commit 到 feature 分支（commit message 讲清这次变更做了什么、对应哪个 change）。NEVER 切回 main 提交、NEVER 直接 commit 到 main。
• 检查 remote：
• 有 remote：始终走 PR，不再 "问是否 push"——

1. git push -u origin 推 feature 分支。
2. 在写 body 之前，扫一遍当前对话上下文里有没有 issue 编号（用户消息出现 #123、"issue 123"、"修复/关闭/解决 issue 123"、或粘过 GitHub issue 链接）：

• 有 → PR body 第一行写 Closes #（多个用逗号分隔或多行），空一行后再接 proposal.md 正文。命令示例：

`` gh pr create --title "" \ --body "$(printf 'Closes #\n\n'; cat openspec/changes/archive/-/proposal.md)" ``

• 没有 → 退化回原命令：gh pr create --title "" --body "$(cat openspec/changes/archive/-/proposal.md)"。

PR body 主体直接粘 proposal.md，因为 proposal 本来就是 why / what / impact，正好是 PR 描述，无需二次编辑。

1. 把 PR URL 回报给用户。
2. NEVER 自己合并 PR / 自己 merge 到 main——合并由 reviewer 拍板。

• 没有 remote：本地 commit 到 feature 分支即结束；告诉用户没法提 PR（兑现 pr-opened 闸门的「无 remote 跳过」分支）。

> 为什么 PR 取代直接 push：直接 push 到主干等于让 reviewer 在事后看到既成事实——PR 是 reviewer 唯一的介入点，把它省掉等于把 code review 这层防御也省掉。把这一步设成始终走 PR（而不是 "问是否 push"），就是因为「问 push」太容易顺嘴答 "好"，而 PR 的存在本身才是约束。 > 为什么 body 直接粘 proposal.md：proposal 已经讲清了 why（动机）、what changes（改了什么）、impact（影响范围），这就是 PR description 该写的内容。再让 agent 二次概括只会失真，不如直接粘。

---

失败路径

• 不确定是不是开发任务 / 进场点判不准 → 先问用户一句确认意图，别默认进流程或猜进场点。
• openspec/ 缺失 → 停在步骤 0，主动提议并（经同意后）引导初始化，NEVER 擅自搭骨架改仓库结构。
• 没出方案就被要求写码 → 没有 plan-written 就不可能写码。提醒用户先出方案、回步骤 2；除非用户明确说"跳过方案直接写"。（注：plan-written 默认 agent 自审通过，不需要用户每次拍板——这是"自动推进"的设计，不是"绕过方案"）
• 测试该写却"不方便测" → 不是跳过测试的理由，而是回到方案改架构使其可测（步骤 2 测试门槛）。
• 写到一半发现方案有硬伤 → 停下回步骤 2 修方案、重新确认，别将错就错继续写。
• 当前在 main 上，已经误改了文件 → 别直接 commit。git stash → 切 feature 分支 → git stash pop → 再继续；改动彻底没必要时 git checkout -- 丢弃。
• 当前在 unrelated feature 分支上，但用户没明确同意"在此继续做" → 停下问，NEVER 擅自落盘 openspec/changes 或写代码——会污染另一个 PR。
• 没有 GitHub remote、gh 用不了（用 GitLab / Gitea / 自建）→ 用对应平台的 PR / MR 命令（如 glab mr create），或本地完成、把分支推上去后让用户去网页开 PR；NEVER 因此降级回 "直接 commit 到 main"。

防错红线

• NEVER 跳过方案直接写代码——plan-written 必经，方案必须落盘到 openspec/changes/。
• NEVER 在推进计划里指定停在 plan-written 的情况下，用户没说"开始写代码"就动代码。
• NEVER 在没有 openspec 的项目里自己搭骨架——停下引导 project-init-docs。
• NEVER 因"不方便单测"就跳过测试——改架构使其可测。
• NEVER 漏掉闭环收尾：写完代码必须按步骤 7 完成归档——移动 change、合并 spec-delta、有 wireframes.md 时必须回流到 docs/wireframes/——再走步骤 8 更新 AGENTS.md。漏回流 wireframes 等于让版式事实源失真，与漏合并 spec-delta 同等严重。
• NEVER 在 main / master / 项目主干分支上做任何写入——包括 openspec/changes 落盘、代码改动、归档动作；步骤 3a 的分支检测必须做。
• NEVER 直接 push 到主干；NEVER 自己合并 PR——开 PR 是 reviewer 的介入点，合并由 reviewer 拍板。
• NEVER 在 unrelated feature 分支上擅自落盘——会污染别人的 PR；停下问用户。
• NEVER 在步骤 0 不明示推进计划就闷头进入步骤 1——用户没机会指定"在哪儿停 / 在哪儿加事"，自动推进就退化成失控。
• NEVER 把"自动推进"理解成"连步骤 1 采访也跳过"——interviewing 是 HARD STOP，对话往返本身是 interview-confirmed 状态的兑现过程，没法替用户答。

---

示例

用户：「给卡片导出加一个『一键导出全系列』的功能。」

流程：

1. 步骤0：是开发任务；仓库有 openspec/ → 继续。明示推进计划（默认形态）：

> 推进计划（步骤 1 采访会自然停下等你回答；其余自动衔接；最后有 remote 会推 feature 分支并开 PR）： > interviewing → interview-confirmed → plan-written → code-written → code-verified → pr-opened

1. 步骤1（interviewing）：采访——「全系列指当前预览里的所有卡片还是某个目录下的？导出命名规则？失败的卡片是跳过还是中断？」最后问「还有补充吗？」用户确认无补充 → ✓ interview-confirmed。
2. 步骤2：聊天框出方案——新增 scripts/export-all.mjs（遍历系列、复用单卡导出逻辑），改 app.html 加一个按钮（有视觉变化 → 附字符图，基线引用 docs/wireframes/pages/app.md）。导出逻辑含可测的文件名生成 / 系列遍历（可测逻辑 → 附单测用例：文件名生成、空系列、部分失败），再附 AI 验证流程（playwright 跑一遍导出、截图核对产物数量）。
3. 步骤3：先做分支检测——git branch --show-current 显示在 main → git fetch origin && git checkout -b change/add-export-all origin/main。再写入 openspec/changes/add-export-all/（proposal + design + tasks + spec-delta + wireframes.md 含字符图）。
4. 步骤4：反思方案，发现没定义"部分失败时是否继续"——这是不确定项，回去问用户、得到回答后补进方案 → ✓ plan-written。推进计划默认没指定停在 plan-written → 自动放行进入步骤 5。
5. 步骤5-6：按 spec 实现 → ✓ code-written；单测绿、playwright 验证导出数量正确 → ✓ code-verified。
6. 步骤7：按 openspec/changes/AGENTS.md 的「归档」节三步并列——① add-export-all/ 移到 archive/2026-06-29-add-export-all/；② 导出能力的 delta spec 合进 openspec/specs/export/；③ wireframes.md 的字符图回流到 docs/wireframes/pages/app.md（按钮变更同步进 flow.md 相关流程节）。
7. 步骤8：更新 AGENTS.md 的脚本清单 → git commit 到 change/add-export-all 分支 → git push -u origin change/add-export-all → gh pr create --title "" --body "$(cat openspec/changes/archive/2026-06-29-add-export-all/proposal.md)" → ✓ pr-opened，把 PR URL 回报给用户。不自己合并。

用户：「为什么我删一个操作员，下面删除预览里却列出了一大串操作员？我们先讨论清楚再决定动不动手——别急着写码。」

流程（问题型开场 + 用户指定停顿，可能不改代码）：

1. 步骤0：是 bug 讨论、仓库有 openspec/ → 路由进 步骤 1（不是从需求起步）。用户 prompt 里说「先讨论清楚」≈ 跑到 interview-confirmed 就停，明示推进计划（B 形态）：

> 推进计划（按你要求在 interview-confirmed 后停下，先把诊断结果摆给你再决定要不要改）： > interviewing → interview-confirmed ⏹停⏹ plan-written → code-written → code-verified → pr-opened

1. 步骤1（interviewing）：诊断——读删除预览的查询逻辑，定位到"预览把同组关联操作员一并列出"。澄清期望结果：「你是觉得根本不该显示这些，还是显示但要标清它们是关联项？」
2. 分叉（→ ✓ interview-confirmed）：

• 用户说「哦原来是关联项，预期的，不用改」→ 给出解释、干净结束，不写 openspec、不改代码。
• 用户说「应该只显示目标本人」→ 结论=需要改 → 进 步骤 2 出方案，走正常闭环。

用户：「给卡片导出加一个『一键导出全系列』的功能。」

WRONG 的做法：

• 直接开始写 export-all.mjs 和改 app.html，跳过采访和方案。
• 写完就说"做好了"，没写任何测试。
• 没把变更落到 openspec/changes，也没归档 delta spec 到 openspec/specs。
• 在 main 分支上直接 git commit + git push origin main，没开 PR。

为什么错：跳过方案 = 用户没机会在写码前纠偏（比如他其实只想导出当前预览那几张）；不写测试 = 文件名生成 / 部分失败这些可测逻辑无保障；不归档 = openspec/specs 与代码现状脱节，下次开发踩坑；直接推 main = 越过了 PR review 这层防御，reviewer 在事后看到既成事实。这个 skill 存在的全部意义就是堵住这四个口子。

用户：「给卡片导出加一个『一键导出全系列』的功能。」（没在 prompt 里指定停在哪儿）

WRONG 的做法：

• 出完方案在聊天框问「方案 OK 吗？要我落盘吗？」等用

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: tranfu-labs
• Source: tranfu-labs/tranfu-skills
• License: MIT

Install and usage instructions live in the source repository linked above.