# Technical Specifications of OpenSpec: Architecture and Workflow Guide

> Explore OpenSpec technical specifications. Discover its Node.js architecture, delta specs, artifact workflows, and AI integration for efficient change management from proposal to archive.

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

---

**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`](https://github.com/Fission-AI/OpenSpec/blob/main/proposal.md), [`design.md`](https://github.com/Fission-AI/OpenSpec/blob/main/design.md), [`tasks.md`](https://github.com/Fission-AI/OpenSpec/blob/main/tasks.md), and delta specs. Completed changes migrate to `openspec/changes/archive/` after merging.

### Runtime Components

The runtime executes through [`bin/openspec.js`](https://github.com/Fission-AI/OpenSpec/blob/main/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`](https://github.com/Fission-AI/OpenSpec/blob/main/src/core/init.ts)) handling repository validation, legacy cleanup, and AI tool detection. The **Command Generation** module ([`src/core/command-generation/index.ts`](https://github.com/Fission-AI/OpenSpec/blob/main/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`](https://github.com/Fission-AI/OpenSpec/blob/main/openspec/config.yaml) file (or [`config.yml`](https://github.com/Fission-AI/OpenSpec/blob/main/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`](https://github.com/Fission-AI/OpenSpec/blob/main/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`](https://github.com/Fission-AI/OpenSpec/blob/main/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`](https://github.com/Fission-AI/OpenSpec/blob/main/SKILL.md) files. The initialization process (`getAvailableTools` in [`src/core/init.ts`](https://github.com/Fission-AI/OpenSpec/blob/main/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`](https://github.com/Fission-AI/OpenSpec/blob/main/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`](https://github.com/Fission-AI/OpenSpec/blob/main/src/index.ts)**: Public entry point re-exporting CLI and core modules
- **[`src/core/init.ts`](https://github.com/Fission-AI/OpenSpec/blob/main/src/core/init.ts)**: Contains `InitCommand` for repository bootstrapping and legacy migration
- **[`src/core/config.ts`](https://github.com/Fission-AI/OpenSpec/blob/main/src/core/config.ts)**: Defines `DEFAULT_SCHEMA`, `AI_TOOLS` constants, and configuration interfaces
- **[`src/core/archive.ts`](https://github.com/Fission-AI/OpenSpec/blob/main/src/core/archive.ts)**: Implements `archiveChange()` function for merging deltas
- **[`src/utils/file-system.ts`](https://github.com/Fission-AI/OpenSpec/blob/main/src/utils/file-system.ts)**: Atomic file operations and permission checking utilities

## Practical Usage Examples

Initialize a new OpenSpec repository:

```bash
npx openspec init

```

This executes `InitCommand`, creating the directory structure, [`config.yaml`](https://github.com/Fission-AI/OpenSpec/blob/main/config.yaml), and tool-specific scaffold files.

Propose a new change using slash-commands:

```bash
/opsx:propose "add dark mode"

```

The command creates `openspec/changes/add-dark-mode/` with [`proposal.md`](https://github.com/Fission-AI/OpenSpec/blob/main/proposal.md) and generates delta specs under the `specs/` subdirectory.

Apply and archive changes programmatically:

```typescript
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:

```yaml

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

```bash
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`](https://github.com/Fission-AI/OpenSpec/blob/main/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`](https://github.com/Fission-AI/OpenSpec/blob/main/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`](https://github.com/Fission-AI/OpenSpec/blob/main/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`](https://github.com/Fission-AI/OpenSpec/blob/main/config.yaml). The [`src/core/init.ts`](https://github.com/Fission-AI/OpenSpec/blob/main/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`](https://github.com/Fission-AI/OpenSpec/blob/main/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`](https://github.com/Fission-AI/OpenSpec/blob/main/bin/openspec.js), with core modules located in `src/core/` including [`init.ts`](https://github.com/Fission-AI/OpenSpec/blob/main/init.ts), [`config.ts`](https://github.com/Fission-AI/OpenSpec/blob/main/config.ts), and [`archive.ts`](https://github.com/Fission-AI/OpenSpec/blob/main/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`](https://github.com/Fission-AI/OpenSpec/blob/main/config.yaml) to activate alternative workflows like "research-first" that skip design phases.