Skip to main content

setup / one install

Get started

Install the skills. Add deterministic checks only if useful.

  1. Install
  2. Check
  3. Loop
  4. Keep

setup route

One install → the loop

plain markdownoptional clioptional mcpany agent
one installnpx skills add jcosta33/suspec-skills -g

  1. Install

    Install the skills globally.

  2. CLI

    Optional deterministic checks.

  3. MCP

    Optional shell-less checks.

  4. First change

    Run one small change.

  5. By hand

    No CLI required.

  6. Committed

    Nothing automatically.

one command, everywhere

Install the skills

One command installs or updates the skills. Nothing lands in the repo.

universal / global install

Universal skills

Tier 01

User-level Markdown skills. Any repo, any capable harness.

Installs
Once, globally, for every repo.
Lands in your repo
Nothing.
npx skills add jcosta33/suspec-skills -gBrowse the catalog

repo-specific / stays put

Repo guides

Tier 02

Your commands, your conventions — committed in the repo they describe, as they already are. The two tiers never overlap.

Owns
Project-specific guidance only.
From Suspec
Nothing to copy in.
your repo, your rulesSee the skills
optional — the deterministic checks

The optional CLI

suspec check <path> reads exactly the files you hand it, reports facts, and never renders a review result. Exit codes are the API: 0 clean, 1 warning, 2 blocking. It is not on npm yet — install it from source.

pwrcheckevidence

# install the CLI from source

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

$ cd suspec-cli

$ corepack enable

$ pnpm install --frozen-lockfile

$ pnpm link --global

# then, on any artifact you name by path

$ suspec check ./spec.md # facts only; exit 0/1/2

CLI details: the CLI page.

optional — shell-less clients

The optional MCP adapter

suspec-mcp exposes the same check surface through two MCP tools for clients that cannot run shell commands directly. It still requires the Suspec CLI, returns facts rather than verdicts, and is installed from source for now.

pwrcheckevidence

# install from source; no published package yet

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

$ cd suspec-mcp

$ corepack enable

$ pnpm install --frozen-lockfile

shell-less clients

Connect through MCP

  • Requires the Suspec CLI on PATH, or an explicit SUSPEC_BIN.
  • Exposes suspec_check and suspec_get_checks.
  • Returns check facts under a fixed no-verdict envelope.
Read the MCP page

First useful change

Start small and run the whole loop once. The loop is proportioned to feature-sized work — a trivial fix earns a one-line inline spec and no files at all; the bug-fix example shows that shorter path. A hands-on walkthrough lives in the tutorial.

where the spec lives

beside your native artifacts / by explicit path

note

Beside your harness's plans and notes. You choose the location; later steps use its full path.

Setup notes: docs/ADOPTING.md

the loop, once through

  • Intent

    name the work

    Start from the request, ticket, or idea. Preserve the wording only when it matters.

  • Spec

    set the bar

    Write AC-NNN requirements, verification commands, and non-goals. Carry the full path forward.

  • Implement

    evidence in

    Run every verification command. Paste real output.

  • Review

    independent eyes

    An independent reviewer checks the packet against the spec.

  • Check

    optional facts

    Check shape, coverage, evidence, and references. Humans still decide.

  • Findings

    what survives

    Promote lessons to memory, decisions to ADRs, defects to issues.

where the spec lives

beside your native artifacts / by explicit path

note

Beside your harness's plans and notes. You choose the location; later steps use its full path.

Setup notes: docs/ADOPTING.md

no cli required

By hand — no CLI

Every step has a by-hand path; the CLI accelerates checking, nothing else.

  1. Write the spec yourself — the shape is documented in artifact formats: status, requirements with ids, a Verify with: line each. Place it beside your native artifacts, as above.
  2. Run each Verify with: command yourself and paste the real output into the spec's Execution section.
  3. Review by checklist — one coverage row per requirement; empty evidence is Unverified, never Supported; exceptions routed to a human. Without the CLI the floor is yours to hold.
what gets committed

Nothing, by Suspec's hand

Your repo takes the code, the tests, and whatever your project's own governance already commits — ADRs, agent guides, the PRs themselves. Specs, task packets, and review packets stay beside your native artifacts, outside the repo, unless that governance says otherwise.

Skills

The full catalog: methodology skills plus the universal disciplines they lean on. Pick the one that fits.

Browse skills