TL;DR

This OpenSpec tutorial shows the operational lifecycle: initialize a repository, use /opsx:propose to create reviewable artifacts, inspect them, use /opsx:apply to execute tasks, verify the resulting behavior, and use /opsx:archive to retain the completed change record. Structure improves traceability; correctness still comes from review and executable evidence.

📋 Table of Contents

✨ Key Takeaways

  • Structured Workflow: OpenSpec turns AI coding from ad-hoc chats into a spec-driven pipeline with a reviewable paper trail.
  • Three-Command Core: The everyday lifecycle is managed via /opsx:propose, /opsx:apply, and /opsx:archive.
  • Bounded execution: Breaking work into tasks and restricting context can reduce scope drift, but the effect must be judged from the diff and tests.
  • Tool-Agnostic: Works across Cursor, Windsurf, Trae, Claude Code, and other assistants — it is not tied to one IDE or model.

Operational Prerequisite: One Reviewed Change

OpenSpec assumes that a change has explicit intent, scenarios, constraints, and tasks that remain synchronized with the implementation. Before following the commands below, use the Spec Coding complete guide for the methodology and framework boundaries. In this tutorial, “source of truth” means the reviewed artifact set your team has chosen to govern this change; files do not enforce themselves.

How OpenSpec Works

OpenSpec is a popular open-source framework for SDD created by Fission-AI. It provides a lightweight, directory-based structure that AI agents can easily parse and execute.

The core philosophy of OpenSpec is fluid not rigid. It doesn't force you into heavy enterprise UML diagrams; instead, it uses simple markdown files with BDD (Behavior-Driven Development) syntax like WHEN/THEN.

graph LR A["1. /opsx:propose"] -->|Generates Spec| B["specs/ & tasks.md"] B -->|Review| C["2. /opsx:apply"] C -->|Executes Code| D["Code Changes"] D -->|Tests Pass| E["3. /opsx:archive"] style A fill:#e1f5fe,stroke:#01579b style C fill:#fff3e0,stroke:#e65100 style E fill:#e8f5e9,stroke:#2e7d32

The Three Pillars of OpenSpec

Command SDD Phase Purpose
/opsx:propose Definition Creates the proposal.md, specs/, and tasks.md artifacts.
/opsx:apply Execution Tells the AI to read tasks.md and implement the code step-by-step.
/opsx:archive Persistence Moves the completed spec into the archive for historical memory.

OpenSpec Tutorial: Step-by-Step Guide

Let's dive into the practical part of this OpenSpec tutorial. We will build a simple "JSON Validator" feature using SDD principles.

Step 1: Installation and Initialization

First, install OpenSpec globally and initialize it in your project.

bash 
# Install OpenSpec globally
npm install -g @fission-ai/openspec@latest

# Navigate to your project and initialize
cd my-ai-project
openspec init

This creates an openspec/ directory in your root folder, establishing the scaffolding needed for the AI to understand your SDD workflow.

Step 2: Propose a Change

In your AI IDE (like Cursor or Trae), open the chat and use the propose command.

Your Input:

text 
/opsx:propose add-json-validator-feature

The AI will generate several files under openspec/changes/add-json-validator-feature/:

  • proposal.md: The high-level goal.
  • specs/spec.md: The detailed requirements using WHEN/THEN.
  • tasks.md: The step-by-step implementation checklist.

Review the specs/spec.md: Make sure the AI captured your intent. A good spec looks like this:

markdown 
### Requirement: JSON Validation Logic

#### Scenario: Valid JSON Input
- **WHEN** the user inputs `{"key": "value"}` and clicks Validate
- **THEN** the system shows a success message
- **AND** formats the JSON with 2-space indentation

#### Scenario: Invalid JSON Input
- **WHEN** the user inputs `{"key": "value"` (missing brace)
- **THEN** the system catches the SyntaxError
- **AND** displays exactly which line the error occurred on

Step 3: Apply the Tasks

