OpenSpec-FissionAI（规范驱动开发）

在 WorkBuddy 中驱动 OpenSpec 的规范驱动开发工作流。
OpenSpec 在任意代码库之上加一层轻量“规范层”，让人和 AI 在动手写代码之前先就“做什么”达成一致
（需求 + 验收场景），随后按清单追踪实现进度，并在归档时把规范增量合并进权威目录 openspec/specs/。

品牌名：OpenSpec-FissionAI。技术技能 id：openspec-fissionai。

何时启用本技能

只要命中下面任意一类信号就启用本技能——不要等用户说出"用 OpenSpec"三个字才反应：很多用户的口语是「先规划 / 先对齐 / 先定 spec」这类表达，同样要接住。

触发词 / 触发语（命中任意一条即启用）

中文口语 / 需求表达：
- "用 OpenSpec 规划" / "用 OpenSpec 管理代码变更" / "跑 openspec" / "openspec 工作流"
- "写个 spec" / "写 spec" / "创建 spec" / "生成 spec" / "出一份 spec"
- "规范驱动开发" / "规格驱动开发" / "spec 驱动开发" / "spec-driven" / "规格驱动"
- "先定 spec 再写代码" / "先写需求再写代码" / "先设计后编码" / "先规划后实现"
- "先把需求写清楚再动手" / "先对齐需求再动手" / "动手前先规划" / "改之前先想清楚"
- "验收场景" / "验收标准" / "验收用例" / "验收点"
- "变更提案" / "写 proposal" / "写提案" / "提案一个变更" / "提个变更"
- "delta spec" / "增量规范" / "需求增量" / "增量需求"
- "编码前先评审方案" / "评审变更方案" / "动手前评审一下"
- "规划代码变更" / "规划一个功能" / "规划这次修复" / "规划下这次改动"
- "技术方案对齐" / "架构方案先对齐" / "改动方案先对齐"

OpenSpec CLI 命令（用户提到任一即启用）：
- openspec new change / openspec new / openspec init / openspec onboard
- openspec instructions / openspec status / openspec list / openspec show
- openspec apply / openspec archive / openspec validate / openspec update
- openspec continue / openspec sync-specs / openspec doctor / openspec context

英文 / 术语：
- "OpenSpec"、"spec-driven development"、"write a spec"、"create a proposal"、"delta specs"
- "ADDED / MODIFIED / REMOVED requirements"、"proposal → specs → design → tasks"

适用场景

• 用户想用明确的需求 + 验收场景规划某个功能 / 修复，而不是边写边想。
• 在全新（greenfield）或已有（brownfield）项目中落地 OpenSpec 规范层。
• 正在实现或归档一个进行中的 OpenSpec 变更。
• 编码前需要评审一份变更方案（proposal / delta specs / design / tasks）。

不适用（不要误触发）

• 纯 git 操作、通用项目管理、看板 / 任务追踪工具——本技能只封装 OpenSpec 的 spec 规划→实现→归档流程。
• 用户已清楚要改哪几行代码、只想直接改——直接进 coding，不必先开 spec。

心智模型（完整说明见 references/concepts.md）

openspec/
├── specs/            # 权威来源——系统“当前”的行为（按领域划分）
│   └── <capability>/spec.md
├── changes/          # 拟议的修改——每个变更一个文件夹
│   └── <change-name>/
│       ├── proposal.md        # 为什么 + 做什么（意图、范围、方案）
│       ├── specs/<cap>/spec.md# DELTA 规范：ADDED / MODIFIED / REMOVED 需求
│       ├── design.md          # 怎么做（技术方案、决策、取舍）
│       ├── tasks.md           # 实现清单（- [ ] 条目）
│       └── .openspec.yaml     # 变更元数据（schema、skip_specs、retire_capabilities）
└── changes/archive/  # 已完成变更归档于此，保留完整上下文

• 规范（Specs） = 行为契约（可观察行为，而非实现细节），用 SHALL/MUST 措辞。
• 变更（Changes） = 增量提案，多个可并行存在、互不冲突。
• Delta 规范用 ## ADDED Requirements / ## MODIFIED Requirements / ## REMOVED Requirements。
  归档时这些增量会合并进主规范——这正是 OpenSpec 能在已有代码上工作的原因：你只指定“改了什么”，
  而不是整套系统。
