项目概述与设计哲学

OpenSpec 是一个面向 AI 编码助手的"规格驱动开发"（Spec-Driven Development, SDD）框架，核心目标是在编码代理真正落笔之前，先以结构化的变更提案和需求规约对齐意图。package.json 中将其描述为 "AI-native system for spec-driven development"，并在 README.md 中以五句话概括其哲学：

→ fluid not rigid
→ iterative not waterfall
→ easy not complex
→ built for brownfield not just greenfield
→ scalable from personal projects to enterprises

资料来源：README.md

OpenSpec 当前版本为 v1.4.1（@fission-ai/openspec），最新发布说明中提到 openspec update 命令已修复对项目自带 workspace.yaml 的兼容性问题。资料来源：package.json 与 v1.4.1 Release Notes

安装与初始化

通过 npm 全局安装 CLI：

npm install -g @fission-ai/openspec

在已有仓库中初始化：

openspec init

该命令会把 OpenSpec 的工作流指令与"skills"注入到所选 AI 助手的命令目录（例如 .claude/commands/opsx:*、.cursor/commands/opsx:* 等）。README.md 推荐使用 /opsx:propose "your idea" 启动新的实验性工作流。资料来源：README.md

OpenSpec 默认收集匿名遥测（仅命令名与版本），可通过环境变量关闭：

export OPENSPEC_TELEMETRY=0
# 或者
export DO_NOT_TRACK=1

遥测在 CI 环境中会自动禁用。资料来源：README.md

核心工作流

OpenSpec 的实验性（opsx:）工作流由一组基于 schema 的命令模板驱动。下表给出最常用的几个工作流及其源码位置：

下面以 propose → apply → archive 为主线展示数据流：

flowchart LR
  A[用户: /opsx:propose idea] --> B[openspec status --change name --json]
  B --> C[openspec instructions applyRequires --json]
  C --> D[创建 proposal/specs/design/tasks]
  D --> E[/opsx:apply]
  E --> F[openspec instructions apply --change name --json]
  F --> G[按 tasks 实现代码]
  G --> H[/opsx:archive]
  H --> I[合并 delta specs 到 openspec/specs]
  I --> J[归档到 openspec/changes/archive]

资料来源：src/core/templates/workflows/propose.ts、src/core/templates/workflows/apply-change.ts、src/core/templates/workflows/archive-change.ts、src/core/templates/workflows/sync-specs.ts

apply 步骤会主动检查 state 字段：若 state: "blocked" 则提示运行 /opsx:continue；若 state: "all_done" 则提示可以归档。同时若 actionContext.mode === "workspace-planning" 且 allowedEditRoots 为空，模板会要求显式选择编辑区域并停止修改文件。资料来源：src/core/templates/workflows/apply-change.ts

CLI 命令与配置

src/core/completions/command-registry.ts 暴露的命令面包括：

• change —— 列出、查看、归档变更
• spec —— 查看、列出、验证规格（如 spec show、spec validate）
• completion —— 生成、安装、卸载 shell 补全脚本（bash/zsh/fish/powershell）
• config —— 查看和修改全局配置（path、list、get、set、unset、reset）
• feedback —— 通过 gh CLI 或预填的 GitHub Issue URL 提交反馈

资料来源：src/core/completions/command-registry.ts 与 src/commands/feedback.ts

feedback 子命令会把标题格式化为 Feedback: <message>，并在正文末尾追加包含版本、平台、时间戳的元数据 footer，最终生成形如 https://github.com/Fission-AI/OpenSpec/issues/new?...&labels=feedback 的预填链接，便于用户在无法调用 gh 时手动提交。资料来源：src/commands/feedback.ts

已知配置陷阱

社区报告（#1216）指出 openspec config set workflows '[...]' 会把所有值当作字符串并被 schema 校验拒绝，因此无法通过 CLI 非交互式地把 workflows 切换为数组类型配置（例如 custom profile）。当前可行的临时办法是直接编辑配置文件，规避 schema 类型推断。

Spec 同步的常见盲区

/opsx:propose 与 /opsx:ff 默认只生成 openspec/changes/<name>/ 下的 delta 制品，不会自动把变更同步进 openspec/specs/。如果跳过 /opsx:sync 直接 archive，specs/ 会长期处于过时状态，且没有任何告警（#1212、#1222）。建议在 archive 之前显式运行 /opsx:sync 或检查 src/core/templates/workflows/sync-specs.ts 中描述的 ADDED/MODIFIED/REMOVED/RENAMED 合并规则。

