OpenSpec-practise

OpenSpec User Manual

Based on practical project experience.

Table of Contents

1. Introduction

OpenSpec is a Spec-Driven Development (SDD) framework designed specifically for AI coding assistants. It ensures that humans and AI reach agreement on requirements by defining specs before writing code.

1.1 What is Spec-Driven Development?

The traditional development workflow is: Requirements → Code directly → Test → Deliver.

The Spec-Driven Development workflow is: Requirements → Write Specs → Validate Specs → Implement.

The advantages of this approach are:

1.2 Core Philosophy

Philosophy Meaning
Fluid, not rigid Documents can be updated at any time; no strict phase gates
Iterative, not waterfall Supports incrementally adding requirements and progressively refining them
Simple, not complex Only Markdown files required; no complex toolchain
Works for both new and existing Suitable for existing codebases (Brownfield) as well as brand-new projects (Greenfield)

Terminology:

1.3 Core Value

  1. Align before building
    • Humans and AI agree on the spec before writing any code
    • Avoids rework caused by AI misunderstanding requirements
  2. Stay organized
    • Each change has its own folder
    • Contains proposal, specs, design, and tasks
  3. Fluid iteration
    • Update any document at any time
    • No rigid phase gates
  4. Tool compatibility
    • Supports 20+ AI coding assistants (Claude Code, Cursor, Junie, Lingma IDE, etc.)

2. Installation

2.1 Prerequisites

Check your Node.js version:

node --version

If your version is too old, it is recommended to use nvm or fnm to manage Node.js versions.

2.2 Installation Commands

Install using npm:

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

Using other package managers:

# pnpm (recommended, faster)
pnpm add -g @fission-ai/openspec@latest

# yarn
yarn global add @fission-ai/openspec@latest

# bun
bun install -g @fission-ai/openspec@latest

2.3 Verify Installation

# Check version number
openspec --version

# View help information
openspec --help

After successful installation, you will see output similar to (or manually run openspec --version to check the version number):

1.3.1

2.4 Configure Shell Auto-Completion (Optional)

Since v1.3.0, to avoid encoding issues in certain terminals (such as PowerShell), Shell auto-completion has been changed to opt-in.

If you want to use openspec command completion in your terminal, you can run the following command to generate and install the completion script (supports bash, zsh, fish, etc.):

# View completion command help
openspec completion --help

3. Project Initialization

3.1 Init Command

openspec init is the entry command for OpenSpec. When run in the project root directory, it will:

  1. Guide you to select the AI tools to integrate (or skip interaction with the --tools parameter)
  2. Create the openspec/ working directory (containing config.yaml, changes/, specs/)
  3. Generate slash commands and Skills files in the directories corresponding to the selected AI tools
cd your-project
openspec init

3.2 Interactive Configuration

openspec init is interactive by default and will ask which AI tools you want to configure:

? Which AI tools do you want to configure? (Press <space> to select)
❯◉ Claude Code
 ◯ Cursor
 ◯ GitHub Copilot
 ◯ Cline
 ◯ Windsurf
 ...

Use the space bar to select and Enter to confirm.

Qoder users: If you are using Qoder IDE, select Qoder. OpenSpec v1.2.0 provides native support for Qoder and will automatically generate the corresponding commands and Skills files in .qoder/commands/opsx/ and .qoder/skills/.

3.3 Non-Interactive Mode

For use in scripts or CI/CD environments, you can skip the interactive configuration:

# Skip all tool configuration
openspec init --tools none

# Configure all supported AI tools
openspec init --tools all

# Configure only specific tools (comma-separated)
openspec init --tools claude,cursor

# Configure Qoder
openspec init --tools qoder

Common tool identifier list:

Tool Name --tools value
Claude Code claude
Qoder qoder
Cursor cursor
JetBrains Junie junie
Lingma IDE lingma
ForgeCode forgecode
IBM Bob bob
GitHub Copilot github-copilot
Cline cline
Windsurf windsurf
Amazon Q Developer amazon-q
Gemini CLI gemini
Continue continue
Roo Code roocode

Full list: Run openspec init --help to see all tool identifiers supported by the current version.

3.4 Directory Structure After Init

