luismori.

OpenSpec Workflows · Part 1

OpenSpec Spec-Driven Development AI Coding Engineering Workflow Product Management Cursor

How to Get Started with OpenSpec: Existing Projects, New Apps, and Common First Changes

A practical, source-backed guide for engineers and PMs adopting OpenSpec: when to start with an existing project, when to use it for a new build, and how to run the first workflow safely.

15 min read Updated Jul 1, 2026

TL;DR

  • OpenSpec is a lightweight spec-driven development layer for AI coding assistants. It gives your team a repo-native place to capture proposals, behavior specs, technical design, tasks, and archived decisions.
  • For existing projects, do not document the whole app first. OpenSpec’s own brownfield guide says to write specs only for the slice you are about to change.
  • For new projects, use OpenSpec before the first implementation branch gets messy. The biggest win is agreeing on behavior, scope, and trade-offs before the AI assistant turns a vague idea into code.
  • There are two places to type commands: openspec ... runs in the terminal; /opsx:... runs in your AI assistant chat.
  • The default first loop is:
TERMINAL   npm install -g @fission-ai/openspec@latest
TERMINAL   cd your-project && openspec init
AI CHAT    /opsx:explore       # optional, when unclear
AI CHAT    /opsx:propose ...
AI CHAT    /opsx:apply
AI CHAT    /opsx:archive
  • My default recommendation:
    • existing product: start with one small real change
    • new product: start with one thin end-to-end capability
    • unclear idea: start with /opsx:explore
    • clear idea: start with /opsx:propose

What You Will Learn Here

By the end of this article, you should be able to:

  • explain what OpenSpec adds on top of normal AI coding chat
  • install and initialize OpenSpec without confusing terminal commands and chat commands
  • choose the right first workflow for an existing app vs a new app
  • run a realistic first change, such as rate limiting or guest checkout
  • understand what files OpenSpec creates and why they belong in git
  • avoid the most common adoption mistakes for engineers and PMs

On July 1, 2026, I reviewed the current OpenSpec README and docs for installation, getting started, existing projects, workflows, supported tools, and customization. The command names, directory layout, delta-spec model, supported-tool behavior, and brownfield guidance below are source-backed. The rollout sequence and team operating advice are my synthesis for engineering and product teams.

For the broader comparison against GitHub Spec Kit, start with OpenSpec vs GitHub Spec Kit. This article is more hands-on: how to start using OpenSpec without turning it into a planning ceremony.

The Problem OpenSpec Solves

AI coding assistants are good at turning a prompt into code. That is useful, but it creates a new problem:

chat idea
  -> generated code
  -> reviewer asks "is this actually what we agreed to build?"
  -> more chat
  -> more code
  -> intent disappears

OpenSpec adds a small layer between the idea and the code:

idea
  -> proposal
  -> behavior specs
  -> design
  -> tasks
  -> implementation
  -> archived spec history

That layer gives engineers something concrete to build against and gives PMs something concrete to review before implementation gets expensive.

OpenSpec’s own README frames the project as fluid, iterative, easy, and built for brownfield as well as greenfield work. In this article, when I call the workflow “lightweight,” I mean that relative to heavier phase-gated spec workflows: the source-backed part is that OpenSpec’s default core profile keeps the loop to explore, propose, apply, sync, and archive; the team-fit interpretation is my judgment.

The Mental Model

OpenSpec has two core directories:

openspec/
|-- specs/
|   `-- <domain>/spec.md        # current system behavior
`-- changes/
    `-- <change-name>/
        |-- proposal.md         # why and what
        |-- design.md           # how
        |-- tasks.md            # implementation checklist
        `-- specs/
            `-- <domain>/spec.md # delta: ADDED/MODIFIED/REMOVED

The important idea is delta specs. A change does not need to describe the entire system. It describes what is being added, modified, or removed.

current behavior
      +
change delta
      =
updated behavior after archive

That is why OpenSpec is especially interesting for existing codebases. You can start with a nearly empty openspec/specs/ directory and let it become useful one real change at a time.

First Decision: Existing Project or New Project?

Use this quick decision flow:

Are you adding OpenSpec to an app that already exists?
      |
      |-- yes
      |   `-- pick one small real change
      |       use /opsx:explore if the code path is unclear
      |       write only the delta for the touched area
      |
      `-- no
          `-- pick one thin end-to-end capability
              use /opsx:propose to shape the first build
              avoid designing every future feature upfront

