How to Understand the OpenSpec Project: Architecture, Workflow, and Implementation Guide

OpenSpec is an AI-native, spec-driven development framework that creates a lightweight agreement layer between developers and AI assistants, enabling iterative development through markdown-based specifications and a fluid workflow of propose-spec-design-task-implement.

Understanding the OpenSpec project from the Fission-AI/OpenSpec repository requires grasping its core philosophy of agreeing on behavior before implementation. This framework bridges the gap between human intent and AI-generated code by establishing a structured yet flexible specification layer in your repository. Whether you are managing a greenfield project or a brownfield codebase, OpenSpec provides the scaffolding to collaborate effectively with AI tools through the openspec CLI and editor slash commands.

Core Architecture and Components

The architecture of OpenSpec revolves around a simple folder structure that separates current system behavior from proposed changes. This separation allows the framework to manage complex development workflows while keeping the cognitive load minimal.

The Specs Directory (openspec/specs/)

The openspec/specs/ directory serves as the source of truth for your system. It contains markdown files that describe current behavior using requirements and scenarios. Unlike traditional documentation that becomes stale, these specs are living documents that evolve with your codebase. When archived, completed changes merge their delta specs into this directory, ensuring it always reflects the implemented reality.

The Changes Directory (openspec/changes/)

Every proposed modification lives in a dedicated subfolder under openspec/changes/. Each change folder contains all artifacts generated during the development lifecycle: proposal.md, specs/, design.md, and tasks.md. This isolation prevents work-in-progress from contaminating the main specs until verification is complete. Once finished, the change moves to openspec/changes/archive/ with a timestamp prefix.

Delta Specs and Artifact Flow

Delta specs represent OpenSpec's brownfield-friendly approach. Instead of rewriting entire specification documents, you only define what is added, modified, or removed. The artifact flow follows a logical sequence: proposal → specs → design → tasks → implement. However, as implemented in openspec/schemas/spec-driven/schema.yaml, these are enablers rather than gates—you can skip or reorder them based on your needs.

Schemas and Configuration

The workflow behavior is governed by schemas defined in YAML files. The default spec-driven schema located at openspec/schemas/spec-driven/schema.yaml defines which artifacts exist and their dependency graph. You can customize this in openspec/config.yaml to create domain-specific workflows while maintaining the same core CLI interface.

The OpenSpec Development Workflow

Understanding OpenSpec requires familiarity with its iterative lifecycle, which mirrors natural development conversations while maintaining structure.

Initialize and Explore

Begin by scaffolding the project structure:

openspec init

This creates openspec/, openspec/specs/, openspec/changes/, and openspec/config.yaml. Before committing to a change, you can explore ideas using the /opsx:explore slash command in AI-enabled editors like Claude or Cursor to clarify requirements without generating artifacts.

Propose and Iterate

Create a new change using either the CLI or slash commands:

openspec new change add-dark-mode

Or in your editor:

/opsx:propose add-dark-mode

This generates openspec/changes/add-dark-mode/ with a proposal.md outline. To fast-forward through all planning artifacts automatically:

openspec ff add-dark-mode

This populates the change folder with specs, design, and tasks in dependency order. Iterate using /opsx:continue or /opsx:ff to refine specifications before implementation.

Apply and Verify

Implementation occurs through the apply command:

/opsx:apply

The AI reads tasks.md, generates the necessary code files (such as src/contexts/ThemeContext.tsx), and checks off completed tasks. Before archiving, verify the implementation matches specifications:

openspec verify --change add-dark-mode

This command runs completeness, correctness, and coherence diagnostics against the delta specs. Finally, archive the completed work:

openspec archive add-dark-mode --yes

This merges delta specs into openspec/specs/ and moves the change folder to the archive.

Design Principles

OpenSpec adheres to four core principles that distinguish it from traditional waterfall or rigid agile frameworks:

• Fluid, not rigid: No forced phase gates exist; you can create artifacts in any order that fits the problem.
• Iterative, not waterfall: Continuous refinement mirrors real-world development where requirements evolve.
• Easy, not complex: Minimal ceremony—a single openspec init and a few markdown files get you started.
• Brownfield-first: Delta specs let you modify large existing codebases without writing full specifications from scratch.

Key Source Files

Understanding these files provides deep insight into OpenSpec's behavior:

• docs/overview.md: High-level mental model and workflow summary.
• docs/concepts.md: Deep dive into specs, changes, delta specs, and schemas.
• docs/commands.md: Reference for AI slash commands (/opsx:*).
• docs/cli.md: Full CLI reference for the openspec command.
• openspec/config.yaml: Project-level configuration including schema selection and context rules.
• openspec/schemas/spec-driven/schema.yaml: Built-in spec-driven workflow definition.
• package.json: NPM package metadata and entry point (bin/openspec.js).
• bin/openspec.js: CLI entry script that loads the compiled TypeScript CLI.

Summary

• OpenSpec is an AI-native framework that puts specifications between human intent and AI implementation.
• The openspec/specs/ directory contains current system truth, while openspec/changes/ houses work-in-progress modifications.
• Delta specs allow lightweight specification of only what changes, making the framework ideal for existing codebases.
• The workflow moves from proposal through specs, design, and tasks to implement, with no mandatory gates.
• The openspec CLI and /opsx:* slash commands provide dual interfaces for terminal and AI-chat workflows.

Frequently Asked Questions

What is the difference between specs and delta specs in OpenSpec?

Specs in openspec/specs/ describe the complete current behavior of your system, while delta specs located in openspec/changes/<name>/specs/ describe only what is added, modified, or removed in a specific change. This distinction allows OpenSpec to work effectively with brownfield projects where you do not need to document the entire existing system before making changes.

How does the OpenSpec artifact flow work?

The artifact flow follows the sequence proposal → specs → design → tasks → implement, as defined in openspec/schemas/spec-driven/schema.yaml. Each artifact feeds the next, but the system is flexible—there are no hard gates preventing you from creating a design before finalizing specs or jumping directly to implementation if the tasks are already clear.

Can I use OpenSpec with existing codebases or only new projects?

OpenSpec is explicitly brownfield-first and designed for existing codebases. The delta spec approach allows you to specify only changes to current behavior without writing full specifications for legacy code. This makes it ideal for retrofitting structure into established projects while maintaining forward momentum.

What is the relationship between the OpenSpec CLI and slash commands?

The openspec CLI provides terminal-based commands for project setup, validation, and lifecycle management, while /opsx:* slash commands (such as /opsx:propose and /opsx:apply) function inside AI-enabled editors like Claude and Cursor. They share the same underlying logic—slash commands in chat essentially mirror their CLI equivalents—but the slash commands allow direct AI integration within your development environment.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}