How-to guides#
Task-shaped guides, each self-contained. Copy/paste should work end to end.
Note
Node.js ≥ 22, git, a shell. Run commands from inside the project: they
walk up from the current directory looking for spec.md, .specops.lock or
specops.config.yaml. To point at another directory, most take
--project-dir <path>; check and validate take it as an argument
(specgate check ../other-project). Each command's --help says which.
By task#
| I want to… | Guide |
|---|---|
| Start, on a new project or an existing repo | Getting started |
| Start from a plan or a client's brief | Write the brief |
| Adopt a repository that already ships, worked end to end | Brownfield adoption, worked example |
| Write requirements, scenarios and matrix rows | Writing specs |
| Make the gate run locally and in CI | Validating |
| Change a spec that already shipped | Reviewing changes |
| Share domain knowledge across repos | Domain packs |
| Wire it into editors, agents, hooks and CI | Automation |
| Drive it from Claude, Cursor or Copilot | Agents |
| Work out why something is not behaving | Troubleshooting |
| Look up a command | Command reference |
By adoption level#
Each level is useful on its own and never requires the ones above it.
| Level | You get | Read |
|---|---|---|
| L1 | Traceable specs in the repo | Getting started, Writing specs |
| L2 | A PR gate that enforces spec and test coverage | Validating |
| L3 | Versioned, reusable domain requirements | Domain packs |
| L4 | Agent-driven delivery, one requirement at a time | Automation, Agents |
Longer reads#
Getting startedThe shortest complete pass: two journeys of five phases, every output real.Domain packs, end to endInstall a pack, upgrade it, take it off.TutorialThe long-form version on a pack, with the reasoning at each step.
The tutorial is deliberately one file: it is a narrative, not a set of tasks.