specgate/docs v0.20.0

Existing project · 1 — Adopt, touching no code#

In this phase

When you finish: Specgate set up on a codebase that already works, without changing a line of it, and a gate that passes with your existing tests.

The example is a small Node invoicing service with two modules (src/invoices, src/customers) and its own tests. Maven, Gradle, Go, Python, Cargo and .NET projects go the same way.

WhoDoes what in this phase
YouRun four commands, read what they propose
SpecgateReads the build file and the layout; writes specification files only
The gateRuns your existing suite, to prove the wiring

1. Look before writing anything — specgate onboard#

bash
cd your-existing-repo
npx @rsaglobaltech/specgate@latest onboard
Terminal
$ specgate onboard
  🧭 onboarding  ~/invoicing
 
  1. What this is
     stack:  Node.js
     tests:  npm test
     detected from package.json
 
  2. Specs
     · not adopted yet — `specgate adopt` writes the skeleton without touching code
 
  3. Capabilities this codebase already implies
     · Invoices             src/invoices  (2 files)
     · Customers            src/customers  (1 files)
 
     A proposal, not a verdict. Merge, split or rename them.
 
  Next
     specgate adopt

onboard writes nothing. It names the stack and test command it found, and the capabilities your layout already implies — a proposal to argue with, not a verdict.

2. Adopt — specgate init#

bash
specgate init
Terminal
$ specgate init
  ◆ specgate · init
 
  ℹ  Existing code found (package.json) — adopting this repository in place. Nothing in your code is touched.
  ℹ  To scaffold a separate new project instead: specgate init --new
 
  Stack detection: package.json ──────────────────────────
    · Project: invoicing
    · Stack: Node.js
    · Test command: npm test
    + spec.md
    + features/adoption/baseline.feature
    + docs/specs/traceability.md
    + docs/specs/adr/README.md
    + AGENTS.md
    + README.md   was missing
    · Traceability: generated from spec.md, tags and tests (`specgate matrix`)
 
  Summary ────────────────────────────────────────────────
    · Files written: 6
    · Files skipped (already present): 0
    · Requirements seeded: 2 proposal(s) from the layout — invoices, customers
  ▲  This does not certify your code yet — it certifies the skeleton.
     A green `validate` right now means the structure is in place, not that any
     behaviour is covered. It starts meaning something when the requirements below
     are real and their scenarios are linked to tests.
 
  ✔  Adoption completed
 
… 7 more lines

init (the same as adopt on a repository with code) writes spec.md, AGENTS.md, a baseline scenario and the generated traceability matrix — and only files that do not exist yet. It seeds one proposed requirement per capability (REQ-002 Invoices, REQ-003 Customers), each marked as a guess, each Draft, so nothing claims to be specified or verified.

3. Tell it how to run your tests#

bash
specgate config set test_cmd "node --test"
Terminal
$ specgate config set test_cmd "node --test"
  ✔  test_cmd = node --test
     harness.config.yaml
     `check` and `done` now run it.

4. Run the gate#

bash
specgate check
Terminal
$ specgate check
  ◆ specgate · check   invoicing
 
  ✔  Specification   validate --strict
  ✔  Tests           node --test
 
  ✔  Gate passed — the specification and `node --test`

Green, with your own tests in it — and a warning that is honest: so far this certifies the skeleton, not the code. Phase 2 changes that.

You're done when…#

  • specgate check ends with ✔ Gate passed and your test command.
  • git diff shows new specification files and no change under src/ or your tests.

Variations#

  • Detection was wrong: specgate adopt --var STACK="Spring Boot 3, Java 21" --var TEST_CMD="./mvnw -B verify".
  • No proposals wanted: specgate init --no-capabilities.
  • A monorepo (Maven/Gradle modules, npm or pnpm workspaces, Cargo members, Go modules): specgate adopt --monorepo adopts each module and writes specops.config.yaml; specgate validate . then prints one line per module.
  • Already on OpenSpec: you may not need to adopt at all — specgate verify gates OpenSpec's archived changes on tests. See Already on OpenSpec.

If something goes wrong#

You seeIt meansDo
The gate failed with your tests redYour suite was already failingFix or skip those tests first — the gate will not certify a red suite
Gate passed — the specification and "nothing here runs your tests"No test commandspecgate config set test_cmd "<your command>"
A new <slug>/ folder appearedNo build file was found, so init scaffoldedRun it at the repository root, where the build file is; or adopt --var STACK=…

Want the whole path on one page first? A worked example: one service adopted end to end.

Next: phase 2 — write down what you rely on →