Existing project default

Use OpenSpec to make one change safer:

"Add rate limiting to public API routes"
"Add guest checkout"
"Fix login redirect after SSO"
"Add audit log export"

Do not start with:

"Document our entire platform"
"Create specs for every service"
"Reverse-engineer every feature before we ship again"

Those sound responsible. In practice, they usually create stale specs nobody trusts.

New project default

Use OpenSpec to protect the first implementation from vague scope:

"Build a team bookmarks app with login, shared collections, and search"

Then scope the first real slice:

"Users can create a workspace, add one bookmark, and see it in a list"

That gives the AI assistant a small system to make real, while leaving room for future OpenSpec changes.

Install and Initialize

OpenSpec currently requires Node.js 20.19.0 or higher.

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

Then initialize it inside your project:

cd your-project
openspec init

If you want a scripted setup for specific tools:

openspec init --tools cursor,claude

OpenSpec’s supported-tools docs also document --tools all, --tools none, and a --profile option. The default profile is core, which includes:

  • /opsx:explore
  • /opsx:propose
  • /opsx:apply
  • /opsx:sync
  • /opsx:archive

The expanded workflows add:

  • /opsx:new
  • /opsx:continue
  • /opsx:ff
  • /opsx:verify
  • /opsx:bulk-archive
  • /opsx:onboard

Enable expanded workflows when you want more explicit control:

openspec config profile
openspec update

One technical caveat: generated skills and commands are profile-dependent and tool-dependent. A Cursor setup, a Claude Code setup, and a --tools none setup will not create the same files. Treat the paths in this article as representative examples, then check your generated directories before committing.

Do Not Mix Up Terminal Commands and Chat Commands

This is the most common early stumble.

TERMINAL commands
  openspec init
  openspec update
  openspec list
  openspec show <change>
  openspec validate <change>

AI CHAT commands
  /opsx:explore
  /opsx:propose add-rate-limiting
  /opsx:apply
  /opsx:archive

There is no separate OpenSpec chat app. You type /opsx:... in the same AI coding assistant chat where you would normally ask for code.

Workflow 1: Add OpenSpec to an Existing Project

Scenario:

You maintain an existing API. You want to add rate limiting to public routes, but you are not sure where requests flow through the middleware stack.

Step 1: Initialize OpenSpec

cd api-service
openspec init --tools cursor

Commit the generated OpenSpec files and tool commands in the same branch where you introduce the workflow. If your repo has strict review rules, make this a small setup PR first.

Step 2: Explore before proposing

In AI chat:

/opsx:explore

Then give it the practical question:

I need to add rate limiting to public API routes.
Please inspect the routing and middleware flow first.
Do not write code yet.
Tell me where the clean insertion point is and what risks exist.

Expected output:

Request path:
  edge proxy
    -> Express app
    -> request logging
    -> auth middleware
    -> route handlers

Candidate insertion points:
  1. Before auth: protects auth endpoints too, but may rate-limit login incorrectly
  2. After auth: user-aware limits, but public anonymous routes need IP fallback
  3. Per-router middleware: more explicit, more repeated config

/opsx:explore creates no artifacts. That is the point. It is a thinking step before OpenSpec commits you to a change folder.

Step 3: Propose a small change

/opsx:propose add-public-api-rate-limiting

Ask for the scope you actually want:

Scope this as a small first change:
- Add IP-based rate limiting to unauthenticated public API routes
- Do not change authenticated user quotas yet
- Add a clear 429 response contract
- Include tests for normal, near-limit, and over-limit requests

OpenSpec should create something like:

