DEV Community: Mike Buyco

Retrofitting OpenSpec Into Existing Projects: A Practical Playbook

Mike Buyco — Wed, 08 Jul 2026 03:35:57 +0000

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

Then initialize in your existing repo:

cd your-existing-project
openspec init

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

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)

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.

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/

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

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

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

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.

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

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:

Order created
Inventory reserved
Payment requested
Payment confirmed
Invoice generated
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:

Authentication
Payments
Orders
Billing
Notifications
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

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

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

Output:

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

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

Output:

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

[x] proposal
[x] specs
[ ] design
[-] tasks (blocked by: design)

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

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:

Update the specification (via /opsx:propose).
Implement the change (via /opsx:apply).
Run validation (openspec validate).
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

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

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

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

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.

Using Claude Code with OpenRouter via `claude-code-router` on Linux

Mike Buyco — Mon, 29 Jun 2026 08:13:52 +0000

Introduction

Claude Code is Anthropic's powerful command-line coding assistant that brings AI directly into your terminal, while OpenRouter is an API aggregator that provides access to multiple AI models through a unified interface. The claude-code-router package bridges these two tools, allowing you to route Claude Code requests through OpenRouter instead of Anthropic's direct API.

This guide covers installation and configuration on Linux systems only.

Prerequisites

Before beginning, ensure your system meets these requirements:

System Requirements

OS: Any modern Linux distribution (Ubuntu 20.04+, Debian 11+, Fedora 36+, Arch Linux, etc.)
Node.js: Version 18.0.0 or higher
npm: Version 8.0.0 or higher
Git: For cloning repositories if needed

Verify Your Setup

# Check Node.js version
node --version

# Check npm version
npm --version

# Check Git version
git --version

If Node.js is not installed or outdated, install it using your distribution's package manager or NodeSource:

# Ubuntu/Debian - Using NodeSource
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt-get install -y nodejs

# Fedora
sudo dnf install nodejs npm

# Arch Linux
sudo pacman -S nodejs npm

Obtaining an OpenRouter API Key

Navigate to openrouter.ai
Create an account or sign in
Go to Keys in your account dashboard
Click Create Key
Copy the generated API key and store it securely

Installing `claude-code-router`

The claude-code-router package should be installed globally alongside Anthropic's official CLI tool.

npm install -g claude-code-router @anthropic-ai/claude-code

Configuration

Method 1: Environment Variables

Create or edit your shell configuration file:

# For Bash
nano ~/.bashrc

# For Zsh
nano ~/.zshrc

Add the following lines:

# Claude Code Router Configuration
export OPENROUTER_API_KEY="your-openrouter-api-key-here"
export CLAUDE_CODE_ROUTER_MODEL="anthropic/claude-3.7-sonnet"

Apply the changes:

# For Bash
source ~/.bashrc

# For Zsh
source ~/.zshrc

Method 2: Configuration File

Alternatively, create a configuration file in your home directory:

mkdir -p ~/.claude-code-router
nano ~/.claude-code-router/config.json

Add your configuration (updated with the correct Claude 3.7 model string):

{
  "apiKey": "your-openrouter-api-key-here",
  "model": "anthropic/claude-3.7-sonnet",
  "baseUrl": "https://openrouter.ai/api/v1",
  "maxTokens": 8192,
  "temperature": 0.7
}

Secure Your API Key

If you prefer using an environment file over a JSON config, ensure you lock down the file permissions so other users on the Linux system cannot read your API key:

# Create a secure environment file
touch ~/.claude-code-router/.env
chmod 600 ~/.claude-code-router/.env
nano ~/.claude-code-router/.env

Add the key inside the file:

OPENROUTER_API_KEY=sk-or-v1-your-actual-key-here

Token Cost Optimization & Prompt Caching

One of the primary benefits of routing Claude Code through OpenRouter is natively leveraging Prompt Caching to heavily optimize your API costs.

When working in large codebases, Claude Code sends significant contextual data (file structures, previous messages, and active file contents) with every single request. OpenRouter automatically supports Anthropic's prompt caching functionality:

Initial Requests: Standard input token pricing applies as the context is written to the cache.
Subsequent Requests: As long as your prompt prefix remains identical (within the 5-minute cache TTL), you receive up to a 90% discount on cached input tokens.

No extra configuration is required in claude-code-router to enable this feature—OpenRouter handles the upstream caching headers automatically when translating requests to Anthropic's backend.

Usage

Configure Claude Code to point to the local proxy, then initialize the router:

export ANTHROPIC_BASE_URL="http://localhost:8080"
ccr code

Configure LLM Models

If you want to quickly switch models without editing config files manually:

ccr ui

Note: This command redirects to a local web UI to configure your preferred OpenRouter models.

Check OpenRouter's model list for the most current routing options and model strings.

Conclusion

The claude-code-router package provides a seamless way to use Claude Code through OpenRouter on Linux, giving you absolute flexibility in model selection while drastically cutting costs via prompt caching. By following this guide, you now have a secure, system-integrated proxy bridging Claude Code with OpenRouter's API infrastructure.

For additional help, consult the package's documentation on npm or GitHub, and periodically check OpenRouter's documentation for API changes or new model additions.

Building a Lua docker environment

Mike Buyco — Sat, 30 Mar 2024 08:48:14 +0000

Intro

I have a keen interest in containerization, a practice that has significantly streamlined my development workflow. Reflecting on my early days in programming around 2011-2012, I recall encountering a common issue when setting up local development environments. Specifically, during the installation of WAMP, I faced an error indicating that port 3306 (MySQL) was already in use. Upon investigation, I discovered that a previous installation of MySQL for a school project was the culprit, highlighting the challenges of managing dependencies and conflicting software configurations.

Motivation

Currently, I am embarking on a journey to learn Lua scripting to complement my son's endeavors in 3D modeling within the Roblox platform. This motivation stems from a desire to actively engage and support his interests, although finding the time amidst other responsibilities remains a challenge. Nevertheless, I am enthusiastic about delving into Lua scripting to enhance our collaborative projects.

Installation

To facilitate my exploration of Lua, I adopt a pragmatic approach by leveraging containerization with Docker to create a dedicated development environment. This method ensures isolation from existing system dependencies and simplifies setup and management.

First, let's build the project structure:

mkdir ~/learn-lua
cd ~/learn-lua

Then, create a Dockerfile and our main.lua script:

touch Dockerfile
touch main.lua

Dockerfile:

# Use a base image with Lua installed
FROM alpine:latest

# Install Lua and LuaRocks
RUN apk --update add lua5.3 lua5.3-dev luarocks5.3

# Optionally, you can install additional Lua packages using LuaRocks
# For example, to install LuaSocket:
# RUN luarocks-5.3 install luasocket

# Set the working directory
WORKDIR /app

# Copy your Lua scripts into the container
COPY . .

# Set the command to run your Lua script when the container starts
CMD ["lua5.3", "main.lua"]

main.lua:

print("Hello, Lua!")

Now to run the lua script:

docker build -t game-lua .
docker run -it --rm game-lua

Time to learn more lua! I will update again soon :D

Creating a simple CLI note app using a shell alias

Mike Buyco — Sun, 30 Oct 2022 14:11:33 +0000

Overview

I've been using the terminal for my work as a software engineer for several years now and really love the idea of doing most of my tasks in the terminal. I mainly use vim as my IDE and have spent lots of time configuring it to my work style and to improve my productivity over the years.

Don't get me wrong, I love tools like VSCode (especially the web version) and I started out using text editors like Notepad++ and Sublime Text 2. But when I learned how to use vim and configure it to become a full-fledged IDE for everyday use, I fell in love with it. Back then I was really looking into how I can write code with minimal overhead as possible.

Some might say, I'm an old school kind of guy and I'd happily take it as a compliment!

Enough with the backstory, let's see how we can take note-taking capabilities into the terminal...

Prerequisites

Vim 8+ or Neovim 0.5+
Unix shell

Creating an alias

If you're using bash, add this line to your .bashrc file:

# Quickly create a note file for today
NOTES_FILENAME="notes-$(date +%Y%m%d).txt"
alias notes="mkdir ~/notes &> /dev/null; touch ~/notes/$NOTES_FILENAME; cd ~/notes; vim ~/notes/$NOTES_FILENAME"

Let's explain the script above...

First off, we create a NOTES_FILENAME variable with the current date formatted into the filename. So for example, today is October 10, 2022, then the file notes-20221010.txt would be created.

Second, we pass that variable to the alias notes= declaration. To learn more about aliases, check out this article.

The alias notes= declaration is like a shortcut for a shell command. So instead of running the actual commands, you save it into a command named notes. In this case, this command does 4 things:

It creates a folder named notes, into the current user's home directory (~/notes)
It creates a file with the name based on the NOTES_FILENAME variable we created earlier.
It cds into the ~/notes directory.
Runs the vim text editor for the file we created.

Notes environment

Now we can access our notes by just running the notes command in the terminal.

If you have configured vim to have a fuzzy search for project files or live grepping action, you should be able to search through your notes. And given the date format we mentioned earlier, you can search by file for a specific date. Simple enough yeah? LGTM!

Conclusion

The steps we did above is a very simple example of how we can quickly create notes in the terminal and focus on writing what's on our mind fast without leaving the terminal. If you're like me and you mostly work on the terminal and use vim as your text editor, this is a very handy tool, simple and practical.

Let me know your thoughts about this. Cheers!

DEV Community: Mike Buyco

Retrofitting OpenSpec Into Existing Projects: A Practical Playbook

Install and Initialize

Start With an Architecture Audit

Organize Around Business Domains

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

Turn Existing APIs Into Specifications

Surface Business Rules

Map the Domain Model

Capture Workflows and Events

Inventory External Dependencies

Prioritize High-Value Domains

Validate Before You Ship

Check Health Across References

Track Progress With Status

Browse What Exists

Keep Specifications Close to the Code

Make Specifications Part of Every Pull Request

Generate Better Tests

Give AI Context Instead of Source Code

Update After CLI Upgrades

Adopt Incrementally

Immediate ROI

Common Pitfalls

A 30-Day Rollout Plan

Ship the System You Have

Using Claude Code with OpenRouter via `claude-code-router` on Linux

Introduction

Prerequisites

System Requirements

Verify Your Setup

Obtaining an OpenRouter API Key

Installing claude-code-router

Configuration

Method 1: Environment Variables

Method 2: Configuration File

Secure Your API Key

Token Cost Optimization & Prompt Caching

Usage

Configure LLM Models

Conclusion

Building a Lua docker environment

Intro

Motivation

Installation

Creating a simple CLI note app using a shell alias

Overview

Prerequisites

Creating an alias

Notes environment

Conclusion

Installing `claude-code-router`