⬡ Specgate

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

npm i -g @rsaglobaltech/specgate   # or prefix every command with npx @rsaglobaltech/specgate@latest

cd your-repo                       # or an empty directory
specgate init                      # adopts the code that is there, touching none of it;
                                   # scaffolds a new project where there is none
specgate ci init                   # the gate as a CI job — GitHub, GitLab, Azure or Jenkins,
                                   # detected from the repository
specgate check                     # the gate, locally

Requires Node.js ≥ 22 — or none with Docker: docker run --rm -v "$PWD:/workspace" ghcr.io/rsaglobaltech/specgate check. The package is scoped, the binary is not (ADR-0024).

→ Getting started · Your team's first pull request · Quickstart for joiners

🔁 The daily loop — five commands

specgate status                                    # what is open, and the next command to run
specgate new "Customers download invoices as PDF"  # requirement + scenario, in one step
# rewrite the scenario's <placeholders>, then write a test that mentions REQ-007:
#   // REQ-007 — a paid invoice downloads as a PDF
specgate done REQ-007                              # runs the gate for it, then marks it Implemented
specgate check                                     # the whole gate — the same one CI runs

That is all most of a team ever types. Mentioning REQ-NNN in a test is the link — there is nothing else to declare. The traceability matrix is generated from spec.md, the scenario tags and your tests; nobody edits it, and CI fails when the committed copy is out of date. done writes nothing while the gate fails, so a requirement it closes is one CI will not reopen.

Everything else — packs, changes, the harness, ALM sync — is in specgate --help --all.

🪜 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 | init, new, done | ~1 hour | | L2 | A PR gate enforcing spec and test coverage | check, ci init | ~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 gate that does not lie. specgate check fails when a delivered requirement has no scenario, template steps, no test that mentions it, or points at a file that is gone. A Draft owes nothing yet: green on day one, stricter with every delivery. Given a test command, it runs your suite too. → Writing specs · Validating · Command reference

Reviews that read intent. The reviewer reads the requirement, its scenario and the test that names it — the gate has already proved the mechanical part. A spec that already shipped changes through a reviewable delta: only what moves, never a copy. Archiving merges it into the spec tree and writes the feature files, so a merged proposal cannot quietly become undone work. → Your team's first pull request · Reviewing changes

From a brief, or from OpenSpec. Save your plan as docs/brief.md, run specgate draft: module by module, it briefs your agent and holds the draft to eleven rules — scenarios per actor and surface, sourced laws, every value in the brief or listed as an assumption, open questions that block, ids each actor can reach. Teams on OpenSpec keep it: specgate verify fails while a change claims a scenario no test names. → A new project, step by step · From a client brief · Already on OpenSpec

Your agent works the same loop. specgate agents init gives Claude Code, Cursor, Copilot, Windsurf, Aider, Gemini, Cline, Codex or Antigravity the five steps as slash commands (/specgate:new, /specgate:done, …) from one definition. Every daily command speaks JSON with stable codes and a fix on each. The MCP server ships in the package: specgate mcp install --client claude. → Agents · The agent contract · Automation and MCP

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: 7 proven in the pilots, 11 starter examples · Supply chain

Unattended delivery. specgate harness run drives plan → agent → verify → done for every pending requirement, each in its own git worktree; it never merges. The agent is any shell command with {prompt_file}; it stops where retrying cannot help. specgate alm sync keeps Jira, Azure Boards or GitHub Issues in step. → The harness · Jira, Azure Boards and GitHub Issues

Tested as you install it. Every release runs an end-to-end suite over every command, against the packed tarball, on Linux, macOS and Windows; releases since 0.14 come from building real products with it, from brief to running app.

🆚 How it compares

| Capability | this | OpenSpec | spec-kit | Cursor rules | README only | | -------------------------------------- | :--------------------: | :------------------------------------------------: | :--------------------------------------------: | :----------------------------------------------------------: | :---------: | | Change lifecycle | ✅ | ✅ | ❌ | ❌ | ❌ | | Versioned domain packs | ✅ | ❌ | ⚠️ | ❌ | ❌ | | Traceability matrix + CI gate | ✅ | ❌ | ⚠️ | ❌ | ❌ | | Agent JSON contract | ✅ | ✅ | ❌ | ❌ | ❌ | | Draft checklist from a brief | ✅ | ❌ | ⚠️ | ❌ | ❌ | | Proves OpenSpec's "done" against tests | ✅ verify | ❌ | ❌ | ❌ | ❌ | | Vendor-neutral | ✅ | ✅ | ✅ | ❌ | ✅ | | Commands to learn before the first PR | ✅ 5 (26 more, opt-in) | ✅ | ✅ | ✅ | ✅ |

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

📚 Documentation

• Getting started · Your team's first pull request · Command reference
• How-to guides · Tutorial · Supply chain · Architecture
• Case study · ADRs · Docs site · Spec coverage report

🧰 Companion tools

Language server · VS Code extension · Maven and Gradle plugins for builds without Node · Docker image ghcr.io/rsaglobaltech/specgate

🤝 Contributing

PRs welcome — see CONTRIBUTING.md (good first: templates, validator rules, domain packs) · MAINTAINERS.md · SECURITY.md for private reports.

📄 License

MIT © RSA Global Tech