Quick Start Guide

This guide walks you through the lifecycle of an OpenSpec change: Proposal → Implementation → Archive.

1. Initialize OpenSpec

If you haven't already, set up your project:

openspec init

Select your preferred AI assistant (e.g., Claude Code, Cursor) to generate helper commands.

2. Create a Change Proposal

OpenSpec separates the current state of your software from proposed changes. Ask your AI assistant to create a proposal.

Prompt to AI:

"Create an OpenSpec change proposal to add a dark mode toggle to the settings page."

The AI will scaffold a directory in openspec/changes/add-dark-mode/ containing:

  • proposal.md: The "Why" and "What".
  • tasks.md: An implementation checklist.
  • specs/: Delta files describing new or modified requirements.

3. Review and Validate

Check the proposed change structure:

# List active changes
openspec list

# View the details of the specific change
openspec show add-dark-mode

# Validate that the specs are correctly formatted
openspec validate add-dark-mode --strict

4. Implement

Your AI assistant (or you) should now implement the code based on the tasks.md checklist.

  • Read proposal.md for context.
  • Execute items in tasks.md.
  • Mark tasks as complete (- [x]) as you go.

5. Archive and Deploy

Once implementation is complete and deployed, archive the change. This merges the "future state" specs into the main specs/ directory, making them the new Source of Truth.

openspec archive add-dark-mode --yes

Your openspec/changes/ directory is now clean, and openspec/specs/ reflects the new functionality.