BMAD, spec-kit, and OpenSpec: three spec-driven paths for AI-assisted development

Vague prompts still produce vague code, even with strong models. That insight is not new, but the response from the open source community is new. Three high-visibility projects ask you to slow down before you type “implement it.” They push structured specs, explicit phases, and stronger context for coding agents. This article compares BMAD-METHOD, GitHub spec-kit, and OpenSpec in plain terms. The goal is not to pick a “winner” for every team. The goal is to know what you are buying, what each one optimizes, and when to leave it on the shelf.

The shared bet

All three share one belief. A single chat thread with a general instruction is a weak project boundary. A shared artifact that says what “done” means is a stronger one. The disagreement is in how that belief becomes practice. BMAD leans on roles and agile ceremony. spec-kit leans on a gated, repo-local workflow that is close to a mini SDLC. OpenSpec leans on change-sized specs and diffs so work stays scoped. None of them replaces tests, code review, or a production mindset. They sit above them, as process glue.

BMAD-METHOD: many hats, one pipeline

BMAD-METHOD (Breakthrough Method for Agile and AI-Driven development) is an open source framework that simulates a multi-role software team. Think analyst, product manager, architect, developer, and more. Work moves through phased planning and execution with help from specialized “agents” in your tool of choice. The stress is on end-to-end flow, not a single “write the function” moment.

What is different about it

• Personas and handoffs are first-class. You are not one anonymous voice in a chat. You are guided through a sequence of roles, each with its own context window in practice, even if the same model underpins them
• Process depth scales with the problem in intent. A small task should not get an enterprise design cycle. A production change still benefits from a trace from intent to story
• Output lives in versioned text (markdown and similar) so the plan can survive the next model upgrade. That is a design choice many teams will recognize from human agile practice.

Where it helps

• Greenfield products and larger features when you need shared clarity across many files and a few humans
• Teams that already like agile ritual and want a structured “who asks what, when” story for LLM work
• Situations where knowledge handoff (from idea to spec to build) is the failure mode, not raw typing speed

Where it is heavy

• Tight fixes in large legacy code with strong tests and a one-line spec may not need a full BMAD run. The overhead is real, so match depth to impact
• Teams allergic to process will fight it unless leaders protect calendar time. This is a culture fit question, not a library import.

GitHub spec-kit: a gated pipeline that lives in the repo

spec-kit is GitHub’s open toolkit for spec-driven development with AI coding tools. The public story is simple. You specify intent, you plan the shape of the solution, you break tasks, then you implement. The CLI and slash-style commands (exact surface depends on version) turn that story into a rhythm your whole team can repeat. It is agent-agnostic in spirit, which matters when your shop uses more than one assistant.

What is different about it

• Phases are explicit gates. The model gets a smaller question at each step. That is the main way it fights ambiguity
• The project frames specs as a form of executable intent: specifications should drive the build, not sit in a wiki graveyard. That does not mean specs run on a CPU. It means they are the main steering input
• The documentation positions the approach for both 0-to-1 work and iterative enhancement of existing systems, not only for net-new code. You should not treat “GitHub’s spec flow equals greenfield only” as a hard rule without reading the current doc.

Where it helps

• New features and medium-sized work where everyone must agree on user journeys and success criteria before code lands
• Teams that want a portable, repo-based method that is easy to show in a PR or design review. Markdown artifacts travel well
• Organizations that already use Claude Code, Copilot, Gemini CLI, and similar, and do not want to bet on a single vendor shell.

Where to be careful

• A thin spec pass can become ritual if no one enforces test evidence or review. The tool does not replace a Definition of Done
• Like every framework here, public academic evidence that ties this exact CLI to defect or cycle time is thin. You still own measurement on your own backlog

OpenSpec: change proposals and deltas for real codebases

OpenSpec from Fission-AI is built around proposals, tasks, and archives in brownfield (existing) systems. A change starts as a proposal that says why and what. Tasks break the work. Deltas describe how requirements or behavior move from today to tomorrow. The aim is to keep the model and humans focused on a slice of the system, not a foggy picture of the whole monolith on every call.

What is different about it

• The mental model is isolation by change set, not “load the world.” That pairs well with the way senior engineers already think about low-risk edits
• It is designed to be portable across many coding agents, with a pattern many teams will use next to a growing AGENTS.md file for machine-readable repo rules
• Slash commands and IDE hooks are part of the story, but the product value is the file layout of intent, not a single UI brand.

Where it helps

• Mature codebases, shared ownership, and frequent, small production changes. Think payments, feature flags, or API contract shifts
• Teams that already use proposals in Git and want a standard shape for them when LLMs are in the loop
• Situations where over-wide context is a risk (wrong file, old module, or stale doc pulled into a long prompt).

Where to be careful

• If the baseline is wrong (no tests, unclear truth of behavior), a sharp proposal can still drive a bad patch. The framework does not discover truth by magic. It only structures the argument
• Very large orgs with dozens of product lines will still need discovery and policy above any single file tree. The OpenSpec repo itself discusses real limits as ecosystems grow, which is honest about scale.

Myths that waste time

Myth 1: “A spec framework removes the need for tests.”

It does not. Specs tell the model and humans what you think you want. Tests tell you what the system actually does. The best use of a spec is to make your tests and your intent line up. If you skip tests, you only moved the failure to production with nicer markdown.

Myth 2: “More agent roles always mean better code.”

Recent system-level work on multi-agent LLM frameworks shows a harsh truth. The same model can look brilliant or broken depending on orchestration, memory, and coordination. Role play can help people think. It is not a guarantee of quality. You still need review and a bar for “good enough to merge.”

Myth 3: “spec-kit is only for greenfield.”

