OpenSpec Workflow: Spec-Driven Development Process

OpenSpec follows a lightweight, iterative workflow that helps you and your AI assistant agree on what to build before any code is written. This guide walks you through each step of the process.

Workflow Overview

The OpenSpec workflow consists of four main phases:

  1. Proposal - Define what you're building and why
  2. Planning - Generate specs, design, and tasks
  3. Implementation - Build the feature following the specs
  4. Archiving - Consolidate knowledge into permanent specs
1

Proposal

/opsx:new

→
2

Planning

/opsx:ff

→
3

Implementation

/opsx:apply

→
4

Archive

/opsx:archive

Step 1: Create a Proposal

Start by creating a new change proposal using the /opsx:new command:

/opsx:new add-dark-mode

What Happens

  • OpenSpec creates a new change folder: openspec/changes/add-dark-mode/
  • Initializes the folder structure
  • Prepares for proposal generation

Proposal Document

The proposal document (proposal.md) captures:

  • Why: The motivation and business case for the change
  • What: What's changing and what's staying the same
  • Scope: Boundaries and limitations
  • Success criteria: How you'll know it's done
Tip: The proposal is reviewable before any code is written. This is your chance to catch misalignment early.

Step 2: Generate Planning Documents

Use the fast-forward command to generate all planning documents at once:

/opsx:ff  # "fast-forward"

Generated Documents

proposal.md

Why we're doing this and what's changing. The business case and scope definition.

specs/

Requirements and scenarios organized by capability. Functional and non-functional requirements.

design.md

Technical approach and architecture decisions. Implementation strategy and trade-offs.

tasks.md

Implementation checklist broken down into actionable tasks. Ordered by dependencies.

Review Before Implementation

This is a critical step. Review all documents before proceeding:

  • Does the proposal align with your goals?
  • Are the specs complete and accurate?
  • Does the design make sense for your architecture?
  • Are the tasks clear and achievable?
Tip: OpenSpec generates concise specs (~250 lines) compared to other tools (~800 lines), making review faster and more focused.

Step 3: Implement

Once you've reviewed and approved the planning documents, implement the change:

/opsx:apply

What Happens

Your AI assistant will:

  1. Read the tasks from tasks.md
  2. Follow the design from design.md
  3. Implement each task systematically
  4. Keep tasks in sync as work progresses
  5. Verify implementation against specs

Implementation Benefits

  • Deterministic: Same specs produce consistent results
  • Reviewable: You can see exactly what will be built
  • Focused: Less noise, faster execution
  • Traceable: Every change links back to a spec
Tip: OpenSpec's implementation phase is noticeably faster than other tools due to less noise in spec files and fewer tasks to process.

Step 4: Archive and Consolidate

After implementation is complete and tested, archive the change:

/opsx:archive

What Happens

  • Moves the change from changes/ to changes/archive/
  • Consolidates knowledge into permanent specifications
  • Updates the main specs in openspec/specs/
  • Updates the OpenSpec dashboard

Knowledge Consolidation

Archiving transforms temporary change documentation into permanent system knowledge:

  • Specs become part of your project's knowledge base
  • Future changes can reference and build upon past work
  • New team members can understand system architecture
  • Context persists beyond chat sessions
Tip: The AGENTS.md file reminds your AI to check consolidated specs before starting any new task.

OpenSpec Workflow Principles

Fluid, Not Rigid

Update any artifact anytime. No rigid phase gates. Iterate freely and adapt as you go.

Iterative, Not Waterfall

Work in small, manageable changes. Review, implement, archive, repeat. No big-bang releases.

Easy, Not Complex

Simple commands, clear structure. Get started in 5 minutes, not hours or days.

Brownfield, Not Just Greenfield

Built for existing codebases. Works with legacy code. No need to start from scratch.

Scalable

From personal projects to enterprise teams. Same workflow, different scales.

Best Practices

Before Starting

  • Clear your context window for better AI performance
  • Use high-reasoning models (Opus 4.5, GPT 5.2) for best results
  • Start with small changes to learn the workflow

During Development

  • Always review proposals and specs before implementing
  • Update artifacts as you learn more (remember: fluid, not rigid)
  • Keep tasks.md in sync with actual progress

After Completion

  • Test thoroughly before archiving
  • Review consolidated specs to ensure knowledge was captured
  • Use archived specs as reference for future work

Next Steps