create-spec-driven-app v0.7.0

Zero runtime dependencies Any agent CLI MIT

Specifications that are
checked, not admired.

Requirements, Gherkin scenarios and a traceability matrix that your CI enforces — plus a harness that drives any coding agent through them, one requirement at a time, in its own git worktree. It never merges. 

npx create-spec-driven-app@latest init

Get started Read the docs Worked example →

11
curated domain packs
24
commands, all JSON-capable
10
agent tools wired from one definition
0
runtime dependencies

A specification nobody checks is a wish

Most teams already write requirements. They live in a wiki, drift from the code within a sprint, and nothing fails when they disagree. Point a coding agent at that and you have automated the drift.

This tool makes the specification a thing that can be wrong: every requirement has a scenario, every scenario has a file, and csda validate fails when the link is broken. Then — and only then — an agent is worth pointing at it.

The loop

Four commands. The same four whether a person or an agent is driving.

  1. 1

    csda init

    Scaffold a project: spec, scenarios, traceability matrix, and the execution contract an agent reads before it writes a line.

  2. 2

    csda plan

    What still needs a test, an implementation or a status change — ordered by dependency, with a fix on every blocker.

  3. 3

    csda harness run

    Hand one requirement to an agent in its own worktree, gate the result, and stop if the gate says no.

  4. 4

    csda validate

    The gate itself: structure, traceability, Gherkin that Cucumber can actually run, and TDD order. This is what CI runs.

Bring your own agent

No agent runtime, no SDK dependency. The agent is any shell command containing {prompt_file} — the harness writes the prompt, substitutes the path, and reads the exit code plus the gate result. 

csda harness run --agent "claude -p < {prompt_file}"
csda harness run --agent "aider --yes --message-file {prompt_file}"
csda harness run --agent "./my-wrapper.sh {prompt_file}"   # anything else

Commit the commands your team uses in .harness/profiles.yaml and pick one by name — or let a profile select itself per requirement, so an infrastructure task and a domain task get different tools and different allowances in the same run.

Wired from one definition: claudecursorcopilotwindsurfaidergeminiclinecodexantigravity

Choosing your agent → How the harness works → Wiring agent tools →

What the gate actually checks

Every item here exists because the loop was caught approving work it had not checked. They are not features; they are scars.

The scenario can fail

Gherkin keywords are case-sensitive, so GIVEN is prose and the scenario runs zero steps — and passes. The gate refuses a scenario Cucumber would see as empty.

The scenario actually ran

A filter that matches nothing exits 0. When the runner is Cucumber, the gate reads its message protocol instead of its exit code.

The agent did not edit the contract

An agent that cannot pass a scenario can relax the scenario. Touching spec.md, features/** or the rules fails the attempt, with the diff fed back.

The diff touched what was promised

The matrix names a test and a production artifact. A green diff that never goes near them is reported, and fails under --strict-artifacts.

The requirement was worth attempting

No feature file, unmet dependencies, or a status of Needs Clarification — checked before an agent is paid for, not after.

The run has a ceiling

--budget-seconds and --max-requirements. Running out is not an error: the run stops cleanly and still reports what it did.

Questions people actually ask

Do I have to use DDD, hexagonal architecture and CQRS?

No. Patterns are optional; principles are not (ADR-0022). Pick an architecture profile and you get only the vocabulary it declares — a static site is not handed six documents describing aggregates it does not have.

Does it work on a repository that already exists?

Yes — csda adopt installs the specification layer without touching your code. Checks that a legacy repository cannot pass yet are flags, and csda doctor reports them as advisories with a fix, so adoption is a door rather than a wall.

Which AI agent does it need?

None in particular, and none at all if you do not want one. Every command works by hand. The harness takes any shell command; there is no SDK and no vendor lock.

Will the harness merge things for me?

Never. It produces a branch per requirement and stops. Merging is a judgement, and a tool that merges its own work removes the only place a person was still reviewing it.

What does it cost to run?

Whatever your agent costs — the harness measures wall-clock, because an agent is any shell command and only the agent knows its token spend. A profile may declare a cost hint, and the report multiplies it out and says it is declared rather than measured.

How is this different from OpenSpec or Spec Kit?

Mostly in what happens after the specification is written. See the comparison, which is honest about where the others are the better choice.

Start with an empty folder

npx create-spec-driven-app@latest init
cd my-spec-driven-app
csda validate .

Getting started I was handed a repo