Technical Specifications of OpenSpec: Architecture and Workflow Guide

OpenSpec is a Node.js-based, spec-driven development framework that uses structured delta specs, artifact workflows, and AI tool integration to manage changes through a proposal-to-archive lifecycle.

The technical specifications of OpenSpec establish a lightweight, behavior-first development framework that mediates between developers and generative AI systems. According to the Fission-AI/OpenSpec repository, the architecture centers on immutable specifications stored in openspec/specs/ that drive automated code generation through a structured Node.js CLI runtime.

Core Architecture and Directory Structure

Repository Layout

The OpenSpec framework enforces a strict directory convention under an openspec/ folder at project root. The Specs directory (openspec/specs/) serves as the immutable source of truth containing requirements and scenarios. Parallel to this, the Changes directory (openspec/changes/) packages discrete units of work, each containing proposal.md, design.md, tasks.md, and delta specs. Completed changes migrate to openspec/changes/archive/ after merging.

Runtime Components

The runtime executes through bin/openspec.js, a Node.js CLI that dispatches slash-commands like /opsx:propose and /opsx:apply. Core logic resides in src/core/, with InitCommand (src/core/init.ts) handling repository validation, legacy cleanup, and AI tool detection. The Command Generation module (src/core/command-generation/index.ts) renders skill files and slash-commands using schema-dependent templates.

Configuration and Schema System

Global Configuration

The openspec/config.yaml file (or config.yml) stores three critical parameters: schema (default: spec-driven), profile (core or custom), and delivery (skills, commands, or both). Created automatically by InitCommand if absent, this file determines which workflow artifacts the system generates.

Workflow Schemas

Schemas are YAML documents defining artifact dependencies and generation rules. The default spec-driven schema, defined as DEFAULT_SCHEMA in src/core/config.ts, orchestrates the flow: proposal → specs → design → tasks. Each artifact declares dependencies—tasks requires both specs and design—ensuring logical sequencing without blocking parallel work.

The OpenSpec Development Workflow

Specs as Source of Truth

Specs represent the canonical behavior description stored in openspec/specs/. Unlike traditional documentation, these structured files function as executable contracts that AI tools reference during implementation.

Changes and Delta Specs

The Changes system encapsulates work in isolated folders under openspec/changes/<change-name>/. Delta Specs describe incremental updates using three operations: ADDED, MODIFIED, and REMOVED. This diff-based approach avoids monolithic spec rewrites, tracking only what differs from the source of truth.

Artifact Flow and Archiving

The Artifacts Flow follows a linear progression: proposal → specs → design → tasks → implement. Each stage builds upon predecessors without blocking subsequent steps. Upon completion, the Archive process (implemented in src/core/archive.ts) merges delta specs into the main specification and relocates the change folder to changes/archive/.

AI Tool Integration and Command Generation

Tool Detection and Skill Files

OpenSpec maintains a catalog of AI tools (Claude, Cursor, etc.) with corresponding skills directories containing SKILL.md files. The initialization process (getAvailableTools in src/core/init.ts) detects installed tools and invokes generateSkillContent to create context-specific instructions.

Slash Command Generation

The framework generates tool-specific slash-commands (e.g., /opsx:propose) via templates in src/core/command-generation/index.ts. These commands respect the profile and delivery settings, producing either skill files, command definitions, or both.

Key Implementation Files

Several TypeScript modules constitute the framework's core:

• src/index.ts: Public entry point re-exporting CLI and core modules
• src/core/init.ts: Contains InitCommand for repository bootstrapping and legacy migration
• src/core/config.ts: Defines DEFAULT_SCHEMA, AI_TOOLS constants, and configuration interfaces
• src/core/archive.ts: Implements archiveChange() function for merging deltas
• src/utils/file-system.ts: Atomic file operations and permission checking utilities

Practical Usage Examples

Initialize a new OpenSpec repository:

npx openspec init

This executes InitCommand, creating the directory structure, config.yaml, and tool-specific scaffold files.

Propose a new change using slash-commands:

/opsx:propose "add dark mode"

The command creates openspec/changes/add-dark-mode/ with proposal.md and generates delta specs under the specs/ subdirectory.

Apply and archive changes programmatically:

import { archiveChange } from './src/core/archive.js';

await archiveChange('add-dark-mode');

The archiveChange function merges delta sections into main spec files and moves the change to archive.

Configure a custom research-first schema:

# openspec/schemas/research-first/schema.yaml

name: research-first
artifacts:
  - id: research   → research.md   (no deps)
  - id: proposal   → proposal.md   (requires research)
  - id: tasks      → tasks.md      (requires proposal)

Activate via:

openspec config profile set custom

Summary

• OpenSpec implements a spec-driven architecture separating behavioral definitions from implementation code
• The framework uses Node.js CLI (bin/openspec.js) with core logic in src/core/ and utilities in src/utils/
• Delta specs track incremental changes through ADDED, MODIFIED, and REMOVED operations
• Configuration centers on openspec/config.yaml with schema, profile, and delivery parameters
• The artifact flow (proposal → specs → design → tasks → implement) ensures structured AI-assisted development
• Archiving (src/core/archive.ts) merges completed changes back to the source of truth

Frequently Asked Questions

What file structure does OpenSpec require?

OpenSpec requires an openspec/ directory at project root containing specs/ (source of truth), changes/ (active work), and config.yaml. The src/core/init.ts module automatically generates this structure when you run npx openspec init.

How does OpenSpec handle changes without rewriting entire specifications?

OpenSpec uses delta specs stored in openspec/changes/<change-name>/specs/ that describe only the differences from the main specifications using ADDED, MODIFIED, and REMOVED markers. The archiveChange() function in src/core/archive.ts merges these deltas into the main specs upon completion.

What programming language is the OpenSpec runtime built with?

The runtime is built with Node.js and TypeScript. The CLI entry point is bin/openspec.js, with core modules located in src/core/ including init.ts, config.ts, and archive.ts.

Can OpenSpec workflows be customized?

Yes. Users can define custom schemas in openspec/schemas/<name>/schema.yaml files that specify artifact dependencies and generation rules. Set profile: custom in config.yaml to activate alternative workflows like "research-first" that skip design phases.

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