OpenSpec Hands-on Guide

Last chapter covered spec-driven development philosophy. This chapter gets hands-on.

OpenSpec is currently the lightest spec-driven tool, especially suited for indie devs and small teams. It's not as "heavy" as Spec Kit, and doesn't require switching IDEs like Kiro. You can use OpenSpec with Cursor, Claude Code, or Windsurf.

This chapter's goal: walk you through a complete case from installation to archiving, seeing real results at each step.

Installation and Initialization

First, ensure your Node.js version is 20.19.0 or higher. Open terminal, enter node --version to check. If too low, upgrade; if sufficient, continue.

Install OpenSpec CLI globally:

npm install -g @fission-ai/openspec@latest

Verify after installation:

openspec --version

Seeing a version number means it's installed. Next, enter your project directory and initialize:

cd my-project
openspec init

An interactive interface appears asking which AI tool you use. It supports many: Claude Code, Cursor, Windsurf, GitHub Copilot, Amazon Q Developer, etc. Select your preferred one.

After initialization, your project gains these additions:

my-project/
|---- AGENTS.md              # AI agent guidance file
\---- openspec/
    |---- project.md         # Project context
    |---- specs/             # Source specs (source of truth)
    |---- changes/           # Change proposals (in progress)
    \---- archive/           # Archived changes

Each file and folder has its purpose.

Understanding Directory Structure

project.md: Project Context

openspec/project.md is the project overview for AI. It tells AI what the project does, what tech stack it uses, what coding conventions to follow.

After initialization, this file is empty or has only a basic template. You need to fill it in so AI better understands your project.

A completed project.md looks roughly like:

# Project Context

## Project Overview
This is a SaaS subscription management platform allowing users to manage software subscriptions, track expenses, and set renewal reminders.

## Tech Stack
- Frontend: Next.js 14 + TypeScript + Tailwind CSS
- Backend: Next.js API Routes + Prisma ORM
- Database: PostgreSQL
- Auth: Better Auth
- Payments: Stripe

## Coding Conventions
- Use TypeScript strict mode
- Components use functional components + hooks
- Styles use Tailwind, avoid inline style objects
- API routes follow RESTful patterns
- Error handling uses unified try-catch pattern

## Directory Structure
- /src/app - Next.js App Router pages
- /src/components - Reusable components
- /src/lib - Utilities and config
- /prisma - Database schema and migrations

## Constraints
- Don't use any deprecated APIs
- All database operations must be server-side
- Sensitive info stored in environment variables

After initialization, OpenSpec prompts you: let AI help fill this file. You can directly tell AI:

AI analyzes your project files and auto-fills. Saves time.

specs/: Source Specs

openspec/specs/ stores the project's current specifications-the "source of truth." Each subfolder represents a feature module, containing a spec.md file describing that module's requirements and behavior.

Initially this directory is empty. As you complete and archive changes, specs accumulate.

changes/: Change Proposals

openspec/changes/ is the workspace. When you want to add new features or modify existing ones, you (or AI) create a change folder here.

Say you want to add two-factor authentication. The change folder might be called add-2fa/, containing:

• proposal.md - describes why this change and what it does
• tasks.md - task checklist for implementing this change
• specs/ - modifications to existing specs (in delta format)
• design.md (optional) - technical design decisions

AGENTS.md: AI Agent Guidance

AGENTS.md at project root is the operations manual for AI. It tells AI how to work with the OpenSpec workflow.

Unlike README.md for humans, AGENTS.md is written specifically for AI, containing specific operation steps and commands. AI tools supporting the AGENTS.md convention (including OpenAI Codex, Cursor, Claude Code, etc.) automatically read this file.

Complete Case: Adding User 2FA

Let's walk through a complete case. Assume your project is a SaaS app; you want to add two-factor authentication for users.

Step 1: Draft Proposal

Open your AI tool (Cursor or Claude Code) and enter:

Create an OpenSpec change proposal: Add two-factor authentication (2FA) for users.
Users can enable 2FA in settings; once enabled, login requires entering a phone verification code.

If using Cursor with OpenSpec slash commands configured, you can directly use:

/openspec:proposal Add user 2FA authentication

