Related Pages

Related topics: Getting Started, System Architecture

Introduction to OpenSpec

OpenSpec is a lightweight specification framework designed to bring structure and alignment to AI-assisted software development. It establishes a shared understanding between human developers and AI coding assistants before any code is written, reducing unpredictability and improving project organization.

Purpose and Scope

AI coding assistants are powerful but often unpredictable when project requirements exist only in chat history. OpenSpec adds a lightweight spec layer that ensures human and AI align on specifications before code gets written.

The framework operates under a core philosophy:

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

Sources: README.md:1-20

Core Features

OpenSpec provides several key capabilities:

Sources: README.md:21-30

Architecture Overview

OpenSpec uses an artifact-guided workflow where changes are organized into structured folders. The system tracks dependencies between artifacts and automatically manages state transitions.

graph TD
    A[User Request] --> B[Proposal]
    B --> C[Specs]
    C --> D[Design]
    D --> E[Tasks]
    E --> F[Implementation]
    F --> G[Archive]
    G --> C
    
    H[Config.yaml] --> A
    H --> B
    H --> C
    
    style A fill:#e1f5fe
    style G fill:#c8e6c9

Sources: CHANGELOG.md:1-30

The Change Structure

Every change in OpenSpec follows a consistent folder structure:

openspec/
├── specs/                    # Source-of-truth specifications
│   └── <capability>/
│       └── spec.md
├── changes/
│   ├── <change-name>/        # Active change folder
│   │   ├── proposal.md       # Why and what changes
│   │   ├── tasks.md          # Implementation checklist
│   │   ├── design.md         # Technical decisions (optional)
│   │   └── specs/
│   │       └── <capability>/
│   │           └── spec.md   # Delta showing additions/modifications
│   └── archive/              # Completed changes
│       └── YYYY-MM-DD-<change-name>/
└── config.yaml               # Project configuration

Sources: README.md:200-230

Workflow System

OpenSpec supports multiple workflow approaches:

Standard Workflow

The traditional linear approach:

1. Propose - Create a change proposal that captures spec updates
2. Review - Review the proposal with AI assistant until agreement
3. Implement - Implement tasks that reference agreed specs
4. Archive - Archive the change to merge approved updates back into source specs

Experimental Workflow

The new artifact-guided workflow using slash commands:

Sources: README.md:150-170

Instruction System

OpenSpec dynamically assembles instructions from three layers:

graph LR
    A[Context] --> D[Enriched Instruction]
    B[Rules] --> D
    C[Template] --> D
    
    A1[project.yaml] --> A
    B1[Artifact-specific] --> B
    C1[Schema template] --> C

Context Layer

Project background from config.yaml including tech stack and conventions. Applied to all artifacts.

Rules Layer

Artifact-specific constraints (e.g., "propose spike tasks for unknowns"). Applied only to matching artifacts.

Template Layer

The actual structure for the output file, sourced from schemas.

Sources: CHANGELOG.md:40-70

Supported AI Tools

OpenSpec integrates with 25+ AI coding assistants through slash commands or natural language:

Native Slash Commands

Workflow-Based Tools

Sources: README.md:80-120

Installation and Setup

Prerequisites

• Node.js >= 20.19.0 - Check with node --version

Installation Methods

Option A: npm (Global)

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

Option B: nix (NixOS)

nix run github:Fission-AI/OpenSpec -- init

Or install to profile:

nix profile install github:Fission-AI/OpenSpec

Sources: README.md:50-80

Quick Start

# Navigate to project
cd your-project

# Initialize OpenSpec
openspec init

# Start a new change
/opsx:propose <what-you-want-to-build>

# Or use CLI directly
openspec new <change-name>

Sources: README.md:40-55

Command Reference

Sources: README.md:180-200

Telemetry

OpenSpec collects anonymous usage statistics to understand usage patterns:

• Collected: Command names and version only
• NOT collected: Arguments, paths, content, or PII
• Auto-disabled: In CI environments

Opt-out:

export OPENSPEC_TELEMETRY=0
# or
export DO_NOT_TRACK=1

Sources: README.md:220-240

Contributing to OpenSpec

# Install dependencies
pnpm install

# Build
pnpm run build

# Test
pnpm test

# Develop CLI locally
pnpm run dev
pnpm run dev:cli

Commit convention:

type(scope): subject

Sources: README.md:250-260

License

OpenSpec is released under the MIT License.

Related Pages

Related topics: Introduction to OpenSpec, Slash Commands

Getting Started

Overview

OpenSpec is a lightweight specification framework designed to help development teams align on requirements before writing code. It provides a structured approach to capturing proposals, specifications, designs, and implementation tasks in organized change folders that integrate seamlessly with AI coding assistants.

The "Getting Started" documentation serves as the entry point for new users, covering prerequisites, installation methods, project initialization, and the fundamental workflows that define how OpenSpec operates. This guide ensures users can quickly set up OpenSpec in their development environment and begin using its artifact-guided workflow for managing changes systematically.

Prerequisites

System Requirements

OpenSpec has specific version requirements that must be met before installation:

Sources: README.md:1

To verify your Node.js installation, run:

node --version

If the version is below 20.19.0, you must upgrade Node.js before proceeding with OpenSpec installation.

Installation

OpenSpec can be installed through multiple methods depending on your development environment and preferences.

Method 1: npm (Global Installation)

The standard installation method uses npm to install OpenSpec globally:

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

After installation, verify the installation by checking the version:

openspec --version

Sources: README.md:1

Method 2: Nix Package Manager

For NixOS or Nix package manager users, OpenSpec can be run directly without explicit installation:

nix run github:Fission-AI/OpenSpec -- init

Alternatively, install to your user profile:

nix profile install github:Fission-AI/OpenSpec

Or add to your Nix configuration for persistent access.

Method 3: Development Installation

For contributors or those who want to work with the source code:

# Clone the repository
git clone https://github.com/Fission-AI/OpenSpec.git
cd OpenSpec

# Install dependencies
pnpm install

# Build the project
pnpm run build

# Run tests
pnpm test

# Develop CLI locally
pnpm run dev

Sources: README.md:1

Project Initialization

Once OpenSpec is installed, navigate to your project directory and initialize the OpenSpec structure:

cd your-project
openspec init

The initialization process creates the necessary directory structure for OpenSpec artifacts:

openspec/
├── config.yaml          # Project configuration and context
├── specs/               # Schema definitions and templates
└── changes/             # Individual change proposals

What `openspec init` Creates

Legacy Cleanup

When running openspec init in an existing project that previously used OpenSpec, the initialization process detects and handles legacy artifacts:

• Old slash command directories (.claude/commands/openspec/)
• Config files with OpenSpec markers (CLAUDE.md, .cursorrules, .windsurfrules)
• Legacy openspec/AGENTS.md files

Users are prompted for confirmation before removing these legacy artifacts.

Sources: README.md:1 Sources: openspec/changes/archive/2026-02-17-merge-init-experimental/design.md:1

Core Workflow: Artifact-Guided Approach

OpenSpec uses an experimental artifact-guided workflow centered on creating structured changes. The workflow revolves around four key artifacts that capture different aspects of a change:

graph TD
    A[Propose Change] --> B[Create Proposal]
    B --> C[Write Specs]
    C --> D[Design Solution]
    D --> E[Define Tasks]
    E --> F[Implement]
    F --> G[Verify]
    G --> H[Archive]
    
    I[Iterate on Any Artifact] -.-> A
    I -.-> B
    I -.-> C
    I -.-> D
    I -.-> E

The Four Core Artifacts

Each change folder under openspec/changes/<change-name>/ contains these artifacts organized in a predictable structure.

Sources: README.md:1

Supported AI Coding Assistants

OpenSpec integrates with over 25 AI coding assistants through slash commands. The supported tools include:

To check if your tool is supported, view the full list of supported tools.

Sources: README.md:1 资料来源 docs/supported-tools.md

Essential Commands

