DEV Community

Cover image for Retrofitting OpenSpec Into Existing Projects: A Practical Playbook
Mike Buyco
Mike Buyco

Posted on

Retrofitting OpenSpec Into Existing Projects: A Practical Playbook

#ai #specdrivendevelopment #programming #webdev

Most teams don't have the luxury of starting from a clean slate. They have production systems, active customers, shipping deadlines, and years of accumulated decisions. That's exactly where OpenSpec delivers the most value.

The objective isn't to stop development and rewrite documentation. It's to capture reality, improve visibility, and make the existing system easier for both engineers and AI to understand.

The fastest path to ROI is incremental adoption alongside normal development.

Install and Initialize

Start from your project root:

# Install globally
npm install -g @fission-ai/openspec@latest

# Verify
openspec --version
Enter fullscreen mode Exit fullscreen mode

Then initialize in your existing repo:

cd your-existing-project
openspec init
Enter fullscreen mode Exit fullscreen mode

This is interactive. OpenSpec will prompt you to select which AI tools to configure (Claude Code, Cursor, Windsurf, Codex, Copilot, etc.). You can skip this non-interactively:

# Configure for specific tools
openspec init --tools claude,cursor

# Or skip tool config entirely
openspec init --tools none
Enter fullscreen mode Exit fullscreen mode

What gets created:

your-project/
├── openspec/
│   ├── config.yaml         # Project configuration
│   ├── specs/              # Your specifications (source of truth)
│   └── changes/            # Proposed changes
├── .claude/skills/         # (if Claude selected)
├── .cursor/commands/       # (if Cursor selected)
└── CLAUDE.md               # (if Claude selected)
Enter fullscreen mode Exit fullscreen mode

Commit this to version control. Your specs belong alongside the code they describe.

Start With an Architecture Audit

Don't begin by writing specifications. Begin by understanding what already exists.

Use /opsx:explore in your AI assistant to read the area you're about to touch:

You: /opsx:explore

AI:  What would you like to explore?

You: I need to understand how our payment processing works — what services
     are involved, what the failure modes are, and where rate limits hit.

AI:  Let me trace it... [reads the codebase]
     Payment flow: CheckoutController → PaymentService → StripeAdapter
     → PaymentConfirmedEvent → InvoiceService.
     Failure modes: Stripe timeout (no retry), webhook idempotency not enforced.
     No rate limiting layer exists today.
Enter fullscreen mode Exit fullscreen mode

This saves the most pain on large codebases. The AI maps your actual structure before any specs are written.

Inventory the major parts of the application:

  • Business domains
  • APIs
  • Database models
  • Background jobs
  • Events
  • External integrations
  • Authentication
  • Authorization
  • Infrastructure

For each business capability, answer practical questions:

  • What problem does it solve?
  • Where does the code live?
  • What triggers it?
  • What data comes in?
  • What data goes out?
  • Which systems depend on it?

Ignore implementation details. Focus on system boundaries.

Organize Around Business Domains

Many mature codebases are organized by technical layers:

app/
├── controllers/
├── models/
├── services/
└── helpers/
Enter fullscreen mode Exit fullscreen mode

Those folders don't describe the business.

Instead, identify stable business capabilities:

  • Orders
  • Billing
  • Inventory
  • Customers
  • Notifications
  • Reporting

Each capability becomes an OpenSpec domain under openspec/specs/. You don't design the whole taxonomy up front — create a domain folder when your first change in that area needs one.

# After your first change is archived, specs accumulate naturally:
openspec list --specs
Enter fullscreen mode Exit fullscreen mode

This structure remains stable even as implementation evolves.

Document the System as It Exists — One Change at a Time

Resist the urge to back-fill everything. Writing specs for code you aren't changing feels productive and usually isn't. Those specs go stale because nothing forces them to track reality.

The key insight: you write specs only for what you're about to change. Your first change documents the slice it touches, the next change documents its slice, and over months your specs fill in naturally around the work you actually do.

Here's how a real first change works:

You: /opsx:propose add-api-rate-limiting
Enter fullscreen mode Exit fullscreen mode

OpenSpec creates the change directory with planning artifacts:

openspec/changes/add-api-rate-limiting/
├── .openspec.yaml          # Change metadata
├── proposal.md             # What and why
├── specs/                  # Delta specs (what changes)
├── design.md               # Technical approach
└── tasks.md                # Implementation steps
Enter fullscreen mode Exit fullscreen mode

Then implement and archive:

You: /opsx:apply

AI: [implements the rate limiting]

