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

> Explore the OpenSpec demo and master spec-first workflow. See how to propose features and manage implementations using slash commands from start to archive.

- Repository: [Fission/OpenSpec](https://github.com/Fission-AI/OpenSpec)
- Tags: tutorial
- Published: 2026-06-28

---

**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`](https://github.com/Fission-AI/OpenSpec/blob/main/src/index.ts) and interactive dashboard rendering handled by [`src/core/view.ts`](https://github.com/Fission-AI/OpenSpec/blob/main/src/core/view.ts).

### Step 1: Propose the Change

Initiate the change workflow using the AI chat command:

```text
/opsx:propose add-logout-button

```

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

### Step 2: Review the Generated Artifacts

Examine the generated files under `openspec/changes/add-logout-button/`, including [`proposal.md`](https://github.com/Fission-AI/OpenSpec/blob/main/proposal.md) and [`specs/auth/spec.md`](https://github.com/Fission-AI/OpenSpec/blob/main/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:

```text
/opsx:apply

```

The AI processes each task listed in [`tasks.md`](https://github.com/Fission-AI/OpenSpec/blob/main/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:

```text
/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:

```bash
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`](https://github.com/Fission-AI/OpenSpec/blob/main/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`](https://github.com/Fission-AI/OpenSpec/blob/main/src/index.ts)**: Entry point that registers the CLI and core services
- **[`src/core/view.ts`](https://github.com/Fission-AI/OpenSpec/blob/main/src/core/view.ts)**: Implements the interactive dashboard launched by `openspec view`
- **[`src/utils/file-system.ts`](https://github.com/Fission-AI/OpenSpec/blob/main/src/utils/file-system.ts)**: Handles reading and writing of proposal, spec, design, and task files
- **[`bin/openspec.js`](https://github.com/Fission-AI/OpenSpec/blob/main/bin/openspec.js)**: CLI wrapper translating terminal commands into core actions
- **[`docs/examples.md`](https://github.com/Fission-AI/OpenSpec/blob/main/docs/examples.md)**: Contains the complete step-by-step demo walkthrough
- **[`docs/commands.md`](https://github.com/Fission-AI/OpenSpec/blob/main/docs/commands.md)**: Reference for all slash commands used in the workflow
- **[`docs/overview.md`](https://github.com/Fission-AI/OpenSpec/blob/main/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`](https://github.com/Fission-AI/OpenSpec/blob/main/src/utils/file-system.ts), while the dashboard UI is implemented in [`src/core/view.ts`](https://github.com/Fission-AI/OpenSpec/blob/main/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`](https://github.com/Fission-AI/OpenSpec/blob/main/docs/examples.md) at the repository root, with additional architectural context available in [`docs/overview.md`](https://github.com/Fission-AI/OpenSpec/blob/main/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`](https://github.com/Fission-AI/OpenSpec/blob/main/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`](https://github.com/Fission-AI/OpenSpec/blob/main/proposal.md), [`design.md`](https://github.com/Fission-AI/OpenSpec/blob/main/design.md), [`tasks.md`](https://github.com/Fission-AI/OpenSpec/blob/main/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`](https://github.com/Fission-AI/OpenSpec/blob/main/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.