Related Pages

Related topics: Core Architecture and Workflow System, AI Tool Integrations and Adapter System

Overview and Getting Started

What is OpenSpec

OpenSpec is a lightweight spec-driven development (SDD) framework designed to bring structure to AI-assisted coding. It provides a thin, opinionated layer on top of AI coding assistants so that humans and AI agree on *what* to build before any code is written, and *why* the change is needed. The project is distributed as an npm package (@fission-ai/openspec) and is installed per-project.

Source: README.md:1-60

The core philosophy, as stated in the README, is intentionally fluid rather than rigid: artifacts can be updated anytime, there are no waterfall-style phase gates, and the system scales from greenfield prototypes to large brownfield codebases. The framework is built to work alongside 30+ AI assistants (Claude Code, Cursor, Codex, Gemini, Kimi CLI, Mistral Vibe, Zed, etc.) and exposes its behavior through both slash commands and CLI subcommands.

Core Concepts

OpenSpec organizes work into three layers, all of which live under an openspec/ directory in the project root:

Source: src/commands/spec.ts:7-30, src/core/templates/workflows/sync-specs.ts:1-40

When a change is archived, its delta specs are merged into the main capability specs, and the change folder is moved into openspec/changes/archive/. This is where community issue #1222 ("Main spec is never created for the first change in a greenfield project") originates — when a delta spec is never produced, archiving leaves openspec/specs/ empty.

Installation and Initialization

OpenSpec is distributed as a Node.js package. Typical first-use flow:

1. Install globally or in a project: npm install -g @fission-ai/openspec
2. From the project root, run openspec init to scaffold the openspec/ directory and configure supported AI tools.
3. Optionally, select a workflow profile (spec-driven, custom, etc.) — see Configuration.