You: /opsx:archive
AI:  Archiving add-api-rate-limiting...
     ✓ Merged specs into openspec/specs/api/rate-limiting/spec.md
     ✓ Moved to openspec/changes/archive/2026-07-08-add-api-rate-limiting/
     Done. Ready for the next change.
Enter fullscreen mode Exit fullscreen mode

Your openspec/specs/ directory doesn't start full and complete. It starts nearly empty and accumulates. Each archived change merges its delta in. The spec becomes thorough only after you've made several changes in that area — which is exactly when you want it thorough.

If placing an order currently reserves inventory, captures payment, generates an invoice, and sends an email, document exactly that sequence. Future improvements belong in future specifications. Accuracy is more valuable than aspiration.

Turn Existing APIs Into Specifications

Every API endpoint already defines a contract. Extract that contract into a structured specification.

Start a change that captures one endpoint:

You: /opsx:propose document-checkout-api
Enter fullscreen mode Exit fullscreen mode

In the delta spec, capture:

  • Endpoint
  • Inputs
  • Validation rules
  • Business behavior
  • Responses
  • Error conditions

The implementation already contains this information. The goal is simply to make it explicit and discoverable.

Surface Business Rules

Business rules are often scattered throughout the codebase: service classes, validation logic, authorization policies, helper methods, database triggers.

Collect them into a single source of truth using the delta spec format. Examples:

  • Orders above a certain value require approval.
  • Administrators may bypass approval.
  • Refunds are only allowed before settlement.
  • Inactive users cannot create new orders.

These rules define how the business operates. They deserve to be documented independently of implementation.

When you archive the change, the rules merge into the domain spec and stay there.

Map the Domain Model

Specifications should describe the business entities that matter. For each entity, capture:

  • Fields
  • Relationships
  • Lifecycle
  • Immutable attributes
  • Derived values
  • Calculated fields

This creates a shared understanding of the data model without requiring engineers to reverse-engineer the database.

Capture Workflows and Events

Modern systems are driven by workflows and events. Document the flow from one business event to the next.

For example:

  1. Order created
  2. Inventory reserved
  3. Payment requested
  4. Payment confirmed
  5. Invoice generated
  6. Customer notified

These workflows often span multiple services and repositories. Making them explicit improves onboarding, debugging, and future refactoring.

Inventory External Dependencies

Every production system relies on external services. Document each dependency along with:

  • Purpose
  • Authentication method
  • Retry strategy
  • Failure behavior
  • Rate limits
  • Fallback process

This information becomes invaluable during incidents and reduces operational risk as the system grows.

Prioritize High-Value Domains

Don't attempt to specify the entire platform in one sprint. Start with the areas that carry the greatest business value.

A typical priority order:

  1. Authentication
  2. Payments
  3. Orders
  4. Billing
  5. Notifications
  6. Reporting

Early wins build momentum while delivering immediate operational benefits.

Validate Before You Ship

OpenSpec validates your changes and specs for structural issues. Use this before every archive:

# Validate a specific change
openspec validate add-api-rate-limiting

# Validate everything — useful before CI or a release
openspec validate --all --strict

# JSON output for scripts
openspec validate --all --json
Enter fullscreen mode Exit fullscreen mode

Example output:

Validating add-api-rate-limiting...
  ✓ proposal.md valid
  ✓ specs/api/spec.md valid
  ✓ design.md valid
  ✓ tasks.md valid

0 warnings, 0 errors
Enter fullscreen mode Exit fullscreen mode

Validation catches structural problems before the AI writes code or before you merge. Make it a habit.

Check Health Across References

If your project references external stores (standalone OpenSpec repos), use doctor to verify everything is connected:

openspec doctor
Enter fullscreen mode Exit fullscreen mode

Output:

Root health:          ✓ healthy
Store "team-context": ✓ registered, remote matches origin
References:           ✓ 1/1 resolved
Enter fullscreen mode Exit fullscreen mode

When a store isn't available locally, doctor tells you exactly how to fix it — typically a git clone and openspec store register command.

Track Progress With Status

Check where a change stands in the artifact pipeline:

# Interactive selection
openspec status

# Specific change
openspec status --change add-api-rate-limiting

# JSON for agent use
openspec status --change add-api-rate-limiting --json
Enter fullscreen mode Exit fullscreen mode

Output:

Change: add-api-rate-limiting
Schema: spec-driven
Progress: 3/4 artifacts complete

[x] proposal
[x] specs
[ ] design
[-] tasks (blocked by: design)
Enter fullscreen mode Exit fullscreen mode

This is especially useful mid-sprint when you have multiple changes in flight.

Browse What Exists 

# List active changes
openspec list

# List specs by domain
openspec list --specs

# Interactive dashboard
openspec view