AI creates a new directory under openspec/changes/, like add-user-2fa/, generating several files.

Generated proposal.md

AI-generated proposal.md looks roughly like:

# Change Proposal: Add User 2FA Authentication

## Change ID
add-user-2fa

## Summary
Add Two-Factor Authentication capability to user accounts,
improving account security.

## Motivation
Current system only has password protection, facing password leak risks.
Two-factor authentication significantly reduces account theft possibility.

## Change Scope
- Settings page adds 2FA toggle
- Login flow adds verification code step
- Database user table adds 2FA-related fields
- New SMS verification code send and verify endpoints

## Affected Specs
- auth/spec.md (auth module)
- user/spec.md (user module)

## Acceptance Criteria
- User can enable/disable 2FA in settings
- With 2FA enabled, login requires 6-digit code
- Verification code valid for 5 minutes
- 5 consecutive wrong codes locks account for 30 minutes

Generated tasks.md

Task checklist is broken down finely:

# Task Checklist

## 1. Database Changes
- [ ] 1.1 Add `two_factor_enabled` boolean field to user table
- [ ] 1.2 Add `two_factor_secret` field to user table (encrypted storage)
- [ ] 1.3 Create verification code record table `otp_codes`
- [ ] 1.4 Run database migration

## 2. Backend API
- [ ] 2.1 Create POST /api/auth/2fa/enable endpoint
- [ ] 2.2 Create POST /api/auth/2fa/disable endpoint
- [ ] 2.3 Create POST /api/auth/2fa/send-code endpoint
- [ ] 2.4 Create POST /api/auth/2fa/verify endpoint
- [ ] 2.5 Modify login endpoint to add 2FA verification step

## 3. Frontend UI
- [ ] 3.1 Add 2FA toggle component to settings page
- [ ] 3.2 Create verification code input modal component
- [ ] 3.3 Modify login page to support 2FA flow
- [ ] 3.4 Add 2FA-related loading and error states

## 4. Testing
- [ ] 4.1 2FA enable/disable flow testing
- [ ] 4.2 Verification code send and verify testing
- [ ] 4.3 Login flow integration testing
- [ ] 4.4 Error handling and edge case testing

Step 2: Review and Align

After proposal generation, review it. Run:

openspec show add-user-2fa

This prints proposal details. You can also use openspec validate to check formatting:

openspec validate add-user-2fa --strict

If there are issues, it tells you what's wrong.

When reviewing, focus on:

1. Are acceptance criteria complete-> Any missing scenarios->
2. Is task breakdown reasonable-> Too large is hard to execute; too small is too fragmented.
3. Is spec delta accurate-> Are ADDED and MODIFIED used correctly->

If adjustments needed, tell AI:

Task checklist is missing SMS provider integration tasks, please add.
Also, add an acceptance criterion: users can view 2FA enable history.

AI updates the relevant files. Go back and forth until you're satisfied.

Step 3: Implement Tasks

With specs confirmed, start coding. Tell AI:

Specs are confirmed. Please start implementing the add-user-2fa change. Execute in tasks.md order.

Or use slash command:

/openspec:apply add-user-2fa

AI implements tasks one by one. After completing each task, it checks off in tasks.md:

## 1. Database Changes
- [x] 1.1 Add `two_factor_enabled` boolean field to user table
- [x] 1.2 Add `two_factor_secret` field to user table (encrypted storage)
- [ ] 1.3 Create verification code record table `otp_codes`
...

During implementation, if AI encounters problems or needs your decision, it pauses to ask. Like:

You answer; AI continues.

This process may take time depending on complexity. The benefit: every step is traceable; you know what AI is doing and why.

Step 4: Archive Change

All tasks complete, tests pass-archive this change:

openspec archive add-user-2fa --yes

Archive operation does several things:

1. Merges deltas from changes/add-user-2fa/specs/ into specs/
2. Moves entire change folder to archive/ directory
3. Updates related spec documents

After archiving, openspec/specs/auth/spec.md contains complete 2FA requirements description, becoming part of project specs. Next time you make related changes, AI reads these specs and knows how the existing system works.

Cursor Integration Tips

If you mainly use Cursor, here are tips for smoother OpenSpec usage.

