Avoid AI Coding Rework with OpenSpec: 3‑Step Workflow for New and Legacy Projects

OpenSpec Overview

OpenSpec is a spec‑driven development framework (GitHub 35.3K ★, 50+ contributors) that reduces AI‑coding misalignment by creating a structured requirement specification before any code is written.

The repository is organized into two top‑level directories: specs/ – source of truth for current behavior, grouped by domain (e.g., specs/auth/spec.md). changes/ – one folder per change proposal containing four artifacts:

Proposal ( proposal.md) – why the change is needed.

Specs ( specs/) – the delta specification.

Design ( design.md) – technical solution.

Tasks ( tasks.md) – implementation checklist.

The four artifacts form a directed‑acyclic graph (DAG) where proposal is the root, specs and design depend on it, and tasks depends on both. The DAG is an enabler rather than a strict gate, so the order can be adjusted.

OpenSpec introduces Delta Spec , which records only what changed. Four operation tags are used:

ADDED – new requirements.

MODIFIED – replaced requirements (must include the full updated block).

REMOVED – deleted requirements.

RENAMED – renamed requirements.

Installation and Initialization

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

# Enter project directory
cd your-project

# Interactive initialization (select AI tool)
openspec init

# Refresh command files after an upgrade
openspec update

After openspec init an openspec/ folder is created:

openspec/
├── specs/      # specification source
└── changes/    # change proposals
    └── archive/  # archived changes

OpenSpec supports more than 20 AI coding assistants (Claude Code, Cursor, GitHub Copilot, Gemini CLI, etc.). Multiple tools can be selected, e.g.:

openspec init --tools claude,cursor

Core Three‑Step Workflow

The entire process collapses to three commands that form a closed loop:

/opsx:propose  →  /opsx:apply  →  /opsx:archive

Optional commands: /opsx:explore – analyze the current codebase before proposing. /opsx:verify – validate completeness, correctness, and coherence after apply.

Scenario 1 – New Project (Greenfield)

1.1 Initialize Project

mkdir todo-app && cd todo-app
git init
openspec init

During initialization choose an AI tool (e.g., Claude Code) and edit openspec/config.yaml to describe the tech stack:

schema: spec-driven
context: |
  Tech stack: React 18, TypeScript, Vite
  Backend: Node.js + Express
  Database: SQLite (development)
  Testing: Vitest
  Style: Tailwind CSS

1.2 Create a Change

Propose a new feature: /opsx:propose add-todo-crud The AI generates four artifacts. An excerpt of specs/todo/spec.md shows a Gherkin‑style requirement:

# Todo Specification
## Purpose
Manage todo items with CRUD operations.

## Requirements
### Requirement: Create Todo
The system SHALL allow users to create new todo items with a title and optional description.
#### Scenario: Valid todo creation
- **GIVEN** the user is on the todo list page
- **WHEN** the user submits a new todo with a title
- **THEN** the todo is added to the list
- **AND** the input field is cleared