# Show a specific change or spec
openspec show add-api-rate-limiting
openspec show auth --type spec
Enter fullscreen mode Exit fullscreen mode

Keep Specifications Close to the Code

Specifications should live alongside the implementation they describe. Keeping documentation within each domain makes updates part of normal development instead of a separate maintenance task.

When specifications travel with the code, they're far more likely to remain accurate over time.

Make Specifications Part of Every Pull Request

Specifications shouldn't be written once and forgotten. Instead, make them part of the development workflow:

  1. Update the specification (via /opsx:propose).
  2. Implement the change (via /opsx:apply).
  3. Run validation (openspec validate).
  4. Review both specification and code together.

Treating specifications as part of the definition of done keeps documentation synchronized with production.

Generate Better Tests

Every documented workflow naturally becomes a set of test cases. A simple "Cancel Order" workflow expands into scenarios:

  • Customer cancels their own order
  • Administrator cancels an order
  • Order already shipped
  • Order already cancelled
  • Payment pending
  • Refund already processed

Using specifications to drive testing increases coverage while ensuring tests reflect business behavior rather than implementation details.

Give AI Context Instead of Source Code

Large codebases overwhelm both people and AI. Instead of exposing hundreds of thousands of lines of implementation, provide structured specifications for the relevant domains.

AI gains access to:

  • Business terminology
  • System boundaries
  • Workflows
  • Constraints
  • Business rules

The result is more accurate code generation, better architectural suggestions, and fewer hallucinations caused by missing context.

After archiving changes, openspec instructions surfaces the relevant spec index to your AI assistant, so it can reference existing behavior when proposing new changes.

Update After CLI Upgrades

When you upgrade the OpenSpec CLI, regenerate your project's instruction files:

npm update @fission-ai/openspec
openspec update
Enter fullscreen mode Exit fullscreen mode

This re-generates tool configurations using your current profile and workflows. Skip this step and your AI assistant's slash commands may drift out of sync with the CLI version.

Adopt Incrementally

Successful OpenSpec adoption doesn't require a migration project. Instead, improve the specification whenever a feature is touched.

The workflow becomes:

/opsx:explore       # understand the area
/opsx:propose       # create the change
/opsx:apply         # implement
openspec validate   # verify structure
/opsx:archive       # merge into living specs
Enter fullscreen mode Exit fullscreen mode

Over time, undocumented legacy systems become well-defined, verifiable, and significantly easier to evolve — without interrupting product delivery.

Immediate ROI

Teams typically see value long before the migration is complete. Within the first few weeks:

  • A shared architectural map
  • Searchable business rules
  • Clear API contracts
  • Documented workflows
  • Improved onboarding
  • Better AI-assisted development
  • More reliable regression testing
  • Faster incident response through documented dependencies

Each improvement compounds as more of the system becomes specified.

Common Pitfalls

The most common mistakes:

  • Documenting the desired architecture instead of production behavior. Specs describe what ships today, not what you plan to build.
  • Attempting to specify the entire platform before shipping. Let real changes drive your specs. One change at a time.
  • Organizing specifications around technical layers instead of business domains. Specs under auth/, payments/, orders/ stay meaningful. Specs under controllers/, models/ mirror code structure, not business structure.
  • Storing documentation in a separate repository. Specs belong alongside the code they describe. Commit openspec/ to git.
  • Refactoring implementation before accurately documenting existing behavior. Document first, then refactor. Otherwise you're specifying aspirational behavior that doesn't match production.

A 30-Day Rollout Plan

Week 1: Install OpenSpec, run openspec init, audit the system, identify business domains, and inventory dependencies.

openspec init
openspec doctor
Enter fullscreen mode Exit fullscreen mode

Week 2: Use /opsx:explore and /opsx:propose to fully specify the highest-value domain, including APIs, models, workflows, and business rules. Validate and archive each change.

Week 3: Make specification updates part of every pull request and code review. Use openspec validate --all --strict in CI.

Week 4: Expand into adjacent domains while generating tests from the documented workflows.

By the end of the month, the team has a living specification, better onboarding materials, stronger regression coverage, and AI-ready documentation — all achieved without pausing product development.

Ship the System You Have

Retrofitting OpenSpec isn't about replacing your architecture. It's about making your current architecture understandable, verifiable, and easier to evolve.

openspec init           # start
/opsx:propose           # one change at a time
openspec validate       # verify before you ship
/opsx:archive           # accumulate living specs
Enter fullscreen mode Exit fullscreen mode

The result isn't just better documentation. It's a development workflow where architecture, implementation, testing, and AI assistance all operate from the same source of truth.

Top comments (0)