During init, OpenSpec can also wire up slash commands or skills for any AI tools detected in the environment. The README confirms that the same flow is the supported entry point for tools like Zed (issue #202).

The Standard Workflow

The artifact-guided /opsx:* workflow is the recommended way to drive OpenSpec. The diagram below summarizes the canonical loop:

flowchart LR
  A[Explore<br/>/opsx:explore] --> B[Propose<br/>/opsx:propose]
  B --> C[Continue<br/>/opsx:continue]
  C --> D[Apply<br/>/opsx:apply]
  D --> E[Verify<br/>/opsx:verify]
  E --> F[Archive<br/>/opsx:archive]
  F --> G[Sync Specs<br/>/opsx:sync]
  G --> H[openspec/specs/ updated]

Explore is a "stance, not a workflow" — the AI reads code, asks questions, and visualizes the problem space, but never writes implementation code. Source: src/core/templates/workflows/explore.ts:14-32

Propose creates a change folder and walks the AI through generating proposal, design, tasks, and spec artifacts based on the active schema's apply.requires list. Source: src/core/templates/workflows/propose.ts:30-90

Continue picks the next pending artifact in the dependency graph when a propose flow was interrupted. Source: src/core/templates/workflows/continue-change.ts:14-50

Apply generates the actual implementation code from the tasks artifact. Verify scores the implementation against the change artifacts (CRITICAL / WARNING / SUGGESTION) before archiving. Source: src/core/templates/workflows/verify-change.ts:14-90

Archive moves the change into openspec/changes/archive/, and Sync Specs intelligently merges delta specs into the main capability specs. Source: src/core/templates/workflows/sync-specs.ts:14-80

A faster combined path (/opsx:ff or "fast-forward") is also available; it executes propose → apply → archive in one shot, but as issue #1212 documents, it can silently leave openspec/specs/ out of date when no delta specs are produced.

Configuration and Tooling

Schemas (Experimental)

openspec schema is the entry point for inspecting and switching workflow profiles. The command resolves schemas from project, user, and package sources and emits a list such as spec-driven, tdd, or custom. Source: src/commands/schema.ts:30-80

Switching profiles with openspec config set workflows '[...]' is a known sharp edge — issue #1216 reports that array-typed config values are coerced to strings and rejected by schema validation, blocking non-interactive profile switches. As a workaround, edit openspec/config.yaml directly or use the interactive openspec config wizard.

Command Generation

OpenSpec's commands are generated through a tool-agnostic pipeline. CommandContent carries the body and metadata, and a ToolCommandAdapter decides the destination path and frontmatter format for each AI tool (for example, .claude/commands/opsx/<id>.md for Claude, Codex's global path, Cursor's commands folder, etc.). Source: src/core/command-generation/types.ts:12-50

This design is what allows a single command body to be rendered correctly across 30+ tools and is the basis for the active proposal in issue #689 to converge on a shared .agent/skills folder.

Multi-Language and Feedback

Spec files are parsed with the Markdown parser in src/commands/spec.ts, so any markdown-compatible syntax is supported. openspec feedback <message> opens a pre-filled GitHub issue (label feedback) with version, platform, and timestamp metadata for triage. Source: src/commands/feedback.ts:30-90

Common Pitfalls for New Users

• Forgetting the delta spec on greenfield projects — first change archives but never writes to openspec/specs/. Run /opsx:sync explicitly. Source: issue #1222
• Flat spec structure only — hierarchical capabilities are still a proposal. Source: issue #662
• Non-interactive config — array values cannot be set through openspec config set. Source: issue #1216
• Fast-path silent staleness — always run /opsx:sync after /opsx:ff. Source: issue #1212

See Also

• Workflows
• Commands and Slash Reference
• Schemas (Experimental)
• Supported AI Tools
• Customization and Community Schemas
• CLI Reference

Related Pages

Related topics: Overview and Getting Started, AI Tool Integrations and Adapter System, Advanced Features, Workspaces, and Common Issues

Core Architecture and Workflow System

Overview and Purpose

OpenSpec is a lightweight spec-driven development (SDD) layer that sits between a human and an AI coding assistant. The system introduces a structured "change" lifecycle — proposal, specs, design, tasks, implementation, and archive — so that intent is captured in version-controlled Markdown before any code is written. As described in README.md, the goal is *agreement before building*: human and AI align on specs first, then iterate freely without rigid phase gates, and the same workflow can drive 20+ AI assistants through tool-specific slash commands.

The core architecture is therefore split into three concerns:

1. Schema-driven artifact generation — a declarative graph that says *what* artifacts a change needs (proposal, design, tasks, specs) and *in what order*.
2. Workflow command templates — natural-language instructions that tell an AI agent *how* to walk that graph for a given intent (explore, propose, apply, verify, archive).
3. CLI surface — the openspec binary, which exposes status, instructions, new change, schema, and friends, plus a tool-agnostic command generator that emits the right file format for each AI tool.

Workflow Command Surface

Every AI-facing command is described by a CommandTemplate record that wraps a Markdown body with metadata, then rendered into tool-specific files (Claude slash commands, Cursor rules, Codex skills, etc.). The shape of that template is defined in src/core/command-generation/types.ts, where CommandContent is the tool-agnostic payload (id, name, description, category, tags, body) and a ToolCommandAdapter decides the output file path and frontmatter format per AI tool.

The CLI groups these by intent. src/commands/workflow/index.ts shows the workflow barrel: status, instructions (with an apply variant), templates, schemas, new change, and set change, plus a DEFAULT_SCHEMA constant. The schema family in src/commands/schema.ts is flagged as experimental; its preAction hook prints Note: Schema commands are experimental and may change. and exposes schema which [name] with --json and --all flags so users can inspect where a schema resolves from (project, user, or package scope).

The `OPSX:` Workflow Family

The experimental "OPSX" workflows are the heart of the new artifact-driven experience. Each is implemented as a standalone template under src/core/templates/workflows/ and registered with category Workflow and tag experimental:

Every template returns a CommandTemplate literal with license: 'MIT' and metadata: { author: 'openspec', version: '1.0' }, and a compatibility: 'Requires openspec CLI.' line, which keeps them self-describing.

Schema-Driven Artifact Generation

The OPSX workflows do not hard-code artifact names. Instead, they call openspec status --change "<name>" --json and parse the response to discover applyRequires, the list of artifact IDs that must exist before implementation can begin, and artifacts, the per-artifact status with dependency edges. This is visible in src/core/templates/workflows/propose.ts, where step 3 reads:

Parse the JSON to get: applyRequires (e.g., ["tasks"]), artifacts (with status and dependencies), and planningHome, changeRoot, artifactPaths, actionContext — path and scope context. Use these instead of assuming repo-local paths.

Each artifact instruction is then fetched via openspec instructions <artifact> --change "<name>" --json, which returns a context block, a rules block, a template, an instruction, a resolvedOutputPath, and a list of completed dependencies to read first. A consistent guardrail — repeated in propose.ts, ff-change.ts, and continue-change.ts — is that context and rules are constraints for the AI, *not* content to copy into the artifact file. continue-change.ts makes this explicit:

Do NOT copy <context>, <rules>, <project_context> blocks into the artifact. These guide what you write, but should never appear in the output.

flowchart LR
  A[User intent] --> B["/opsx:propose"]
  B --> C["openspec new change <name>"]
  C --> D["openspec status --json"]
  D --> E{applyRequires done?}
  E -- No --> F["openspec instructions <artifact> --json"]
  F --> G[Write artifact to resolvedOutputPath]
  G --> D
  E -- Yes --> H["/opsx:apply → implement tasks"]
  H --> I["/opsx:verify"]
  I --> J["/opsx:archive → merge into /specs"]

The same status JSON also exposes actionContext.mode, which can be "workspace-planning". verify-change.ts instructs the agent to STOP and explain that full workspace implementation verification is not supported, rather than guess at repo-local ownership or edit linked repos.

Common Workflows and Their Patterns

Explore is intentionally the most permissive command. Per explore.ts, it is "a stance, not a workflow" — no fixed steps, no required sequence, no mandatory outputs. The hard rule is "Explore mode is for thinking, not implementing": the agent may read files and create OpenSpec artifacts, but must never write application code, and must remind the user to exit explore mode if they ask for implementation.

Propose and FF are the two entry points into a new change. Both follow the same dependency-walking loop: create the change directory with openspec new change "<name>", fetch the build order, then loop over artifacts in dependency order, reading each dependency first, fetching instructions, writing the file to resolvedOutputPath, and re-running openspec status until every applyRequires ID is done. ff-change.ts is the fast-path variant optimized for spec-driven schemas. As community issue #1212 notes, this fast path can leave openspec/specs/ permanently out of date if the user never runs sync — which is exactly what OPSX: Sync Specs is for.

Continue (continue-change.ts) is the lighter sibling of propose: it advances one artifact at a time and explicitly forbids skipping or reordering.

Verify runs *before* archive and produces a scorecard grouped by CRITICAL, WARNING, and SUGGESTION — issues are tied to file/line references, and the command degrades gracefully when artifacts are missing (tasks-only, tasks+specs, or full triad). Sync Specs (sync-specs.ts) merges ADDED / MODIFIED / REMOVED / RENAMED deltas from a change into the main specs, and is designed to be idempotent: "running twice should give same result." Onboard (onboard.ts) is a phased, conversational flow that pauses for user approval between proposal and spec phases, explicitly resolving resolvedOutputPath before writing.

Community issue #1222 — *Main spec is never created for the first change in a greenfield project* — and the requested openspec diff command in #427 both stem from the same root cause: archive moves a change into /changes/archive but does not, by itself, materialize it into /specs/. The architecture's answer is to make OPSX: Sync Specs an explicit, idempotent step in the workflow rather than an implicit side effect of archive.

See Also

• README.md — Project overview, comparison with Spec Kit and Kiro, updating instructions.
• src/commands/schema.ts — Schema resolution CLI (schema which, schema which --all --json).
• src/commands/workflow/index.ts — Barrel for the workflow command family.
• docs/workflows.md — User-facing workflow combinations and patterns.
• docs/cli.md — Terminal reference for the openspec binary.

Related Pages

Related topics: Overview and Getting Started, Core Architecture and Workflow System, Advanced Features, Workspaces, and Common Issues

AI Tool Integrations and Adapter System

Overview and Purpose

OpenSpec ships as a spec-driven development framework that works with more than 20 AI coding assistants (Claude Code, Cursor, Codex, Gemini CLI, Windsurf, Zed, OpenCode, Kimi CLI, Mistral Vibe, etc.) as advertised in README.md. The mechanism that makes this broad compatibility possible is the Adapter System living under src/core/command-generation/. The system decouples the *what* (tool-agnostic command content) from the *how* (tool-specific file paths and frontmatter), so the same workflow logic is rendered correctly for every supported AI tool.

The package itself is published as @fission-ai/openspec (version 1.4.1) and exposes a bin/openspec.js entry point, as declared in package.json. Adapter logic is registered through the command-generation module and driven by the user’s selected tools at init and update time.

Architecture

The Adapter System follows a three-layer design: content templates → tool-agnostic commands → tool-specific adapters → on-disk files.

flowchart LR
    A[Workflow Templates<br/>src/core/templates/workflows/*.ts] --> B[CommandContent<br/>tool-agnostic]
    B --> C[ToolCommandAdapter<br/>per-tool strategy]
    C --> D[Generated Files<br/>.claude/commands/, .cursor/commands/, etc.]
    B --> E[Registry<br/>src/core/command-generation/registry.ts]
    E --> C
    C --> F[Adapter index<br/>src/core/command-generation/adapters/index.ts]

• Workflow templates live in src/core/templates/workflows/ and define the body text of each /opsx:* command — e.g. propose.ts, ff-change.ts, apply-change.ts, verify-change.ts, sync-specs.ts, explore.ts, continue-change.ts, and onboard.ts (Source: src/core/templates/workflows/propose.ts).
• Tool-agnostic content is expressed via the CommandContent interface in src/core/command-generation/types.ts, which captures id, name, description, category, tags, and body — nothing tool-specific.
• Per-tool adapters implement the ToolCommandAdapter interface defined in the same file, supplying getFilePath(commandId) and a formatter that wraps the content in the tool’s required frontmatter. Path return values are project-relative, with the noted exception of tools whose prompts are globally scoped (Source: src/core/command-generation/types.ts).
• The registry (src/core/command-generation/registry.ts) maps toolId values (matching AIToolOption.value) to their adapter instances, while the adapter index (src/core/command-generation/adapters/index.ts) aggregates every concrete adapter — Claude, Cursor, Codex, and others — in one place.

The generator.ts file orchestrates the full pipeline: it pulls the tool-agnostic content, looks up the matching adapter from the registry, resolves the output path, and writes the final file. This separation is what allows the same propose workflow body to land in .claude/commands/opsx/propose.md, .cursor/commands/opsx/propose.md, or a Codex prompt with identical semantics.

Command Content and Adapter Contract

The shared contract between the generator and each adapter is encoded in types.ts. Every adapter must implement toolId, getFilePath(commandId), and a content formatter. Because CommandContent is intentionally minimal, a new AI tool only needs to (1) register an adapter that defines its file path and frontmatter conventions, and (2) be added to the adapter index — no template changes are required. This is the contract that has historically allowed OpenSpec to add tools like Kimi CLI and Mistral Vibe (mentioned in the v1.4.0 release) without modifying workflow logic.

The Claude adapter (src/core/command-generation/adapters/claude.ts) is the reference implementation: it returns .claude/commands/opsx/<commandId>.md and wraps the body with the YAML frontmatter Claude Code expects (Source: src/core/command-generation/adapters/claude.ts). Other adapters in the same adapters/ directory follow the same shape, differing only in path prefix and frontmatter keys. The same workflow files — for example the ff-change.ts template that drives the fast-path workflow — are rendered through whichever adapter is selected during openspec init or openspec update (Source: src/core/templates/workflows/ff-change.ts).

Schema-Driven Workflows and Tooling

The adapter layer sits on top of OpenSpec’s schema system, exposed through the openspec schema command (src/commands/schema.ts). Schemas describe an ordered set of artifacts (e.g. proposal, specs, design, tasks) and the dependencies between them. The schema command’s --all flag enumerates every schema with its resolution source (project, user, or package), so the same workflow content can be regenerated for any configured tool without losing artifact order or applyRequires metadata (Source: src/commands/schema.ts).

This design means that workflows such as /opsx:propose and /opsx:ff — which create artifacts in dependency order using openspec status --change "<name>" --json — emit the same structured instructions regardless of the underlying AI assistant. The template is identical; only the adapter wrapping differs.

Community Demand and Extensibility

Community activity has put sustained pressure on the Adapter System to keep pace with new tools:

• Feature requests for ZCode (Zhipu AI Agents) (issues #1223, #1224) ask for a new adapter that writes ZCode-specific commands. Adding support is documented to require implementing ToolCommandAdapter and registering it in the adapter index.
• Issue #689 proposes a standard .agent/skills folder so any agent supporting the convention can share one adapter, reducing per-tool duplication.
• Issue #202 (Zed IDE) and issue #780 (Superpowers skill-pack distribution) highlight that integration shape matters as much as feature parity — Zed already works by reading openspec/agents.md, but a first-class adapter is still desired.
• Issue #1221 asks for agent discovery improvements so that natural-language invocations like openspec <verb> are mapped to /opsx:<verb> at init/update time, surfacing the registered commands regardless of which adapter wrote them.

The adapter architecture already accommodates these requests: because the registry and adapter index are isolated from the workflow content, new tools can be onboarded without touching the templates in src/core/templates/workflows/. The same pattern is what enabled v1.4.0 to ship Kimi CLI (skills-only, writing to .kimi/skills/) and Mistral Vibe alongside the existing tools in a single release.

See Also

• README.md — Project overview, philosophy, and quickstart
• src/commands/schema.ts — Schema resolution and listing
• src/core/templates/workflows/ — All workflow body templates consumed by the adapters
• docs/supported-tools.md — Full list of supported AI tools and install paths
• docs/customization.md — How to add new tools, schemas, and community extensions

Related Pages

Related topics: Core Architecture and Workflow System, AI Tool Integrations and Adapter System

Advanced Features, Workspaces, and Common Issues

OpenSpec is a lightweight spec-driven development layer that augments AI coding assistants with a shared, reviewable specification workflow. Beyond the core /opsx:propose → /opsx:apply → /opsx:archive flow, the project ships a set of advanced workflow commands, a schema system for customizing artifact generation, and workspace planning concepts that control where change artifacts live. This page documents those surfaces and the common failure modes community users encounter.

Advanced Workflow Commands

The workflow templates under src/core/templates/workflows/ define slash-command bodies that an AI assistant executes. They are tagged experimental in their metadata to signal that their behavior may evolve. Source: src/core/templates/workflows/propose.ts:1-15

OPSX: Propose and Fast-Forward

/opsx:propose resolves the artifact build order from openspec status --change "<name>" --json, then iterates through artifacts in dependency order, calling openspec instructions <artifact> --change "<name>" --json to get a template, instruction, context, rules, and resolvedOutputPath for each. The AI writes one file at a time and only proceeds when the previous file exists on disk. Source: src/core/templates/workflows/propose.ts:30-90

/opsx:ff (fast-forward) is a shortcut that creates and applies a change in one step. It accepts a single change name and a "fast-path" schema — typically spec-driven — that minimizes the artifact set. Source: src/core/templates/workflows/ff-change.ts:1-30

OPSX: Continue

/opsx:continue picks up an in-progress change by querying openspec status --change "<name>" --json, locating the next artifact whose dependencies are satisfied, and writing it. It also enforces a strict rule: <context> and <rules> blocks returned by the CLI are constraints for the AI, never file content. Source: src/core/templates/workflows/continue-change.ts:1-25

OPSX: Sync-Specs

Delta specs under changes/<name>/specs/*.md describe intent (ADDED, MODIFIED, REMOVED, RENAMED requirements). /opsx:sync-specs reads both the delta and the main spec, then applies intelligent merging: a MODIFIED requirement can carry only the new scenarios rather than the full replacement, and the operation is idempotent — running it twice yields the same main spec. Source: src/core/templates/workflows/sync-specs.ts:1-45

OPSX: Verify

/opsx:verify cross-checks an implementation against the change artifacts. It returns a scorecard with issues graded CRITICAL, WARNING, or SUGGESTION, and degrades gracefully: if only tasks.md exists, it verifies task completion only; if tasks + specs exist, it skips the design check. Source: src/core/templates/workflows/verify-change.ts:1-50

When status reports actionContext.mode: "workspace-planning", the command refuses to infer repo-local implementation ownership and stops, because full workspace implementation verification is outside its current scope. Source: src/core/templates/workflows/verify-change.ts:20-25

OPSX: Explore

/opsx:explore is explicitly not a workflow — it is a "stance" with no fixed steps, no required sequence, and no mandatory outputs. The AI acts as a thinking partner: it may read code, surface multiple directions, and visualize with ASCII diagrams, but it must never implement features or write code in this mode. Source: src/core/templates/workflows/explore.ts:1-20

Schemas and the Schema Command

Schemas describe which artifacts a workflow produces and in what order. The schema CLI subcommand (prefixed as experimental on every invocation) exposes three operations:

Source: src/commands/schema.ts:30-55

Schemas can be resolved from three locations — project (./openspec/schemas/), user (~/.config/openspec/schemas/), and package (the bundled defaults). The experimental spec-driven schema is the one most users hit via /opsx:ff, and it is the source of the well-known "stale spec" failure mode discussed below.

Workspace Planning and Path Context

Modern OpenSpec commands no longer assume artifacts live next to the spec. openspec status --change "<name>" --json returns a rich context object that downstream AI commands must consume:

• planningHome — directory where the change scaffold is created (often inside a workspace repo)
• changeRoot — directory containing proposal.md, tasks.md, and the change's specs/
• artifactPaths — concrete (or glob) output paths for each artifact
• actionContext — describes the mode of operation (e.g., repo-local vs. workspace-planning)

Source: src/core/templates/workflows/verify-change.ts:15-20, src/core/templates/workflows/propose.ts:35-45

flowchart LR
  A[openspec status --change <name> --json] --> B{actionContext.mode}
  B -- "repo-local" --> C[Write to changeRoot/artifactPaths]
  B -- "workspace-planning" --> D[Verify refuses; manual sync required]
  C --> E[Re-run status; check applyRequires]
  E --> F[Loop until all artifacts done]

The ToolCommandAdapter interface in src/core/command-generation/types.ts is what lets the same command body be rendered into Claude's .claude/commands/opsx/, Cursor's .cursor/commands/opsx/, Codex's global prompt store, and so on. Source: src/core/command-generation/types.ts:1-35

Common Issues and Workarounds

The community has surfaced several recurring issues that map directly to the advanced surfaces above.

1. Main spec is never created for the first change in a greenfield project. When a project starts with no capabilities, applying and archiving a change drops the result into /changes/archive without ever writing to /specs/. The mitigation is to run /opsx:sync-specs <change-name> explicitly after archive; the workflow's idempotent merging ensures the main spec is created on first sync. (Issue #1222.)

2. spec-driven fast-path leaves openspec/specs/ permanently out of date. Because spec-driven is a minimal schema, archive can complete without triggering sync. There is no automatic warning. The recovery path is to invoke /opsx:sync-specs against the archived change, which reads the delta and rebuilds the main spec. (Issue #1212.)

3. openspec config set workflows '[...]' rejects array values. The config set command treats every value as a string and the schema validator rejects the resulting workflows field, making non-interactive switching to a custom profile impossible. Until that is fixed, the workaround is to edit the project config file directly or use interactive init. (Issue #1216.)

4. No openspec diff command. Users currently copy openspec/changes/*/specs/A.md next to openspec/specs/A/spec.md to compare them by hand. A first-class diff command has been requested in issue #427. Until it ships, /opsx:sync-specs can act as a dry-run preview when its writes are inspected manually.

5. Agent-discovery gap with natural-language openspec <verb>. Users typing openspec propose in plain language do not reach the /opsx:propose slash command. A proposal to map discovery at init/update time is tracked in issue #1221; the in-tree workaround is to instruct the assistant explicitly to use the /opsx: namespace.

6. Hierarchical spec structure not supported. OpenSpec assumes a flat specs/{capability}/spec.md layout. Larger teams have asked for nested groupings in issue #662. Today, capability names can encode hierarchy with dashes (e.g., billing-invoices).

7. Tool-adapter parity drift. Different tools receive the same command body but render frontmatter and path layouts differently via ToolCommandAdapter. When a new tool (e.g., Kimi CLI, Mistral Vibe, or the requested ZCode) is added, its adapter must implement both getFilePath() and formatContent(). Source: src/core/command-generation/types.ts:18-35

See Also

• Concepts — how changes, specs, and workflows fit together
• Customization — community schemas and project-level overrides
• Commands — slash command catalog
• Workflows — combine commands into end-to-end patterns
• Supported Tools — tool integrations and install paths

Doramagic Pitfall Log

Found 30 structured pitfall item(s), including 3 high/blocking item(s). Top priority: Maintenance risk - Maintenance risk requires verification.

1. Maintenance risk: Maintenance risk requires verification

• Severity: high
• Finding: Project evidence flags a maintenance risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: community_evidence:github | https://github.com/Fission-AI/OpenSpec/issues/427

2. Security or permission risk: Security or permission risk requires verification

• Severity: high
• Finding: Developers should check this security_permissions risk before relying on the project: Feature Request: Add support for ZCode (Zhipu AI Agents)
• User impact: Developers may expose sensitive permissions or credentials: Feature Request: Add support for ZCode (Zhipu AI Agents)
• Recommended check: Before packaging this project, run the relevant install/config/quickstart check for: Feature Request: Add support for ZCode (Zhipu AI Agents). Context: Source discussion did not expose a precise runtime context.
• Evidence: failure_mode_cluster:github_issue | https://github.com/Fission-AI/OpenSpec/issues/1223

3. Security or permission risk: Security or permission risk requires verification

• Severity: high
• Finding: Project evidence flags a security or permission risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: community_evidence:github | https://github.com/Fission-AI/OpenSpec/issues/1217

4. Installation risk: Installation risk requires verification

• Severity: medium
• Finding: 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
• User impact: Developers may fail before the first successful local run: openspec config set workflows '[...]' fails — config set cannot set the array-typed workflows key
• Recommended check: Before packaging this project, run the relevant install/config/quickstart check for: openspec config set workflows '[...]' fails — config set cannot set the array-typed workflows key. Context: Observed when using node, linux
• Evidence: failure_mode_cluster:github_issue | https://github.com/Fission-AI/OpenSpec/issues/1216

5. Installation risk: Installation risk requires verification

• Severity: medium
• Finding: Developers should check this installation risk before relying on the project: v1.1.0 - Cross-Platform Fixes, Nix Improvements
• User impact: Upgrade or migration may change expected behavior: v1.1.0 - Cross-Platform Fixes, Nix Improvements
• Recommended check: Before packaging this project, run the relevant install/config/quickstart check for: v1.1.0 - Cross-Platform Fixes, Nix Improvements. Context: Observed during installation or first-run setup.
• Evidence: failure_mode_cluster:github_release | https://github.com/Fission-AI/OpenSpec/releases/tag/v1.1.0

6. Installation risk: Installation risk requires verification

• Severity: medium
• Finding: Developers should check this installation risk before relying on the project: v1.2.0 - Profiles, Pi & Kiro Support
• User impact: Upgrade or migration may change expected behavior: v1.2.0 - Profiles, Pi & Kiro Support
• Recommended check: Before packaging this project, run the relevant install/config/quickstart check for: v1.2.0 - Profiles, Pi & Kiro Support. Context: Observed when using windows
• Evidence: failure_mode_cluster:github_release | https://github.com/Fission-AI/OpenSpec/releases/tag/v1.2.0

7. Installation risk: Installation risk requires verification

• Severity: medium
• Finding: Developers should check this installation risk before relying on the project: v1.3.0 - New Tool Integrations
• User impact: Upgrade or migration may change expected behavior: v1.3.0 - New Tool Integrations
• Recommended check: Before packaging this project, run the relevant install/config/quickstart check for: v1.3.0 - New Tool Integrations. Context: Observed during installation or first-run setup.
• Evidence: failure_mode_cluster:github_release | https://github.com/Fission-AI/OpenSpec/releases/tag/v1.3.0

8. Installation risk: Installation risk requires verification

• Severity: medium
• Finding: Developers should check this installation risk before relying on the project: v1.3.1 - Path & Telemetry Fixes
• User impact: Upgrade or migration may change expected behavior: v1.3.1 - Path & Telemetry Fixes
• Recommended check: Before packaging this project, run the relevant install/config/quickstart check for: v1.3.1 - Path & Telemetry Fixes. Context: Observed when using windows, linux
• Evidence: failure_mode_cluster:github_release | https://github.com/Fission-AI/OpenSpec/releases/tag/v1.3.1

9. Installation risk: Installation risk requires verification

• Severity: medium
• Finding: Developers should check this installation risk before relying on the project: v1.4.0 - Kimi CLI, Mistral Vibe
• User impact: Upgrade or migration may change expected behavior: v1.4.0 - Kimi CLI, Mistral Vibe
• Recommended check: Before packaging this project, run the relevant install/config/quickstart check for: v1.4.0 - Kimi CLI, Mistral Vibe. Context: Observed during installation or first-run setup.
• Evidence: failure_mode_cluster:github_release | https://github.com/Fission-AI/OpenSpec/releases/tag/v1.4.0

10. Installation risk: Installation risk requires verification

• Severity: medium
• Finding: Project evidence flags a installation risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: community_evidence:github | https://github.com/Fission-AI/OpenSpec/issues/1221

11. Installation risk: Installation risk requires verification

• Severity: medium
• Finding: Project evidence flags a installation risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: community_evidence:github | https://github.com/Fission-AI/OpenSpec/issues/1222

12. Installation risk: Installation risk requires verification

• Severity: medium
• Finding: Project evidence flags a installation risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: community_evidence:github | https://github.com/Fission-AI/OpenSpec/issues/1216

Community Discussion Evidence

Doramagic exposes project-level community discussion separately from official documentation. Review these links before using OpenSpec with real data or production workflows.

• Main spec is never created for the first change in a greenfield project - github / github_issue
• Why Cursor version is still 2mo ago - github / github_issue
• Feature Request: Add support for ZCode (Zhipu AI Agents) - github / github_issue
• Feature Request: Add support for ZCode (Zhipu AI Agents) - github / github_issue
• Agent discovery: map natural-language "openspec <verb>" to /opsx:<verb> - github / github_issue
• [[Community Integration Proposal] Minimal AISOP execution graph for the O](https://github.com/Fission-AI/OpenSpec/issues/1217) - github / github_issue
• [openspec config set workflows '[...]' fails — config set cannot set](https://github.com/Fission-AI/OpenSpec/issues/1216) - github / github_issue
• Zed IDE support? - github / github_issue
• spec-driven fast-path workflow silently produces stale specs with no rec - github / github_issue
• Feature Request: Provide an openspec diff command to show differences - github / github_issue
• v1.4.1 - Update Fix - github / github_release
• Installation risk requires verification - GitHub / issue