下一步

• 想了解 AI 助手接入与 skills 目录布局，请参见 Supported Tools。
• 想自定义工作流 schema，请参见 Custom Workflows & Schemas。
• 想参与贡献，请阅读 README.md 中的 *Contributing* 段落：小型修复可直接 PR，较大改动需要先提交 OpenSpec 变更提案。资料来源：README.md

See Also

• Supported Tools
• Workflows & Schemas
• Configuration
• Community FAQ

本页聚焦于这三个机制如何协同工作：artifact graph 描述"什么工件存在、它们之间的依赖关系是什么"；schemas 定义"使用哪些工件、按什么顺序生成"；change lifecycle 则把二者串成一条从探索到归档的端到端流程。

一、Artifact Graph：工件与依赖的核心模型

Artifact graph 是 OpenSpec 实验性 OPSX 工作流的内部数据模型。它将一个 *change（变更）* 分解为若干 *artifacts（工件）*，并通过 applyRequires 字段声明"实施前必须完成的工件"。资料来源：src/commands/workflow/shared.ts

export interface ApplyInstructions {
  changeName: string;
  changeDir: string;
  schemaName: string;
  initiative?: InitiativeLink;
  contextFiles: Record<string, string[]>;
  progress: { total: number; complete: number; remaining: number; };
  tasks: TaskItem[];
  state: 'blocked' | 'all_done' | 'ready';
  missingArtifacts?: string[];
  instruction: string;
}

ApplyInstructions 是 artifact graph 向外暴露的主要输出形态，其中：

• state 字段决定变更是否可进入实施阶段，取值为 blocked / all_done / ready。
• progress 字段实时统计 complete / total，供 /opsx:apply 进度条使用。
• contextFiles 聚合每个工件引用的项目文件路径，作为生成后续工件的上下文。
• instruction 字段是 schema 注入给 AI 助手的当前工件指令模板。

二、Schemas：可插拔的工作流模式

Schema 是 OpenSpec 中"工作流（workflow）"的具象化。默认 schema 名为 spec-driven，由 DEFAULT_SCHEMA 常量定义。资料来源：src/commands/workflow/shared.ts:DEFAULT_SCHEMA

每个 schema 是一个 YAML/JSON 文件，描述工件序列与依赖。/openspec schema 子命令会列出所有可解析的 schema，并标注其来源（project / user / package）。资料来源：src/commands/schema.ts, src/commands/workflow/schemas.ts

2.1 标准工件清单（spec-driven）

spec-driven schema 至少包含以下四个工件：

资料来源：src/commands/schema.ts, src/core/templates/workflows/propose.ts

2.2 schema 的解析优先级

schema which 子命令支持 --all 参数，依次在 project（项目内 .openspec/schemas/）、user（用户级 ~/.config/openspec/schemas/）和 package（npm 包内）三层目录下查找同名 schema，项目级优先级最高，便于团队定制。资料来源：src/commands/schema.ts

三、Change Lifecycle：OPSX 端到端流程

OPSX 系列斜杠命令把 artifact graph 与 schema 编排成一条可执行的流水线。下图展示了完整的变更生命周期：

flowchart LR
  A[/opsx:explore/] --> B[/opsx:new <name>/]
  B --> C[/opsx:propose/]
  C --> D[artifact graph<br/>applyRequires]
  D -->|all done| E[/opsx:apply/]
  E --> F[本地测试]
  F --> G[/opsx:verify/]
  G --> H[/opsx:archive/]
  H --> I[open spec/specs/]
  I -.delta.-> J[/opsx:sync/]
  classDef opt fill:#eef,stroke:#88a;
  class A,J opt;

3.1 探索阶段：`/opsx:explore`

Explore 是一种"姿态"而非固定流程：助手只读不写，可视化思考、质疑假设，但严禁实现代码。Explore 的产物是若干 *OpenSpec artifacts*，可由用户主动保存。资料来源：src/core/templates/workflows/explore.ts

3.2 提案与生成：`/opsx:new` + `/opsx:propose` + `/opsx:continue`

• /opsx:new <name>：仅创建变更目录并打印第一份工件的模板与上下文，不生成任何内容。资料来源：src/core/templates/workflows/new-change.ts
• /opsx:propose：一步到位生成 applyRequires 中声明的全部工件，遇到歧义再向用户确认。资料来源：src/core/templates/workflows/propose.ts
• /opsx:continue：智能推进到下一个未完成工件，依赖图通过 openspec status --change <name> --json 实时查询。资料来源：src/core/templates/workflows/continue-change.ts

3.3 实施与校验：`/opsx:apply` + `/opsx:verify`

/opsx:apply 解析 ApplyInstructions，逐个读入已完成的依赖工件作为上下文，按 template 字段生成代码。/opsx:verify 则反过来，把实现回比 tasks.md / specs.md / design.md，按 CRITICAL / WARNING / SUGGESTION 三档产出问题清单。资料来源：src/core/templates/workflows/verify-change.ts

3.4 归档与同步：`/opsx:archive` + `/opsx:sync`

/opsx:archive 把变更目录移动到 planningHome.changesDir/YYYY-MM-DD-<name>/，并把 .openspec.yaml 一起搬走。归档时若存在 delta specs，会先调用 openspec-sync-specs 技能把增量同步进 open spec/specs/，再确认是否继续。资料来源：src/core/templates/workflows/archive-change.ts, src/core/templates/workflows/sync-specs.ts

四、已知陷阱与社区反馈

1. 首次变更不会创建主 spec（issue #1222）：/opsx:archive 在 greenfield 项目中默认跳过 spec 同步，导致 open spec/specs/ 始终为空。规避方式：归档前显式执行 /opsx:sync，或检查 planningHome 是否被正确识别。
2. spec-driven 快路径产生过期 spec（issue #1212）：/opsx:ff 与 /opsx:propose 的 spec-driven 模式在归档时不会主动发出警告。建议团队在 CI 中追加 openspec validate 与 openspec diff（参见 issue #427 的功能请求）作为兜底。
3. config set 不能写入数组：issue #1216 反映 openspec config set workflows '[...]' 会被当作字符串并被 schema 拒绝，团队需直接编辑 open spec/config.yaml 或使用 custom profile 的初始化向导。
4. 斜杠命令与自然语言映射：issue #1221 建议在 init / update 时把 openspec <verb> 自动映射到 /opsx:<verb>，以缓解命令发现性差的问题。

五、小结

• Artifact graph：以 ApplyInstructions 为核心，用 applyRequires 描述工件依赖、用 state 控制可执行性。
• Schemas：把工件序列模板化，支持项目级覆盖，是 OpenSpec 走向"工作流即配置"的关键。
• Change lifecycle：从 explore → new → propose → apply → verify → archive → sync 形成闭环，每一步都通过 openspec status --change <name> --json 与 CLI 共享同一份真源（source of truth）。

资料来源：src/core/command-generation/types.ts, src/core/templates/workflows/propose.ts, src/core/templates/workflows/archive-change.ts, src/commands/workflow/shared.ts, README.md

See Also

• Workflows
• Commands Reference
• CLI Reference
• Customization & Community Schemas
• Supported Tools
• Concepts

AI 工具集成：适配器、斜杠命令与技能

概述与设计目标

OpenSpec 是一套面向 AI 编码助手的"规范驱动开发"（Spec-Driven Development, SDD）系统。README.md 明确宣称其通过斜杠命令适配 20+（v1.4.0 起扩展到 30+）款 AI 助手，覆盖 Claude Code、Cursor、Codex、Windsurf 等不同形态的 IDE 与 CLI。

为避免在每个工具中重复实现相同的工作流文本，OpenSpec 在 src/core/command-generation/ 下设计了一套"工具无关 + 工具特化"的双层结构：先把所有命令写成统一的 CommandContent，再由 ToolCommandAdapter 根据目标 IDE/CLI 决定文件路径与 frontmatter 格式。这一设计直接回应了社区诉求——例如 Issue #202（Zed IDE 支持）、Issue #1224/#1223（Zhipu ZCode 支持）——新增一个集成时只需新增一个适配器，即可复用全部工作流命令。

核心接口：工具无关到工具特化

src/core/command-generation/types.ts 定义了两个核心接口：

• CommandContent：工具无关的命令数据，含 id（如 explore、apply）、name、description、category、tags 与 body（命令正文）。
• ToolCommandAdapter：每种工具的实现需提供 getFilePath(commandId)（返回项目内相对路径，例如 .claude/commands/opsx/explore.md；对 Codex 等全局作用域的工具可返回绝对路径）与 format(content)（产出含 frontmatter 的完整文件内容）。