your-project/
├── openspec/                     # OpenSpec working directory
│   ├── config.yaml               # Project config (tech stack, conventions, etc., injected into AI requests)
│   ├── changes/                  # Change proposal directory (one folder per feature/change)
│   └── specs/                    # Main spec directory (archived specs)
├── .qoder/                       # Qoder-specific directory (example)
│   ├── commands/opsx/            # /opsx slash commands (invoked directly from IDE)
│   │   ├── propose.md
│   │   ├── explore.md
│   │   ├── apply.md
│   │   └── archive.md
│   └── skills/                   # Agent Skills (auto-detected and loaded by AI)
│       ├── openspec-propose/SKILL.md
│       ├── openspec-explore/SKILL.md
│       ├── openspec-apply-change/SKILL.md
│       └── openspec-archive-change/SKILL.md
└── ... (other project files)

Note: openspec init generates commands and Skills files in the corresponding directories based on the AI tools you selected. For example, selecting Claude Code generates .claude/commands/opsx/ and .claude/skills/; selecting Qoder generates .qoder/commands/opsx/ and .qoder/skills/.

3.5 File Descriptions

File/Directory Purpose Required
config.yaml Project background, tech stack, constraints, per-document rule injections Recommended
changes/ Stores active change proposals Required
specs/ Stores archived specs Optional

Difference from older versions: Since v1.0.0, openspec/AGENTS.md and openspec/project.md have been removed. Project context is now written uniformly into the context: field of openspec/config.yaml, which is injected into every AI planning request — more reliable than the old approach.

config.yaml structure example:

schema: spec-driven

context: |
  Tech stack: TypeScript, React, Node.js
  Testing: Jest with React Testing Library
  API: RESTful, documented in docs/api.md
  We maintain backwards compatibility for all public APIs

rules:
  proposal:
    - Include rollback plan for risky changes
  specs:
    - Use Given/When/Then format for scenarios
  design:
    - Include sequence diagrams for complex flows
  tasks:
    - Break tasks into max 2-hour chunks

4. Creating Change Proposals

In OpenSpec, all feature development, bug fixes, and architectural changes are managed as individual “Changes”.

4.1 Creating a New Change

Option 1: Use a slash command (recommended, one step):

/opsx:propose <description>

This command will:

  1. Infer a kebab-case change name (e.g., add-user-auth)
  2. Create openspec/changes/<name>/
  3. Generate all documents — proposal.md, design.md, specs/, tasks.md — in sequence

Option 2: Create the change directory only (used under the extended workflow profile):

Slash command:

/opsx:new <change-name>

Equivalent CLI command:

openspec new change <change-name>

Only initializes the change directory structure without creating any documents; suitable for use with /opsx:continue to manually generate documents step by step.

Naming convention: Use kebab-case (hyphen-separated). The name should clearly and concisely describe the change.

# Good naming examples
add-user-authentication
add-payment-module
fix-login-timeout

# Poor naming examples
feature1           # Too vague
addUserAuth        # Should use kebab-case

4.2 Example: Creating the AI Infrastructure CMDB Core Change

/opsx:propose "Implement AI Infrastructure CMDB core functionality"

The AI will automatically create the change and generate all planning documents:

✓ Created change directory: openspec/changes/ai-infra-cmdb-core/
✓ Created proposal.md
✓ Created design.md
✓ Created specs/ directory
  ✓ specs/accelerator-management/spec.md
✓ Created tasks.md
✓ Created .openspec.yaml

Change 'ai-infra-cmdb-core' created successfully!

4.3 Change Directory Structure Explained

openspec/changes/<change-name>/
├── .openspec.yaml     # Change metadata (ID, status, creation time, etc., managed automatically by CLI)
├── proposal.md        # Proposal document [REQUIRED] describes Why and What
├── design.md          # Technical design document (architecture, data model, API design, etc.)
├── tasks.md           # Implementation task list (to-dos organized by milestone)
└── specs/             # Spec directory (stores capability spec files)
    ├── <capability-1>/
    │   └── spec.md    # Capability spec (using Requirement + Scenario format)
    ├── <capability-2>/
    │   └── spec.md

4.4 File Roles

File Role Required Format Requirements
proposal.md Explains “why” and “what” Required Must contain ## Why and ## What Changes (enforced by validator); recommended to include ## Capabilities (needed by AI workflow)
specs/<capability>/spec.md Detailed requirements and acceptance scenarios Required Must use Delta Header + Requirement + Scenario format
design.md Technical implementation plan Recommended No strict format requirements
tasks.md Implementation task list Recommended No strict format requirements

