🧭 create-spec-driven-app

Specs as executable contracts — requirements, scenarios and traceability that CI enforces.

Stop coding before requirements are operationally clear. Every requirement maps to a scenario, a domain artefact, an implementation and a test — and the gate fails when one is missing.

⚡ Start

Existing codebase — the common enterprise case:

cd your-repo
npx create-spec-driven-app@latest onboard   # reads the repo, proposes its capabilities
npx create-spec-driven-app@latest adopt     # writes the spec skeleton, touches no code
npx create-spec-driven-app@latest validate .

New project:

npx create-spec-driven-app@latest init      # interactive wizard

Requires Node.js ≥ 22 — or none at all with the Docker image:

docker run --rm -v "$PWD:/workspace" ghcr.io/rsaglobaltech/csda validate . --strict-tdd

→ Getting started · Quickstart for joiners

🪜 Adopt one level at a time

Each level is useful on its own and never requires the ones above it.

| Level | You get | Commands | Cost | | --- | --- | --- | --- | | L1 | Traceable specs in your repo | onboard, adopt | ~1 hour | | L2 | A PR gate enforcing spec and test coverage | validate --strict-tdd | ~1 hour | | L3 | Versioned, reusable domain requirements | specops add / sync / diff | ~1 day | | L4 | Agent-driven delivery, one requirement at a time | agents init, harness run | ~1 week |

🛠️ What it does

A daily loop, not a one-shot scaffolder. csda status says where the project stands and what to run next; csda plan is the queue; csda req adds and links requirements so nobody hand-edits the ten-column matrix; csda done closes them. → Quickstart · Command reference

Specs that are checked. csda validate fails the build when a requirement has no scenario, no test, or no row in the traceability matrix. --strict-tdd fails it when a requirement moves past Draft without a test. → Writing specs · Validating

Changes you review as intent. Modify a spec that already shipped through a reviewable delta — only what moves, never a copy. Archiving merges it into the spec tree, writes the matrix rows and materialises the feature files, so a merged proposal cannot quietly become undone work. → Reviewing changes

Domain knowledge as a dependency. A pack is a versioned, schema-validated domain model. Install it, pin it, upgrade it deliberately — and review the upgrade as intent with specops diff --as-change, not as a file diff. → Domain packs

An agent surface that is a contract. Twelve commands speak JSON with stable diagnostic codes and a fix on each — every command of the daily loop, and a test asserts it. csda agents init wires the loop into eight agent tools from one definition. → Agents · The agent contract

Unattended delivery. csda harness run drives plan → agent → verify → done for every pending requirement, each in its own git worktree. It never merges. csda ci init generates the gate for GitHub, GitLab, Azure or Jenkins, and csda alm sync keeps Jira or Azure Boards in step.

Any agent CLI. No agent runtime, no SDK dependency: the agent is any shell command containing {prompt_file} — claude -p < {prompt_file}, aider --yes --message-file {prompt_file}, or my-wrapper.sh {prompt_file} for anything else. Commit your team's commands in .harness/profiles.yaml and pick one by name. → Automation · The harness · Jira and Azure Boards

It stays current. csda update refreshes the generated agent files after an upgrade, three-way merging your edits rather than clobbering them. csda doctor reports what has drifted, with a fix per finding. → Command reference

🆚 How it compares

| Capability | this | OpenSpec | spec-kit | Cursor rules | README only | | --- | :-: | :-: | :-: | :-: | :-: | | Change lifecycle | ✅ | ✅ | ❌ | ❌ | ❌ | | Versioned domain packs | ✅ | ❌ | ⚠️ | ❌ | ❌ | | Traceability matrix + CI gate | ✅ | ❌ | ⚠️ | ❌ | ❌ | | Agent JSON contract | ✅ | ✅ | ❌ | ❌ | ❌ | | Vendor-neutral | ✅ | ✅ | ✅ | ❌ | ✅ | | Smaller surface to learn | ❌ | ✅ | ✅ | ✅ | ✅ |

OpenSpec is the closest tool and the honest comparison: if you want the change loop without versioned packs or an enforced matrix, theirs is the better fit. → Full matrix, trade-offs and migration paths

📚 Documentation

• Command reference — every command, grouped by when you reach for it
• How-to guides — by task and by adoption level
• Tutorial — long-form, on a real public pack
• Supply chain — pack pinning, digests, signing, air-gapped installs, SBOM
• Architecture — three repos, three lifecycles
• Bootstrap prompt — the one freeform-AI step
• Case study · ADRs · Docs site

🧰 Companion tools

MCP server (mcp-spec-driven) · Language server (lsp-spec-driven) · VS Code extension (vscode-spec-driven) · Maven and Gradle plugins for teams that do not want Node on the build agent.

🤝 Contributing

PRs welcome — see CONTRIBUTING.md. Good first contributions: new module templates, validator rules, additional domain packs. MAINTAINERS.md says who owns what; SECURITY.md is how to report a vulnerability privately.

📄 License

MIT © RSA Global Tech