src/core/command-generation/index.ts 将 CommandAdapterRegistry、generateCommand / generateCommands 以及 claudeAdapter / cursorAdapter / windsurfAdapter 等一并导出，调用方通过 CommandAdapterRegistry.get('cursor') 取出对应适配器即可写入文件系统。资料来源：src/core/command-generation/types.ts:1-52 与 src/core/command-generation/index.ts:1-30。

flowchart LR
    A[工作流模板<br/>propose/apply/explore/...] --> B[CommandContent<br/>id/name/body]
    B --> C{CommandAdapterRegistry}
    C -->|get claude| D[claudeAdapter]
    C -->|get cursor| E[cursorAdapter]
    C -->|get windsurf| F[windsurfAdapter]
    C -->|get codex| G[codexAdapter]
    D --> H[.claude/commands/opsx/*.md]
    E --> I[.cursor/commands/opsx/*.md]
    F --> J[.windsurf/commands/opsx/*.md]
    G --> K[CODEX_HOME/prompts/opsx-*.md]

斜杠命令模板体系

OpenSpec 的斜杠命令以 CommandTemplate 形式集中放置在 src/core/templates/types.ts 与 src/core/templates/workflows/ 目录中。每条命令由 name（如 OPSX: Propose）、description、category（统一为 Workflow）、tags 与 content 字段构成。content 字段即命令的"代理可读正文"，它告诉 AI 助手如何与 openspec CLI 协作。

资料来源：src/core/templates/workflows/propose.ts:1-15; 模板明确要求从 CLI 的 JSON 中读取 applyRequires / resolvedOutputPath / artifactPaths / actionContext，并把 context 与 rules 当作"对代理的约束"而非文件内容。各模板共享一组 Guardrails：每次调用只创建一个产物、按依赖顺序创建、写入后必须校验文件存在——这些规则分散在 propose.ts、ff-change.ts 与 sync-specs.ts 中，确保不同代理以一致方式产出可归档的变更。

技能、Shell 补全与社区扩展

除斜杠命令外，src/core/templates/types.ts 还定义了 SkillTemplate（含 name / description / instructions 与可选 license / compatibility / metadata），用于在支持 Skills 协议的代理中以"技能"形式呈现 OpenSpec——v1.4.0 起 Kimi CLI 走的就是技能通道（OpenSpec 技能落到 .kimi/skills/），由 /skill:openspec-* 调用。

src/core/completions/types.ts 中的 CompletionGenerator 接口允许为 bash / zsh / fish 等 shell 各自生成补全脚本；src/commands/schema.ts 提供 openspec schema which [--all] [--json] 子命令，用于定位某个工作流 schema 来自项目、用户目录还是包内，从而让自定义工作流与社区 schema 扩展成为可能。

社区也在持续推动更多统一：Issue #689 提议用 .agent/skills 目录统一所有支持该规范的代理；Issue #780 提议把 OpenSpec 打包成 Superpowers 技能；Issue #1221 希望把 openspec <verb> 这类自然语言在 init/update 时映射为 /opsx:<verb>，降低代理发现成本。

常见失败模式

• 斜杠命令被识别为自然语言：未走 propose.ts 中"先 openspec new change、再读 --json"的流程，而是直接让代理撰写内容，会导致 applyRequires 缺失或 resolvedOutputPath 错误。
• 环境差异下的产物路径：v1.3.1 Release notes 强调产物路径已改为通过原生 realpath 解析；仍使用旧版本的项目在大小写不敏感或存在符号链接的文件系统上会遇到路径不匹配。
• Greenfield 首次变更的 spec 落地：Issue #1222 反馈在 OpenCode 等代理上首次变更只进入 /changes/archive 而未生成主 spec，根因是工作流未触发 opsx:sync 步骤；#1212 同样指出 spec-driven schema 的 fast-path 会"静默"留下陈旧主 spec，且无任何告警。

参见

• 工作流概念与变更生命周期：Concepts
• 命令与技能清单：Commands
• 支持的工具与安装路径：Supported Tools
• 自定义与社区 schema：Customization
• CLI 命令参考：CLI

高级功能：工作区、上下文存储、配置与定制

1. 概览与定位

OpenSpec 在基础的"提议 → 应用 → 归档"工作流之上，提供一组可配置、可扩展的"高级特性"，覆盖四个维度：项目级 Schema 定制、跨 AI 工具的命令生成、运行时上下文（Context Store）查询，以及 Shell 补全脚本分发。这些能力共同支撑 OpenSpec 的核心理念——"fluent, not rigid"——使得同一份 SDD 流程既能在 30+ 种 AI 助手中复用，又能按团队偏好裁剪 资料来源：README.md。

高级特性在 CLI 中主要体现为 schema、spec、update 等子命令，以及生成阶段使用的模板引擎。schema 命令被显式标记为 [experimental]，提醒用户其行为可能在后续版本中调整 资料来源：src/commands/schema.ts。

2. Schema 与工作流定制

2.1 Schema 解析来源

openspec schema which <name> 与 openspec schema which --all 用于诊断工作流 schema 的解析位置。代码中将 schema 按来源划分为 project、user、package 三层，使项目级定制可以覆盖用户级与内置默认 资料来源：src/commands/schema.ts。

2.2 可插拔工作流

OpenSpec 并不把"提案—设计—任务"格式写死，而是通过 schema 的 apply.requires 字段声明实现阶段所需产出的 artifact 集合。/opsx:propose 模板要求 AI 读取 applyRequires，按顺序创建所有依赖产物（如 proposal.md、design.md、tasks.md） 资料来源：src/core/templates/workflows/propose.ts。/opsx:ff（fast‑forward）则把"提议+实现+归档"压缩成一条快速通道，专为小改动设计 资料来源：src/core/templates/workflows/ff-change.ts。

2.3 持续化与校验

/opsx:continue 根据当前变更状态挑选下一个未完成的 artifact 并创建；/opsx:verify 在归档前对照 spec/design/tasks 检查实现质量，分级输出 CRITICAL / WARNING / SUGGESTION，并支持"优雅降级"——若某些 artifact 不存在则跳过对应检查 资料来源：src/core/templates/workflows/verify-change.ts 与 src/core/templates/workflows/continue-change.ts。/opsx:sync 进一步把变更内的 delta spec 以"ADDED/MODIFIED/REMOVED/RENAMED"格式合并回主 spec 资料来源：src/core/templates/workflows/sync-specs.ts。

flowchart LR
  A[openspec init] --> B[Project schema source]
  U[User global schema] --> B
  P[Package builtin schema] --> B
  B --> C{Choose workflow}
  C -->|spec-driven| D[opsx:propose → apply → archive]
  C -->|fast-forward| E[opsx:ff]
  D --> F[opsx:sync delta → main spec]
  D --> G[opsx:verify]
  G --> H[opsx:archive]

3. 跨工具命令生成

为了让同一份命令体（CommandContent）能落地到 Claude、Cursor、Codex、Kimi CLI、Mistral Vibe 等 30+ 工具，OpenSpec 抽象出 ToolCommandAdapter 接口：每种工具实现 getFilePath 与 format 两个方法，分别处理路径差异（项目级 vs 全局级）与 frontmatter 差异 资料来源：src/core/command-generation/types.ts。这种"内容与格式解耦"是 OpenSpec 能把"组合命令 + 技能 + 提示"同步推送到 20+ 助手中的关键。

4. Shell 补全

CompletionGenerator 接口统一了 Bash、Zsh、Fish 等 shell 的补全脚本生成入口：传入 CommandDefinition[] 即可产出对应语法的脚本 资料来源：src/core/completions/types.ts。它与 CommandContent 共享同一份命令元数据，避免命令变更时补全脚本与实际子命令脱节。

5. 已知限制与社区反馈

• 配置写入限制：社区报告 openspec config set workflows '[...]' 会被当作字符串而无法写入数组型 workflows 键，导致非交互切换 custom profile 失败（issue #1216）。该问题揭示了配置子命令对复杂类型的支持尚不完整。
• 多仓库/工作区：openspec update 在项目自带 workspace.yaml（如 Dagster）时曾出现解析异常，已在 v1.4.1 修复 资料来源：release v1.4.1。
• greenfield 首次归档：issue #1222 报告第一个变更归档时未自动创建主 spec；可借助 /opsx:sync 显式触发 delta→main 合并 资料来源：src/core/templates/workflows/sync-specs.ts。
• 缺失命令：社区呼吁 /opsx:repair（issue #821）、openspec diff（issue #427）以及 Spec 差异比对能力，以填补 apply→archive 之间的修复与回归检查空白。

See Also

• 工作流（Workflows）
• 支持的工具（Supported Tools）
• 定制化（Customization）
• CLI 参考
• 概念（Concepts）

Pitfall Log / 踩坑日志

项目：Fission-AI/OpenSpec

摘要：发现 30 个潜在踩坑项，其中 3 个为 high/blocking；最高优先级：维护坑 - 来源证据：Feature Request: Provide an openspec diff command to show differences between a spec and its modified version.。

1. 维护坑 · 来源证据：Feature Request: Provide an `openspec diff` command to show differences between a spec and its modified version.

• 严重度：high
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：Feature Request: Provide an openspec diff command to show differences between a spec and its modified version.
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 证据：community_evidence:github | https://github.com/Fission-AI/OpenSpec/issues/427 | 来源类型 github_issue 暴露的待验证使用条件。

2. 安全/权限坑 · 失败模式：security_permissions: Feature Request: Add support for ZCode (Zhipu AI Agents)

• 严重度：high
• 证据强度：source_linked
• 发现：Developers should check this security_permissions risk before relying on the project: Feature Request: Add support for ZCode (Zhipu AI Agents)
• 对用户的影响：Developers may expose sensitive permissions or credentials: Feature Request: Add support for ZCode (Zhipu AI Agents)
• 证据：failure_mode_cluster:github_issue | https://github.com/Fission-AI/OpenSpec/issues/1223 | Feature Request: Add support for ZCode (Zhipu AI Agents)

3. 安全/权限坑 · 来源证据：[Community Integration Proposal] Minimal AISOP execution graph for the OpenSpec propose workflow

• 严重度：high
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[Community Integration Proposal] Minimal AISOP execution graph for the OpenSpec propose workflow
• 对用户的影响：可能影响授权、密钥配置或安全边界。
• 证据：community_evidence:github | https://github.com/Fission-AI/OpenSpec/issues/1217 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

4. 安装坑 · 失败模式：installation: `openspec config set workflows '[...]'` fails — `config set` cannot set the array-typed `work...

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this installation risk before relying on the project: openspec config set workflows '[...]' fails — config set cannot set the array-typed workflows key
• 对用户的影响：Developers may fail before the first successful local run: openspec config set workflows '[...]' fails — config set cannot set the array-typed workflows key
• 证据：failure_mode_cluster:github_issue | https://github.com/Fission-AI/OpenSpec/issues/1216 | openspec config set workflows '[...]' fails — config set cannot set the array-typed workflows key

5. 安装坑 · 失败模式：installation: v1.1.0 - Cross-Platform Fixes, Nix Improvements

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this installation risk before relying on the project: v1.1.0 - Cross-Platform Fixes, Nix Improvements
• 对用户的影响：Upgrade or migration may change expected behavior: v1.1.0 - Cross-Platform Fixes, Nix Improvements
• 证据：failure_mode_cluster:github_release | https://github.com/Fission-AI/OpenSpec/releases/tag/v1.1.0 | v1.1.0 - Cross-Platform Fixes, Nix Improvements

6. 安装坑 · 失败模式：installation: v1.2.0 - Profiles, Pi & Kiro Support

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this installation risk before relying on the project: v1.2.0 - Profiles, Pi & Kiro Support
• 对用户的影响：Upgrade or migration may change expected behavior: v1.2.0 - Profiles, Pi & Kiro Support
• 证据：failure_mode_cluster:github_release | https://github.com/Fission-AI/OpenSpec/releases/tag/v1.2.0 | v1.2.0 - Profiles, Pi & Kiro Support

7. 安装坑 · 失败模式：installation: v1.3.0 - New Tool Integrations

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this installation risk before relying on the project: v1.3.0 - New Tool Integrations
• 对用户的影响：Upgrade or migration may change expected behavior: v1.3.0 - New Tool Integrations
• 证据：failure_mode_cluster:github_release | https://github.com/Fission-AI/OpenSpec/releases/tag/v1.3.0 | v1.3.0 - New Tool Integrations

8. 安装坑 · 失败模式：installation: v1.3.1 - Path & Telemetry Fixes

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this installation risk before relying on the project: v1.3.1 - Path & Telemetry Fixes
• 对用户的影响：Upgrade or migration may change expected behavior: v1.3.1 - Path & Telemetry Fixes
• 证据：failure_mode_cluster:github_release | https://github.com/Fission-AI/OpenSpec/releases/tag/v1.3.1 | v1.3.1 - Path & Telemetry Fixes

9. 安装坑 · 失败模式：installation: v1.4.0 - Kimi CLI, Mistral Vibe

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this installation risk before relying on the project: v1.4.0 - Kimi CLI, Mistral Vibe
• 对用户的影响：Upgrade or migration may change expected behavior: v1.4.0 - Kimi CLI, Mistral Vibe
• 证据：failure_mode_cluster:github_release | https://github.com/Fission-AI/OpenSpec/releases/tag/v1.4.0 | v1.4.0 - Kimi CLI, Mistral Vibe

10. 安装坑 · 来源证据：Agent discovery: map natural-language "openspec <verb>" to /opsx:<verb> at init/update time

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Agent discovery: map natural-language "openspec <verb>" to /opsx:<verb> at init/update time
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 证据：community_evidence:github | https://github.com/Fission-AI/OpenSpec/issues/1221 | 来源讨论提到 node 相关条件，需在安装/试用前复核。

11. 安装坑 · 来源证据：Main spec is never created for the first change in a greenfield project

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Main spec is never created for the first change in a greenfield project
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 证据：community_evidence:github | https://github.com/Fission-AI/OpenSpec/issues/1222 | 来源类型 github_issue 暴露的待验证使用条件。

12. 安装坑 · 来源证据：`openspec config set workflows '[...]'` fails — `config set` cannot set the array-typed `workflows` key

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：openspec config set workflows '[...]' fails — config set cannot set the array-typed workflows key
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 证据：community_evidence:github | https://github.com/Fission-AI/OpenSpec/issues/1216 | 来源讨论提到 node 相关条件，需在安装/试用前复核。

13. 配置坑 · 失败模式：configuration: Feature Request: Add support for ZCode (Zhipu AI Agents)

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this configuration risk before relying on the project: Feature Request: Add support for ZCode (Zhipu AI Agents)
• 对用户的影响：Developers may misconfigure credentials, environment, or host setup: Feature Request: Add support for ZCode (Zhipu AI Agents)
• 证据：failure_mode_cluster:github_issue | https://github.com/Fission-AI/OpenSpec/issues/1224 | Feature Request: Add support for ZCode (Zhipu AI Agents)

14. 配置坑 · 失败模式：configuration: Main spec is never created for the first change in a greenfield project

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this configuration risk before relying on the project: Main spec is never created for the first change in a greenfield project
• 对用户的影响：Developers may misconfigure credentials, environment, or host setup: Main spec is never created for the first change in a greenfield project
• 证据：failure_mode_cluster:github_issue | https://github.com/Fission-AI/OpenSpec/issues/1222 | Main spec is never created for the first change in a greenfield project

15. 配置坑 · 失败模式：configuration: [Community Integration Proposal] Minimal AISOP execution graph for the OpenSpec propose workflow

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this configuration risk before relying on the project: [Community Integration Proposal] Minimal AISOP execution graph for the OpenSpec propose workflow
• 对用户的影响：Developers may misconfigure credentials, environment, or host setup: [Community Integration Proposal] Minimal AISOP execution graph for the OpenSpec propose workflow
• 证据：failure_mode_cluster:github_issue | https://github.com/Fission-AI/OpenSpec/issues/1217 | [Community Integration Proposal] Minimal AISOP execution graph for the OpenSpec propose workflow

16. 配置坑 · 失败模式：configuration: v1.0.0 - The OPSX Release

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this configuration risk before relying on the project: v1.0.0 - The OPSX Release
• 对用户的影响：Upgrade or migration may change expected behavior: v1.0.0 - The OPSX Release
• 证据：failure_mode_cluster:github_release | https://github.com/Fission-AI/OpenSpec/releases/tag/v1.0.0 | v1.0.0 - The OPSX Release

17. 能力坑 · 能力判断依赖假设

• 严重度：medium
• 证据强度：source_linked
• 发现：README/documentation is current enough for a first validation pass.
• 对用户的影响：假设不成立时，用户拿不到承诺的能力。
• 证据：capability.assumptions | https://github.com/Fission-AI/OpenSpec | README/documentation is current enough for a first validation pass.

18. 维护坑 · 失败模式：migration: Feature Request: Provide an `openspec diff` command to show differences between a spec and it...

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this migration risk before relying on the project: Feature Request: Provide an openspec diff command to show differences between a spec and its modified version.
• 对用户的影响：Developers may hit a documented source-backed failure mode: Feature Request: Provide an openspec diff command to show differences between a spec and its modified version.
• 证据：failure_mode_cluster:github_issue | https://github.com/Fission-AI/OpenSpec/issues/427 | Feature Request: Provide an openspec diff command to show differences between a spec and its modified version.

19. 维护坑 · 来源证据：Why Cursor version is still 2mo ago

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：Why Cursor version is still 2mo ago
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 证据：community_evidence:github | https://github.com/Fission-AI/OpenSpec/issues/1225 | 来源类型 github_issue 暴露的待验证使用条件。

20. 维护坑 · 来源证据：spec-driven fast-path workflow silently produces stale specs with no recovery path

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：spec-driven fast-path workflow silently produces stale specs with no recovery path
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 证据：community_evidence:github | https://github.com/Fission-AI/OpenSpec/issues/1212 | 来源类型 github_issue 暴露的待验证使用条件。

21. 维护坑 · 维护活跃度未知

• 严重度：medium
• 证据强度：source_linked
• 发现：未记录 last_activity_observed。
• 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
• 证据：evidence.maintainer_signals | https://github.com/Fission-AI/OpenSpec | last_activity_observed missing

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 证据：downstream_validation.risk_items | https://github.com/Fission-AI/OpenSpec | no_demo; severity=medium

23. 安全/权限坑 · 存在评分风险

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 对用户的影响：风险会影响是否适合普通用户安装。
• 证据：risks.scoring_risks | https://github.com/Fission-AI/OpenSpec | no_demo; severity=medium

24. 安全/权限坑 · 来源证据：Feature Request: Add support for ZCode (Zhipu AI Agents)

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Feature Request: Add support for ZCode (Zhipu AI Agents)
• 对用户的影响：可能影响授权、密钥配置或安全边界。
• 证据：community_evidence:github | https://github.com/Fission-AI/OpenSpec/issues/1224 | 来源讨论提到 api key 相关条件，需在安装/试用前复核。

25. 能力坑 · 失败模式：capability: Why Cursor version is still 2mo ago

• 严重度：low
• 证据强度：source_linked
• 发现：Developers should check this capability risk before relying on the project: Why Cursor version is still 2mo ago
• 对用户的影响：Developers may hit a documented source-backed failure mode: Why Cursor version is still 2mo ago
• 证据：failure_mode_cluster:github_issue | https://github.com/Fission-AI/OpenSpec/issues/1225 | Why Cursor version is still 2mo ago

26. 能力坑 · 失败模式：capability: Zed IDE support?

• 严重度：low
• 证据强度：source_linked
• 发现：Developers should check this capability risk before relying on the project: Zed IDE support?
• 对用户的影响：Developers may hit a documented source-backed failure mode: Zed IDE support?
• 证据：failure_mode_cluster:github_issue | https://github.com/Fission-AI/OpenSpec/issues/202 | Zed IDE support?

27. 能力坑 · 失败模式：conceptual: spec-driven fast-path workflow silently produces stale specs with no recovery path

• 严重度：low
• 证据强度：source_linked
• 发现：Developers should check this conceptual risk before relying on the project: spec-driven fast-path workflow silently produces stale specs with no recovery path
• 对用户的影响：Developers may hit a documented source-backed failure mode: spec-driven fast-path workflow silently produces stale specs with no recovery path
• 证据：failure_mode_cluster:github_issue | https://github.com/Fission-AI/OpenSpec/issues/1212 | spec-driven fast-path workflow silently produces stale specs with no recovery path

28. 运行坑 · 失败模式：performance: Agent discovery: map natural-language "openspec <verb>" to /opsx:<verb> at init/update time

• 严重度：low
• 证据强度：source_linked
• 发现：Developers should check this performance risk before relying on the project: Agent discovery: map natural-language "openspec <verb>" to /opsx:<verb> at init/update time
• 对用户的影响：Developers may hit a documented source-backed failure mode: Agent discovery: map natural-language "openspec <verb>" to /opsx:<verb> at init/update time
• 证据：failure_mode_cluster:github_issue | https://github.com/Fission-AI/OpenSpec/issues/1221 | Agent discovery: map natural-language "openspec <verb>" to /opsx:<verb> at init/update time

29. 维护坑 · issue/PR 响应质量未知

• 严重度：low
• 证据强度：source_linked
• 发现：issue_or_pr_quality=unknown。
• 对用户的影响：用户无法判断遇到问题后是否有人维护。
• 证据：evidence.maintainer_signals | https://github.com/Fission-AI/OpenSpec | issue_or_pr_quality=unknown

30. 维护坑 · 发布节奏不明确

• 严重度：low
• 证据强度：source_linked
• 发现：release_recency=unknown。
• 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
• 证据：evidence.maintainer_signals | https://github.com/Fission-AI/OpenSpec | release_recency=unknown