Comparison: create-spec-driven-app vs. alternatives#
This document positions create-spec-driven-app honestly against the tools
teams commonly evaluate when adopting Spec-Driven Development or AI-assisted
scaffolding: OpenSpec, GitHub spec-kit, Cursor rules, Aider conventions,
and plain README.md files.
OpenSpec is the closest comparison and the one worth reading first — it is the best current exponent of the change-lifecycle idea, and several things in this tool exist because of it.
Bias disclosure. This is written by the maintainers of
create-spec-driven-app. Where we lose, we say so. We have asked the maintainers of each compared tool for review; their feedback (if received) is referenced in footnotes.
1. At-a-glance matrix#
| Capability | create-spec-driven-app | OpenSpec | GitHub spec-kit | Cursor .cursorrules | Aider CONVENTIONS.md | Plain README.md |
|---|---|---|---|---|---|---|
| Generates an initial repo structure | ✅ | ⚠️ minimal | ✅ | ❌ | ❌ | ❌ |
| Ships with a domain pack format | ✅ (YAML+schema) | ❌ | ⚠️ ad-hoc | ❌ | ❌ | ❌ |
| DDD-lite artefacts (aggregates, contexts, events) | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ |
| Gherkin scenario stubs | ✅ | ⚠️ prose scenarios | ⚠️ via templates | ❌ | ❌ | ❌ |
| Traceability matrix | ✅ rich + legacy | ❌ | ⚠️ basic | ❌ | ❌ | ❌ |
validate CI gate | ✅ shipped GHA | ✅ | ⚠️ external | ❌ | ❌ | ❌ |
| JSON Schema for the DSL | ✅ draft 2020-12 | n/a (plain markdown) | ❌ | ❌ | ❌ | n/a |
| VS Code extension | ⚠️ built, not on the Marketplace | ❌ | ❌ | n/a (own editor) | ❌ | ❌ |
| MCP server | ✅ shipped | ❌ | ❌ | ❌ | ❌ | ❌ |
| Language server (LSP) | ✅ shipped | ❌ | ❌ | n/a (own editor) | ❌ | ❌ |
| Change lifecycle (propose → review → archive) | ✅ shipped | ✅ their idea first | ❌ | ❌ | ❌ | ❌ |
Versioned, installable packs (specops) | ✅ shipped | ❌ | ❌ | ❌ | ❌ | ❌ |
| Cross-platform CLI (Windows/Linux/macOS) | ✅ Node | ✅ Node | ⚠️ Bash-heavy | ✅ | ✅ | ✅ |
| Locked-in to one AI vendor | ❌ | ❌ | ❌ | ✅ Cursor | ❌ | ❌ |
| Discoverable pack registry | ⚠️ generator ships, not yet hosted | n/a | ❌ | ❌ | ❌ | n/a |
| Zero-install (just docs) | ❌ | ❌ | ❌ | ❌ | ❌ | ✅ |
| Agent JSON contract, documented and tested | ✅ generated from source | ✅ hand-written | ❌ | ❌ | ❌ | ❌ |
| Slash commands for agent tools | ✅ 8 tools | ✅ | ❌ | n/a | ❌ | ❌ |
| Configurable artefact graph | ✅ csda schema | ✅ | ❌ | ❌ | ❌ | ❌ |
| Multi-repo spec sharing | ✅ private packs | ⚠️ Stores | ❌ | ❌ | ❌ | ❌ |
| Time to first value | ⚠️ minutes | ✅ minutes | ✅ minutes | ✅ instant | ✅ instant | ✅ instant |
✅ supported · ⚠️ partial / via workaround · ❌ not supported · 🚧 in progress
2. When each tool wins#
create-spec-driven-app wins when…#
- Your team needs explicit traceability between requirements, scenarios, and code (regulated industries, audited deliveries).
- You want a DDD-lite domain model in machine-readable form so AI agents and humans share the same vocabulary.
- You operate multiple environments (dev/feature/prod) and want generated
Docker / devcontainer /
.envscaffolding aligned with the domain. - You want a portable, vendor-neutral workflow that works with Claude, Cursor, Aider, Copilot, or no agent at all.
OpenSpec wins when…#
- You want the change lifecycle and nothing else. OpenSpec is smaller, and smaller is a feature: fewer concepts to teach, less to get wrong.
- Your specs are prose, not a domain model. If aggregates, commands and events would be ceremony for your team, our DDD-lite artefacts are cost without benefit.
- You want plain markdown with no schema. Our
pack.yamlbuys reuse and validation; it also buys a format to learn. - You are starting today and want the shortest path to a working loop.
We took the delta format, the ADDED/MODIFIED/REMOVED grammar and the
idea of an audited agent contract from their design. Where we differ is
deliberate: they optimise for the change loop, we add versioned domain packs
(specops) and a traceability matrix that CI enforces. If you do not need
those two things, their smaller surface is the better tool.
Their contract documents a set of known inconsistencies — snake_case in one command family and camelCase in another. We had the advantage of reading that before writing ours, and picked one. We are not cleverer; we were later.
GitHub spec-kit wins when…#
- You're already deep in the GitHub ecosystem and want first-party tooling with deeper repo integration (issues, PRs, projects).
- You only need lightweight templates without DDD vocabulary.
- You prefer Microsoft/GitHub to govern the spec format directly.
spec-kitis fast-moving; some gaps above will close. Recheck quarterly.
Cursor .cursorrules wins when…#
- Cursor is your only AI coding tool and your team has standardised on it.
- You want rules that bias the model's behaviour without changing the repo layout or tests.
Locks you into Cursor; not portable to other agents or to plain command-line workflows.
Aider CONVENTIONS.md wins when…#
- You work primarily from the terminal with Aider and want a single, human-readable file the agent reads on every prompt.
- Your team is small (1–3 engineers) and the overhead of formal traceability isn't justified.
No structural enforcement — conventions drift over time without CI gates.
Plain README.md wins when…#
- The project is a prototype or research spike that may not survive the quarter.
- You're solo and the cost of any tooling exceeds the cost of forgetting.
Fine for week-1. Doesn't scale past week-12.
3. When create-spec-driven-app loses#
These are the honest trade-offs. We'd rather you choose a different tool than adopt ours and regret it.
| Scenario | What hurts | Recommendation |
|---|---|---|
| Solo developer, 1-week throwaway | Setup overhead exceeds the project lifespan | Use a README.md + Gherkin in a single file |
| Cursor-only team, no portability concern | Our CLI duplicates what .cursorrules already does for them | Stick with Cursor rules |
Already on GitHub spec-kit for 6+ months | Switching cost > marginal feature gap | Wait for spec-kit to add DDD/JSON-Schema; we'll re-publish this page |
| Front-end-only project with no domain logic | DDD vocabulary feels heavy | Use --type frontend (lighter) but consider plain templates |
| Highly conservative shop, no Node.js allowed | We require Node ≥ 22 at runtime | Run the published Docker image, or the Maven / Gradle plugin, which launch the CLI for you |
| You hate YAML | Pack format is YAML | We won't ship JSON/TOML packs in 0.x; revisit in 1.0 |
4. Migration paths#
From OpenSpec → create-spec-driven-app#
The delta format is deliberately the same, so the specs come across as-is.
csda adoptin the repo — it never overwrites an existing file.- Move
openspec/changes/<id>/todocs/specs/changes/<id>/and add achange.yaml(csda change new <id>writes one to copy). - Move
openspec/specs/<capability>/spec.mdtodocs/specs/capabilities/<capability>/spec.md. csda change validate— theADDED/MODIFIED/REMOVEDgrammar is compatible; what it will flag is missing RFC-2119 keywords and scenario steps that are prose rather than- GIVENbullets.- Optionally add
<!-- csda:trace uc=… cmd=… -->comments where you want requirements to reach the traceability matrix. Without them a requirement still archives, with-in those columns.
Do not migrate if what you valued was the smaller surface. Steps 4 and 5 are the tax for the matrix and the CI gate; if you do not want those, you do not want this tool.
From spec-kit → create-spec-driven-app#
- Run
npx create-spec-driven-app init --config your.config --out ./next. - Copy your existing
spec-kitartefacts into the generateddocs/specs/. - Run
validate— it will tell you what's missing in the traceability matrix. - Keep
spec-kitrunning for 1 release cycle as a parallel checker.
From .cursorrules → create-spec-driven-app#
- Generate a project with
csda init. - Move your Cursor rules into
AGENTS.mdandAI_RULES.md(we generate both). - Reference the generated traceability matrix from your rules so Cursor reads them on every prompt.
From plain README.md → create-spec-driven-app#
- Generate a project as above.
- Copy the existing README into
docs/specs/glossary.md. - Run
pack initto scaffold a domain pack from your existing module list.
5. Questions worth asking before you choose#
- Will my team use this in 12 months? — Tools that require discipline die. Tools that have a CI gate survive.
- Does my AI agent of choice exist in 12 months? — Vendor lock-in is expensive when the vendor pivots or shuts down.
- Do I care about audit trails? — If yes, traceability matrix and schema-validated specs are non-negotiable.
- Do I need cross-team consistency? — If yes, a versioned pack format beats prose conventions.
- What's the cost of being wrong? — All four alternatives are reversible in <1 day; choose the one that lets you experiment cheapest.
6. References#
- Case Study 1: Smart Parking brownfield adoption
- OpenSpec (last reviewed 2026-08) — the benchmark that shaped this tool's change lifecycle; the full analysis is in
mejoras/openspec-benchmark-plan.md - GitHub spec-kit (last reviewed 2026-05)
- Cursor
.cursorrulesdocumentation - Aider CONVENTIONS.md guide
Our own column was last verified against the shipped CLI on 2026-08-16. OpenSpec was reviewed 2026-08; the other columns 2026-05. Pull requests with corrections are welcome — see CONTRIBUTING.md.