4.5 Change Lifecycle

Propose (slash command) → Write Specs → Validate → Implement (apply) → Archive
  1. Propose: /opsx:propose <description> (generates all planning documents in one step)
  2. Write specs: Edit proposal.md and specs/
  3. Validate: openspec validate <name>
  4. Implement: /opsx:apply — execute development following tasks.md
  5. Archive: /opsx:archive — merges the change’s spec Deltas back into the openspec/specs/ main spec directory, cleans up the temporary directory under openspec/changes/, and marks the feature spec as officially “live”

5. Document Structure Specification

This section details the format requirements for proposal.md and spec.md. Please follow these formats strictly, or openspec validate will fail.

Template files: OpenSpec ships with built-in templates for all documents. You can view template paths with the openspec templates command, or use /opsx:propose / /opsx:new slash commands to automatically generate complete documents.

5.1 proposal.md - Proposal Document

Core requirements: proposal.md must contain ## Why and ## What Changes — two sections enforced by the validator. It is also recommended to include a ## Capabilities section as the key input for AI to automatically generate specs/<name>/spec.md files.

5.1.1 Why Are These Sections Required?

OpenSpec’s design philosophy is “first think clearly about why, then decide what, then clarify which capabilities are affected”:

5.1.2 Full Format Template

Built-in template paths can be viewed with openspec templates; the /opsx:propose slash command automatically generates a fully populated proposal.

Required section structure:

proposal.md structure:
├── ## Why [REQUIRED - enforced by validator]
│   ├── ### Background
│   ├── ### Problem Statement
│   └── ### Alternatives Considered
├── ## What Changes [REQUIRED - enforced by validator]
│   ├── ### New Resources Added
│   └── ### New Capabilities (natural-language summary of feature points)
├── ## Capabilities [RECOMMENDED - needed by AI workflow, drives spec file generation]
│   ├── ### New Capabilities (kebab-case identifier list, each maps to a specs/<name>/ directory)
│   └── ### Modified Capabilities (requirement changes to existing capabilities)
├── ## Impact
├── ## Scope (optional)
│   ├── ### In Scope
│   └── ### Out of Scope
├── ## Goals (success criteria, optional)
└── ## References (optional)

Note: Section headings must exactly match ## Why and ## What Changes (case-sensitive).

5.2 specs/ Directory - Capability Specs

Core requirement: specs/ must use capability folders — one folder per capability.

Directory Structure Example

specs/
├── accelerator-management/     # Capability 1: Accelerator management
│   └── spec.md
├── training-job-lifecycle/     # Capability 2: Training job lifecycle
│   └── spec.md
├── inference-service/          # Capability 3: Inference service
│   └── spec.md
└── relationship-management/    # Capability 4: Relationship management
    └── spec.md

Important rules:

5.3 spec.md - Capability Spec Format

Core requirement: Must use Delta Header + Requirement + Scenario format.

5.3.1 Format Quick Reference

Element Format Example
Delta Header ## ADDED/MODIFIED/REMOVED Requirements ## ADDED Requirements
Requirement heading ### Requirement: <title> ### Requirement: GPU Auto-Discovery
Scenario heading #### Scenario: <title> #### Scenario: NVIDIA GPU Discovery
Scenario content Gherkin format Given/When/Then

Delta Header selection guide:

Delta Header When to use
## ADDED Requirements New capabilities or requirements added in this change
## MODIFIED Requirements Modifications to an existing Requirement in the spec
## REMOVED Requirements Requirements explicitly deprecated or deleted

5.3.2 Full Format Template

Built-in template paths can be viewed with openspec templates.

Required format structure:

spec.md structure:
├── # Capability Name
├── ## Overview (recommended)
│   - Brief description of the capability
│   - Problem it solves
└── ## ADDED/MODIFIED/REMOVED Requirements [REQUIRED]
    ├── ### Requirement: <title>
    │   ├── **Priority**: P0/P1/P2
    │   ├── **Rationale**: ...
    │   └── #### Scenario: <title>
    │       └── Given/When/Then

5.3.3 Correct Example