openspec/changes/add-public-api-rate-limiting/
|-- proposal.md
|-- design.md
|-- tasks.md
`-- specs/api/spec.md

Step 4: Review the artifacts

For PMs, review proposal.md and the scenarios in the delta spec:

## ADDED Requirements

### Requirement: Public API Rate Limiting
The system SHALL limit unauthenticated public API requests by client IP.

#### Scenario: Over-limit request
- GIVEN an unauthenticated client has exceeded the request limit
- WHEN the client calls a public API route
- THEN the system returns HTTP 429
- AND the response includes retry guidance

For engineers, review design.md and tasks.md:

Does this match the actual middleware stack?
Does the 429 response contract match API conventions?
Are tests attached to behavior, not implementation details?
Is the rollout reversible?

Before moving to /opsx:apply, use a small review checklist:

Scope
  [ ] Is this one logical change?
  [ ] Are non-goals explicit?

Behavior
  [ ] Does the delta spec describe user-visible behavior?
  [ ] Are edge cases written as scenarios?

Implementation
  [ ] Does design.md match the actual code path?
  [ ] Are tasks small enough to review?
  [ ] Is there a validation command or test plan?

Step 5: Apply, verify, and archive

/opsx:apply

If you use expanded workflows:

/opsx:verify

Then finish:

/opsx:archive

After archive, the delta spec becomes part of the main openspec/specs/api/spec.md behavior library, and the change moves under openspec/changes/archive/.

Workflow 2: Start a New Project with OpenSpec

Scenario:

You want to build a small internal tool for team bookmarks. Engineers want a clean first slice; PMs want to avoid building search, permissions, import/export, and analytics before the core behavior is proven.

Step 1: Create the project

mkdir team-bookmarks
cd team-bookmarks
git init
npm init -y
openspec init --tools cursor

If the app framework is not chosen yet, use /opsx:explore first:

/opsx:explore

Prompt:

We need a small internal team bookmarks app.
Compare a simple Astro + API route approach vs Next.js vs a lightweight Express backend.
Focus on what lets us ship the first authenticated bookmark flow fastest.
Do not create files yet.

Step 2: Propose the first thin slice

/opsx:propose team-bookmarks-mvp

Prompt:

Create the MVP spec for:
- A user can create one workspace
- A user can add a bookmark with title and URL
- A user can see bookmarks in a list
- No sharing, tags, import/export, or full-text search yet
- Keep the implementation small enough for one PR

The goal is not a perfect product plan. The goal is a first slice that teaches the team whether the architecture and workflow are working.

Step 3: Use artifacts as review surfaces

PM review:

proposal.md
  -> is the MVP scope right?

specs/bookmarks/spec.md
  -> are the user-visible behaviors correct?

tasks.md
  -> is the PR small enough to review?

Engineering review:

design.md
  -> is the stack choice explicit?
  -> are persistence and auth boundaries clear?

tasks.md
  -> can backend, UI, and tests run in parallel?
  -> is there a validation path before archive?

Step 4: Apply and archive

/opsx:apply
/opsx:archive

Now the new project has both code and the first spec history. Future features become new OpenSpec changes:

add-tags
add-shared-workspaces
add-bookmark-search
add-import-from-browser-export

Each one can be scoped and reviewed separately.

Common Scenario Playbook

Scenario A: You have a bug but not a clear cause

Start with:

/opsx:explore

Use it like a diagnostic partner:

Users are sometimes redirected to the wrong page after login.
Trace the login callback and redirect logic.
Give me likely causes and the smallest change worth proposing.

Then:

/opsx:propose fix-login-redirect-after-auth

This avoids writing a spec for the wrong bug.

Scenario B: You have a clear feature request

Skip exploration if the scope is already clear:

/opsx:propose add-invoice-csv-export

Then review:

proposal.md -> scope and non-goals
spec.md     -> export behavior and permissions
design.md   -> query, format, and performance choices
tasks.md    -> implementation checklist

Scenario C: You already have a PRD

Do not bulk-convert the whole PRD.

Use it as source material for the current change:

/opsx:explore

Prompt:

Here is the PRD section for guest checkout.
Extract only the requirements needed for the first implementation PR.
Identify open questions before we create an OpenSpec change.

Then:

/opsx:propose add-guest-checkout

Scenario D: You are in a monorepo

Start simple:

repo-root/
|-- apps/web/
|-- services/api/
|-- packages/ui/
`-- openspec/

Use domains that match how your team thinks:

