# What is Fission-AI OpenSpec? A Spec-First AI Coding Framework

> Discover Fission-AI OpenSpec, the spec-first AI coding framework. This agreement layer uses Markdown for planning, ensuring better code generation from AI assistants. Learn more.

- Repository: [Fission/OpenSpec](https://github.com/Fission-AI/OpenSpec)
- Tags: getting-started
- Published: 2026-06-28

---

**Fission-AI OpenSpec is a lightweight "agreement layer" that sits between developers and AI coding assistants, enabling spec-first planning through Markdown artifacts before any code is generated.**

OpenSpec is an open-source project maintained by Fission-AI that introduces a structured yet flexible workflow for AI-assisted software development. Rather than allowing AI models to generate code from vague prompts, the framework establishes a **spec-first** methodology where requirements, designs, and tasks are captured in version-controlled Markdown files before implementation begins. This approach ensures alignment between developers and AI assistants while maintaining the full history of decisions alongside the codebase.

## Core Philosophy and Design Principles

The Fission-AI OpenSpec project rejects rigid waterfall methodologies in favor of an iterative, lightweight process. According to the repository's documentation in [`README.md`](https://github.com/Fission-AI/OpenSpec/blob/main/README.md) (lines 26-34), the framework adheres to three core principles: **fluid not rigid**, **iterative not waterfall**, and **easy not complex**.

The mental model, as detailed in [`docs/overview.md`](https://github.com/Fission-AI/OpenSpec/blob/main/docs/overview.md) (lines 11-27), establishes that the **spec** serves as the single source of truth stored under `openspec/specs/`. Each **change** represents a unit of work contained in its own folder under `openspec/changes/`, housing a proposal, delta specs, design documents, and task lists. **Delta specs** describe only what is added, modified, or removed, while the **archive** process folds completed changes back into the permanent truth.

## Architectural Overview

The OpenSpec codebase organizes functionality into distinct layers, each with specific responsibilities:

- **CLI Layer**: Implemented in [`bin/openspec.js`](https://github.com/Fission-AI/OpenSpec/blob/main/bin/openspec.js), this layer provides commands like `openspec init`, `openspec config`, and `openspec update` to bootstrap and manage projects.

- **Core Engine**: Located in [`src/utils/item-discovery.ts`](https://github.com/Fission-AI/OpenSpec/blob/main/src/utils/item-discovery.ts) and [`src/utils/change-metadata.ts`](https://github.com/Fission-AI/OpenSpec/blob/main/src/utils/change-metadata.ts), the engine handles parsing, validation, and merging of Markdown artifacts while tracking work-sets, tasks, and dependencies.

- **Schema Definition**: The [`schemas/spec-driven/schema.yaml`](https://github.com/Fission-AI/OpenSpec/blob/main/schemas/spec-driven/schema.yaml) file formally defines the shape of spec-driven documents, including requirements, scenarios, and tasks.

- **Templates**: Markdown templates for proposals, specifications, and designs reside in [`schemas/spec-driven/templates/spec.md`](https://github.com/Fission-AI/OpenSpec/blob/main/schemas/spec-driven/templates/spec.md), providing standardized formats for documentation.

## The OpenSpec Workflow

The framework implements a five-stage workflow that creates a reproducible, reviewable change package living alongside your code:

1. **Initialize**: Run `openspec init` to create the `openspec/` directory structure with `specs/` and `changes/` subdirectories.

2. **Explore** (optional): Use the `/opsx:explore` slash command to have the AI assistant surface implementation options before creating any artifacts.

3. **Propose**: Execute `/opsx:propose <name>` to generate a change folder containing [`proposal.md`](https://github.com/Fission-AI/OpenSpec/blob/main/proposal.md), delta 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).

4. **Apply**: Trigger `/opsx:apply` to have the AI implement the tasks, updating the codebase according to the specified design.

5. **Archive**: Run `/opsx:archive` to merge delta specs into `openspec/specs/` and move the change folder to `openspec/changes/archive/`.

This loop is deliberately **enabler-not-gate**: you can edit any artifact at any time without forced phase ordering.

## Key Concepts in OpenSpec

Understanding the framework requires familiarity with several foundational concepts:

- **Specs are the truth**: Permanent specifications live under `openspec/specs/` (e.g., `openspec/specs/auth/`, `openspec/specs/payments/`), serving as the authoritative reference for system behavior.

- **Changes are units of work**: Each change occupies its own folder under `openspec/changes/` with standardized artifacts representing the complete proposal.

- **Delta specs**: These documents describe only modifications to existing specifications rather than duplicating complete requirements, minimizing maintenance overhead.

- **Artifact pipeline**: The workflow follows a logical progression from `proposal → specs → design → tasks → implement`, creating a paper trail of decisions.

- **Archiving**: The process of merging deltas back into the main specs and moving completed changes to the archive folder, preserving historical context.

## Getting Started with OpenSpec

Install the CLI globally and initialize a new project:

```bash

# Install the CLI globally

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

# Initialise a project

cd my-project
openspec init

```

The initialization command creates the standard directory structure and configures the project for spec-driven development. As documented in [`README.md`](https://github.com/Fission-AI/OpenSpec/blob/main/README.md) (lines 90-97), the tool supports multiple package managers including npm, pnpm, yarn, bun, and Nix.

## Working with the AI Assistant

OpenSpec integrates with AI coding assistants through slash commands. Here is a typical interaction flow:

```text
You: /opsx:explore
AI:  What would you like to explore?

You: I want a dark‑mode toggle.

AI:  Here are three possible implementations…

You: /opsx:propose add-dark-mode
AI:  Created openspec/changes/add-dark-mode/
      ✓ proposal.md
      ✓ specs/
      ✓ design.md
      ✓ tasks.md

You: /opsx:apply
AI:  Implementing tasks...
      ✓ 1. Add theme context provider
      ✓ 2. Create toggle component
      ✓ 3. Wire up localStorage

You: /opsx:archive
AI:  Specs updated, change archived.

```

You can inspect generated changes programmatically using Node.js:

```typescript
import { readFileSync } from 'fs';
import { resolve } from 'path';

// Load a proposal file
const proposalPath = resolve('openspec/changes/add-dark-mode/proposal.md');
const proposal = readFileSync(proposalPath, 'utf‑8');

console.log('Proposal title:', proposal.split('\n')[0]);

```

The [`src/utils/item-discovery.ts`](https://github.com/Fission-AI/OpenSpec/blob/main/src/utils/item-discovery.ts) utilities manage the discovery of these files, while [`src/utils/change-metadata.ts`](https://github.com/Fission-AI/OpenSpec/blob/main/src/utils/change-metadata.ts) handles metadata including IDs, timestamps, and status tracking.

## Summary

- **Fission-AI OpenSpec** provides a **spec-first agreement layer** between developers and AI assistants, ensuring alignment before code generation.

- The **architecture** consists of a CLI entry point in [`bin/openspec.js`](https://github.com/Fission-AI/OpenSpec/blob/main/bin/openspec.js), a core engine in [`src/utils/item-discovery.ts`](https://github.com/Fission-AI/OpenSpec/blob/main/src/utils/item-discovery.ts) and [`src/utils/change-metadata.ts`](https://github.com/Fission-AI/OpenSpec/blob/main/src/utils/change-metadata.ts), and schema definitions in [`schemas/spec-driven/schema.yaml`](https://github.com/Fission-AI/OpenSpec/blob/main/schemas/spec-driven/schema.yaml).

- The **workflow** follows five stages: Initialize, Explore, Propose, Apply, and Archive, creating reproducible change packages.

- **Key files** include specs (permanent truth in `openspec/specs/`), changes (temporary work units in `openspec/changes/`), and delta specs (modifications only).

- The framework supports **iterative editing** without rigid ceremony, works with any toolchain, and maintains full decision history alongside the codebase.

## Frequently Asked Questions

### What problem does Fission-AI OpenSpec solve?

OpenSpec addresses the alignment gap between developers and AI coding assistants. Without a structured approach, AI models generate code from ambiguous prompts, leading to implementations that diverge from actual requirements. By forcing a **spec-first** approach where Markdown artifacts capture intent before code generation, OpenSpec ensures that both human developers and AI assistants agree on the plan before implementation begins.

### How does OpenSpec differ from traditional specification tools?

Unlike heavy waterfall methodologies or rigid specification systems, OpenSpec is designed to be **fluid and iterative**. The framework stores specs as Markdown files in the repository alongside code, supports incremental updates through delta specs, and allows editing at any stage. The `/opsx:explore` and `/opsx:propose` commands enable rapid iteration without the ceremony of traditional software specification processes.

### What are the main components of an OpenSpec change?

An OpenSpec change is a folder under `openspec/changes/` containing four key artifacts: a **proposal** ([`proposal.md`](https://github.com/Fission-AI/OpenSpec/blob/main/proposal.md)) describing the change intent, **delta specs** describing only what is modified, a **design** ([`design.md`](https://github.com/Fission-AI/OpenSpec/blob/main/design.md)) detailing implementation approach, and **tasks** ([`tasks.md`](https://github.com/Fission-AI/OpenSpec/blob/main/tasks.md)) listing specific implementation steps. Once completed, the `/opsx:archive` command merges these into the permanent specs and moves the change to `openspec/changes/archive/`.

### Can OpenSpec work with any AI model or coding assistant?

Yes, OpenSpec is **model-agnostic** and works with any AI coding assistant that supports slash commands or custom instructions. The repository documentation recommends using high-reasoning models for best results, but the framework itself does not depend on specific AI providers. The CLI ([`bin/openspec.js`](https://github.com/Fission-AI/OpenSpec/blob/main/bin/openspec.js)) manages the local artifact structure, while the AI interaction happens through standardized commands like `/opsx:propose` and `/opsx:apply`.