The example below shows the core Requirement + Scenario structure. For a complete example (including the ## Overview section), see examples/openspec/changes/v1-mvp/specs/domain-model/spec.md (e-commerce domain model spec):

## ADDED Requirements

### Requirement: Product Entity Definition

The system SHALL define a product entity containing a unique identifier, name, price, and stock level.

**Priority**: P0 (Critical)

**Rationale**: Products are the core entity of an e-commerce system and the foundation for all transactions.

#### Scenario: Create a Valid Product

Given a new product needs to be created
When product information is provided { id, name, priceCents, stock }
Then the product entity is created successfully
And id format is prod_xxxx
And priceCents >= 0
And stock >= 0

5.3.4 Common Error Examples

❌ Error example:

## ADDED Requirements

### REQ-001: GPU Discovery # Error: uses a custom numbering scheme

System SHALL discover GPUs.

#### Scenario: Discovery # Error: scenario title is too vague

✅ Correct version:

## ADDED Requirements

### Requirement: GPU Auto-Discovery # Correct: uses standard format

The system should automatically discover GPU devices in the cluster.

**Priority**: P0 (Critical)

**Rationale**: Core functional requirement.

#### Scenario: NVIDIA GPU Discovery # Correct: scenario title is specific

Given a Kubernetes cluster with NVIDIA GPU nodes
When the discovery agent is deployed to the cluster
Then all NVIDIA GPUs are enumerated and recorded in the CMDB

5.4 design.md - Technical Design

The technical design document has no strict format requirements, but it is recommended to include the following sections.

Built-in template paths can be viewed with openspec templates.

Recommended section structure:

Section Name Recommended Content
Architecture Overview Overall system architecture diagram (Mermaid or ASCII recommended) and layer relationship description
Core Components List of core modules, each module’s responsibilities, boundaries, and internal implementation notes
Data Model Field definitions, types, constraints, and inter-entity relationships for key entities
API Design Interface routes, request/response formats, and error code specifications
Integration Patterns Integration approaches with external systems/modules, including events, queues, synchronous calls, etc.
Technology Stack Selected technologies and libraries, rationale, and comparison with alternatives
Security Authentication, authorization, data encryption, input validation, and other security design points
Deployment Environment requirements, deployment steps, and rollback plan

5.5 tasks.md - Task List

The task list is used to break down the design into executable implementation steps. It is recommended to organize by milestone using GitHub-style Markdown task lists so that items can be checked off directly in the IDE.

Built-in template paths can be viewed with openspec templates.

Recommended section structure:

Example:

## Milestone 1 - Domain Model

### Definition of Done

- All P0 Requirements implemented
- `openspec validate v1-mvp` passes
- Unit tests cover all domain entities

### Tasks

- [x] Define Product entity type (id, name, priceCents, stock)
- [x] Define Cart / CartItem entity types
- [ ] Define Order / OrderItem entity types
- [ ] Implement orchestration validation logic for domain entities

## Milestone 2 - Service Layer

### Definition of Done

- All service methods have corresponding integration tests

### Tasks

- [ ] Implement CatalogService.getProduct / listProducts
- [ ] Implement CartService.addItem / removeItem
- [ ] Implement OrderService.checkout

5.6 Format Quick Reference

proposal.md required sections:

├── ## Why [REQUIRED - enforced by validator]
│   ├── ### Background
│   ├── ### Problem Statement
│   └── ### Alternatives Considered
├── ## What Changes [REQUIRED - enforced by validator]
│   ├── ### New Resources Added
│   └── ### New Capabilities
└── ## Capabilities [RECOMMENDED - needed by AI workflow, drives spec file generation]
    ├── ### New Capabilities
    └── ### Modified Capabilities

specs/[capability]/spec.md required format:

├── # Capability Name
├── ## Overview (recommended)
└── ## ADDED/MODIFIED/REMOVED Requirements [REQUIRED]
    ├── ### Requirement: <title>
    │   ├── **Priority**: P0/P1/P2
    │   ├── **Rationale**: ...
    │   └── #### Scenario: <title>
    │       └── Given/When/Then

5.7 Template File Summary

Template Corresponding built-in file (view full path with openspec templates) Purpose
proposal.md template schemas/spec-driven/templates/proposal.md Proposal document template
spec.md template schemas/spec-driven/templates/spec.md Capability spec template
design.md template schemas/spec-driven/templates/design.md Technical design template
tasks.md template schemas/spec-driven/templates/tasks.md Task list template

6. Validation and Common Errors

6.1 Validation Command

After writing documents, use the validation command to check whether the format is correct:

openspec validate <change-name>

On success:

Change '<change-name>' is valid

On failure, specific error messages will be displayed.

6.2 Common Errors and Solutions

6.2.1 Error 1: No Deltas Found

Error message:

✗ [ERROR] file: Change must have at least one delta. No deltas found.
Ensure your change has a specs/ directory with capability folders

Cause: The specs/ directory structure is incorrect.

Solution:

  1. Ensure there is a capability folder under specs/:

    specs/
└── your-capability/      # Capability folder
    └── spec.md           # Spec file

  2. Ensure spec.md contains a Delta Header:

    ## ADDED Requirements

### Requirement: Some Requirement

...

Common mistake:

specs/
└── spec.md              # ❌ Error: placed directly in the specs/ root

6.2.2 Error 2: Requirement Entry Parsing Failed

Error message:

✗ [ERROR] cap1/spec.md: Delta sections ## ADDED Requirements were found, but no requirement entries parsed. Ensure each section includes at least one "### Requirement:" block (REMOVED may use bullet list syntax).

Cause: The requirement heading format is incorrect.

Error examples:

## ADDED Requirements

### REQ-001: GPU Discovery # ❌ Error: uses a custom numbering scheme

### GPU Discovery # ❌ Error: missing "Requirement:" prefix

### requirement: GPU Discovery # ❌ Error: "requirement" should be capitalized

Correct format:

## ADDED Requirements

### Requirement: GPU Auto-Discovery # ✓ Correct format

6.2.3 Error 3: Missing Scenario Block

Error message:

✗ [ERROR] cap1/spec.md: ADDED "test" must include at least one scenario

Cause: Every requirement must have at least one scenario.

Error example:

### Requirement: GPU Auto-Discovery

The system should automatically discover GPU devices.

# ❌ No scenario block

Correct format:

### Requirement: GPU Auto-Discovery

The system should automatically discover GPU devices.

**Priority**: P0 (Critical)

**Rationale**: Core functional requirement.

#### Scenario: NVIDIA GPU Discovery

Given a Kubernetes cluster with NVIDIA GPU nodes
When the discovery agent is deployed to the cluster
Then all NVIDIA GPUs are enumerated and recorded in the CMDB

6.3 Debugging Tips

6.3.1 View Delta Parsing Results

If validation fails but you are unsure why, you can view the parsed structure:

openspec show <change-name> --json --deltas-only

This outputs the parsed result in JSON format, helping you understand how OpenSpec is interpreting your documents.

6.3.2 View Change Status

openspec status --change <change-name>

Tip: Since v1.3.0, if no changes currently exist, the openspec status command will exit gracefully (with a “no changes” message) instead of throwing a fatal error.

Example output:

Change: ai-infra-cmdb-core
Schema: spec-driven
Progress: 1/4 artifacts complete

[x] proposal
[ ] design
[ ] specs
[-] tasks (blocked by: design, specs)

6.3.3 Validation Checklist

Before running openspec validate, confirm:

7. Command Reference

7.1 Init and Create

Command Description Example
openspec init Initialize an OpenSpec project openspec init --tools qoder
openspec new change <name> Create only the change directory openspec new change add-user-auth
openspec update Update AI skill and command files openspec update

7.2 View and Validate

Command Description Example
openspec view Open the terminal UI openspec view
openspec status --change <name> View change status openspec status --change user-auth
openspec validate <name> Validate change document format openspec validate user-auth
openspec list --changes List all changes openspec list --changes
openspec list --specs List all specs openspec list --specs
openspec show <name> Show change details openspec show user-auth --json --deltas-only

7.3 Archive and Manage

Command Description Example
openspec archive <name> Archive a completed change (merges Deltas into the specs/ main directory and cleans up the temporary directory under changes/) openspec archive user-auth

7.4 Config and Debug

Command Description Example
openspec config list View current configuration openspec config list
openspec config profile Set the workflow profile openspec config profile
openspec templates View absolute paths to built-in templates openspec templates
openspec schemas List available schemas openspec schemas
openspec --version View version number openspec --version
openspec --help View help information openspec --help

7.5 Global Options

openspec [options] <command>

Options:
  -V, --version     Show version number
  -h, --help        Show help information
  --no-color        Disable colored output

Note: --json is a per-command option, not a global option. For example: openspec show <name> --json or openspec validate --json.

7.6 Command Quick Reference

Quick reference for common commands:

# Initialize project
openspec init --tools none

# Create change directory (directory only, no documents generated)
openspec new change <name>

# List all changes / specs
openspec list --changes
openspec list --specs

# Validate a change
openspec validate <name>

# View status
openspec status --change <name>

# Archive a change
openspec archive <name>

# Update tool files
openspec update

8. Best Practices

8.1 Proposal Writing Best Practices

8.1.2 Practices to Avoid

8.1.3 Example Comparison

❌ Poor Why section:

## Why

We need to add user authentication functionality.

✅ Good Why section:

## Why

### Background

The current system has no user authentication, allowing anyone to access all data and functionality.
This results in:

- No accountability for operation logs
- Sensitive data left unprotected
- No way to implement fine-grained access control

### Problem Statement

The system needs a secure and reliable user authentication mechanism supporting:

- Username/password login
- Third-party OAuth login (GitHub, Google)
- Session management and secure logout

### Alternatives Considered

1. **Build a custom auth system**: Full control, but high development and maintenance cost
2. **Use Auth0**: Feature-rich, but relatively expensive
3. **Use Keycloak**: Open-source and free, supports multiple protocols ✓ Selected

8.2 Spec Writing Best Practices

8.2.2 Practices to Avoid

8.3 Scenario Writing Best Practices

8.3.1 Gherkin Format Key Points

Keyword Purpose Example
Given Precondition; describes initial state Given the user is logged into the system
When Triggering action When the user clicks the "Submit Order" button
Then Expected result Then the order status changes to "Pending Payment"
And Connects multiple conditions or results And the user receives an order confirmation email

8.3.2 Good Scenario Example

Scenario: Pay for an order with a credit card

Given the user is logged into the system
And the cart contains 2 items totaling $29.99
And the user has a credit card on file
When the user selects "Credit Card Payment" and confirms
Then the order is created successfully
And $29.99 is charged to the credit card
And the user receives a payment success notification
And inventory is reduced by 2

8.3.3 Poor Scenario Example

Scenario: Payment

Given the system
When payment
Then success

Problems:

8.4 Iterative Development Best Practices

8.5 AI Collaboration Best Practices

OpenSpec 1.0+ introduced the new OPSX workflow, replacing the old phase-locked mode. All commands are installed into the corresponding AI tool directory via openspec init.

Default Core configuration (4 commonly used commands):

Command Purpose
/opsx:propose <description> Creates a change in one step and intelligently generates all planning documents (AI infers the kebab-case directory name and fills in proposal/design/specs/tasks)
/opsx:explore Enter exploration mode: think through problems and investigate the codebase without writing code
/opsx:apply Implement tasks following tasks.md
/opsx:archive Complete and archive the current change

Extended workflow commands (enabled via openspec config profile):

Command Purpose
/opsx:new Initialize change directory structure only, without creating documents
/opsx:continue Create the next document in dependency order (step-by-step mode)
/opsx:ff Fast-forward to generate all planning documents in one step
/opsx:verify Verify that the implementation is consistent with the spec
/opsx:sync Merge Delta Specs into the main spec without archiving
/opsx:bulk-archive Batch-archive multiple completed changes
/opsx:onboard Guided 15-minute full-workflow walkthrough, ideal for onboarding new users

Migration note: Legacy commands (/openspec:proposal, /openspec:apply, /openspec:archive) were removed in v1.0.0. Mapping:

8.5.2 Tips for Collaborating with AI

  1. Explore before proposing: When unsure, use /opsx:explore to think things through, then use /opsx:propose once clear
  2. Embrace fluid iteration: Discovered a design error during implementation? Simply edit the relevant document — no phase locks
  3. Periodically clear conversation context: Before starting implementation tasks, it is recommended to clear the current conversation context to ensure high-quality instruction injection
  4. Iterate incrementally: Validate after completing each requirement, then proceed to the next

8.6 Team Collaboration Best Practices

8.6.1 Code Review Checklist

When reviewing a PR, check the OpenSpec documents:

8.6.2 Documentation Maintenance

9. Appendix

9.1 Supported AI Tools

OpenSpec supports 20+ AI coding assistants. The most common ones are:

Tool Type Support Level
Claude Code CLI + IDE Full support
Qoder IDE Full support
Cursor IDE Full support
JetBrains Junie IDE plugin Full support
Lingma IDE IDE plugin Full support
ForgeCode IDE plugin Full support
IBM Bob IDE plugin Full support
GitHub Copilot IDE plugin Full support
Cline VS Code plugin Full support
Windsurf IDE Full support
Amazon Q Developer IDE plugin Full support
Gemini CLI CLI Full support
Continue IDE plugin Full support
Aider CLI Supported (command-line tool; openspec init auto-generation not supported)
Roo Code VS Code plugin Full support

9.2 Telemetry Settings

OpenSpec collects anonymous usage statistics to improve the product. To disable:

# Option 1: Set environment variable
export OPENSPEC_TELEMETRY=0

# Option 2: Use the universal telemetry opt-out flag
export DO_NOT_TRACK=1

# Option 3: Set permanently in your shell config file
echo 'export OPENSPEC_TELEMETRY=0' >> ~/.zshrc  # Zsh
echo 'export OPENSPEC_TELEMETRY=0' >> ~/.bashrc # Bash

9.3 FAQ

9.3.1 Q1: What is the difference between OpenSpec and Swagger/OpenAPI?

Feature OpenSpec OpenAPI/Swagger
Primary purpose Spec-driven requirements development API interface documentation
Document type Markdown YAML/JSON
Validation CLI validation + AI understanding Syntax validation
Applicable phase Early development (requirements definition) Mid-development (interface definition)
Target users Product managers + developers + AI Developers + frontend

The two can be used together: use OpenSpec to define requirements and scenarios first, then use OpenAPI to define interface details.

9.3.2 Q2: How do I introduce OpenSpec into an existing project?

  1. Run openspec init --tools none in the project root
  2. Create a change proposal for the next feature
  3. Build the spec system incrementally; there is no need to cover all existing functionality at once

9.3.3 Q3: What if the AI doesn’t follow the spec after I write it?

  1. Run openspec update to refresh Skills and command files
  2. Restart the IDE to make slash commands take effect
  3. Add specific constraints to the rules: field in openspec/config.yaml
  4. Use /opsx:apply to have the AI start from the task list rather than asking it to write code directly

9.3.4 Q4: Can multiple changes proceed simultaneously?

OpenSpec’s change directory design naturally supports parallel workflows, but dependencies need to be managed reasonably.

Yes, multiple changes can proceed simultaneously. Each change is an independent folder and they do not interfere with each other. However, to reduce the risk of merge conflicts, it is recommended to:

9.3.5 Q5: How to describe internal logic changes (e.g., database state changes) using externally observable behavior?

OpenSpec emphasizes “externally observable behavior”, but this is not limited to front-end UI changes; it also includes inter-system interactions and changes in persisted state. For purely internal logic (e.g., a condition change that only reflects in the database), you can handle it in the following ways to maintain Spec consistency.

9.3.6 Q6: Are BDD format Specs (Given/When/Then) written by AI or humans?

To ensure the accuracy of business logic and the stability of specifications, teams should adopt a collaborative model of human-led design and AI-assisted generation.

9.3.7 Q7: How to maintain the readability of baseline Specs when business logic becomes complex (e.g., hundreds of lines in a single method)?

Complex business logic often makes Specs difficult to read. In such cases, architectural splitting and expression optimization are required to maintain document clarity and maintainability.

Resource Link
Official repository https://github.com/Fission-AI/OpenSpec
Getting started https://openspec.pro/getting-started/
Official documentation https://github.com/Fission-AI/OpenSpec/tree/main/docs
npm package https://www.npmjs.com/package/@fission-ai/openspec
Companion slides (old version) openspec-user-manual-v1.pptx
Companion slides (current) openspec-user-manual-v2.pptx

Document version: 2.2 Last updated: 2026-05-07 Based on Issue #7 added FAQ and optimized document structure. Includes OpenSpec v1.3.1 updates.

This site is open source. Improve this page.