Skip to main content
Suspec
suspec-cli — reference implementation

suspec-cli

Optional CLI for the Suspec workflow.

Scaffold files, run checks, manage worktrees.

Command surface settlingNo verdicts

Command families

optional helper surface

  1. 01

    Setup

    init · update · new · pull · agents emit

    Create or refresh kit-owned files.

  2. 02

    Check

    check · status

    Report workspace facts and gaps.

  3. 03

    Review

    review · promote

    Compare evidence and draft findings.

  4. 04

    Run

    worktree · run

    Isolate task work and launch agents.

  5. 05

    JSON

    show

    Expose parsed artifacts for scripts.

install
pwrcheckevidence

# source install for now

$ HOST=github.com/jcosta33

$ PKG=suspec-cli

$ SRC=$HOST/$PKG.git

$ git clone https://$SRC

$ cd "$PKG"

$ npm install

$ npm run build

$ npm link

# then run commands as

$ suspec --help

the-loop.sh — a task, end to end
pwrcheckevidence

# scaffold a workspace first

$ suspec check # lint a spec or the whole workspace; exit 0/1/2

$ suspec worktree create auth-refresh --task TASK-12 # isolate the task on its own branch

$ suspec review TASK-12 # reconcile the finished run — diff vs report vs spec

$ suspec status -i # the board — specs, tasks, reviews, gaps

commands.md — public surface

Commands

Start with suspec check and suspec review. Use the rest when the workspace needs them.

command catalog12 commands / 5 families

init · update · new · pull · agents emit

Setup commands

5 commands

  • suspec init [dir]

    Scaffold a Suspec workspace without overwriting existing files.

  • suspec update [--check|--write]

    Check or refresh kit-owned files. Project work stays untouched.

  • suspec new <task|spec>

    Create a spec or cut a task packet from a spec.

  • suspec pull <ref>

    Snapshot an external ticket into intake/.

  • suspec agents emit --codex

    Generate Codex agent files from Claude Code agent definitions.

check · status

Check commands

2 commands

  • suspec check [file]

    Check one file or the workspace. Exit codes fit CI.

  • suspec status

    Print specs, tasks, reviews, and gaps. Use --json for scripts.

review · promote

Review commands

2 commands

  • suspec review <task>

    Compare the task, run report, and git diff.

  • suspec promote <task>

    Draft a finding from a finished task.

worktree · run

Run commands

2 commands

  • suspec worktree

    Create, list, remove, or prune task worktrees.

  • suspec run <task> --agent <name>

    Launch a prepared task with your configured agent.

show

JSON commands

1 command

  • suspec show <task|spec|review|checks>

    Print parsed artifacts as JSON.

design.md — why a CLI?

Why a CLI?

Suspec is plain files. The CLI handles repeatable chores around those files.

  • One worktree per task

    Keep parallel runs out of the main checkout.

  • Markdown is the source of truth

    The CLI reads the files. It does not replace them.

  • It reports checks, not decisions

    Checks report facts. Review decides.

Don't need the CLI yet?

Use the starter kit and write a spec. Add the CLI later.

Get started

Reference repository

Source, issues, and release notes live on GitHub.

Open suspec-cli on GitHub →

Using an MCP client? suspec-mcp exposes the same facts (read + reconcile, no verdict)