mcpField
O
openspec-workflow

openspec-workflow

github.com/wyattowalsh开发536 次安装8 周前更新
代码仓库

关于 openspec-workflow

OpenSpec Workflow 是用 OpenSpec 管理非简单仓库变更的技能，涵盖工具初始化、变更文档、验证和归档。它帮助维护者判断何时需要结构化变更管理，并默认将下游生成工具留在本地。

主要功能

  1. 01诊断 OpenSpec 环境
  2. 02初始化下游工具工作流
  3. 03读取变更状态与指引
  4. 04验证规范和变更
  5. 05归档已完成的变更
  6. 06指导文档顺序与就绪状态

适用场景

  1. 01准备较大规模的仓库变更
  2. 02检查下一份所需变更文档
  3. 03在实现完成前验证
  4. 04归档已验证的变更

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/wyattowalsh/agents --skill openspec-workflow

安装后在 Claude Code 中输入/openspec-workflow确认已加载。

包含的文件

除 SKILL.md 外，安装时一起下载的参考资料和脚本。

evals/
evals.json
scripts/
check.py
openspec_cli.py
scripts/asset_toolkit/
__init__.py
_shared.py
common.py
package.py
validate_evals.py
validate_hooks.py
validate_skill.py

详细介绍

OpenSpec 工作流

将 OpenSpec 用作本仓库中涉及可移植 Agent 资源、下游工具、文档生成、钩子、捆绑包元数据或验证行为的非简单变更的规范与变更控制平台。

分派

$ARGUMENTS操作
空显示仓库的 OpenSpec 快速路径
doctor诊断 OpenSpec 工具链和项目状态
init [tools]在本地生成下游 OpenSpec 技能/命令
status <change>以 JSON 格式读取变更工件状态
instructions <artifact> <change>获取 AI 可读的后续步骤说明
validate验证所有 OpenSpec 规范和变更
archive <change>验证并归档已完成的变更
自然语言变更请求判断是否需要使用 OpenSpec，然后创建或继续变更

快速路径

  1. 开始 OpenSpec 工作前诊断设置：
uv run python skills/openspec-workflow/scripts/openspec_cli.py doctor

  1. 对于非简单的仓库变更，使用生成的上游 OpenSpec 技能/命令（若可用）创建或继续 OpenSpec 变更。

  2. 如果生成的上游 OpenSpec 技能不可用，请使用仓库封装工具管理结构化状态：

uv run python skills/openspec-workflow/scripts/openspec_cli.py status --change <change> --format json
uv run python skills/openspec-workflow/scripts/openspec_cli.py instructions <artifact> --change <change> --format json
  1. 在实现完成或归档前进行验证：
uv run python skills/openspec-workflow/scripts/openspec_cli.py validate

何时使用 OpenSpec

当变更影响以下任一方面时，请使用 OpenSpec：

  • skills/、agents/、mcp/、mcp.json 或第一方 MCP 约定
  • AGENTS.md、instructions/ 或平台桥接文件
  • agent-bundle.json、插件清单、同步清单或下游框架设置
  • 可移植技能 CLI 行为、生成的 README/文档输出或文档导航
  • OpenSpec 规范、模式或生成的下游工具设置

对于小型、独立的错别字修复，或用户请求和仓库约定已完全明确结果的单文件本地变更，请跳过 OpenSpec。

如果非简单变更的范围或方案会由用户决定，需遵循 instructions/global.md 中的深度路由，并在创建或继续变更工件前调用 /grill-me。

下游工具

OpenSpec 生成的上游技能和命令默认仅在本地生成。若下游工具应提供原生 OpenSpec 工作流，请生成这些内容：

uv run python skills/openspec-workflow/scripts/openspec_cli.py init --apply
uv run python skills/openspec-workflow/scripts/openspec_cli.py update --apply

默认的仓库映射如下：

仓库 AgentOpenSpec 工具
claude-codeclaude
codexcodex
crushcrush
cursorcursor
opencodeopencode

除非用户明确要求将某个特定工件提升为仓库自有源文件，否则不要提交生成的 .claude、.cursor、.opencode、.agent、.crush 或 .codex OpenSpec 工件。

工件顺序

Agent 资源变更

对于本仓库的自定义 agent-asset-change 模式，请按以下顺序创建工件：

  1. proposal
  2. affected-surfaces
  3. design
  4. validation-matrix
  5. tasks

使用 openspec status --json 确认哪个工件已就绪，再让 AI 创建该工件。

归档准备就绪

只有在实现和验证全部完成后才能归档。确保提案、受影响范围、设计、验证矩阵和任务与最终发布状态一致。

规范术语

请严格使用以下规范术语：

术语含义
OpenSpec change在 openspec/changes/ 下跟踪的仓库行为或资产变更提案
Artifact提案、设计、任务列表、规格增量或供 AI 读取的指令文档
Downstream tool setup为外部 Agent 框架生成的本地技能、命令或配置
Archive完成变更并将其移入持久化规格历史记录
Validation matrix将受影响的方面映射到所需验证命令的 Artifact

验证约定

在宣布变更完成之前，请在此技能目录中运行：

python scripts/check.py
uv run python skills/openspec-workflow/scripts/openspec_cli.py doctor --format json
uv run python skills/openspec-workflow/scripts/openspec_cli.py validate --format json

如果命令因缺少 Node/OpenSpec 工具而无法运行，请报告阻碍，并提供安装 Node >=20.19.0 后应运行的准确命令。

完成标准：

  1. scripts/check.py 退出码为 0。
  2. openspec_cli.py doctor 和 validate 通过；如果受阻，需提供准确的后续命令。
  3. 技能目录中不包含仓库控制平面 CLI 的引用。
  4. OpenSpec 决策以仓库策略和实际受影响的文件为依据。
  5. 必需的 Artifact 均已存在，或明确说明跳过的原因。
  6. 除非明确批准，否则不得提交生成的下游 Artifact。

关键规则

  1. 对公共资产格式、下游工具、文档生成、钩子、包元数据或验证行为的非简单变更，请使用 OpenSpec。
  2. 对单独的拼写错误修复，或仓库约定已充分决定结果的单文件本地编辑，不要使用 OpenSpec。
  3. 如果其他 AI 工具需要机器可读的状态或指令，请优先使用 uv run python scripts/openspec_cli.py ... --format json。
  4. 除非明确批准，否则不要提交生成的 .claude、.cursor、.opencode、.github、.agent、.crush、.codex 或 .gemini OpenSpec Artifact。
  5. 先验证，再归档；任务、规格或验证方面仍有未解决的问题时，绝不要归档变更。
  6. 默认将生成的下游技能和命令保留在本地。
  7. 将缺少 OpenSpec 或 Node 工具报告为阻碍，并提供配置完成后可重试的准确命令。

评论

支持 Markdown