create-spec-driven-app v0.7.0

Getting started#

Two ways in, depending on whether the code already exists. Both take under an hour and neither requires reading anything else first.

Adopt SDD on an existing repository#

Goal: the brownfield path (L1) — install specs, rules and the traceability matrix on a codebase that already exists, without touching a line of code.

cd your-existing-repo

# Detects the stack from pom.xml / build.gradle / package.json / go.mod
npx create-spec-driven-app@latest adopt

# Passes immediately — the generated baseline REQ-001 anchors the matrix
npx create-spec-driven-app@latest validate .

What adopt writes (and only if the file does not already exist):

FilePurpose
spec.mdRequirement sections; seeded with REQ-001 "existing behaviour is preserved".
AI_RULES.mdAgent/human rulebook with your detected stack and test command.
features/adoption/baseline.featureBaseline Gherkin scenario pinning the adoption invariant.
docs/specs/traceability.mdRich matrix with the baseline row.
docs/specs/adr/README.mdADR index for future decisions.

Override anything the detection got wrong with --var:

npx create-spec-driven-app@latest adopt \
  --var DOMAIN="health information exchange" \
  --var TEST_CMD="./mvnw -B verify"

Then retro-fill real requirements one at a time (recipe 2) and lock the gate in CI (recipes 4–5).

Generate your first project#

Goal: scaffold a new repo with spec.md, AI_RULES.md, docs/specs/, an empty features/ directory, and a traceability matrix.

# 1. Start from the shipped example
cp examples/project.config.example /tmp/acme-energy-hub.config

# 2. Edit /tmp/acme-energy-hub.config — minimum keys:
#   PROJECT_NAME, PROJECT_SLUG, PROJECT_TYPE, DOMAIN, STACK, API_STYLE, TESTING

# 3. Scaffold
npx create-spec-driven-app@latest init \
  --config /tmp/acme-energy-hub.config \
  --out /tmp

# 4. Verify
tree /tmp/acme-energy-hub -L 2

Useful flags:

FlagUse
--dry-runPrint every file that would be written; don't touch disk.
--forceOverwrite a pre-existing target directory.
--no-gitSkip git init (defaults to initialising).

Replace the scaffold with real requirements#

Goal: turn the template spec.md and traceability.md into project-specific content.

  1. Open spec.md. Replace every placeholder paragraph; keep the REQ-NNN heading convention because the validator uses it.
  2. Update docs/specs/traceability.md. Use the rich 10-column header if you want full DDD coverage; the legacy 4-column form is also accepted.
  3. Each REQ-NNN you add to spec.md must appear in traceability.md and (eventually) in a .feature file. validate flags missing rows; validate --strict-tdd also flags missing scenarios/tests.

Tip: keep AI_RULES.md open in your editor. It is what every coding agent reads on every prompt — changes there propagate to Claude/Cursor/Aider without re-prompting.

Then: the daily loop#

Scaffolding is day one. From day two the loop is four commands, and none of them asks you to edit the ten-column matrix by hand.

csda status                      # where things stand, and what to run next
csda plan                        # the queue: what still needs a test or code
csda req add "Operators can export a monthly report"
csda req link REQ-007 --feature features/reporting/export.feature \
                      --test src/ReportTest.java
csda done REQ-007 --check        # validates first, then flips the status

csda status is the one to start the day with — it names the single next command, so you never have to remember which of the others applies.

If validate complains about something mechanical — an orphan .feature, a requirement in spec.md with no row — csda fix --dry-run shows what it would repair, and csda fix applies it.

Next#