Quick Command Reference

Sources: README.md:1 资料来源 docs/cli.md

The Experimental Workflow

OpenSpec offers an experimental artifact-guided workflow that provides a more flexible, iterative approach to managing changes.

Enabling Experimental Features

openspec experimental

Experimental Slash Commands

资料来源 docs/opsx.md

Workflow Comparison

Telemetry

OpenSpec collects anonymous usage statistics to understand usage patterns. Only command names and version numbers are collected—no arguments, paths, content, or personally identifiable information.

To opt out:

export OPENSPEC_TELEMETRY=0

Or set the DO_NOT_TRACK environment variable:

export DO_NOT_TRACK=1

Telemetry is automatically disabled in CI environments.

Sources: README.md:1

Next Steps

After completing the initial setup:

1. Review Documentation

• Workflows - Combos and patterns
• Commands - Slash commands & skills
• Concepts - How OpenSpec fits together

1. Try the Workflow

• Create your first proposal using /opsx:propose
• Work through the artifact sequence
• Archive and review the result

1. Configure Your Tool

• Set up slash commands for your preferred AI assistant
• Run openspec update to refresh command files

1. Explore Advanced Features

• Multi-language support: docs/multi-language.md
• Customization options: docs/customization.md
• Community schemas: Browse the catalog in customization docs

Troubleshooting

Common Issues

Getting Help

• Join the OpenSpec Discord for questions
• Follow @0xTab on X for updates
• Review archived changes in openspec/changes/archive/ for examples

Related Pages

Related topics: Introduction to OpenSpec, Artifact Graph System, Workflows

System Architecture

OpenSpec is a lightweight specification framework designed to add a spec layer between human-AI alignment and code implementation. The system architecture enables teams to agree on what to build before any code is written, maintaining organization through structured change folders and dynamic instruction generation.

Architecture Overview

OpenSpec follows a modular architecture with clear separation between CLI interface, core business logic, and artifact management. The framework is designed to be tool-agnostic, supporting 25+ AI assistants through slash commands and natural language processing.

graph TD
    subgraph "CLI Layer"
        CLI[CLI Entry Point]
        Commands[Slash Commands]
    end
    
    subgraph "Core Layer"
        Config[Project Config]
        Schemas[Schema System]
        Artifacts[Artifact Graph]
        Instructions[Instruction Loader]
    end
    
    subgraph "Change Management"
        Changes[Change Folders]
        Proposals[Proposals]
        Specs[Specs]
        Designs[Designs]
        Tasks[Tasks]
    end
    
    CLI --> Commands
    Commands --> Artifacts
    Artifacts --> Instructions
    Instructions --> Config
    Instructions --> Schemas
    Artifacts --> Changes
    Changes --> Proposals
    Changes --> Specs
    Changes --> Designs
    Changes --> Tasks

Core Components

CLI Interface

The CLI serves as the entry point for all OpenSpec operations. It handles initialization, change management, and command execution across supported tools.

Sources: openspec/changes/archive/2025-08-06-add-init-command/design.md:1-50

Schema System

Schemas define the workflow structure and artifact templates for OpenSpec changes. The system supports three schema sources:

Sources: openspec/changes/archive/2026-02-17-project-local-schemas/design.md:1-30

Schema Resolution Order:

1. CLI --schema flag (explicit override)
2. .openspec.yaml in change directory (change-specific binding)
3. openspec/config.yaml schema field (project default)
4. "spec-driven" (hardcoded fallback)

The default spec-driven schema includes artifacts: proposal, specs, design, and tasks.

Sources: openspec/changes/archive/2026-02-17-project-config/design.md:1-50

Artifact Graph System

The artifact graph tracks dependencies between different artifacts and manages their creation state. This system replaces the old phase-locked workflow with a flexible action-based model.

Artifact Types

Instruction Loading

Instructions are dynamically assembled from three layers:

graph LR
    A[Context] --> D[Enriched Instruction]
    B[Rules] --> D
    C[Template] --> D
    
    subgraph "Instruction Components"
        A
        B
        C
    end

Sources: openspec/changes/archive/2025-12-28-add-instruction-loader/design.md:1-30

Instruction Structure:

<context>
[Project context from config.yaml]
</context>

<rules>
- Rule 1 for specific artifact
- Rule 2 for specific artifact
</rules>

