Skip to main content

suspec-cli — optional reinforcement

suspec-cli

Deterministic checks over explicit files. Facts and exit codes, no verdict.

Optional — no step requires itExit codes are the API

The whole surface

three invocations · --json on any

  1. 01

    Spec / change plan

  2. 02

    Review packet

  3. 03

    Contract JSON

No interactive mode, dashboard, or scaffolding. Exit codes: 0 clean · 1 warning · 2 blocking.

Install suspec-cli

install — from source, not npm

Requires Node.js 22.6 or newer and pnpm 10.

pwrcheckevidence

# not on npm — install from source

$ git clone https://github.com/jcosta33/suspec-cli

$ cd suspec-cli

$ corepack enable

$ pnpm install --frozen-lockfile

$ pnpm link --global

# sanity check — prints checks contract 0.21.0

$ suspec check --contract

A suspec check session, end to end

session.sh — facts and exit codes
pwrcheckevidence

# a spec, by explicit path — its own kind's lint

$ suspec check ./spec.md # exit 0 — clean

# a review packet, reconciled against its companions

$ suspec check ./review.md --spec ./spec.md --task ./task.md

C016 blocking — review.md: Supported on AC-003 with an empty evidence cell

$ echo $? # 2 — blocking

# a required companion missing is never a shallower check

$ suspec check ./review.md # blocking — a review requires --spec; exit 2

$ suspec check --contract --json # the contract, for other tools

the surface, invocation by invocation

Invocations

The artifact's kind is read from its own type: frontmatter, never from its filename or location. Every invocation takes --json — the same facts, structured: check id, severity, message, location.

invocation catalogthe entire surface

suspec check <artifact> [<artifact>...]

Artifacts

form

  • suspec check <path> [<path>...]

    Check named artifacts. Batches return the highest severity.

suspec check <review> --spec <spec> [--task <task>]

Review

form

  • suspec check <review> --spec <spec> [--task <task>]

    Reconcile a review packet against explicit spec and task paths.

suspec check --contract

Contract

form

  • suspec check --contract

    Print contract 0.21.0 as JSON: check id, name, and severity.

floor.md — why a checker?

Cheap checks before expensive judgment

What the checker earns its keep on: facts a lazy or dishonest reviewer cannot fake. It checks shape, references, and evidence binding without another model call. It does not prove the evidence is true.

  • C012

    Coverage

    Every in-scope requirement needs a coverage row.

  • C013

    Command match

    Evidence must match the spec's Verify with: command.

  • C016

    Supported needs evidence

    Supported without evidence blocks.

  • C020

    Reference resolves

    Task references must resolve.

  • lint

    Per-artifact lint

    Artifact type selects its lint rules.

  • exit 2

    Missing companion blocks

    Missing --spec or --task blocks with exit 2.

What it does not do

  • No resolution

    Every path is explicit. No discovery.

  • No gate

    It reports facts. Humans gate merges.

  • No verdicts

    Humans own the decision. The checker validates evidence binding.

  • No execution

    It validates recorded evidence; it runs no tests or agents.

  • No writes

    Read-only. No scaffolds or managed state.

Do you need the CLI?

No step requires it. Suspec works by hand; install the skills, then add the checker when the work earns a deterministic floor.

npx skills add jcosta33/suspec-skills -g

Meet the skills Get started

Reference repository

Source, issues, and install notes live on GitHub. The checks contract itself lives in the canon repo: checks/checks.yaml (opens in new tab).

Open suspec-cli on GitHub →

Running shell-less? suspec-mcp carries the same check surface over MCP