Mastering OpenSpec: A CLI Guide to Spec‑Driven Development and AI Integration

Development History

OpenSpec (short for "spec‑driven develop") is a library that enables specification‑first development by managing project specifications, agents, and change proposals through a simple CLI.

CLI Basics

Project Initialization (Setup) openspec init – creates an .openspec/ directory (or openspec/) with the initial structure.

Purpose: Initializes OpenSpec in the current directory.

Update Configuration openspec update – refreshes OpenSpec configuration and AGENTS.md for the AI tool.

When to use: After adding a new AI tool (e.g., Cursor, Copilot) or when the AI seems less effective.

List Active Changes openspec list – lists all active changes (Active Changes).

Display: Shows Change ID, status, and progress from tasks.md (e.g., [2/5]).

Show Change Details openspec show <change-id> [--json] [--deltas-only] – outputs detailed JSON information about a specific change, primarily for AI consumption.

Visual TUI openspec view – launches a terminal UI to visualize task progress.

Quality Control openspec validate <change-id> [--strict] – validates the spec files (Markdown frontmatter, task completeness, proposal structure). --strict forces errors on any formatting issue.

Finish and Archive openspec archive <change-id> [--yes] – merges a change into the main openspec/specs/ directory and moves it to changes/archive/.

Utility Commands openspec version – shows the installed version. openspec help – displays help documentation.

Typical Development Workflow

The workflow consists of four stages: Draft (create a change with openspec init and edit project.md, proposal.md, tasks.md), Review (run openspec validate), Apply (execute tasks sequentially, marking them in tasks.md), and Archive (merge into the permanent specs with openspec archive).

Directory Structure

openspec/</code><code>├── project.md          # Project conventions</code><code>├── specs/              # Current truth – what is built</code><code>│   └── [capability]/   # Single focused capability</code><code>│       ├── spec.md      # Requirements and scenarios</code><code>│       └── design.md    # Technical patterns</code><code>├── changes/            # Proposals – what should change</code><code>│   ├── [change-name]/</code><code>│   │   ├── proposal.md # Why, what, impact</code><code>│   │   ├── tasks.md    # Implementation checklist</code><code>│   │   ├── design.md   # Technical decisions (optional)</code><code>│   │   └── specs/      # Delta changes</code><code>│   │       └── [capability]/</code><code>│   │           └── spec.md # ADDED/MODIFIED/REMOVED</code><code>│   └── archive/        # Completed changes

Problems with Traditional SDD

Time‑pressured projects often skip thorough specifications.

Specs become outdated as code evolves.

Writing and maintaining detailed specs feels like a burden for many developers.

Why OpenSpec Is Gaining Attention

OpenSpec treats specifications as code, allowing AI agents to read and update them directly. This reduces the “spec‑to‑code” gap and enables AI‑assisted development where the AI generates or modifies specs, tasks, and design documents.

AI Prompt Engineering vs. CLI Commands

Beginners often confuse terminal commands with AI slash commands. The article clarifies the relationship: CLI commands perform concrete file operations, while AI slash commands generate or modify those files through prompts.

Practical Example: Mobile PPT Outline Notification

A change is described with proposal.md, tasks.md, and spec.md to add a Snackbar notification on mobile devices. The example shows how to break down the work into tasks, define scenarios, and track progress with [x] checkboxes.

IDE Integration

Cursor and other IDEs can invoke OpenSpec commands directly, enabling a seamless workflow where the AI suggests changes and the CLI applies them.

Handling Duplicate or Missing Requirements

Review existing specs with openspec list and openspec show before creating new proposals.

If a duplicate is found, ask the user whether to modify the existing change.

Update Philosophy

OpenSpec intentionally omits an explicit update CLI because Markdown files are inherently editable. Updates are performed by editing the relevant spec.md, tasks.md, or by creating a new proposal that overwrites the previous version.

Best Practices for Updating

Manual edit of the change folder (fastest).

Reuse the /openspec‑proposal command to generate a new draft that overwrites the old one.

During openspec apply, adjust tasks.md first if needed.

Archiving Errors and Troubleshooting

If openspec archive fails (e.g., missing requirement header), verify that the change is still in openspec/changes/ and not already moved to changes/archive/. Ensure the spec’s requirements match the archived version, then re‑run validation and archive.

Long‑Term Solutions

Prompt the AI to stop on errors and present clear messages for manual correction.

Maintain strict validation ( --strict) to catch formatting issues early.

Spec Types and Their Meaning

ADDED – Insert new requirements or scenarios.

MODIFIED – Replace existing content; high risk because it discards old logic.

REMOVED – Delete obsolete scenarios.

Choosing Between OpenSpec and Spec Kit

OpenSpec is lightweight, ideal for brownfield projects, rapid iteration, and low token consumption. Spec Kit is heavyweight, suited for greenfield projects, strict governance, and detailed documentation.

Reference Links

https://openspec.dev/

https://github.com/Fission-AI/OpenSpec

https://github.com/github/spec-kit

https://aistudio.google.com