Once you are happy with the spec and tasks, instruct the AI to execute.

Your Input:

text 
/opsx:apply add-json-validator-feature

The AI will now read tasks.md, implement the code, and check off the tasks one by one. By forcing the AI to follow the task list, you prevent it from randomly modifying unrelated files—a common issue in Vibe Coding.

Step 4: Archive the Artifacts

After the code is written and tests pass, you must archive the change. This is critical for long-term project memory.

Your Input:

text 
/opsx:archive add-json-validator-feature

The AI will move the folder to openspec/changes/archive/[date]-add-json-validator-feature/. Future AI sessions can read this archive to understand why certain architectural decisions were made.

Advanced OpenSpec Techniques

1. Combining OpenSpec with CLAUDE.md

OpenSpec handles the lifecycle of a specific feature, while CLAUDE.md handles the global rules of the repository.

For a smoother SDD experience, record your global conventions in CLAUDE.md:

markdown 
# Project Constitution
- We use React Functional Components only.
- We never use inline CSS; use CSS Modules.
- All new features should be developed using OpenSpec `/opsx:propose`.

Treat CLAUDE.md as a convention aid, not an enforcement mechanism: it shapes the model's output and reduces obvious drift, but the model can still ignore a line. It is not a build gate and not a security boundary — keep real guardrails (tests, linters, CI, access controls) outside the prompt.

2. Handling Task Deviations

If the AI encounters an unexpected issue during /opsx:apply (e.g., a library is deprecated), do not just tell it to hack a fix. Stop the apply process, manually update specs/spec.md and tasks.md to reflect the new reality, and then resume /opsx:apply. This ensures your SSOT remains accurate.

Best Practices for SDD Development

  1. Keep Specs Fluid, Not Rigid — Focus on the what and why (boundary conditions, error handling), not the exact code syntax.
  2. Atomic Proposals — Do not propose "Build an entire e-commerce backend" in one go. Propose "add-user-auth", then "add-product-catalog".
  3. Close completed changes deliberately — After verification, archive completed artifacts according to the repository workflow. Do not archive an unverified or partially applied change merely to clear the workspace.
  4. Use High-Reasoning Models — The propose phase benefits most from a strong reasoning model. Model names change fast, so pick the current top-tier reasoning model your assistant offers rather than pinning a specific version.

⚠️ Common Mistakes:

  • Changing requirements mid-flight → If you change your mind, update the spec.md first. Don't just chat with the AI to change the code.
  • Skipping the review phase → Always read the tasks.md generated by /opsx:propose before running /opsx:apply.

FAQ

Q1: How do I use OpenSpec in an existing project?

You can introduce OpenSpec gradually. Run openspec init in your existing repo. For your next small feature or bug fix, use /opsx:propose. You don't need to write specs for legacy code; just use SDD for all new changes moving forward.

Q2: Does SDD development slow down coding?

It adds up-front authoring and review. Whether that investment reduces later debugging or rework depends on change complexity, team discipline, artifact quality, and enforcement. Measure lead time, review time, escaped defects, and rework against a comparable baseline rather than assuming a universal productivity gain.

Q3: OpenSpec vs. Cursor Rules: What is the difference?

Cursor Rules (.cursorrules) dictate how the AI writes code (e.g., syntax, style). OpenSpec dictates what the AI builds and manages the workflow. They are highly complementary; you should use both together.

Q4: Can I use OpenSpec without an AI IDE?

Yes, subject to the current OpenSpec CLI and host integration documented by the project. The important requirement is that the selected interface creates, reads, and updates the same reviewed artifacts; an IDE chat surface is a convenience, not a correctness property.

Summary

OpenSpec's /opsx:propose → review → /opsx:apply → verification → /opsx:archive lifecycle creates a reviewable record around an AI-assisted change. Its value is traceability and explicit checkpoints, not guaranteed code quality. Keep artifacts synchronized, inspect the diff, run project gates, and preserve deviations before archiving.