Pitfall: Scenario headings must be level‑4 ( ####). Using three # or a bullet list causes the Delta Spec to be silently ignored.

1.3 Apply and Archive

Execute the tasks in tasks.md sequentially: /opsx:apply Completed items are marked - [x]. The process can be paused and resumed by re‑running the same command.

After all tasks finish, archive merges the Delta Spec into the main specs/ folder and moves the change folder to changes/archive/…: /opsx:archive If the Expanded Profile is enabled, run a verification step:

/opsx:verify

Scenario 2 – Adding a Feature to an Existing (Brownfield) Project

2.1 Explore First

/opsx:explore

The AI asks “What do you want to explore?” and, after describing the goal (e.g., “add dark mode”), reports the current styling approach (CSS Modules + Tailwind) and existing hooks.

2.2 Propose the Feature

/opsx:propose add-dark-mode

The generated Delta Spec contains both ADDED and MODIFIED tags because the feature introduces new UI elements and extends the existing theme management:

## ADDED Requirements
### Requirement: Dark Mode Theme
The system SHALL support a dark color scheme globally.
#### Scenario: Toggle dark mode
- **GIVEN** the user is in light mode
- **WHEN** the user clicks the theme toggle
- **THEN** all UI components switch to dark mode
- **AND** the preference is saved to localStorage

## MODIFIED Requirements
### Requirement: Theme Management
The system SHALL manage theme state through a ThemeContext with light, dark, and system preferences.
(Previously: only font size management)

2.3 Apply and Archive

Run the same /opsx:apply and /opsx:archive commands. The Delta Spec merges added requirements and replaces modified ones in specs/.

Scenario 3 – Fixing a Bug in a Legacy Project

3.1 Locate the Problem

/opsx:explore

Describing the symptom “login sometimes redirects to an error page” leads the AI to discover a race condition where the auth token is written after the redirect.

3.2 Propose the Fix

/opsx:propose fix-login-redirect

The Delta Spec focuses on MODIFIED because the behavior changes:

## MODIFIED Requirements
### Requirement: Post‑Login Redirect
The system SHALL redirect to the intended page only after the auth token is confirmed written to storage.
(Previously: redirect immediately after API response)
#### Scenario: Successful login redirect
- **GIVEN** a user submits valid credentials
- **WHEN** the auth API returns success
- **THEN** the system writes the token to localStorage
- **AND** waits for storage write confirmation
- **AND** redirects to the originally intended page

#### Scenario: Storage write failure
- **GIVEN** a user submits valid credentials
- **WHEN** the auth API returns success
- **AND** localStorage write fails
- **THEN** an error message is displayed
- **AND** the user remains on the login page

The “Previously” comment makes the change explicit for reviewers.

3.3 Parallel Changes

OpenSpec allows multiple changes to run in parallel. While fixing the bug, a new change for dark mode can be created: /opsx:new fix-login-redirect After completing the bug fix, resume the dark‑mode work: /opsx:apply add-dark-mode The AI reports “Resuming add‑dark‑mode… Picking up at task 2.3”, showing independent progress.

Practical Tips and Common Pitfalls

Scenario headings must use four # (level‑4). Incorrect levels are ignored silently.

MODIFIED entries must contain the entire updated requirement block, from ### Requirement: through all scenarios.

Spec vs. Design vs. Tasks :

Spec – observable behavior (inputs, outputs, error conditions).

Design – how the behavior will be achieved (architecture, patterns).

Tasks – concrete implementation steps, typically ≤ 2 hours each.

Change granularity – one logical unit equals one change folder. Use clear names such as add-dark-mode, fix-login-redirect. Avoid vague names like feature‑1 or update.

When to update vs. create a new change :

Minor tweak, discovery that code differs from expectation, or scope shrink → update current change.

Fundamental intent shift, scope expansion > 50 %, or independent work that can be completed alone → archive current change and create a new one.

config.yaml context field is injected into all generation commands. Example:

context: |
  Tech stack: TypeScript, React 18, Node.js, PostgreSQL
  API style: RESTful, JSON responses
  Testing: Vitest for unit tests, Playwright for e2e
  Important: All public APIs must maintain backwards compatibility

Comparison of the Three Scenarios

Starting point : empty directory (new) vs. existing code (legacy).

Recommended command : propose for new projects; explore → propose for legacy additions and bug fixes.

Delta Spec type : mostly ADDED (new) vs. ADDED + MODIFIED (feature) vs. mainly MODIFIED (bug).

Spec accumulation : builds from scratch, gradual addition, or gradual correction.

Change granularity : medium for new and feature work, small for bug fixes.

Parallel needs : few for new projects, possible for feature work, frequent for bug fixes.

Key Takeaways

For a brand‑new project, run init + propose and let the spec grow incrementally; a complete design is not required up front.

When extending an existing codebase, start with explore to surface the current architecture, then describe only the added or modified parts with Delta Spec.

When fixing bugs, explicitly document the before‑and‑after behavior in a MODIFIED requirement; reviewers can understand the fix without reading the code.

Running the propose → apply → archive loop on a small feature gives a practical feel for spec‑driven development. Refine the spec format over time rather than striving for perfection on day one.