specgate/docs v0.20.0

Getting started#

Specgate turns what a product must do into requirements, scenarios that pin them down, and tests that name them — and refuses to call anything done until the test passes. Three things to do, in order.

1. Install it#

You need Node.js 22 or later, and the test runner your project already uses (npm test, ./mvnw verify, pytest, go test ./... — Specgate runs it, it does not replace it).

bash
npm install -g @rsaglobaltech/specgate     # the command is `specgate`
specgate --help                            # or, without installing: npx @rsaglobaltech/specgate@latest --help

A coding agent (Claude Code, Codex, Cursor, Copilot, Aider…) is optional. Every step works by hand; the agent is a faster pair of hands.

2. Pick your path#

From scratchA new product, maybe a client's brief. Five steps: install, turn the brief into checked requirements, build the first one, prove it, keep the loop going.An existing projectCode that already works. Five steps: adopt it without touching a line, write down one behaviour you rely on, close it with a test you already have, put the gate in CI.A whole new application`specgate init --forja`: forja generates a Next.js + Expo monorepo or a Spring Boot / Quarkus API with the architecture in place, and adopts Specgate.You cloned a spec-driven repoSomeone else set it up. Five minutes to see where the project stands and close your first requirement.

Each path is five short steps, one page each. A bar at the top of every page shows where you are; every terminal on those pages is real output, recorded from the CLI — a check fails the build when a page and the CLI disagree.

Starting from a plan or a client's brief? Most projects do: read Write the brief after step 1. Your plan goes in docs/brief.md as it is, and your agent can propose the four fields Specgate needs at its top.

3. Learn the daily loop#

Once a project is set up, the day is five commands:

  1. specgate status — where you stand

    What is left, requirement by requirement, and the one command to run next. specgate on its own does the same.

  2. specgate new "<what it does>" — one more requirement

    Its sentence in spec.md, a scenario to fill in, and its row in the matrix.

  3. A test that names it

    Write a test that mentions REQ-007 — that mention is the link. Nothing to declare.

  4. specgate done REQ-007 — close it

    Marked Implemented only if the gate passes for it: the specification, the link and your test suite.

  5. specgate check — before a pull request

    The whole gate. The same command runs in CI.

At the foot of status sits Gato, the cat that keeps the gate. It grows as requirements close and falls sick when check is red; what it means.

The two paths side by side#

StepFrom scratchAn existing project
1Install and set upAdopt, touching no code
2Specify — the brief becomes a checked draft, a module at a timeSpecify — one behaviour you rely on
3Build — test first, by hand or with the harnessFirst requirement — the test you have names it
4Prove — done, check, reportCI — the gate on every pull request
5Every day — CI and the loopEvery day — one module at a time

Upgrading from 0.18 or earlier?#

Since 0.19 everything is called specgate: the markers in your specs (<!-- specgate:trace … -->), the .specgate/ folder and the SPECGATE_* variables. A project on the old csda: format fails validate with old_format and the command to migrate it, once (ADR-0032).

Already on OpenSpec?#

Keep writing your specs with OpenSpec. specgate verify reads openspec/ in place, never writes to it, and fails when an archived change claims a scenario no test names. Nothing to migrate: Already on OpenSpec.

Then#