22 - Spec Driven Development

The landscape of software development is undergoing a rapid, AI-driven transformation.
Competing philosophies — Vibe Coding, AI assisted coding and Spec Coding (or Spec-Driven Development) are emerging.

Vibe-Coding is a new approach to software development that focuses on the emotional and social aspects of coding. Usually no technical background is required.
AI-assisted coding is a more traditional approach to software development, where AI is used to assist developers in writing code. Ask Questions, simple agent usage.
Spec-Driven Development is a new approach to software development that focuses on the technical aspects of coding. It is a more structured approach to software development, where the developer writes a specification for the code they want to write, and then the AI writes the code for them.

Most developers write code first and document later. Spec-driven development inverts this approach.

In traditional development, your code is the source of truth. Writing specs is something you do later (often as an afterthought).

Spec-driven development flips the script. Your spec becomes the source of truth, and you let AI handle the implementation details and write the code. This way, your specifications become executable, thanks to AI coding agents.

There are several tools available to help you with spec-driven development:

BMAD
Spec-Kit
OpenSpec

and some others...

SPARC (Specification, Pseudocode, Architecture, Refinement, Completion) — from the Agentics Foundation community. Most mature of the alternatives. Has tooling for Claude Code, Cursor, and Cline via claude-flow. Multi-agent orchestration with dedicated agents per phase. Decent GitHub presence.
Agent OS (buildermethods.com) — lighter-weight. Focuses on extracting existing coding standards from a codebase and injecting them as context for agents. More about maintaining consistency than full spec authoring. Complements rather than replaces the others.
Pre.dev — mentioned frequently as a spec management layer that sits outside any specific IDE. The spec lives in the repo, agents become interchangeable. Interesting from an architecture perspective — separation of spec authoring from spec execution.
superpowers - https://github.com/obra/superpowers
gsd (get shit done) - https://github.com/gsd-build/get-shit-done https://github.com/punal100/get-stuff-done-for-kilocode

So it is: intent → spec → plan → execution — difference is where the human gate is, how specs are versioned, and how multi-agent orchestration works.

Specs as source of truth

Practically works today:

BMAD — explicitly designed for this. The whole point of its multi-agent pipeline is that specs + architecture docs are comprehensive enough to regenerate. People have demonstrated delete-and-regenerate workflows with it.
Spec-Kit — spec + plan + tasks structure is meant to survive code deletion. The spec is the contract, code is the artifact.
SPARC — same deal. Each phase produces durable markdown artifacts. Code is the last phase output.

Where it breaks down in practice:

You won't get identical code. LLMs are non-deterministic. You'll get functionally equivalent code — different variable names, different implementation choices, maybe different libraries.
The more complex the app, the more your specs need to capture edge cases, integration details, and architectural constraints. Vague specs = drift on regeneration.
Database migrations, external service configs, deployment specifics — these are the things specs often underspecify. The "boring plumbing" is where regeneration fails.
If the original specs were AI-generated (common in these workflows), they may have captured what was built rather than what was intended. Subtle but critical difference.

Spec-Kit

Spec-Kit GitHub

GitHub Spec-Kit: The "Keep It Simple" Option.

Spec-Kit is ideal for developers or small teams who want to improve the quality of AI-generated code by adding more structure; it's straightforward, uses your existing tools, and is backed by GitHub. It works best for small to medium-sized projects or features where you need a clear, structured way to define new functionality without the overhead of a full project management system.

Use Spec-Kit if:

You're building something new from scratch
You want structure but don't want to spend a week learning a framework
You're already using Copilot, Claude Code, or similar tools
You're just one dev or a small team
You've never tried spec-driven dev before and want to ease into it

OpenSpec

OpenSpec GitHub

OpenSpec: The "I Have Legacy Code" Option.

OpenSpec adds a lightweight specification workflow that locks intent before implementation, giving you deterministic, reviewable outputs, and is designed to work with the AI tools you already use through custom slash commands where supported and context rules everywhere else. OpenSpec is purpose-built for brownfield (existing codebases), with its lightweight, change-centric design avoiding the friction of imposing greenfield workflows on legacy code.

Go with OpenSpec if:

You're working with an existing codebase (this is the big one)
You want to move fast without a ton of ceremony
You need good change tracking and versioning
You hate bloated tooling
Your workflow is basically: propose change → implement → done

BMAD

BMAD Github

BMAD: The "I'm Building the Death Star" Option.

BMAD-Method is a comprehensive framework for agentic agile AI-driven development that uses specialized AI agents and personas to transform domains beyond just software development, built on agentic collaboration principles and known as the Breakthrough Method of Agile AI-Driven Development. BMAD is a multi-agent framework that acts like an entire AI development team, representing a very different philosophy from lightweight toolkits.

This is the nuclear option. BMAD doesn't just help you write specs—it simulates an entire development team.

