How-to guides#
Task-shaped guides, each self-contained. Copy/paste should work end to end.
Prerequisites: Node.js ≥ 22,
git, a shell. Every command that operates on a project accepts--project-dir <path>and also walks up from the current directory looking forspec.md,.specops.lockorspecops.config.yaml.
By task#
| I want to… | Guide |
|---|---|
| Start, on a new project or an existing repo | Getting started |
| 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#
- Quickstart — one page, for joining a project that already uses this.
- Walkthrough — the shortest complete pass, on a real public pack.
- Tutorial — the long-form version, with the reasoning at each step. Deliberately one file: it is a narrative, not a set of tasks.