Enable Slash Commands

When initializing OpenSpec with Cursor selected, it auto-creates .cursor/commands/ directory with predefined slash commands. You can directly use in Cursor:

• /openspec:proposal - Create new change proposal
• /openspec:apply - Implement change
• /openspec:archive - Archive completed change

If slash commands don't appear, restart Cursor. Commands load at startup.

Use @ to Reference Spec Files

Cursor's @ symbol can reference files. Works great with OpenSpec:

@openspec/project.md
@openspec/specs/auth/spec.md

Based on existing auth specs, please add OAuth login support.

This way AI reads your project context and existing specs, reducing misunderstandings.

Cursor Rules with OpenSpec

Add to your .cursorrules file to make Cursor always consider OpenSpec specs:

Before any feature development, first check if there are related specs in openspec/specs/.
If yes, strictly implement per specs.
If no, first create a change proposal through OpenSpec workflow.

Even if you forget, Cursor reminds you to check specs first.

Common Issues and Lessons Learned

Developers have hit various pitfalls using OpenSpec. Here are common ones.

Issue 1: AI-Generated Specs Too Vague

Sometimes you simply say "add a comments feature" and AI generates a vague proposal. Solution: provide more specific requirements:

x Add a comments feature

v Add article comments feature:
- Logged-in users can comment on articles
- Comments support plain text, max 500 characters
- Users can edit/delete their own comments
- Comments display newest first, 20 per page
- Comments need moderation before public display

More specific requirements = more precise generated specs.

Issue 2: Change Conflicts

If you have multiple change proposals open simultaneously, they might modify the same spec file, causing conflicts when archiving.

Use openspec list to view all active changes:

openspec list

If overlap found, either merge changes or complete and archive them sequentially. Avoid too many simultaneous changes.

Issue 3: Wrong MODIFIED vs ADDED

Common beginner mistake.

• ## ADDED Requirements: Adding entirely new functionality unrelated to existing features
• ## MODIFIED Requirements: Modifying existing feature behavior

When using MODIFIED, first copy the complete original requirement, then make modifications. Don't just write the changed parts, or info is lost during archiving.

Issue 4: Specs and Code Diverge

After using for a while, code might change without spec updates (especially during urgent bug fixes).

Recommended: any code modification should have a corresponding OpenSpec change, even small ones. Once habituated, specs stay in sync with code.

If divergence found, take time for a spec sync-have AI read code and update specs. Sharpening the axe won't delay the woodcutting.

Practical Templates

Finally, sharing templates I commonly use-copy directly.

proposal.md Template

# Change Proposal: [Feature Name]

## Change ID
[change-id]

## Summary
[One-sentence description of what this change does]

## Motivation
Why is this change needed? What problem does it solve?

## Change Scope
- [Affected module 1]
- [Affected module 2]
- [New feature points]

## Out of Scope
- [Explicitly excluded content]

## Technical Constraints
- [Technical restrictions to follow]

## Acceptance Criteria
- [ ] [Specific verifiable condition 1]
- [ ] [Specific verifiable condition 2]
- [ ] [Specific verifiable condition 3]

## Related Links
- [Design mockup URL]
- [Related Issue]

tasks.md Template

# Task Checklist

## Estimated Time
[Overall estimate]

## 1. [Phase name, e.g. "Database Changes"]
- [ ] 1.1 [Specific task]
- [ ] 1.2 [Specific task]

## 2. [Phase name, e.g. "Backend Development"]
- [ ] 2.1 [Specific task]
- [ ] 2.2 [Specific task]
- [ ] 2.3 [Specific task]

## 3. [Phase name, e.g. "Frontend Development"]
- [ ] 3.1 [Specific task]
- [ ] 3.2 [Specific task]

## 4. Testing & Documentation
- [ ] 4.1 Unit tests
- [ ] 4.2 Integration tests
- [ ] 4.3 Update related documentation

## Notes
- [Things to note during implementation]

Next chapter is the MBRY prompt framework. After learning to manage requirements with OpenSpec, you also need to know how to communicate efficiently with AI. MBRY is a concise prompt structure that helps you hit the mark every time you talk to AI.