BMAD makes sense if:

You're working on a massive, complex project
You need enterprise-level project management
You're managing multiple repos
You have time to invest in learning it (it's not trivial)
You need it to work across different domains, not just code
Your project is complicated enough that having AI agents debate architecture actually helps

So Which One Should I Pick?

For pioneering greenfield projects, choose between BMAD's deep role-planning and spec-kit's structured rigor: for complex domain logic and early architecture debates, BMAD excels, while for straightforward architecture but strict compliance, spec-kit is safer; for modernizing legacy systems, OpenSpec is purpose-built for brownfield with its lightweight, change-centric design.

	OpenSpec.	Spec-Kit.	BMAD
Setup Time	5 minutes	30 minutes.	"Why did I do this"
Best For.	Existing codebases	New projects	Enterprise stuff
Complexity	Low.	Medium.	High.
Workflow.	2 steps	4 steps.	Multi-agent chaos
Who's in Charge	You	You.	You + AI agents.
Overhead.	Almost none.	Manageable.	Significant

Pick OpenSpec if:

You've got legacy code (this is 90% of us, let's be real)
You want to try this spec-driven thing without committing your life to it
Fast iteration > comprehensive process
You just want it to work

Pick Spec-Kit if:

You're starting something new
You want something GitHub-official that won't disappear
You're cool with a bit more structure
You're new to this whole spec-driven thing
You want good documentation and community support

Pick BMAD if:

Your project is legitimately huge
You need full project management, not just spec management
You have time to learn a complex system
You're tired of coordinating between multiple repos
You work at a place that actually uses words like "comprehensive framework"

OpenSpec

Let's start with the simplest option. OpenSpec is a lightweight, change-centric approach to spec-driven development.

Tree

Openspec github

Needs Node.js >= 20.19.0.

Install with > npm install -g @fission-ai/openspec@latest

Then (ide closed)

cd my-project
openspec init

And follow the instructions.

Now open your IDE and start a chat with Kilo Code and OpenSpec.

Your project rules go to openspec/config.yaml

schema: spec-driven

context: |
  Tech stack
  - ASP.NET Core 10 (MVC + Razor Pages)
  - Entity Framework Core 10 with PostgreSQL
  - ASP.NET Core Identity (authentication/authorization)
  - OpenAI SDK (v2.7.0) for LLM integration
  - CsvHelper for data import/export
  - X.PagedList for pagination
  - Bootstrap (via wwwroot libs)
  
  Code Style
  - Nullable reference types enabled, warnings treated as errors
  - Primary constructors for classes
  - File-scoped namespaces
  - `default!` for required string properties in entities
  - Use ViewModels when the view needs more data than a direct domain entity or `IEnumerable<Entity>` (e.g., Create/Edit views needing `SelectList` for foreign-key dropdowns, or Index views with pagination/filter state). Simple views that only need the entity itself can use the domain entity directly. `ViewBag` and `ViewData` must not be used.

  Architecture Patterns
  - Layered architecture: WebApp → App.BLL → App.DAL.EF → App.Domain
  - Domain entities inherit from `BaseEntity` (provides `Guid Id`)
  - Cascade delete disabled globally; manage relationships explicitly
  - All DateTime values auto-converted to UTC in EF Core
  - Areas support for admin/user separation (Admin area planned)
  
  Entity Framework Core - No Tracking Mode (CRITICAL)
  **DbContext uses `QueryTrackingBehavior.NoTrackingWithIdentityResolution`**
  
  This means entities retrieved from database queries are NOT automatically tracked by the change tracker. When updating existing entities:
  
  ```csharp
  // WRONG - changes will NOT be saved
  var entity = await _context.Entities.FirstOrDefaultAsync(e => e.Id == id);
  entity.Property = newValue;
  await _context.SaveChangesAsync(); // Nothing happens!
  
  // CORRECT - explicitly attach and mark as modified
  var entity = await _context.Entities.FirstOrDefaultAsync(e => e.Id == id);
  entity.Property = newValue;
  _context.Entities.Update(entity); // Required!
  await _context.SaveChangesAsync(); // Changes saved
  ```

  - `Add()` for new entities works as expected
  - `Update()` is REQUIRED for modifying existing entities
  - `Remove()` works for deletes (entity gets attached if needed)
 

Main commands to use:

opsx-new.md description - starts to create new proposal (arcitect mode)
opsx-ff.md - create all proposal documents in one go (continue chat from new)
opsx-apply.md spec-name - implement proposal (start new task in orchestrator mode)
opsx-archive.md spec-name - archive proposal (move to archive folder)`

Specs as source of truth​

Spec-Kit​

OpenSpec​

BMAD​

So Which One Should I Pick?​

OpenSpec​

Specs as source of truth

Spec-Kit

OpenSpec

BMAD

So Which One Should I Pick?

OpenSpec