@birdie_moblie/open_spec

v2.3.2

Published

11 hours ago

AI-native Spec Coding 工具：确定性产品规格工作流

0High
0Medium
0Low

oren-birdie

openspec specs cli ai development

OpenSpec v2

OpenSpec 是面向 AI 编码协作的确定性产品规格工作流。v2 使用轻量 packet、统一 Hook、分层 Skill 和按 task category 初始化的 code Worker；每个 code task 拆成 scout → build → verify → repair 四个短命子代理阶段，控制会话只编排、不读代码与截图，宿主不支持 subagent 时主 agent 按同一组节点文件执行。

工作流

init
  -> new change
  -> sources add / collect
  -> parse -> tech(可跳过) -> plan
  -> Gate-A
  -> code workers
  -> Gate-B
  -> verify / fix-verify
  -> Gate-C
  -> openspec/archive/YYYY-MM-DD-<change>/

Skill 入口与状态机节点的对应关系：

/opsx-propose：collect → parse → tech → plan，停在 Gate-A
/opsx-apply：批准 Gate-A 后逐个 code worker，停在 Gate-B
/opsx-verify：批准 Gate-B 后跑 QA，停在 Gate-C
/opsx-fix-verify / /opsx-archive / /opsx-resume / /opsx-source-update / /opsx-gate-decision / /opsx-explore

一个 change 的主要产物是 spec.md（产品章节与「决策记录」，tech 在末尾写「实现决策」）和 plan/tickets/<id>-<slug>.md（一张一个 ticket，frontmatter 放调度字段，正文写要做什么与验收）。已登记来源之间的冲突在 parse 阶段逐条访谈用户决策，开发中发现的冲突同样补决策、不回退 Gate-A；openspec status --change <name> --answers --json 列出问答历史，供 Gate 汇报与 spec 对照。旧产物格式（无 layout: 2 标记）的 change 需用创建它的版本完成。

快速开始

需要 Node.js 22 或 24。本仓库通过 package.json 的 packageManager 字段钉住 pnpm 11。

安装 pnpm

先执行 pnpm -v。没有该命令时，已有 Node 的环境优先用 Corepack（会按仓库钉住的版本准备 pnpm）：

corepack enable

其他方式：

macOS（Homebrew）：brew install pnpm
POSIX 独立脚本：curl -fsSL https://get.pnpm.io/install.sh | sh -（pnpm 11 的独立脚本不支持 Intel Mac，可用 Homebrew）
npm：npx get-pnpm

装完后新开一个终端，确认 pnpm -v 可用。

构建并注册全局 `openspec` 命令

在仓库根目录：

pnpm install
pnpm run build
pnpm add -g .

pnpm 11 已移除 pnpm link --global。把本地 CLI 注册成全局命令的方式是在包目录执行 pnpm add -g .：它读取 package.json 的 bin.openspec（./bin/openspec.js），之后任意目录都能直接跑 openspec。该入口依赖 dist/，必须先 pnpm run build。

不想注册全局时，继续用 node bin/openspec.js <命令>。

openspec init --tools claude,codex,cursor --preset flutter-mobile --preset-repo <preset 仓库> --preset-ref refs/tags/<tag> --yes
openspec new change improve-checkout
openspec sources add --change improve-checkout --notes "简化结算确认" --json

全局命令常见问题

pnpm link --global 报错，或提示没有 --global。 pnpm 11 删除了该选项。改在仓库根目录执行 pnpm add -g .。卸载：pnpm remove -g @birdie_moblie/open_spec。

ERR_PNPM_NO_GLOBAL_BIN_DIR。 全局 bin 目录未创建，或不在 PATH 里。执行 pnpm setup，再 source ~/.zshrc（bash 则 ~/.bashrc）或重开终端。从 pnpm 10 升到 11 后通常要再跑一次 setup。不要用 sudo（会写到 root 的家目录，而不是当前用户）。

openspec: command not found。 PATH 没有包含 pnpm 全局 bin。看 pnpm bin -g 的输出，确认该目录出现在 echo $PATH 中。zsh 可能缓存了旧的命令位置，执行 hash -r。也可用 ls "$(pnpm bin -g)/openspec" 确认二进制是否已注册。

能跑但版本不对，或 which openspec 指向别处。 which -a openspec 看优先级。以前用 npm install -g 或项目里的 install-cli.mjs 装过的副本可能排在前面。卸掉冲突的 npm 全局包，或让 pnpm bin -g 在 PATH 里更靠前。包名是 @birdie_moblie/open_spec，命令名仍是 openspec。

Cannot find module '.../dist/cli.js'。 还没 build，或 dist/ 被删了。重新 pnpm run build。改 TypeScript 源码后也要再 build；一般不必重新 pnpm add -g .，除非改了 bin 字段。

团队成员

已初始化的业务项目里用安装脚本对齐 CLI 版本：

node openspec/install-cli.mjs
openspec doctor --json

成本实验与只读用量分析见成本测试指南。支持 Codex/Claude 日志去重、父子线程核算、明确费用口径，以及保留旧默认输出的精简协议。

init --yes 才会调用 Claude/Codex 的原生 marketplace；Cursor 返回需要在 UI 完成的 pending_user_action。CI 或其他非 TTY 环境未给确认时也返回 pending（退出码 2），--skip-plugins 会把跳过决定写入项目 runtime receipt。可用 OPENSPEC_HOME 隔离 marketplace cache。

开发验证

pnpm run lint
pnpm run build
pnpm run typecheck:test
pnpm test

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme