Skip to content
OpenSpec

Quick Start

This guide walks through a complete OpenSpec workflow from proposal to archive.

  1. Initialize OpenSpec

    Terminal window
    cd your-project
    openspec init

    Select your AI tools when prompted. This creates the openspec/ directory.

  2. Create a Change Proposal

    Ask your AI assistant:

    Create an OpenSpec change proposal for adding two-factor authentication

    The AI creates:

    openspec/changes/add-two-factor-auth/
    ├── proposal.md       # Why and what
    ├── tasks.md          # Implementation checklist
    └── specs/
        └── auth/
            └── spec.md   # Requirement deltas

  3. Review the Proposal

    Terminal window
    openspec show add-two-factor-auth

    Refine with your AI until specs match your needs.

  4. Validate the Change

    Terminal window
    openspec validate add-two-factor-auth --strict

    Fix any formatting issues before proceeding.

  5. Implement the Tasks

    /openspec:apply add-two-factor-auth

    The AI works through tasks.md, marking items complete.

  6. Archive After Deployment

    Terminal window
    openspec archive add-two-factor-auth --yes

    This:

    • Moves the change to archive/
    • Updates main specs with the deltas
    • Records the completion date

Example: The Complete Flow

Section titled “Example: The Complete Flow”
Terminal window
# 1. Start fresh
openspec init


# 2. Check what exists
openspec list           # Active changes
openspec list --specs   # Existing specs


# 3. After AI creates proposal
openspec validate add-2fa --strict


# 4. Review everything
openspec show add-2fa


# 5. After implementation
openspec archive add-2fa --yes

What’s Next?

Section titled “What’s Next?”