spec-driver

the specification-driven development eigentoolkit

An open, opinionated CLI for spec-driven development. Notably, it:

lets markdown files impersonate a relational database
scaffolds spec generation (and maintenance!) for Go, Python and TypeScript projects.
manages a cohesive set of nouns and verbs. Together, they form an adaptable framework for building at sustainable pace with agents.

Stick with the defaults and use everything — or cherry-pick and customise the templates to suit.

Spec-driver is a "variable bureaucracy" framework: work from one line descriptions in a lightweight backlog, up to standalone requirement documents, detailed runsheets, detailed spec revisions, and a full audit trail of verifications tests linked to functional & non-functional requirements.

If you're building something ambitious, the process that got you started will not get you where you're going - and it's a plus if you don't have to declare process bankruptcy three times on the way there.

spec-drivercame about because I was blown away by spec-kit... until I realised it wasn't actually trying to solve the problem I'd assumed it was. You start with specifications, and it's got a great workflow for taking them from idea to implementation — but there's no support for actually keeping them as a source of truth once you're done.

	spec-kit	spec-driver
status	production - robust, excellent agent commands, multiple maintainers, feature complete	beta - expect some rough edges & feature gaps; single maintainer
ideal projects	smaller projects / microservices (language agnostic)	go, python, typescript projects - any size
expected prior experience	new to spec-driven development	prior experience with other tools
key strengths	documentation; strong community adoption; polished onboarding	structured data; evergreen specs; unified CLI for automation
weaknesses	specifications are disposable; works best with modest codebases; no support for legacy adoption	works for me™; rough edges; potential bugs; gaps in documentation & guidance

fig a) Comparing spec-kit and spec-driver

TL'DR- if you haven't tried spec-kit, maybe start there. If you find yourself wanting more, spec-driver might be for you.

The pitch

Stop banging rocks together.

spec-driven development is the only sane way to code with agents
so ... you want to write a spec
but technical design requires understanding the existing code
so ... it's not long until this means a research phase is required for every spec
but that only gives you a local understanding of the code explicitly inspected

If we're to elevate the role of specifications and build a methodology around them being "executable" by agent developers to drive implementation, isn't it a sign of a critical design flaw if those specifications, and the research that informs them, are only accurate at a point in time?

Put another way: if specs are important enough to name a movement after ...

why would we accept disposable specs (and research) when we could, at no greater cost, ensure the specs remain a system of truth about the actual technical design and implementation, and the embodied product requirements?

Maintain verifiably accurate, interlinked, evergreen specifications for your entire project
Product specs for user-motivated features, use cases and requirements
Tech specs for system architecture and implementation guidance
Deterministically generate cheap, concise, accurate documentation for every line of code within the scope of your spec
These generated contracts provide an excellent complement to (and insurance against) the stochastic nature of research & implementation agents.
They're also an extremely concise, token-effecient reference for both agents and humans
Requirements persist and evolve after initial implementation, with a rich lifecycle; verification and audit mechanisms
quickly capture desisions, risks, issues, and problem statements / product hypotheses into your backlog
Prioritise, interrogate, and generate implementation plans from your backlog, or absorb them into specs
Evolutionary governance of your project with ADRs (architecture decision records), policies and standards
Process hooks and tooling support ensure they're considered during design, implementation and verification, and audits give you the confidence to change both the code and the rules.
Markdown + embedded YAML makes a surprisingly powerful platform for structured data, and is highly legible to both human and agent developers
The registry turns markdown files into relational data— establishes relationships, quick lookups and validation, and propagates updates

fig b) a typical workflow: create a delta to bundle some changes; design, plan, implement and verify them; then capture the context with an auto-generated revision, and reflect the changes to specs / requirements

Run the spec-driver sync command to automatically:

stub out new specs for unspecified modules
warn (or
```
--prune
```
when specs are "orphaned" by moved or deleted code
audit contract drift: detect when code changes aren't covered by specs

Design goals

first-class support for legacy codebases
keep agents on track, no matter how large the codebase
a fast, consistent, unified CLI for everything
a great UX for both humans and agents
multiple paths to victory: adapt the framework as your needs change, or to the scale and criticality of the task
be ready to eat right out of the box

Design principles

Begin with correctness (a robust conceptual model ), and then make it comprehensible; don't start with what's easy and then try to make it work correctly. Compare the trajectories of MySQL (it was fast, they tried to make it correct) and PostgreSQL (it was correct, they made it fast).
self-teaching over instruction if we provide tooling which clarifies and reinforces the data model (as with
```
spec-driver schema show
```
and the prompts to use it when creating new files), the agent needs far less documentation and behavioural scaffolding, and can often intuit, and even clarify for you how to use the system appropriately.