# How to Understand the OpenSpec Project: Architecture, Workflow, and Implementation Guide > Understand the OpenSpec project with this guide covering its AI-native architecture, workflow, and implementation. Learn how OpenSpec streamlines developer and AI assistant collaboration. - Repository: [Fission/OpenSpec](https://github.com/Fission-AI/OpenSpec) - Tags: architecture - Published: 2026-06-28 --- **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`](https://github.com/Fission-AI/OpenSpec/blob/main/proposal.md), `specs/`, [`design.md`](https://github.com/Fission-AI/OpenSpec/blob/main/design.md), and [`tasks.md`](https://github.com/Fission-AI/OpenSpec/blob/main/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`](https://github.com/Fission-AI/OpenSpec/blob/main/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`](https://github.com/Fission-AI/OpenSpec/blob/main/openspec/schemas/spec-driven/schema.yaml) defines which artifacts exist and their dependency graph. You can customize this in [`openspec/config.yaml`](https://github.com/Fission-AI/OpenSpec/blob/main/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: ```bash openspec init ``` This creates `openspec/`, `openspec/specs/`, `openspec/changes/`, and [`openspec/config.yaml`](https://github.com/Fission-AI/OpenSpec/blob/main/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: ```bash openspec new change add-dark-mode ``` Or in your editor: ```text /opsx:propose add-dark-mode ``` This generates `openspec/changes/add-dark-mode/` with a [`proposal.md`](https://github.com/Fission-AI/OpenSpec/blob/main/proposal.md) outline. To fast-forward through all planning artifacts automatically: ```bash 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: ```text /opsx:apply ``` The AI reads [`tasks.md`](https://github.com/Fission-AI/OpenSpec/blob/main/tasks.md), generates the necessary code files (such as [`src/contexts/ThemeContext.tsx`](https://github.com/Fission-AI/OpenSpec/blob/main/src/contexts/ThemeContext.tsx)), and checks off completed tasks. Before archiving, verify the implementation matches specifications: ```bash openspec verify --change add-dark-mode ``` This command runs completeness, correctness, and coherence diagnostics against the delta specs. Finally, archive the completed work: ```bash 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`](https://github.com/Fission-AI/OpenSpec/blob/main/docs/overview.md)**: High-level mental model and workflow summary. - **[`docs/concepts.md`](https://github.com/Fission-AI/OpenSpec/blob/main/docs/concepts.md)**: Deep dive into specs, changes, delta specs, and schemas. - **[`docs/commands.md`](https://github.com/Fission-AI/OpenSpec/blob/main/docs/commands.md)**: Reference for AI slash commands (`/opsx:*`). - **[`docs/cli.md`](https://github.com/Fission-AI/OpenSpec/blob/main/docs/cli.md)**: Full CLI reference for the `openspec` command. - **[`openspec/config.yaml`](https://github.com/Fission-AI/OpenSpec/blob/main/openspec/config.yaml)**: Project-level configuration including schema selection and context rules. - **[`openspec/schemas/spec-driven/schema.yaml`](https://github.com/Fission-AI/OpenSpec/blob/main/openspec/schemas/spec-driven/schema.yaml)**: Built-in spec-driven workflow definition. - **[`package.json`](https://github.com/Fission-AI/OpenSpec/blob/main/package.json)**: NPM package metadata and entry point ([`bin/openspec.js`](https://github.com/Fission-AI/OpenSpec/blob/main/bin/openspec.js)). - **[`bin/openspec.js`](https://github.com/Fission-AI/OpenSpec/blob/main/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//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`](https://github.com/Fission-AI/OpenSpec/blob/main/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.