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

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 (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 (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, 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 and 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 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, 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, delta specs, design.md, and 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:

# 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 (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:

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:

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 utilities manage the discovery of these files, while 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, a core engine in src/utils/item-discovery.ts and src/utils/change-metadata.ts, and schema definitions in 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) describing the change intent, delta specs describing only what is modified, a design (design.md) detailing implementation approach, and tasks (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) manages the local artifact structure, while the AI interaction happens through standardized commands like /opsx:propose and /opsx:apply.

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