<template>
[Schema's specs template]
</template>

Rules only appear for the specific artifact they're configured for. Artifacts without rules (e.g., design, tasks) don't get a <rules> section.

Sources: openspec/changes/archive/2026-02-17-project-config/design.md:50-100

Project Configuration

Project configuration is stored in openspec/config.yaml and provides shared context and rules across the entire project.

Configuration Structure

context: |
  Tech stack: TypeScript, React
  Key conventions: ...

schema: spec-driven

rules:
  proposal:
    - Include rollback plan
  specs:
    - Use Given/When/Then format for scenarios

Sources: openspec/changes/archive/2026-02-17-project-config/design.md:100-150

Design Decisions

1. Config file location: openspec/config.yaml in project root

• Mirrors structure used by other tools (e.g., .github/)
• Keeps OpenSpec-related files under one directory

1. XML tags vs Markdown sections: Use XML-style tags <context> and <rules>

• Clear delimiters that don't conflict with Markdown
• Agents can easily parse structure

1. Rules validation: Warn on unknown artifact IDs, don't error

• Future-proof for new artifact types
• Non-breaking change for existing configs

Sources: openspec/changes/archive/2026-02-17-project-config/design.md:150-200

Command Workflow

Modern Workflow (opsx)

The new artifact-guided workflow provides flexible action-based interactions:

Sources: README.md:1-50

Legacy Commands

The legacy slash commands have been removed:

• /openspec:proposal - Removed
• /openspec:apply - Removed
• /openspec:archive - Removed

Tool-specific instruction files (CLAUDE.md, .cursorrules, AGENTS.md, project.md) are no longer generated.

Sources: CHANGELOG.md:1-30

Change Lifecycle

graph TD
    A[Create Change] --> B[Write Proposal]
    B --> C[Create Specs]
    C --> D[Write Design]
    D --> E[Implement Tasks]
    E --> F[Archive Change]
    
    G[Explore Ideas] -.-> A
    
    style A fill:#e1f5fe
    style F fill:#fff3e0

Change Directory Structure

openspec/
├── config.yaml           # Project configuration
├── schemas/              # Project-local schemas
│   └── <schema-name>/
│       └── templates/
└── changes/
    ├── <change-name>/
    │   ├── proposal.md
    │   ├── specs/
    │   │   └── *.md
    │   ├── design.md
    │   ├── tasks.md
    │   └── .openspec.yaml
    └── archive/
        └── <date>-<change-name>/

Sources: openspec/changes/archive/2025-09-29-add-slash-command-support/proposal.md:1-30

Data Flow Architecture

Instruction Generation Flow

sequenceDiagram
    participant User
    participant CLI
    participant Config
    participant Schema
    participant Loader
    participant Output
    
    User->>CLI: openspec instructions <artifact>
    CLI->>Config: readProjectConfig()
    Config-->>CLI: context + rules
    CLI->>Schema: resolveSchemaForChange()
    Schema-->>CLI: schema name
    CLI->>Loader: loadInstructions(change, artifact)
    Loader->>Schema: getTemplate(artifact)
    Schema-->>Loader: baseInstructions
    Loader->>Config: getRulesForArtifact(artifact)
    Config-->>Loader: artifactRules
    Loader->>Output: enrichInstruction(context, rules, template)
    Output-->>User: Enriched instruction with XML sections

Sources: openspec/changes/archive/2026-02-17-project-config/design.md:200-250

Schema Loading Priority

When loading schemas, the system checks multiple locations in order:

graph TD
    A[Schema Request] --> B{Project schemas dir?}
    B -->|Yes| C[Return project-local schema]
    B -->|No| D{User schemas dir?}
    D -->|Yes| E[Return user schema]
    D -->|No| F[Return package schema]
    
    C --> G[Schema found]
    E --> G
    F --> G

Sources: openspec/changes/archive/2026-02-17-project-local-schemas/design.md:50-80

Extensibility Points

Slash Command Configuration

Slash commands are managed through a SlashCommandConfigurator that handles multiple files per tool:

• getTargets(): Expose targets with path and kind
• generateAll(projectPath, openspecDir): For init
• updateExisting(projectPath, openspecDir): For update

Sources: openspec/changes/archive/2025-09-29-add-slash-command-support/proposal.md:50-80

Template System

Templates are brief, actionable, and sourced from openspec/README.md. Each command body includes:

• Guardrails: Ask 1-2 clarifying questions if needed
• Step list tailored to workflow stage
• Pointers to troubleshooting tips

Sources: openspec/changes/archive/2025-09-29-add-slash-command-support/proposal.md:30-50

Security Considerations

The implementation includes several security measures:

Sources: openspec/changes/archive/2025-08-06-add-init-command/design.md:50-70

Performance and Caching

Project config is read multiple times during a single command execution:

1. Schema resolution - To know which schema to use
2. Instruction loading - To inject context and rules

Rules are validated lazily during instruction loading (not at config load time) because:

• Schema isn't known at config load time (circular dependency)
• Warnings shown when user actually uses the feature (better UX)
• Validation warnings cached per session to avoid spam

Sources: openspec/changes/archive/2026-02-17-project-config/design.md:250-280

Technology Stack

Sources: README.md:50-80

Related Pages

Related topics: Workflows, Getting Started, Supported AI Tools

Slash Commands

Slash Commands provide a convenient shorthand mechanism for invoking OpenSpec workflows directly from AI coding assistants. Instead of typing verbose natural language instructions, users can trigger specific OpenSpec actions through a single slash command invocation, streamlining the specification-driven development workflow.

Overview

OpenSpec integrates with over 20 AI coding assistants through native slash command support. These commands serve as shortcuts that invoke predefined workflow templates, allowing AI assistants to execute OpenSpec operations without requiring manual CLI invocation.

The slash command system is built on two fundamental principles:

1. Centralized Templates: Command bodies are defined once and reused across all supported tools, ensuring consistency while allowing minimal per-tool adaptations.
2. Per-Tool Organization: Each AI assistant receives its commands in the format and location that tool natively recognizes.

Sources: openspec/changes/archive/2025-09-29-add-slash-command-support/proposal.md:1-20

Supported Tools and Command Formats

Different AI coding assistants use varying conventions for slash command naming and organization. The following table summarizes the supported tools and their respective command formats.

Sources: README.md:1-80

Core Commands

OpenSpec defines three primary slash commands that cover the essential workflow stages.

Proposal Command

The proposal command initiates a new change specification. When invoked, the AI assistant creates a dedicated change folder with the necessary artifact structure.

You: /openspec:propose add-dark-mode
AI:  Created openspec/changes/add-dark-mode/
     ✓ proposal.md — why we're doing this, what's changing
     ✓ specs/       — requirements and scenarios
     ✓ design.md    — technical approach
     ✓ tasks.md     — implementation checklist
     Ready for implementation!

Sources: README.md:1-30

Apply Command

The apply command transitions the workflow from specification to implementation. It reads the tasks from the change folder and executes them in sequence, marking each task as complete.

You: /opsx:apply
AI:  Implementing tasks...
     ✓ 1.1 Add theme context provider
     ✓ 1.2 Create toggle component
     ✓ 2.1 Add CSS variables
     ✓ 2.2 Wire up localStorage
     All tasks complete!

Sources: README.md:1-30

Archive Command

The archive command finalizes a completed change by moving it to the archive directory and updating the source-of-truth specifications.

You: /openspec:archive
AI:  Archived to openspec/changes/archive/2025-01-23-add-dark-mode/
     Specs updated. Ready for the next feature.

Sources: README.md:1-30

Command File Structure

File Format and Metadata

Slash command files are stored as Markdown with optional YAML frontmatter for tool-specific metadata. The frontmatter, when supported, includes fields such as name, description, and category or tags.

Related Pages

Related topics: Slash Commands, Artifact Graph System

Workflows

Overview

Workflows in OpenSpec define the ordered sequence of artifacts that get created during a change's lifecycle. They provide a structured approach to capturing requirements, design decisions, and implementation tasks before any code is written.

Purpose: Workflows ensure that human and AI assistants align on what to build through a consistent, repeatable process that captures the "why," "what," and "how" of each change.

Scope: A workflow determines which artifacts need to be created, in what order, and what dependencies exist between them.

Sources: README.md

Core Concepts

Artifacts

Artifacts are the files created during a change lifecycle. OpenSpec supports the following artifact types:

Sources: openspec/changes/archive/2025-09-29-add-slash-command-support/proposal.md

Workflow Stages

Each workflow progresses through distinct stages:

graph LR
    A[Propose] --> B[Design]
    B --> C[Specs]
    C --> D[Tasks]
    D --> E[Apply]
    E --> F[Archive]
    
    style A fill:#e1f5fe
    style E fill:#fff3e0
    style F fill:#f3e5f5

Sources: README.md

Workflow Templates

OpenSpec ships with predefined workflow templates located in src/core/templates/workflows/.

The New Change Workflow

The new change workflow (new-change.ts) scaffolds a complete change structure:

export const newChangeWorkflow = {
  name: "New Change",
  description: "Scaffold a new OpenSpec change and validate strictly.",
  async execute(params) {
    // 1. Validate change name (kebab-case)
    // 2. Check if change already exists
    // 3. Create change directory
    // 4. Show artifact status
    // 5. Output first artifact template
  }
};

Sources: src/core/templates/workflows/new-change.ts

Workflow Execution Steps

When initiating a new change, the workflow performs these steps in order:

1. Validate the change name

• Must be kebab-case (e.g., add-dark-mode)
• If invalid, prompt for a valid name

1. Check for existing changes

• If a change with the same name exists, suggest using continue-change instead

1. Create the scaffold

• Run openspec init --change "<name>" with --schema <name> if a specific workflow is requested
• Creates openspec/changes/<name>/ with the selected schema

``bash openspec status --change "<name>" `` This displays which artifacts need creation and which are ready (dependencies satisfied).

1. Show artifact status

``bash openspec instructions <first-artifact-id> --change "<name>" `` This outputs the template and context for creating the first artifact.

1. Output first artifact template

1. STOP and wait for user direction

Sources: src/core/templates/workflows/new-change.ts:1-60

Guardrails

The new change workflow includes important guardrails:

• Do NOT create any artifacts yet — only show the instructions
• Do NOT advance beyond showing the first artifact template
• Pass --schema only if using a non-default workflow
• Changes with invalid names (not kebab-case) trigger a prompt for correction
• Existing changes suggest using /continue instead

Sources: src/core/templates/workflows/new-change.ts

Workflow Patterns

Spec-Driven Workflow

The spec-driven workflow emphasizes design-first approach:

graph TD
    P[proposal] --> D[design]
    D --> S[specs]
    S --> T[tasks]
    
    P -.->|blocking| S
    P -.->|blocking| T
    D -.->|blocking| T

Artifact Flow

┌────────────────────┐
│ Archive & Update   │
│ Specs (source)     │
└────────────────────┘
         │
         ▼
┌────────────────────┐
│ 1. Draft proposal  │
└────────────────────┘
         │
         ▼
┌────────────────────┐
│ 2. Review proposal │
└────────────────────┘
         │
         ▼
┌────────────────────┐
│ 3. Implement tasks │
└────────────────────┘
         │
         ▼
┌────────────────────┐
│ 4. Archive change  │
└────────────────────┘
         │
         ▼
┌────────────────────┐
│ Specs updated      │
└────────────────────┘

Sources: openspec/changes/archive/2025-10-14-add-windsurf-workflows/proposal.md

Workflows with Slash Commands

OpenSpec integrates with multiple AI coding assistants through slash command workflows. Each tool has its own command structure and file format.

Supported Tools and Commands

Sources: README.md

Slash Command File Structure

Slash command files follow a consistent pattern:

Related Pages

Related topics: System Architecture, Workflows, Schemas

Artifact Graph System

Overview

The Artifact Graph System is the core module of OpenSpec that manages artifact dependencies, workflow state detection, and schema-driven instruction generation. It provides a declarative way to define artifact relationships through YAML schemas and enables intelligent workflow progression based on filesystem state.

Purpose

The system solves several key problems in AI-assisted development:

1. Dependency Management - Ensures artifacts are created in the correct order based on their dependencies
2. State Detection - Automatically detects which artifacts are completed, ready, or blocked based on filesystem presence
3. Schema Resolution - Supports both user-defined schemas (via XDG directories) and built-in package schemas
4. Instruction Generation - Enriches templates with project context, artifact-specific rules, and dependency status

High-Level Architecture

graph TB
    subgraph "Artifact Graph System"
        YAML[("Schema YAML")]
        GRAPH[("ArtifactGraph")]
        STATE[("State Detection")]
        INSTR[("Instruction Loader")]
        CTX[("ChangeContext")]
    end
    
    subgraph "Schema Sources"
        USER[("User Schemas<br/>XDG_DATA_HOME")]
        BUILTIN[("Built-in Schemas<br/>Package")]
    end
    
    YAML --> GRAPH
    GRAPH --> STATE
    GRAPH --> CTX
    STATE --> CTX
    CTX --> INSTR
    
    USER -->|resolveSchema| GRAPH
    BUILTIN -->|resolveSchema| GRAPH

Core Concepts

Artifacts

Artifacts are the fundamental units of work in OpenSpec. Each artifact has:

Schema Structure

Schemas define the workflow for a change. They are YAML files with the following structure:

name: spec-driven
version: 1
description: Specification-driven development workflow

artifacts:
  - id: proposal
    generates: "proposal.md"
    template: "proposal.md"
    requires: []

  - id: specs
    generates: "specs/*.md"
    template: "spec.md"
    requires: [proposal]

  - id: design
    generates: "design.md"
    template: "design.md"
    requires: [proposal]

  - id: tasks
    generates: "tasks.md"
    template: "tasks.md"
    requires: [specs, design]

ArtifactGraph Class

The ArtifactGraph class is the central component that loads schemas and provides graph query operations.

Class Structure

export class ArtifactGraph {
  private artifacts: Map<string, Artifact>;
  private schema: SchemaYaml;

  private constructor(schema: SchemaYaml) {
    this.schema = schema;
    this.artifacts = new Map(schema.artifacts.map(a => [a.id, a]));
  }
}

Factory Methods

Query Methods

State Detection

The state detection module (state.ts) monitors the filesystem to determine the status of each artifact relative to a change directory.

State Types

State Detection Logic

interface ArtifactGraphResult {
  completed: string[];      // Artifact IDs that are fully completed
  ready: string[];          // Artifact IDs ready to work on
  blocked: BlockedArtifacts; // Artifact IDs with their unmet dependencies
  buildOrder: string[];     // Topological order for creation
}

The detection process:

1. For each artifact, check if files matching generates exist in the change directory
2. Collect all completed artifact IDs into a CompletedSet (a Set<string>)
3. For each non-completed artifact, find which dependencies are unmet
4. Artifacts with all dependencies met are marked ready

Topological Sorting

The system uses Kahn's algorithm for topological sorting to determine the correct build order for artifacts.

Algorithm Properties

• Cycle Detection: Kahn's algorithm naturally fails on cyclic dependencies, providing natural cycle detection
• Stable Ordering: Independent artifacts are returned in definition order
• Linear Time: O(V + E) where V is artifacts and E is dependencies

Error Format

When a cycle is detected, the error message clearly identifies the cycle path:

Cyclic dependency detected: A → B → C → A

Schema Resolution

The resolver.ts module handles loading schemas from multiple sources with a defined priority order.

Resolution Order

graph LR
    A[("Schema Name")] --> B{Global Override?}
    B -->|Yes| C["${XDG_DATA_HOME}/openspec/schemas/<name>"]
    B -->|No| D{Package Built-in?}
    D -->|Yes| E["<package>/schemas/<name>"]
    D -->|No| F[("Error: Schema not found")]
    C --> G[("Loaded Schema")]
    E --> G

Resolution Paths

Fallback Behavior: If XDG_DATA_HOME is not set, the system falls back to ~/.local/share on Unix systems.

Built-in Schemas

OpenSpec ships with two built-in schemas:

spec-driven Schema

The default schema following a proposal → specs → design → tasks workflow:

name: spec-driven
artifacts:
  - id: proposal
    generates: "proposal.md"
    requires: []
  - id: specs
    generates: "specs/*.md"
    requires: [proposal]
  - id: design
    generates: "design.md"
    requires: [proposal]
  - id: tasks
    generates: "tasks.md"
    requires: [specs, design]

tdd Schema

An alternative schema for test-driven development:

name: tdd
artifacts:
  - id: tests
    generates: "tests/*.md"
    requires: []
  - id: implementation
    generates: "implementation.md"
    requires: [tests]
  - id: docs
    generates: "docs.md"
    requires: [implementation]

Instruction Loading

The instruction-loader.ts module enriches templates with change-specific context and project configuration.

ChangeContext Interface

interface ChangeContext {
  changeName: string;
  changeDir: string;
  schemaName: string;
  graph: ArtifactGraph;
  completed: CompletedSet;
}

Instruction Output Structure

Instructions are formatted with XML-like sections for AI consumption:

<artifact id="proposal" change="add-auth" schema="spec-driven">
<context>
[Project context from config]
</context>

<rules>
[Artifact-specific rules from config]
</rules>

<template>
[Schema's template content]
</template>

Context Injection Rules

File Structure

src/core/artifact-graph/
├── index.ts              # Public exports
├── types.ts              # Zod schemas and TypeScript types
├── graph.ts              # ArtifactGraph class
├── state.ts              # State detection logic
├── resolver.ts           # Schema resolution
├── schema.ts             # YAML parsing and validation
├── outputs.ts            # Output path resolution
├── instruction-loader.ts # Template enrichment
└── schemas/              # Built-in schema definitions
    ├── spec-driven/
    │   ├── schema.yaml
    │   └── templates/
    └── tdd/
        ├── schema.yaml
        └── templates/

Integration Points

With Workflow Commands

The Artifact Graph System integrates with the /opsx:continue and /opsx:apply workflows:

1. Continue Workflow - Reads instructions for the next ready artifact
2. Apply Workflow - Checks completion status and provides apply-phase instructions

With Project Config

Project-level configuration (openspec/config.yaml) can provide:

• Default schema selection
• Project context for all artifacts
• Per-artifact rules and guidelines

Testing

The system includes comprehensive test coverage:

Related Documentation

• Schema Directories Design - Schema directory structure
• Instruction Loader Design - Template loading and enrichment
• Apply-Phase Schema Design - Apply phase configuration
• Project Config Design - Project-level configuration integration

Related Pages

Related topics: Validation System, Artifact Graph System

Schemas

Schemas define the workflow structure for OpenSpec changes. They specify which artifacts should be created, their dependencies, requirements for completion, and how the apply phase operates.

Overview

A schema in OpenSpec is a configuration that defines a complete workflow for planning and implementing changes. Schemas specify:

• The artifacts to create (e.g., proposal, specs, design, tasks)
• The dependencies between artifacts
• Requirements that must be met before each artifact is considered complete
• Templates for generating artifact content
• Apply phase configuration for implementation guidance

Schemas are self-contained directories containing schema.yaml and template files, following a structure similar to Helm charts. Sources: openspec/changes/archive/2025-12-28-restructure-schema-directories/design.md

Schema Directory Structure

schemas/
├── spec-driven/
│   ├── schema.yaml           # Schema definition
│   └── templates/
│       ├── proposal.md
│       ├── design.md
│       ├── spec.md
│       └── tasks.md
└── tdd/
    ├── schema.yaml
    └── templates/
        ├── spec.md
        ├── test.md
        ├── implementation.md
        └── docs.md

Built-in schemas are distributed with the package, while user overrides can be placed in XDG data directories. Sources: openspec/changes/archive/2025-12-28-restructure-schema-directories/design.md

Schema Resolution Order

OpenSpec resolves schemas using a priority-based lookup:

graph TD
    A[Schema Request] --> B{CLI --schema flag?}
    B -->|Yes| C[Use CLI flag]
    B -->|No| D{.openspec.yaml in change?}
    D -->|Yes| E[Use change metadata]
    D -->|No| F{openspec/config.yaml schema?}
    F -->|Yes| G[Use project default]
    F -->|No| H{"spec-driven" fallback}

Sources: openspec/changes/archive/2026-02-17-project-config/design.md

Schema YAML Format

Core Fields

name: spec-driven
version: 1
description: Specification-driven development

Artifacts Section

The artifacts array defines each artifact in the workflow:

artifacts:
  - id: proposal
    generates: proposal.md
    template: proposal.md
    requires: []
    
  - id: specs
    generates: specs/
    template: spec.md
    requires:
      - proposal

Sources: schemas/spec-driven/schema.yaml

Built-in Schemas

spec-driven

The default schema focused on specification-driven development. It emphasizes clear requirements and scenarios before implementation.

Artifact Flow:

graph LR
    A[proposal] --> B[specs]
    B --> C[design]
    C --> D[tasks]
    D --> E[apply]

workspace-planning

Schema for multi-repository planning and coordination across workspaces.

Sources: schemas/workspace-planning/schema.yaml

tdd (Test-Driven Development)

Schema focused on tests first, following the pattern: spec → test → implementation → docs.

Requirements Format

Requirements define completion criteria for artifacts. They use a structured format with scenarios.

## Requirements

### Requirement: <name>
<description using SHALL/MUST for normative requirements>

#### Scenario: <name>
- **WHEN** <condition>
- **THEN** <expected outcome>

Key Formatting Rules:

• Requirements use ### Requirement: with exactly 3 hashtags
• Scenarios use #### Scenario: with exactly 4 hashtags
• Use SHALL/MUST for normative requirements (avoid should/may)
• Every requirement MUST have at least one scenario

Sources: schemas/spec-driven/schema.yaml

Apply Phase Configuration

The optional apply block defines how implementation should proceed:

apply:
  requires:
    - specs
    - design
    - tasks
  tracks:
    - id: implementation
      label: Implementation
  instruction: |
    Proceed with implementation based on the tasks artifact.

Sources: openspec/changes/archive/2026-01-06-make-apply-instructions-schema-aware/tasks.md

Schema Resolution Implementation

The resolveSchema() function handles schema loading with user overrides:

// Resolution order (highest to lowest priority)
1. ${XDG_DATA_HOME}/openspec/schemas/<name>/schema.yaml   // User override
2. <package>/schemas/<name>/schema.yaml                   // Built-in

function getPackageSchemasDir(): string {
  const currentFile = fileURLToPath(import.meta.url);
  // Navigate from src/core/artifact-graph/ to package root
  return path.join(path.dirname(currentFile), '..', '..', '..', 'schemas');
}

Sources: openspec/changes/archive/2025-12-28-restructure-schema-directories/design.md

Template Loading

Templates are loaded relative to the schema's templates/ directory:

# In schema.yaml
artifacts:
  - id: proposal
    template: "proposal.md"  # → schemas/spec-driven/templates/proposal.md

Templates are simple markdown files without template engine dependencies. Context injection prepends a header section:

Related Pages

Related topics: Getting Started

Configuration

OpenSpec uses a layered configuration system that manages project-level settings, global defaults, and user preferences. This configuration architecture enables teams to share project context, define artifact-specific rules, and customize the OpenSpec workflow across different environments.

Overview

The OpenSpec configuration system serves three primary purposes:

1. Schema Selection — Define which OpenSpec schema to use for change management
2. Context Injection — Provide project background (tech stack, conventions, terminology) that gets injected into generated artifacts
3. Per-Artifact Rules — Define constraints and guidelines that apply to specific artifact types

graph TD
    A[User Project] --> B[openspec/config.yaml]
    A --> C[Global Config]
    A --> D[User Config]
    
    B --> E[Schema Resolution]
    C --> E
    D --> E
    
    E --> F[spec-driven]
    E --> G[minimal]
    E --> H[custom schemas]
    
    F --> I[Artifact Generation]
    G --> I
    H --> I
    
    I --> J[proposal.md]
    I --> K[specs/*.md]
    I --> L[design.md]
    I --> M[tasks.md]

Sources: openspec/changes/archive/2026-02-17-project-config/design.md

Configuration Files

Project Configuration (`openspec/config.yaml`)

The project-level configuration file lives in the openspec/ directory and is designed to be committed to version control. This ensures all team members share the same project context and rules.

Location: <project-root>/openspec/config.yaml

Structure:

schema: spec-driven
context:
  project_name: My Application
  tech_stack:
    - Node.js
    - TypeScript
    - PostgreSQL
  conventions:
    - Use async/await for all asynchronous operations
    - Follow conventional commits
  terminology:
    - "change" refers to a feature or fix being implemented
    - "artifact" refers to a generated file

rules:
  proposal:
    - Include spike tasks for unknowns
  specs:
    - Use SHALL/MUST for normative requirements
    - Every requirement needs at least one scenario

Sources: openspec/changes/archive/2026-02-17-project-config/proposal.md

Schema Configuration

Each schema defines its own structure and templates. The spec-driven schema, for example, includes requirements for how artifacts should be formatted:

artifacts:
  - id: proposal
    generates: proposal.md
    requires: []
    
  - id: specs
    generates: specs/*.md
    requires:
      - proposal
      
  - id: design
    generates: design.md
    requires:
      - proposal
      - specs

Sources: schemas/spec-driven/schema.yaml

Configuration Architecture

Configuration Resolution Order

OpenSpec resolves configuration values using a specific precedence order:

graph LR
    A[CLI Flag] -->|highest| B[Change Metadata]
    B --> C[Project Config]
    C -->|lowest| D[Global Config]
    D --> E[Hardcoded Default]

Sources: openspec/changes/archive/2026-02-17-project-config/design.md

Module Structure

src/core/
├── config.ts           # Main configuration module
├── config-schema.ts    # Configuration schema definitions
├── global-config.ts    # Global configuration management
├── project-config.ts   # Project-level configuration handling
└── profiles.ts         # Profile management

Sources: openspec/changes/archive/2026-02-17-project-config/design.md

Core Modules

Project Config Module

The project-config.ts module handles reading, parsing, and validating project-level configuration.

Key Responsibilities:

• Read openspec/config.yaml from the project root
• Parse YAML into typed configuration objects
• Validate schema names against available schemas
• Provide error messages for misconfiguration

Validation Logic:

export function validateProjectConfig(config: ProjectConfig): ValidationResult {
  const errors: string[] = [];
  
  if (config.schema) {
    const availableSchemas = getAvailableSchemas();
    if (!availableSchemas.includes(config.schema)) {
      errors.push(`Invalid schema: ${config.schema}`);
    }
  }
  
  return { valid: errors.length === 0, errors };
}

Sources: src/core/project-config.ts

Profile Management

Profiles allow users to customize their OpenSpec workflow by selecting different command sets and behaviors.

graph TD
    A[Profile Selection] --> B[Minimal Profile]
    A --> C[Artifact-Guided Profile]
    A --> D[Experimental Profile]
    
    B --> B1[Basic commands: init, list, show]
    C --> C1[opsx commands: new, continue, ff]
    D --> D1[Early access features]

Available Profiles:

Sources: openspec/README.md

Configuration CLI Commands

The config command group provides interactive management of OpenSpec configuration.

Commands

Interactive Profile Selection

$ openspec config profile
? Select a profile:
  > minimal (default)
    artifact-guided (recommended)
    experimental

Sources: src/commands/config.ts

Context and Rules Injection

How Context Works

The project context section is injected into generated artifacts to provide project-specific background information:

# Get instructions for artifact with context
openspec instructions specs --change my-feature

# Output structure:
<context>
[Project context from config.yaml]
</context>

<template>
[Schema's specs template]
</template>

Sources: openspec/changes/archive/2026-02-17-project-config/proposal.md

Rule Injection by Artifact Type

Rules are only injected for artifacts that have them configured:

graph TD
    A[Artifact Request] --> B{Has rules?}
    B -->|Yes| C[Include rules section]
    B -->|No| D[Skip rules section]
    
    C --> E[<context>]
    C --> F[<rules>]
    C --> G[<template>]
    
    D --> E
    D --> G

Example: Rules for proposal artifact:

rules:
  proposal:
    - Include spike tasks for unknown complexities
    - Reference existing patterns before inventing new ones

Example: Rules for specs artifact:

rules:
  specs:
    - Use SHALL/MUST for normative requirements
    - Every requirement MUST have at least one scenario
    - Scenarios MUST use exactly 4 hashtags (####)

Sources: schemas/spec-driven/schema.yaml

Schema Resolution

Resolution Function

The resolveSchemaForChange() function determines which schema to use:

export function resolveSchemaForChange(
  changeName: string,
  cliSchema?: string
): string {
  // 1. CLI flag wins
  if (cliSchema) {
    return cliSchema;
  }

  // 2. Change metadata (.openspec.yaml)
  const metadata = readChangeMetadata(changeName);
  if (metadata?.schema) {
    return metadata.schema;
  }

  // 3. Project config (NEW)
  const projectConfig = readProjectConfig();
  if (projectConfig?.schema) {
    return projectConfig.schema;
  }

  // 4. Hardcoded default
  return 'spec-driven';
}

Sources: openspec/changes/archive/2026-02-17-project-config/design.md

Project-Local Schemas

OpenSpec supports project-local schemas that override built-in schemas:

graph TD
    A[Schema Request] --> B{Project-local exists?}
    B -->|Yes| C[Use project-local]
    B -->|No| D{User override exists?}
    D -->|Yes| E[Use user override]
    D -->|No| F[Use built-in]

Schema Search Order:

1. <project>/openspec/schemas/<name>/
2. <user-data>/openspec/schemas/<name>/
3. <npm-package>/schemas/<name>/

Sources: openspec/changes/archive/2026-02-17-project-local-schemas/design.md

Global Configuration

Global configuration lives in the user's home directory and provides defaults that apply across all projects.

Default Location: ~/.config/openspec/config.yaml (Linux/macOS)

Purpose:

• Default profile selection
• Telemetry preferences
• Editor-specific settings

Telemetry Configuration

OpenSpec collects anonymous usage statistics by default:

# Opt-out via environment variable
export OPENSPEC_TELEMETRY=0
# or
export DO_NOT_TRACK=1

Sources: openspec/README.md

Validation and Error Handling

Configuration Validation

The validation system checks for common configuration errors:

export function validateConfig(config: unknown): ValidationResult {
  const errors: string[] = [];
  
  // Check schema validity
  if (!config.schema || !isValidSchema(config.schema)) {
    errors.push(`Invalid schema: ${config.schema}`);
  }
  
  // Check context structure
  if (config.context && typeof config.context !== 'object') {
    errors.push('Context must be an object');
  }
  
  return { valid: errors.length === 0, errors };
}

Error Messages

When validation fails, OpenSpec provides actionable error messages:

Error: Invalid schema 'unknown-schema'
Available schemas:
  Built-in: spec-driven, minimal, gpt-prompts
  Project-local: (none found)

Fix: Edit openspec/config.yaml and change 'schema: unknown-schema' to a valid schema name

Sources: src/core/project-config.ts

Migration from Legacy Config

Old Configuration Files

OpenSpec previously used different configuration mechanisms that are now deprecated:

Migration Steps

1. Run openspec init to detect legacy artifacts
2. Review the migration hints provided
3. Manually migrate project.md content to config.yaml.context
4. Delete old configuration files when ready

Sources: openspec/changes/archive/2026-02-17-merge-init-experimental/design.md

Best Practices

Configuration Organization

1. Commit config.yaml — Keep project configuration in version control for team consistency
2. Use descriptive context — Include tech stack, conventions, and terminology
3. Define artifact rules — Set clear guidelines for each artifact type
4. Keep rules concise — Rules should be actionable constraints, not verbose documentation

Team Collaboration

# Share configuration via git
git add openspec/config.yaml
git commit -m "Add project config with context and rules"

# Everyone gets the same context and rules automatically

Sources: openspec/changes/archive/2026-02-17-project-config/proposal.md

Summary

The OpenSpec configuration system provides a flexible, layered approach to managing project settings:

• Project-level config (openspec/config.yaml) for team-shared context and rules
• Schema-based organization for consistent artifact generation
• Per-artifact rules for tailored guidelines
• Profile system for workflow customization
• Validation to catch configuration errors early

Related Pages

Related topics: Schemas, Configuration

Validation System

Overview

The OpenSpec Validation System is a multi-layered infrastructure that ensures specification files, change artifacts, and project configurations conform to defined schemas and structural requirements. The validation system serves as the quality gate for the entire OpenSpec workflow, preventing malformed specs from entering the repository and maintaining consistency across teams and projects.

The validation system operates at multiple levels: structural validation of markdown content, schema-based validation using Zod, and command-level validation for CLI operations. This layered approach ensures that validation is both comprehensive and performant, catching errors early in the development workflow.

The system is designed to be reusable across different commands and workflows, following the principle established in the implementation order that schemas and validation infrastructure should be shared between command implementations.

Architecture Overview

graph TD
    A[User/CLI Command] --> B[Validation Entry Point]
    B --> C[Command Validation]
    B --> D[Spec Structure Validation]
    B --> E[Schema Validation]
    
    C --> F[openspec validate]
    C --> G[openspec show --json --deltas-only]
    C --> H[openspec instructions]
    
    D --> I[Markdown Parser]
    D --> J[Spec Structure Parser]
    D --> K[Scenario Parser]
    
    E --> L[Zod Schemas]
    E --> M[Custom Validators]
    
    I --> N[Header Extraction]
    I --> O[Content Normalization]
    J --> P[Requirement Parsing]
    J --> Q[Delta Detection]
    K --> R[WHEN/THEN Format]
    K --> S[Scenario Validation]
    
    L --> T[ArtifactSchema]
    L --> U[SchemaYamlSchema]
    L --> V[ChangeMetadataSchema]

Core Components

Validation Types (`src/core/validation/types.ts`)

The types module defines the foundational data structures used throughout the validation system. These types are constructed using Zod schemas to enable runtime validation with full type inference.

The type definitions ensure that all validation operations work with consistent data structures, reducing runtime errors and improving developer experience through IDE autocompletion.

Validation Constants (`src/core/validation/constants.ts`)

Constants define the boundaries and thresholds for validation operations. These values are extracted into a dedicated module to allow easy tuning without modifying validation logic.

// Example constant categories
const VALIDATION = {
  MAX_REQUIREMENT_LENGTH: 500,
  MAX_SCENARIO_COUNT: 50,
  MIN_REQUIREMENT_COUNT: 1,
  REQUIRED_HEADERS: ['## Purpose', '## Requirements'],
} as const;

const ERROR_CODES = {
  MISSING_REQUIREMENT: 'SPEC_001',
  MISSING_SCENARIO: 'SPEC_002',
  INVALID_FORMAT: 'SPEC_003',
  CYCLIC_DEPENDENCY: 'GRAPH_001',
  INVALID_DELTA: 'DELTA_001',
} as const;

Core Validator (`src/core/validation/validator.ts`)

The validator module contains the primary validation logic that orchestrates checks across different validation layers. It provides a unified interface for validating various OpenSpec artifacts.

Key Responsibilities:

• Coordinating validation across multiple layers (structural, schema, semantic)
• Aggregating errors and warnings from different validators
• Providing detailed error messages with file paths and line numbers
• Supporting both synchronous and asynchronous validation flows

// Conceptual validation flow
async function validateSpec(specPath: string): Promise<ValidationResult> {
  const errors: ValidationError[] = [];
  const warnings: ValidationWarning[] = [];
  
  // Layer 1: File existence and readability
  const fileResult = await validateFileAccess(specPath);
  if (!fileResult.valid) return fileResult;
  
  // Layer 2: Structure validation
  const structure = await parseSpecStructure(specPath);
  const structureErrors = validateStructure(structure);
  errors.push(...structureErrors);
  
  // Layer 3: Content validation
  const contentErrors = validateContent(structure);
  errors.push(...contentErrors);
  
  // Layer 4: Cross-reference validation
  const xrefErrors = validateCrossReferences(structure);
  errors.push(...xrefErrors);
  
  return {
    valid: errors.length === 0,
    errors,
    warnings,
  };
}

Spec Structure Validation

Markdown Parser (`src/core/parsers/spec-structure.ts`)

The spec structure parser extracts structured data from markdown-formatted specification files. It handles the unique requirements of OpenSpec's spec format, including requirement blocks, scenario definitions, and delta operations.

Parsing Capabilities:

The parser handles multiple content types found in OpenSpec specifications:

• Requirements: Extracted from ### Requirement: headers with accompanying descriptions
• Scenarios: Parsed from #### Scenario: headers using WHEN/THEN/AND format
• Delta Operations: Identifies ADDED, MODIFIED, REMOVED, and RENAMED sections
• Frontmatter: Processes YAML frontmatter for metadata and schema references

Critical Parsing Rules:

Per the schema specification, scenario headers must use exactly four hashtags (####) followed by Scenario:. Using three hashtags or bullet-point formats will result in silent parsing failures.

// Scenario detection pattern
const SCENARIO_PATTERN = /^#### Scenario:\s*(.+)$/gm;
const WHEN_PATTERN = /^\*?\*?WHEN\*?\*?\s+(.+)$/im;
const THEN_PATTERN = /^\*?\*?THEN\*?\*?\s+(.+)$/im;
const AND_PATTERN = /^\*?\*?AND\*?\*?\s+(.+)$/im;

Content Normalization

The validation system normalizes input content to handle platform-specific line endings. This is particularly important because different operating systems use different line ending conventions:

• Unix/Linux/macOS: LF (\n)
• Windows: CRLF (\r\n)
• Legacy systems: CR (\r)

The parser normalizes all line endings before processing to ensure consistent behavior regardless of the file's origin.

Schema Validation

Zod Integration

OpenSpec uses Zod for schema validation throughout the system. Zod provides runtime type validation with compile-time type inference, eliminating the gap between TypeScript types and runtime behavior.

Schema Types:

Schema Loading and Validation

Schemas are loaded from openspec/schemas/<schema-name>/schema.yaml and validated against the SchemaYamlSchema before use. This two-stage validation ensures that invalid schema definitions are caught early.

// Schema loading flow
async function loadSchema(schemaName: string, projectRoot: string): Promise<SchemaYaml> {
  const schemaPath = getSchemaPath(schemaName, projectRoot);
  const rawYaml = await fs.readFile(schemaPath, 'utf-8');
  const parsed = YAML.parse(rawYaml);
  
  // Validate against schema schema
  const result = SchemaYamlSchema.safeParse(parsed);
  if (!result.success) {
    throw new SchemaValidationError(result.error);
  }
  
  return result.data;
}

Command-Level Validation

CLI Validate Command (`src/commands/validate.ts`)

The openspec validate command provides the primary interface for manual and automated validation of OpenSpec artifacts.

Usage:

openspec validate <change> [--strict]
openspec validate --specs [--all]
openspec validate --changes [--all]

Flags:

Validation Output:

When validation succeeds, the command outputs a summary table:

✓ Change "add-dark-mode" validated successfully
  - proposal.md: valid
  - specs/auth/spec.md: valid (2 requirements, 5 scenarios)
  - tasks.md: valid (12 tasks)

When validation fails, the output includes detailed error information:

✗ Validation failed for "update-auth-flow"
  - specs/auth/spec.md:12
    ERROR [SPEC_002]: Requirement "Legacy export" missing scenario
    HELP: Add at least one scenario using "#### Scenario:" header

  - specs/auth/spec.md:45
    ERROR [SPEC_003]: Invalid WHEN/THEN format
    HELP: Use "**WHEN** condition" and "**THEN** outcome" format

Validation Workflows

Change Lifecycle Validation

graph LR
    A[Create Change] --> B[Validate Proposal]
    B --> C{Valid?}
    C -->|No| D[Fix Errors]
    D --> B
    C -->|Yes| E[Implement Tasks]
    E --> F[Validate Specs]
    F --> G{Valid?}
    G -->|No| H[Update Specs]
    H --> F
    G -->|Yes| I[Archive Change]
    I --> J[Final Validation]
    J --> K[Merge to Source]

Delta Detection Validation

The validation system extracts deltas from change spec files and validates their structure before applying them to the source specifications. This ensures that only properly formatted changes are merged.

Delta Types:

Delta Extraction Process:

1. Parse the spec file in the change's specs/ directory
2. Identify delta section headers using operation prefixes
3. Validate each delta against the appropriate schema
4. Check for conflicts between MODIFIED and REMOVED deltas
5. Generate a validation report with all findings

Error Handling

Error Code Reference

Recovery Strategies

The validation system implements graceful degradation for common issues:

Silent Failures Prevention:

• Scenario parsing failures are caught and reported explicitly
• Missing headers trigger specific error messages with fix suggestions
• Format violations include the expected format in the error output

Partial Success Handling:

When a file contains multiple issues, validation continues to identify all problems rather than failing on the first error. This reduces the number of validation cycles needed to fix all issues.

Integration with Other Modules

Project Configuration

The validation system respects project-level configuration defined in openspec/config.yaml. Project-specific rules can be configured to add validation constraints beyond the defaults.

validation:
  strict: true
  allowedDeltaTypes: [ADDED, MODIFIED, REMOVED]
  requireDesignArtifact: true

Artifact Graph Integration

Validation is integrated with the artifact graph system to validate artifact state transitions and dependency requirements. Before marking an artifact as complete, the validation system verifies all prerequisites are satisfied.

Change Manager Integration

The change manager uses validation to enforce naming conventions and structural requirements when creating new changes. Invalid change names or structures are rejected at creation time.

Best Practices

Writing Valid Specs

1. Use Exact Headers: Always use #### Scenario: with four hashtags for scenarios
2. Follow WHEN/THEN Format: Structure scenarios with clear conditions and outcomes
3. Include All Scenarios: Every requirement must have at least one scenario
4. Use ADDED/MODIFIED/REMOVED: Prefix delta sections with operation names
5. Keep Scenarios Testable: Scenarios should describe observable behavior

Validation in CI/CD

Integrate validation into continuous integration pipelines:

# Example CI configuration
- name: Validate OpenSpec changes
  run: |
    npx openspec validate --changes --strict

Debugging Validation Failures

When validation fails, use the JSON output for programmatic inspection:

openspec show add-feature --json --deltas-only

This outputs the parsed deltas without full change details, helping identify parsing issues.

Related Pages

Related topics: Slash Commands

Supported AI Tools

OpenSpec is designed to integrate seamlessly with a wide variety of AI coding assistants. The supported AI tools system enables OpenSpec to provide consistent specification workflows across different development environments and toolchains.

Overview

OpenSpec supports AI tools through a multi-layered integration system that includes:

• Native Slash Commands: Built-in commands directly recognized by the AI tool
• Slash Command Templates: Tool-specific command files with frontmatter metadata
• AGENTS.md Compatible: Workflow instructions that AI tools can automatically discover

Sources: README.md:1-100

Architecture

The AI tools integration is built on a modular architecture with three core components:

graph TD
    A[User Request] --> B[OpenSpec CLI]
    B --> C{Determine Tool}
    C --> D[Claude Code]
    C --> E[Cursor]
    C --> F[Codex]
    C --> G[Amazon Q]
    C --> H[Other Tools]
    
    D --> I[Slash Commands]
    E --> J[Cursor Commands]
    F --> K[Codex Commands]
    G --> L[Q Developer Prompts]
    H --> M[AGENTS.md]
    
    I --> N[openspec/proposal<br/>openspec/apply<br/>openspec/archive]
    J --> O[openspec-proposal<br/>openspec-apply<br/>openspec-archive]

Sources: src/core/command-generation/adapters/index.ts

Supported Tools List

OpenSpec integrates with the following AI coding assistants:

Sources: docs/supported-tools.md

Tool Categories

Native Slash Commands

Tools with native slash command support have built-in OpenSpec commands. When initializing OpenSpec for these tools, select the appropriate integration option.

graph LR
    A[openspec init] --> B[Select Tool]
    B --> C[Claude Code]
    B --> D[Cursor]
    B --> E[Windsurf]
    
    C --> F[Creates: .claude/commands/openspec/]
    D --> G[Creates: .cursor/commands/]
    E --> H[Creates: .windsurf/workflows/]

Sources: README.md:150-200

AGENTS.md Compatible

Some tools automatically read workflow instructions from openspec/AGENTS.md. These tools can be instructed to follow the OpenSpec workflow using natural language.

Sources: README.md:200-250

Command Structure

Slash Command Format

Commands follow a consistent pattern across tools but with tool-specific adaptations:

Doramagic Pitfall Log

Doramagic extracted 16 source-linked risk signals. Review them before installing or handing real data to the project.

1. Installation risk: /opsx:apply suggests openspec-continue-change which is not installed on core profile

• Severity: high
• Finding: Installation risk is backed by a source signal: /opsx:apply suggests openspec-continue-change which is not installed on core profile. Treat it as a review item until the current version is checked.
• User impact: First-time setup may fail or require extra isolation and rollback planning.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: Source-linked evidence: https://github.com/Fission-AI/OpenSpec/issues/963

2. Configuration risk: Support schema extension or partial overrides to avoid full shadowing of built-in schemas

• Severity: high
• Finding: Configuration risk is backed by a source signal: Support schema extension or partial overrides to avoid full shadowing of built-in schemas. Treat it as a review item until the current version is checked.
• User impact: Users may get misleading failures or incomplete behavior unless configuration is checked carefully.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: Source-linked evidence: https://github.com/Fission-AI/OpenSpec/issues/1074

3. Maintenance risk: open:sync messed up my spec.md files

• Severity: high
• Finding: Maintenance risk is backed by a source signal: open:sync messed up my spec.md files. Treat it as a review item until the current version is checked.
• User impact: Users cannot judge support quality until recent activity, releases, and issue response are checked.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: Source-linked evidence: https://github.com/Fission-AI/OpenSpec/issues/911

4. Installation risk: Codex generated assets reference unsupported AskUserQuestion/TodoWrite/Task tools

• Severity: medium
• Finding: Installation risk is backed by a source signal: Codex generated assets reference unsupported AskUserQuestion/TodoWrite/Task tools. Treat it as a review item until the current version is checked.
• User impact: First-time setup may fail or require extra isolation and rollback planning.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: Source-linked evidence: https://github.com/Fission-AI/OpenSpec/issues/1103

5. Installation risk: First steps don't work

• Severity: medium
• Finding: Installation risk is backed by a source signal: First steps don't work. Treat it as a review item until the current version is checked.
• User impact: First-time setup may fail or require extra isolation and rollback planning.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: Source-linked evidence: https://github.com/Fission-AI/OpenSpec/issues/820

6. Installation risk: v1.1.0 - Cross-Platform Fixes, Nix Improvements

• Severity: medium
• Finding: Installation risk is backed by a source signal: v1.1.0 - Cross-Platform Fixes, Nix Improvements. Treat it as a review item until the current version is checked.
• User impact: First-time setup may fail or require extra isolation and rollback planning.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: Source-linked evidence: https://github.com/Fission-AI/OpenSpec/releases/tag/v1.1.0

7. Installation risk: v1.3.1 - Path & Telemetry Fixes

• Severity: medium
• Finding: Installation risk is backed by a source signal: v1.3.1 - Path & Telemetry Fixes. Treat it as a review item until the current version is checked.
• User impact: First-time setup may fail or require extra isolation and rollback planning.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: Source-linked evidence: https://github.com/Fission-AI/OpenSpec/releases/tag/v1.3.1

8. Configuration risk: Incomplete artifacts marked as "done" after workflow interruption

• Severity: medium
• Finding: Configuration risk is backed by a source signal: Incomplete artifacts marked as "done" after workflow interruption. Treat it as a review item until the current version is checked.
• User impact: Users may get misleading failures or incomplete behavior unless configuration is checked carefully.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: Source-linked evidence: https://github.com/Fission-AI/OpenSpec/issues/1084

9. Configuration risk: OpenCode sync missing

• Severity: medium
• Finding: Configuration risk is backed by a source signal: OpenCode sync missing. Treat it as a review item until the current version is checked.
• User impact: Users may get misleading failures or incomplete behavior unless configuration is checked carefully.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: Source-linked evidence: https://github.com/Fission-AI/OpenSpec/issues/1007

10. Configuration risk: v0.22.0 - Project Configuration

• Severity: medium
• Finding: Configuration risk is backed by a source signal: v0.22.0 - Project Configuration. Treat it as a review item until the current version is checked.
• User impact: Users may get misleading failures or incomplete behavior unless configuration is checked carefully.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: Source-linked evidence: https://github.com/Fission-AI/OpenSpec/releases/tag/v0.22.0

11. Configuration risk: v1.0.0 - The OPSX Release

• Severity: medium
• Finding: Configuration risk is backed by a source signal: v1.0.0 - The OPSX Release. Treat it as a review item until the current version is checked.
• User impact: Users may get misleading failures or incomplete behavior unless configuration is checked carefully.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: Source-linked evidence: https://github.com/Fission-AI/OpenSpec/releases/tag/v1.0.0

12. Capability assumption: README/documentation is current enough for a first validation pass.

• Severity: medium
• Finding: README/documentation is current enough for a first validation pass.
• User impact: The project should not be treated as fully validated until this signal is reviewed.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: capability.assumptions | github_repo:1032459340 | https://github.com/Fission-AI/OpenSpec | README/documentation is current enough for a first validation pass.

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.

• Codex generated assets reference unsupported AskUserQuestion/TodoWrite/T - github / github_issue
• Incomplete artifacts marked as "done" after workflow interruption - github / github_issue
• /opsx:apply suggests openspec-continue-change which is not installed on - github / github_issue
• Feedback: Deep verification test - PUA mode v3 active - github / github_issue
• Protect OpenSpec from AI slop PRs - github / github_issue
• open:sync messed up my spec.md files - github / github_issue
• Support schema extension or partial overrides to avoid full shadowing of - github / github_issue
• [[Feature Request/Suggestion] Extension to package for custom schemas, as](https://github.com/Fission-AI/OpenSpec/issues/1081) - github / github_issue
• First steps don't work - github / github_issue
• OpenCode sync missing - github / github_issue
• v1.3.1 - Path & Telemetry Fixes - github / github_release
• v1.1.0 - Cross-Platform Fixes, Nix Improvements - GitHub / issue