The OpenSpec Workflow

OpenSpec enforces a disciplined 3-stage workflow to prevent requirements drift and ensure AI assistants remain aligned with human intent.

Stage 1: Creating Changes (Proposal)

Before writing code, you define what is changing.

  1. Identify Need: A new feature, refactor, or architectural shift.
  2. Scaffold: Create a unique directory under openspec/changes/<change-id>/.
  3. Define Specs: Write Deltas (Additions, Modifications, Removals) for the relevant capabilities.
  4. Plan: Create a tasks.md file breaking the work into verifiable steps.
  5. Validate: Use openspec validate to ensure the proposal is structurally sound.

Why? This stage forces alignment on the "What" and "Why" before spending resources on the "How".

Stage 2: Implementation

This is the coding phase. The AI assistant uses the artifacts from Stage 1 as its instructions.

  1. Context Loading: The AI reads proposal.md and specs/ to understand requirements.
  2. Execution: The AI works through tasks.md sequentially.
  3. Tracking: Tasks are marked as complete ([x]) in real-time.

Why? By following a pre-approved checklist, the AI avoids hallucinating features or skipping edge cases defined in the specs.

Stage 3: Archiving (Integration)

Once the code is deployed and verified, the change proposal is no longer a "proposal"—it is reality.

  1. Archive Command: Running openspec archive <change-id> moves the change folder to openspec/changes/archive/.
  2. Spec Merging: The CLI automatically applies the Spec Deltas (ADDED/MODIFIED requirements) to the main openspec/specs/ directory.

Why? This keeps your documentation (specs/) permanently in sync with your codebase. The specs/ folder always represents the currently deployed capabilities.