# The four tools

Each card runs one command on the [example repository](https://github.com/spec-family/example) as
it stands on `main` at [`77b504f`](https://github.com/spec-family/example/commit/77b504ff1625988557b2767356b68d4a40f09a8c), where every
check holds, with the release the card names. The block is what that release
printed; the [stories](https://spec-family.github.io/stories/index.md) show the same tools finding something. The
description under each name is the one the release itself carries.

## spec-brief

Lifecycle management for task briefs: lint the contract, map parallel collisions, and archive a round in one atomic command.

```console
$ npx --no-install @spec-family/spec-brief lint
briefs/001_charge-a-late-fee.md
  6  note     "src/fees.js" in affectedFiles matches no file in the tree  glob-matches-nothing
              expected when the round creates it; otherwise check the spelling
  6  note     "test/fees.test.js" in affectedFiles matches no file in the tree  glob-matches-nothing
              expected when the round creates it; otherwise check the spelling

0 errors, 0 warnings, 2 notes in 1 brief(s)
```

Exit `0` · spec-brief 0.15.0.

[README](https://github.com/spec-family/spec-brief/blob/v0.15.0/README.md) · [Reference](https://github.com/spec-family/spec-brief/blob/v0.15.0/docs/reference/README.md) · [npm](https://www.npmjs.com/package/@spec-family/spec-brief/v/0.15.0)

## spec-graph

Turn Markdown specs into a verifiable relational graph. Catches ghost handovers, stale premises, broken references, work marked done without its evidence, and commits and paths that are not there, in CI.

```console
$ npx --no-install @spec-family/spec-graph check
spec-graph 8 documents · 13 items · 24 relations · 7 open

63.54ms
✔ the specification graph is consistent
```

Exit `0` · spec-graph 0.26.0.

[README](https://github.com/spec-family/spec-graph/blob/v0.26.0/README.md) · [Reference](https://github.com/spec-family/spec-graph/blob/v0.26.0/docs/reference/README.md) · [npm](https://www.npmjs.com/package/@spec-family/spec-graph/v/0.26.0)

## spec-guard

Hold your code to what your Markdown says about it: the claims specs, ADRs, READMEs and agent instructions make about your codebase, as assertions that run in CI.

```console
$ npx --no-install @spec-family/spec-guard
spec-guard 3 specs · 6 assertions · javascript

6 passed · 18ms
✔ every spec assertion holds
```

Exit `0` · spec-guard 0.35.0.

[README](https://github.com/spec-family/spec-guard/blob/v0.35.0/README.md) · [Reference](https://github.com/spec-family/spec-guard/blob/v0.35.0/docs/reference/README.md) · [npm](https://www.npmjs.com/package/@spec-family/spec-guard/v/0.35.0)

## spec-harness

The agent-facing member of the spec-* tools: context for a round, a guard on the agent's writes, an audit when it ends, probes that prove a defect before it is filed, and rulings a person signs.

`````console
$ npx --no-install @spec-family/spec-harness context --brief 001
# Round 001: Charge a late fee

Status active · wave 1 · branch `main` · measured from `main`

## The contract

`briefs/001_charge-a-late-fee.md`, in full:

````markdown
---
status: active
date: 2026-11-09
type: feature
wave: 1
affectedFiles: [src/fees.js, test/fees.test.js]
protectedFiles: [src/loans.js, docs/**]
---

# 001 — Charge a late fee

## Intent

A book given back after its due day is charged 25 cents for each day late,
in whole cents as [ADR-0001](../docs/adr/0001-money-is-whole-cents.md)
requires, computed from the loan as the desk records it today.

## Negative Scope

- No change to how a book is lent or given back.
- No fee for anything but lateness.

## Not Empowered

- `src/loans.js`: the loan record. Every report reads it as it is, and a new
  field on it is a decision of its own.
- `docs/`: the decisions and the specification this round is held to.

## Invariants

- [ ] `lateFee` is exported from `src/fees.js`

<!-- @assert-count target="src/fees.js" symbol="export function lateFee" min="1" -->

## Acceptance Criteria

- [ ] a book given back on its due day is charged nothing
- [ ] a book given back three days late is charged 75 cents
````

## Scope, as the guard reads it

May write:
- `src/fees.js`
- `test/fees.test.js`

Must not change without a ruling:
- `src/loans.js`
- `docs/**`

Rulings in force:
- none

## Depends on

- nothing

## Rules in force for this scope

### docs/adr/0001-money-is-whole-cents.md

- line 18: "parseFloat" must not appear in src - money is whole cents
- line 19: "toFixed" must not appear in src - money is whole cents

### docs/adr/0002-the-desk-reads-no-clock.md

- line 18: "Date" must not appear in src - the desk reads no clock

### docs/spec/lending.md

- line 12: "test('a book on the shelf is lent for 21 days'" must appear at least 1 time in test/loans.test.js
- line 16: "test('a book on loan is not lent again'" must appear at least 1 time in test/loans.test.js
- line 20: "test('a book given back is on the shelf again'" must appear at least 1 time in test/loans.test.js

## How this round works

- Before writing a file, ask whether the round may: `spec-harness guard <path>`, or the `check_path` tool.
- A protected file is changed only under a ruling a person signs. If the round cannot be done without one, stop and ask: `spec-harness escalate --path <file> --reason <why>`, or the `request_escalation` tool. Do not work around it.
- Every box in the brief ends ticked, or with a note under it that starts with a disposition (`**Delegated`, `**Accepted debt`, `**Rejected`, or what the repository configures).
- When the work is done, run `spec-harness audit` and fix what it reports. The archive is a person's decision, not the round's.

## Documents the brief cites

### `docs/adr/0001-money-is-whole-cents.md` - ADR-0001: Money is whole cents (accepted)

````markdown
---
status: accepted
---

# ADR-0001: Money is whole cents

## Context

The desk will charge fees. A fee computed in floating point can come out a
fraction of a cent off, and a fee written as a decimal string invites
parsing it back as one.

## Decision

Every amount of money the desk computes is a whole number of cents. No code
in `src/` parses or formats an amount as a decimal.

<!-- @assert-absence target="src" glob="*.js" symbol="parseFloat" reason="money is whole cents" -->
<!-- @assert-absence target="src" glob="*.js" symbol="toFixed" reason="money is whole cents" -->
````
`````

Exit `0` · spec-harness 0.26.0.

The packet is what an agent starts the round with: the brief in full, its
scope as the guard reads it, the rules in force, and the documents the brief
cites.

[README](https://github.com/spec-family/spec-harness/blob/v0.26.0/README.md) · [Reference](https://github.com/spec-family/spec-harness/blob/v0.26.0/docs/reference/README.md) · [npm](https://www.npmjs.com/package/@spec-family/spec-harness/v/0.26.0)

## Install

```sh
npm install --save-dev @spec-family/<tool>
npx --no-install @spec-family/<tool>
```

Every tool runs on Node 22 or later, calls no model and makes no
network request. The [overview](https://github.com/spec-family/spec-core/blob/main/docs/overview.md) says which tool to start with.

---

This is the Markdown version of https://spec-family.github.io/tools/. Every command's output in it is printed by spec-brief 0.15.0, spec-graph 0.26.0, spec-guard 0.35.0 and spec-harness 0.26.0 in the site's CI; [llms.txt](https://spec-family.github.io/llms.txt) lists every page.