• 归档（Archive）把增量合并进 specs/，并把变更移入 changes/archive/。

默认工作流 schema 为 spec-driven：
proposal → specs → design → tasks → implement →（verify）→ archive。

WorkBuddy 如何驱动 OpenSpec（无需 slash 命令外壳）

OpenSpec 自带的 agent 技能使用 /opsx:propose 风格 slash 命令。WorkBuddy 没有这类命令入口，
因此通过 openspec CLI（Bash）驱动同一套工作流。CLI 是事实来源；随技能附带的
references/builtin-skills/*.md 是 OpenSpec 官方 agent 指令的原文，若你想精确了解各阶段行为可查阅。

0. 前置条件与初始化

需要 Node.js ≥ 20.19.0。一次性安装（或直接运行 scripts/setup-openspec.sh）：

npm install -g @fission-ai/openspec@latest

然后在目标项目内：

cd <project>
openspec init --tools none --no-animation   # 非交互式脚手架 openspec/（specs/、changes/、config.yaml）
openspec list          # 验证能解析出 root；为空 = 健康起点

想一键完成“安装 + init + 自检”，运行随附脚本：

bash <skill>/scripts/setup-openspec.sh [project-dir]

1. 探索（可选，大变更前建议先做）

阅读代码库、权衡方案，帮用户把模糊想法打磨清晰。立场与记录规则见
references/builtin-skills/openspec-explore.md。OpenSpec 感知上下文：openspec list --json
随后读取解析出的 root 的 openspec/config.yaml（context + 各 artifact 的 rules）。把它们当约束
应用，切勿复制进 artifact 文件。

2. 提案（Propose）——创建变更并写齐全部 artifact（仅规划）

> 规划边界：此步骤仅授权“规划”，不要修改项目代码。写完 artifact 后停下，等待用户提出 apply 请求。

openspec new change "<change-name>"          # kebab-case；创建脚手架 + .openspec.yaml
openspec status --change "<change-name>" --json

解析 status --json：
- applyRequires —— 实现前必需的 artifact（如 ["tasks"]）。
- artifacts[].status —— done | skipped | ready | blocked；含 requires 依赖边。
- planningHome、changeRoot、artifactPaths、actionContext —— 与 store/作用域相关的路径。

按依赖顺序遍历 artifact；对每个 ready 的 artifact：

openspec instructions <artifact-id> --change "<change-name>" --json

JSON 返回 template（文件结构）、instruction（权威指引）、context/rules（给你的约束，
不要复制进文件）、以及 resolvedOutputPath。把 artifact 写到该路径；写每个新文件前先从磁盘
重新读取其依赖 artifact。把 skipped/warning（skip_specs）视为“不要创建”。一直循环到每个
传递必需的 artifact 都变成 done/skipped。

编写规则（详见 references/writing-specs.md 与 assets/schema.yaml）：
- proposal.md：Why / What Changes / Capabilities（新增 + 修改）/ Impact。Capabilities 段是进入
specs 阶段的契约。
- specs/：行为契约，每个能力一个文件。Delta 操作以 ## 标题表示：ADDED / MODIFIED /
REMOVED / RENAMED。每个 ### Requirement: 需要 ≥1 个 #### Scenario:（WHEN/THEN 形式）——
必须恰好 4 个井号，否则会静默失败。新能力需以 ## Purpose（≥50 字）开头。用 SHALL/MUST。
- design.md：仅在需要时创建（横切关注、新依赖、安全/性能/迁移、或存在歧义）。结构：
Context / Goals-Non-Goals / Decisions / Risks / Migration / Open Questions。
- tasks.md：- [ ] X.Y 描述 复选框，每条说明如何验证完成。不用 - [ ] 的任务不会被 apply 追踪。

完成后：openspec status --change "<change-name>" 并给出评审摘要。提示用户进入 apply，不要自动 apply。

3. 应用（Apply）——实现 tasks

openspec status --change "<change-name>" --json
openspec instructions apply --change "<change-name>" --json

读取 contextFiles 中每个路径（proposal、specs、design、tasks）。逐条实现 pending 任务；改动保持最小、
限定范围；一完成立即把 - [ ] 翻成 - [x]。状态处理：blocked → 暴露并等待；all_done → 建议归档。
若实现过程暴露出设计问题或新增了范围，暂停并询问——绝不悄悄收窄、推迟或简化已指定的行为。
把 context（必需）与 operationGuidance（建议）当作提示级输入；与受控工作流输入冲突时上报。
完整规则见 references/builtin-skills/openspec-apply-change.md。

4. 校验（Verify，可选）

openspec validate "<change-name>"     # 格式 + 结构校验（失败 exit 1）
openspec show "<change-name>"         # 增量的人类可读摘要

5. 归档（Archive）——合并增量并归档变更

openspec instructions archive --change "<change-name>" --json   # 建议性输入（可选）
openspec archive "<change-name>"                                # 合并增量 → specs/，移入 archive/

openspec archive 在 --json 下是非交互式的，会把 ADDED/MODIFIED/REMOVED 增量合并进主 specs/；
仅当该变更的 .openspec.yaml 设置 retire_capabilities: true 时才会“退役”某个能力（删除其 spec）。
完整的 agent 驱动归档 / 同步逻辑见 references/builtin-skills/openspec-archive-change.md。

存储（Stores，多仓库 / 团队规划，beta）

Store 是注册在本机的一个独立 OpenSpec 仓库；在其中规划的变更可跨多个代码仓库。当用户指名某个
store 时，运行 openspec store list --json，随后在每个需要解析 root 的命令上追加 --store <id>
（new change、status、instructions、list、show、validate、archive、doctor、context、
schemas、view），并在整个工作流中保持 sticky。详见 references/concepts.md（Stores）与源码仓库内的
docs/stores-beta/user-guide.md。

机器可读的 CLI 契约

每个 --json 命令恰好输出一个 JSON 文档（2 空格缩进）。root 解析、payload 形状、退出码与诊断码在
references/agent-contract.md 中有完整规定——编写 CLI 脚本或解析输出时请先读它。

参考资料（按需加载）

• references/concepts.md —— 完整心智模型、delta 规范格式、schema、归档。
• references/getting-started.md —— 前五分钟、会创建什么、示例变更。
• references/workflows.md —— 何时用哪个命令 / 模式。
• references/commands.md —— 完整 CLI + slash 命令参考。
• references/writing-specs.md —— 什么样的需求 / 场景才算强。
• references/reviewing-changes.md —— 编码前评审草稿方案要查什么。
• references/agent-contract.md —— 权威的 JSON 形状、退出码、诊断码。
• references/troubleshooting.md、references/faq.md、references/glossary.md。
• references/existing-projects.md、references/editing-changes.md、references/customization.md、
  references/multi-language.md、references/supported-tools.md。
• references/builtin-skills/*.md —— 13 个 OpenSpec 官方 agent 技能原文（openspec-propose、
  openspec-apply-change、openspec-archive-change、openspec-explore、openspec-new-change、
  openspec-continue-change、openspec-ff-change、openspec-verify-change、openspec-update-change、
  openspec-sync-specs、openspec-bulk-archive-change、openspec-onboard）。
• references/examples.md、references/overview.md、references/installation.md。

随附资源

• assets/schema.yaml —— spec-driven schema（artifact 依赖图 + 指令）。
• assets/templates/{proposal,spec,design,tasks}.md —— artifact 文件模板。

护栏

• 提案 = 仅规划。绝不在提案步骤内实现代码或开始 apply。
• 写新 artifact 前先从磁盘重新读取其依赖 artifact（用户可能已编辑）。
• context/rules 是给你的约束，切勿复制进 artifact 或代码。
• Delta 场景必须恰好用 ####（4 个井号）。新能力需要 ## Purpose。
• 不要手工脚手架 openspec/changes/<name>/ —— 始终用 openspec new change。
• 代码改动保持最小、限定在单个任务内；暴露新增范围，不要自行吸收。
• 选中 store 时使用 store 感知的 planningHome.root 路径，绝不硬编码仓库路径。