Quickstart

This guide sets up SLCR in an existing repository. By the end, you'll have a specification for one area of your code, validators connected to your existing tests, and a report of which requirements the code meets.

A coding agent does most of the writing. To learn how SLCR works with a small example first, see the Tutorial.

1. Install the CLI and the agent skill⁠Link to this section

Install the CLI with Homebrew:

brew install wack/tap/slcr

From the repository root, install the agent skill, which teaches coding agents to use SLCR:

npx skills add wack/slcr

See Installation for other ways to install either one.

2. Create a specification⁠Link to this section

From the repository root:

slcr init --name <project-name> --title "<Project Name>"

This creates SPEC.slcr.toml and the project manifest, SLCR.toml.

3. Write requirements for one area⁠Link to this section

Pick one well-understood area of the codebase, such as one service, API, or command, and ask your agent:

Using the slcr skill, write requirements in SPEC.slcr.toml for <area>,
describing what the code does today. Add acceptance criteria. Run slcr vet
and fix anything it reports.

If you already have a requirements document for that area, convert it instead. See Migrating existing documents.

Review the result as a document:

slcr render

Read SPEC.md and correct anything that doesn't match how the code should behave.

4. Connect your existing tests⁠Link to this section

Ask your agent:

Using the slcr skill, declare a tool for this project's test runner with
slcr tools add, writing a descriptor in tools/ if needed. Then add
validators that connect existing tests to the requirements they verify.
Don't write new tests. Run slcr vet when you're done.

See Add a validator tool to declare a tool yourself.

5. Check the code against the spec⁠Link to this section

slcr check

The summary line shows how many requirements are satisfied, unsatisfied, and unknown:

<project-name>: 9 satisfied, 1 unsatisfied, 4 unknown (3 coverage gaps)

• Satisfied requirements are verified by passing tests.
• Unsatisfied requirements have a failing test. Either the code or the requirement is wrong. See Troubleshoot slcr check.
• Unknown requirements can't be decided yet. A requirement with no validator and nothing refining it is a coverage gap. A requirement made of parts is unknown when its unknown parts could still change the result. Unknown requirements don't fail the check.

Next steps⁠Link to this section

• Close coverage gaps by asking your agent to write validators for the unknown requirements, one at a time, from each requirement's slice.
• Add the next area of the codebase to the same spec.
• Check every change automatically with Run SLCR in CI.
• Learn the ideas behind SLCR in Specifications and the other Concepts pages.