Spec-Driven Development with OpenSpec: Architecting with Intent

Introduction

AI coding assistants like GitHub Copilot have fundamentally changed how we write software. They are fast, powerful, and increasingly capable—but they come with a critical flaw: they lack consistent alignment with original requirements

Ask for a feature, and you might get something close… but not quite right. Ask again, and the implementation may drift further. Over time, what you get is not your original intent—it’s a sequence of loosely connected guesses.

This phenomenon—often called “vibe coding”—is one of the biggest blockers to reliable AI-assisted development.

Enter Spec-Driven Development (SDD), and more specifically, OpenSpec—a lightweight, open-source framework designed to make AI coding deterministic, auditable, and aligned with human intent.

The Core Problem: Intent Drift in AI Development

Traditional development has a known gap: translating requirements into code.

AI makes this worse in a subtle way:

• Context is ephemeral (chat history fades)
• Instructions are inconsistent
• Assumptions accumulate silently

The result?

Code that reflects conversation history, not original intent

OpenSpec directly addresses this by introducing a persistent, structured specification layer between humans and AI.

What is OpenSpec?

OpenSpec is a spec-driven development framework designed specifically for AI coding assistants.

At its core, it ensures:

• Humans and AI agree before code is written
• Specifications are structured and versioned
• Outputs are deterministic and reviewable

Unlike prompt-driven workflows, OpenSpec introduces a formal development lifecycle driven by specs—not chat.

The OpenSpec Philosophy

“Structure before code. Alignment before execution.”

OpenSpec shifts development from:

• Prompt → Code → Fix → Repeat

to:

• Spec → Align → Implement → Verify

This is a fundamental shift—from reactive coding to intent-driven engineering.

The OpenSpec Workflow (End-to-End)

OpenSpec introduces a clean, artifact-driven workflow.

🔹 Stage 1: Proposal (Define Intent)

Create a structured proposal describing:

• What you’re building
• Why it matters
• Scope and boundaries

openspec proposal create add-user-authentication

This becomes your intent anchor.

🔹 Stage 2: Spec & Design (Define Behavior)

OpenSpec generates structured artifacts:

• proposal.md → intent and scope
• specs/ → precise requirement changes
• design.md → architecture decisions
• tasks.md → step-by-step execution

These artifacts collectively define:

What to build, how it behaves, and how it should be implemented

🔹 Stage 3: Apply (AI Implementation)

/opsx:apply add-user-authentication

The AI:

• Reads tasks.md
• Implements step-by-step
• Updates artifacts if needed

No ambiguity. No drift.

🔹 Stage 4: Archive (Finalize)

/opsx:archive add-user-authentication

• Specs become part of system truth
• Changes are traceable
• Knowledge is preserved

Advanced Workflow: OPSX (Iterative & Flexible)

OpenSpec also introduces an experimental workflow (OPSX) that removes rigid phases:

proposal → specs → design → tasks → implement
   ↑         ↑        ↑              ↓
   └─────────┴────────┴──────────────┘

This allows:

• Iterative refinement
• Mid-cycle adjustments
• Continuous spec evolution (GitHub)

Real Example: Building a Feature with OpenSpec

Step 1: Define the Proposal

# Add User Profile API
Goal:
Allow users to retrieve profile details
Scope:
- API endpoint
- Validation
- Error handling

Step 2: Define Spec Changes

## ADDED Requirements
### Get User Profile
- Input: user_id (UUID)
- Output: name, email
#### Scenario:
- If user exists → return profile
- If not → return 404

Step 3: Tasks

- Create FastAPI endpoint
- Add validation
- Implement DB lookup
- Add error handling

Step 4: AI Implementation via Copilot

Using GitHub Copilot, the AI now:

• Works from structured intent
• Avoids hallucinated assumptions
• Produces consistent output

Why OpenSpec + Copilot is Powerful

✅ Deterministic Development

Specs eliminate ambiguity → AI produces predictable code

✅ Persistent Context

No reliance on chat history

✅ Auditability

Every change is tracked and reviewable

✅ Tool-Agnostic

Works with:

• Copilot
• Cursor
• Claude Code
• Others

Architectural Perspective:

Intent Layer (Specs)
        ↓
AI Execution Layer
        ↓
Code Layer
        ↓
Validation Layer

This enables:

• Contract-first APIs
• Spec-driven microservices
• AI-governed CI/CD pipelines

Benefits of Spec-Driven Development with OpenSpec

🚀 Engineering Productivity

• Faster feature delivery
• Reduced back-and-forth
• Cleaner implementations

💰 Business Impact

• Better requirement alignment
• Reduced rework cost
• Faster time-to-market

🧠 AI Optimization

• Higher-quality prompts
• Less hallucination
• Better reproducibility

Challenges and Considerations

⚠️ Requires Discipline –

Specs must be well-written and maintained

⚠️ Learning Curve

Teams must adapt to a spec-first mindset

⚠️ Overhead for Small Changes

Not all tasks need full spec workflow

Best Practices for Using OpenSpec

• Treat specs as source of truth
• Keep specs modular and minimal
• Use tasks.md for execution clarity
• Always review before /apply
• Version specs alongside code

The Future: From Code-Driven to Spec-Driven Engineering

We are witnessing a shift:

• From writing code → defining intent
• From debugging logic → validating specs
• From manual implementation → AI execution

Tools like OpenSpec are early signals of this transformation.

In the future, developers won’t just write code—they will design systems through specifications.

Getting Started with OpenSpec in Local Development

One of the biggest advantages of OpenSpec is that it integrates naturally into a modern local development workflow. Developers can use it directly from their IDE while collaborating with AI coding assistants like GitHub Copilot.

This section walks through setting up OpenSpec locally using Visual Studio Code.

Local Setup: Installing and Using OpenSpec in VS Code

1. Prerequisites
   

   • Node.js (v20.19.0+ recommended)
   • Visual Studio Code
   • Access to:
     

     • GitHub Copilot or
     • Cursor / Claude Code compatible environments

   • Git (Optional)

2. Install Openspec globally
   

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

3. Then navigate to your project directory and initialize
   

   • cd your-project
   • openspec init
     

     • 

4. Open Project in Vs Code
5. At this point VS Code becomes your primary workspace for
   

   • Writing proposals
   • Defining specs
   • Generating tasks
   • Applying AI-assisted implementation

6. Now tell your AI: /opsx:propose <what-you-want-to-build>
7. Initialize Your First Spec
   

   • Create Proposal
     

     • /opsx:propose implement-users-crud-app {provide proposal intent, what you want to build}
     • this will generates
       

       • changes/
       • └── implement-users-crud-app/
       • ├── proposal.md
       • ├── design.md
       • ├── tasks.md
       • └── specs/

   • Apply Changes
     

     • /opsx:apply implement-users-crud-app

   • Archive Changes
     

     • /opsx:archive implement-users-crud-app

Conclusion

AI has made software development faster—but not necessarily more reliable.

Spec-Driven Development, powered by OpenSpec, fixes that by introducing:

• Structure
• Alignment
• Determinism

When combined with tools like GitHub Copilot, it transforms development into a predictable, scalable, and intent-driven process.

🚀 Final Thought

If Agile changed how we build
and DevOps changed how we deliver

then Spec-Driven Development—powered by OpenSpec—will redefine
how we think, design, and create software in the AI era.

Author’s Note:
If you’re already using AI for coding, the next leap isn’t better prompts—it’s better specifications. Start there, and everything else becomes easier.