The official spec-kit documentation describes both greenfield and iterative enhancement. Your team’s habit might be greenfield-first. The tool’s stated scope is wider. Judge it on a real modernization task, not on a label you read in a thread.

Myth 4: “OpenSpec means we only ever send a diff to the model.”

Narrow context is a tactic to cut noise and cost. It is not a universal law. Sometimes you need a whole file, a whole package, or a runbook. The skill is to send enough context to be correct and not more than that. That balance changes by task and by model.

Myth 5: “We adopted BMAD, so our governance is done.”

Nope. For regulated or security-sensitive work, you still own threat modeling, access control, audit, and data handling. A process file does not pass an exam for you. It only helps you describe intent in a form your team and your tools can repeat.

When none of these is the right answer (yet)

Sometimes the problem is not process. It is hazard.

• The codebase has no tests, no type checks, and no clear owners. A spec layer will not find ground truth. Fund basics first
• The team is still arguing about whether to use an assistant. Fix the policy, the secret handling, and the client rules before you optimize “how we prompt”
• A single strong engineer with a test harness can ship a fix faster than a five-phase ceremony. Maturity is knowing the difference, not always picking the heaviest tool in the box
• Saying “not now” is a valid technical opinion. It is not laziness. It is scheduling reality

A simple decision path

1. Start with the failure mode you see most. If you miss requirements before code, spec-kit and BMAD planning are natural. If you drown in context and merge wrong code in big repos, lean toward OpenSpec-shaped scoping. If you miss human alignment across many stakeholders, BMAD’s role play can help, even if it is not the fastest path.

2. Size the ritual to the risk. A security-sensitive change deserves tests, review, and perhaps threat modeling, no matter which file names you use. No markdown layer replaces a risk discussion.

3. Pick a pilot before a policy. Run one project with a single framework. Measure lead time, rework, and escaped defects. Public benchmarks on models do not map one-to-one to your “legacy COBOL plus new API” world. You need local numbers.

4. Keep a stable agent contract on disk. Many teams add AGENTS.md (see also openai/agents.md) for build, test, and style rules. That work complements all three. It is not a competitor. It is the floor.

The honest part: evidence and epistemic humility

Research in software engineering and LLM prompting shows a pattern that is easy to misread. Structured, clear prompts and constraints can improve outcomes on well-defined tasks. So can better tool interfaces for agents, as the SWE-bench and agent-system literature repeatedly stresses. Multi-agent setups are not a free pass. New framework-level benchmarks show that architecture can swing latency, accuracy, and success rates by a wide margin, even with the same base model. That is a strong warning against “we turned on more personas, so we are safe.”

This article does not claim a peer-reviewed, randomized trial for BMAD, spec-kit, or OpenSpec on your defect rate. The honest position for thought leadership is this. The mechanisms make sense. The tools are young. The proof is in your own discipline: tests, review, measurement, and adult governance. NIST and related guidance on generative AI and the secure software development lifecycle (for example NIST’s GenAI work and the SSDF community profile for generative AI) is where regulated industries will look when risk matters. Frameworks in this article do not replace that layer.

How this connects to the wider stack

• MCP (Model Context Protocol) is a separate axis. It standardizes how agents call tools and data, which helps govern what a machine can touch
• Research agents (SWE-agent, AutoCodeRover, and similar) optimize autonomous repair. They are not the same as human-in-the-loop spec kits, but they agree on one thing. The environment and tests often matter more than a clever chat opener.

One week in the life (concrete picture)

Picture a team that picks spec-kit for a new service. Monday, they write the user journey and success criteria. Tuesday, they lock the plan and stack. Wednesday, they split tasks and assign owners. Thursday, they implement with an agent and hand-edit the rough edges. Friday, they merge with tests and a short retro on what felt slow. The framework did not remove work. It sequenced it so the model did not improvise in a vacuum on day one.

Picture another team on a brownfield API. They use OpenSpec to say what changes, what stays, and what the client will see. The proposal is small. The review is fast. The model still needs a human to say “this error code is part of our public contract”. The framework kept the debate in a few files instead of a hundred-message thread.

Picture a platform group that uses BMAD-style roles for a large initiative. The PM-shaped pass surfaces scope questions early. The architect-shaped pass catches an integration risk. The dev pass is shorter because the argument already happened. The cost was calendar time up front. The win was fewer three a.m. pages when the edge case finally surfaced in prod.

None of these weeks is automatic success. They are plausible when the team commits to the same ritual and measures the same few numbers after the change.

Key takeaways

• BMAD-METHOD is for teams that want role-based, agile-shaped co-planning with the model. It shines when the problem is alignment and long intent chains. It is heavy for tiny fixes
• GitHub spec-kit is for teams that want a clear, gated spec-to-code rhythm in the repository. It fits many greenfield and modernization stories. Success still depends on tests and honest Definition of Done
• OpenSpec is for teams that live in brownfield code and need proposals, deltas, and scoping so LLMs and humans do not drown in context
• Complement, don’t confuse: AGENTS.md-style files, your CI, your review bar, and your org risk practice sit under any of the three. Pick the spec layer that matches risk and codebase age, then measure
• Stay skeptical of hype and of GitHub star counts as proof. Stars are attention, not a deployment census or a quality certificate

Conclusion

There is no moral prize for the busiest agent workflow. The prize is software that works, that teams can change without fear, and that matches what the business asked for. BMAD, spec-kit, and OpenSpec are three serious attempts to put writing first back in the middle of AI-assisted delivery. None of them absolves you from hard engineering. The right choice is the one that matches your default risk and your codebase age, and that you are willing to measure like any other process bet.

If you try one, try it on one stream of work, with one set of quality gates you already trust. Compare outcomes to your pre-framework baseline. That experiment is more valuable than any blog post, including this one.