openspec/specs/
|-- auth/spec.md
|-- checkout/spec.md
|-- search/spec.md
`-- admin/spec.md

For true multi-repo planning, OpenSpec has a beta Stores feature. I would treat that as promising but evolving, and start with one repo-level openspec/ directory unless the cross-repo need is real.

What to Put in openspec/config.yaml

OpenSpec project config is the easiest customization point for teams. Use it to teach the agent your stack and review rules.

schema: spec-driven

context: |
  Tech stack: TypeScript, Astro, React islands, Tailwind CSS.
  Deployment: Cloudflare Pages static output.
  Testing: npm run build is required before article PRs.
  Content convention: user-facing text lives in content/ when possible.

rules:
  proposal:
    - Include explicit non-goals.
    - Identify affected user roles.
  specs:
    - Use Given/When/Then scenarios.
    - Separate current behavior from proposed changes.
  design:
    - Mention rollback or migration risk when state changes.
  tasks:
    - Keep tasks small enough for one reviewer to verify.

Keep this config useful, not encyclopedic. The docs mention a 50KB context limit, but the practical limit is attention: the larger the context, the easier it is for important rules to disappear in noise.

What Engineers and PMs Should Review

              PM REVIEW                       ENGINEERING REVIEW
              ---------                       ------------------
proposal.md   problem, scope, non-goals        affected systems, rollout risk
spec.md       behavior, scenarios, edge cases  testability, current-vs-new behavior
design.md     trade-offs in plain language     architecture, dependencies, failure modes
tasks.md      delivery shape and review size   sequencing, parallel work, validation
archive       decision history                 future maintenance context

The point is not to make PMs read implementation details or engineers rewrite product language. The point is to give each role a stable place to correct the part they own.

The First Week Adoption Plan

If I were adding OpenSpec to a real team, I would not start with a workshop.

I would do this:

Day 1
  initialize OpenSpec in a small branch
  add project config with minimal context

Day 2
  pick one real upcoming change
  run /opsx:explore if unclear
  run /opsx:propose

Day 3
  review proposal/spec/design/tasks with PM + engineer
  remove overreach
  clarify non-goals

Day 4
  run /opsx:apply
  adjust artifacts if implementation reveals reality was different

Day 5
  verify if using expanded profile
  archive
  merge the change
  write down what felt useful and what felt heavy

After that, decide whether OpenSpec belongs in:

  • every product feature
  • only risky features
  • brownfield changes with unclear behavior
  • onboarding and reverse-engineering work
  • new-project scaffolding

Do not force it everywhere until the first few changes prove the habit.

Common Mistakes

Mistake 1: Backfilling the whole app

OpenSpec’s existing-project guide is direct: you do not document the whole codebase to start. You document what you are about to change.

Mistake 2: Treating /opsx:propose as implementation approval

Proposal means the change has a shape. It does not mean the scope is right. Review the artifacts before /opsx:apply.

Mistake 3: Archiving without syncing reality

If implementation discovers a different design, update the artifact before archive. Otherwise, openspec/specs/ becomes aspiration instead of behavior.

Mistake 4: Hiding specs from product

If PMs only see the final code diff, OpenSpec loses half its value. The spec exists so product feedback can land before code review becomes the only review surface.

Mistake 5: Over-customizing on day one

Start with project config. Reach for custom schemas after you have repeated evidence that the default artifacts do not match your team process.

How This Fits with the Previous Comparison Article

The previous article compared OpenSpec and GitHub Spec Kit side by side. The short version:

  • OpenSpec is strong when you want living specs, delta changes, and fluid iteration.
  • Spec Kit is strong when you want explicit gates, richer artifact bundles, and extension catalogs.

For this article’s use case - getting started in an existing codebase or a new app - OpenSpec’s advantage is its adoption curve. You can start small:

one repo
  -> one change
  -> one delta spec
  -> one archived decision

That is enough to learn whether the workflow helps your team.

Sources

Primary sources reviewed on July 1, 2026:

  • Fission AI, OpenSpec README - philosophy, quick start, Node requirement, default and expanded workflows, usage notes
  • Fission AI, Installation - package managers, Node.js 20.19+ prerequisite, update behavior
  • Fission AI, Getting Started - terminal vs AI chat commands, first loop, directory layout, artifact descriptions, delta spec archive behavior
  • Fission AI, Using OpenSpec in an Existing Project - brownfield-first guidance, do not spec the whole codebase, first real change model, monorepo note
  • Fission AI, Workflows - core profile, expanded workflows, /opsx:explore, /opsx:verify, archive behavior, update-vs-new heuristic
  • Fission AI, Supported Tools - generated skills and commands, supported tool IDs, profile-dependent install behavior
  • Fission AI, Customization - openspec/config.yaml, context/rules injection, custom schemas, community schemas

Related reading on this site: