Spec-Driven Development

Spec-Driven Development with OpenSpec and the BMAD Method

OpenSpec makes every change to an existing system start with a reviewable proposal. BMAD gives you a full team of AI agents for planning bigger initiatives. Here's how each works, and how we combine them.

Most companies aren't building new systems from scratch. They're changing systems that already exist, often with large codebases and complicated business rules. Two open-source frameworks help here in different ways. OpenSpec makes every change start with a short, reviewable spec. The BMAD Method gives you a structured team of AI agents to plan bigger pieces of work. Used together, they cover everything from roadmap to pull request.

Two tools, two problems

OpenSpec

“How do I make sure my AI assistant changes exactly what we agreed in this codebase?” It is lightweight and change-centred, and works well on existing code.

BMAD Method

“How do I plan a big initiative properly before anyone codes?” It provides agent roles, workflows and documents for analysis, planning, architecture and delivery.

OpenSpec: change-driven specs

OpenSpec, from Fission AI, is a free, MIT-licensed CLI. It keeps two things in your repository:

  • openspec/specs/: the current truth, describing how the system behaves today, organised by capability.
  • openspec/changes/<change-name>/: proposed changes, each with a proposal.md (why and what), design.md (technical approach), tasks.md (checklist) and delta specs marking requirements as ADDED, MODIFIED or REMOVED.

When a change ships, you archive it: its deltas are merged into openspec/specs/ and the change folder moves to an archive. The specs always describe the system as it is now, and the history of every change is kept.

OpenSpec in practice

Install it once (Node.js 20.19 or later) and initialise each project. The openspec commands run in your terminal. The /opsx: commands run in your AI assistant's chat.

# terminal
npm install -g @fission-ai/openspec@latest
cd md-hrms
openspec init            # pick your AI tools (Claude Code, Cursor, Copilot …)

# AI chat
/opsx:explore            # optional: think the idea through first
/opsx:propose add-payslip-assistant
/opsx:apply              # implement, ticking off tasks.md
/opsx:archive            # merge delta specs into openspec/specs/

Useful terminal commands include openspec list (active changes), openspec validate <change> and openspec view (an interactive dashboard).

Example delta spec

Say we're adding an AI payslip assistant to an existing HRMS. The proposal includes a delta spec like this:

## ADDED Requirements

### Requirement: Payslip questions
The system SHALL let an employee ask questions about their own payslip
in natural language and answer only from that employee's payroll data.

#### Scenario: Employee asks about a deduction
- **WHEN** an employee asks "Why is my PF deduction higher this month?"
- **THEN** the assistant explains the change using that month's salary structure
- **AND** cites the payslip lines it used

#### Scenario: Employee asks about a colleague
- **WHEN** an employee asks about another employee's salary
- **THEN** the assistant refuses and logs the attempt

Reviewers approve the behaviour before any code exists. Then /opsx:apply implements it.

Upgrading from an older OpenSpec? Version 1.0 replaced the old /openspec:proposal, /openspec:apply and /openspec:archive commands with the /opsx: family. Re-run openspec init to refresh the commands.

BMAD: an AI agile team

The BMAD Method (Breakthrough Method for Agile AI-Driven Development) is an MIT-licensed framework from BMad Code. Instead of one general-purpose assistant, it gives you specialised agents, each with a clear role and a defined set of workflows:

AgentResponsibilityTypical output
AnalystBrainstorming, market and domain researchProject brief
Product ManagerRequirements and scopePRD (product requirements document)
UX DesignerUser journeys and UI specificationUX spec
ArchitectSystem design and technical decisionsArchitecture document
Scrum MasterTurn the plan into epics and context-rich storiesStory files
DeveloperImplement one story at a timeCode + tests
Test Architect / QATest strategy, risk and quality gatesTest plans, reviews

BMAD works in phases (analysis, planning, solutioning, implementation) and scales the amount of planning to the size of the work. A small fix can take a quick path, while a new product gets the full set of documents.

BMAD in practice

# installs agents and workflows into your project (Node.js 20+)
npx bmad-method install

# then, inside your AI IDE (Claude Code, Cursor, …)
/bmad-help    # BMad-Help tells you which workflow to run next

A typical greenfield run: the Analyst produces a brief, then the PM writes the PRD, the Architect designs the system, and the Scrum Master creates stories that carry all the context a Developer agent needs. Each story is implemented and reviewed in turn. The documents live in your repository, so the team and the agents share the same source of truth.

Using OpenSpec and BMAD together

The two tools work at different levels, so they combine well:

  1. Plan the initiative with BMADAnalyst → PM → Architect produce the brief, PRD and architecture for, say, “AI features for MD HRMS”.
  2. Slice into changesThe Scrum Master's epics and stories become a list of OpenSpec changes (add-payslip-assistant, add-leave-forecast…).
  3. Specify each change with OpenSpec/opsx:propose captures the exact behaviour as delta specs, using the BMAD documents as context.
  4. Build and review/opsx:apply implements, engineers review the pull request, and QA checks it against the scenarios.
  5. Archive/opsx:archive updates the living specs, so the next change starts from accurate documentation.

BMAD keeps the big picture coherent, and OpenSpec keeps each change precise and traceable.

Spec-Kit vs OpenSpec vs BMAD

Spec-KitOpenSpecBMAD Method
Best forNew features and greenfield modulesChanges to existing (brownfield) systemsPlanning large initiatives end to end
Core flowconstitution → specify → plan → tasks → implementexplore → propose → apply → archiveanalysis → planning → solutioning → implementation
Main artefactsspec.md, plan.md, tasks.md per featureLiving specs + per-change proposals with deltasBrief, PRD, architecture, epics and stories
WeightMediumLightHeavier, but scales to the work
Installuv tool install specify-cli …npm i -g @fission-ai/openspecnpx bmad-method install

Read our Spec-Kit guide for a closer look at the first option.

How we use them at MD Technosoft

For new products we usually start with BMAD planning and Spec-Kit features. For existing client systems, such as HRMS, e-commerce or portals that have been in production for years, OpenSpec is our default, because each change is small, reviewable and easy to roll back. Both fit into our wider AI-DLC workflow and are run by engineers who can join your team as Forward Deployed Engineers.

  • OpenSpec
  • BMAD Method
  • Brownfield
  • AI Agents

Sources & further reading

Bring spec-driven, AI-assisted delivery to your team

We can run a pilot Bolt with your team, or embed Forward Deployed Engineers who already work this way.