OpenSpec Demo: A Complete Walkthrough of the Spec-First Workflow

OpenSpec provides a working demo in its Examples & Recipes documentation that demonstrates the complete spec-first change management loop, from proposing a logout button feature to archiving the implementation using slash commands like /opsx:propose and /opsx:apply.

The OpenSpec repository includes a concrete demonstration of its AI-driven change management system through a practical "add logout button" example. This OpenSpec demo illustrates how the framework maintains authoritative specifications in openspec/specs/ while isolating unit-of-work changes in openspec/changes/<name>/ directories. Understanding this example reveals how OpenSpec bridges the gap between specification and implementation using a structured, reviewable workflow orchestrated by both AI chat slash commands and the terminal CLI.

How the OpenSpec Demo Works

The demonstration follows a spec-first workflow where specifications serve as the single source of truth for system behavior. The change management loop lives entirely inside your repository and is orchestrated through slash commands in AI chat or the terminal CLI, with core runtime plumbing implemented in src/index.ts and interactive dashboard rendering handled by src/core/view.ts.

Step 1: Propose the Change

Initiate the change workflow using the AI chat command:

/opsx:propose add-logout-button

This command triggers creation of the directory openspec/changes/add-logout-button/ containing four key artifacts: proposal.md (why and what), specs/ (new requirements and scenarios), design.md (technical approach), and tasks.md (implementation checklist). The file system operations are handled by logic in src/utils/file-system.ts.

Step 2: Review the Generated Artifacts

Examine the generated files under openspec/changes/add-logout-button/, including proposal.md and specs/auth/spec.md. Edit these markdown files directly to refine requirements, adjust technical approaches, or modify the task checklist before implementation begins.

Step 3: Apply the Implementation

Execute the implementation phase with the AI chat command:

/opsx:apply

The AI processes each task listed in tasks.md, writing code for items such as "Add logout button to header" and "Clear session on click". This applies the spec delta to your working codebase while following the design constraints established in the previous step.

Step 4: Archive the Change

Finalize the workflow and merge changes back to the source of truth:

/opsx:archive

This command merges the delta specs into the main openspec/specs/ tree and moves the change folder to openspec/changes/archive/2026-06-22-add-logout-button/, preserving the complete implementation history while removing the active change status.

Step 5: Inspect the Repository State

Use the terminal CLI to review the completed work and repository status:

openspec list          # shows active changes (none after archiving)

openspec show add-logout-button   # shows archived change details

openspec view          # launches the interactive dashboard

The CLI commands are defined in bin/openspec.js, which translates terminal inputs into core actions.

Key Implementation Files Behind the Demo

Several source files power this demonstration according to the OpenSpec source code:

• src/index.ts: Entry point that registers the CLI and core services
• src/core/view.ts: Implements the interactive dashboard launched by openspec view
• src/utils/file-system.ts: Handles reading and writing of proposal, spec, design, and task files
• bin/openspec.js: CLI wrapper translating terminal commands into core actions
• docs/examples.md: Contains the complete step-by-step demo walkthrough
• docs/commands.md: Reference for all slash commands used in the workflow
• docs/overview.md: High-level architectural description of the spec-first methodology

Summary

• The OpenSpec demo provides a working "add logout button" example that demonstrates the complete change management loop.
• The workflow uses /opsx:propose, /opsx:apply, and /opsx:archive chat commands alongside CLI tools like openspec view and openspec list.
• Generated artifacts live in openspec/changes/<name>/ before final merging into openspec/specs/ upon archiving.
• File system operations are handled by src/utils/file-system.ts, while the dashboard UI is implemented in src/core/view.ts.

Frequently Asked Questions

Where can I find the official OpenSpec demo documentation?

The complete demo is documented in docs/examples.md at the repository root, with additional architectural context available in docs/overview.md. These files contain the exact command sequences and expected outputs for the logout button example.

What commands does the OpenSpec demo use to manage changes?

The demo utilizes slash commands /opsx:propose, /opsx:apply, and /opsx:archive within AI chat, plus terminal commands including openspec list, openspec show, and openspec view as defined in bin/openspec.js. These commands orchestrate the spec-first workflow from creation to archival.

How does OpenSpec organize files during the demo workflow?

Changes are isolated in openspec/changes/<name>/ directories containing proposal.md, design.md, tasks.md, and delta specs. Upon archiving, these merge into openspec/specs/ while the change moves to openspec/changes/archive/, with file operations managed by src/utils/file-system.ts.

Can I run the OpenSpec demo on any existing codebase?

Yes, once OpenSpec is initialized in a repository, you can execute this demo workflow using the documented commands and folder structure. The system creates the necessary openspec/ directory structure automatically when you run the proposal command, making it adaptable to any project.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}