OpenSpec: A Change‑Driven Development Framework for One‑Click Project Planning and Delivery

Installation

Install the latest OpenSpec package globally with npm install -g @fission-ai/openspec@latest. After installation, run openspec --version (e.g., 0.13.0) and initialize a new project using openspec init. The tool creates the OpenSpec structure, configures AI assistants (e.g., Cursor), and confirms successful initialization.

Initial Interaction

Copy the three suggested prompts into the Cursor chat window to:

Populate the project context by asking OpenSpec to read openspec/project.md and fill in details such as tech stack and conventions.

Create the first change proposal with a placeholder feature description.

Explain the OpenSpec workflow from openspec/AGENTS.md and how to collaborate with the AI.

Three‑Stage OpenSpec Workflow

Stage 1 – Create Change (Planning) : List existing specs with openspec list, create a unique change ID (e.g., add-copy-button), write a proposal describing the scenario, and validate it using openspec validate <change-id> --strict. Approval is required before implementation.

Stage 2 – Implement Change (Development) : Read proposal.md and tasks.md, complete tasks sequentially, and mark each as done only after verification. Development must not start without approved tasks.

Stage 3 – Archive Change (Completion) : After deployment, move the change folder to changes/archive/YYYY‑MM‑DD‑[name]/, update the main spec files under specs/, and re‑validate the archived state.

Example: Chrome Extension Copy‑Bypass Proposal

The author creates a proposal to bypass copy‑restriction mechanisms in a new Chrome extension. OpenSpec generates the following directory structure:

openspec/changes/add-copy-bypass-core/
├── proposal.md          # Why, what, impact
├── tasks.md            # 30 implementation tasks
└── specs/
    └── copy-bypass/
        └── spec.md      # 6 core requirements, 15 scenarios

Core requirements include CSS user‑select removal, JavaScript event listener removal, event handler reset, Selection API protection, content‑script injection, and non‑invasive operation. Validation confirms correct format, presence of scenarios for each requirement, and overall compliance with OpenSpec rules.

Extending the Proposal with Automated Testing

The author adds Chrome‑DevTools MCP automated tests to tasks.md, increasing the task count from 30 to 40. New tasks cover installation of test dependencies, creation of a tests/ directory, and four sub‑sections for testing:

Manual test setup for building and loading the extension.

Automated tests using MCP commands ( navigate_page, take_snapshot, evaluate_script) for CSS user‑select, JavaScript events, event‑handler resets, Selection API protection, and MutationObserver handling.

Compatibility testing, including console‑message inspection and performance verification.

Real‑world site validation.

The MCP tool table lists each command and its purpose. Validation confirms the updated proposal passes all checks.

Next Steps and Interaction Options

After validation, the author can choose:

Option A – Start Implementation : The AI will create project scaffolding (e.g., package.json, vite.config.js), set up Manifest V3, configure Vue 3, and begin core feature development.

Option B – Review Proposal : Inspect proposal.md, tasks.md, and specs/copy-bypass/spec.md for any adjustments.

Option C – Modify Proposal : Provide additional changes to be incorporated.

Commands such as openspec show add-copy-bypass-core display the full task list, while /openspec:apply add-profile-filters triggers execution of tasks. Once all tasks are marked completed (changing - [ ] to - [x]), the change can be archived with /openspec:archive add-profile-filters (or with --yes / -y flags).

Usage Summary

OpenSpec enables developers to manage change‑driven development entirely through natural‑language prompts in tools like Cursor, eliminating the need for manual command‑line syntax. It maintains a history of completed changes, supports automated testing integration, and ensures traceable, auditable development cycles.