Skip to main content
Suspec
setup / first workspace

Get started

Start with the starter kit. Use the CLI when you want scaffolding and checks.

  1. 01New repo
  2. 02Existing project
  3. 03Copy
  4. 04Check
  5. 05Work

  1. 01

    New repo

    Start from the starter kit.

  2. 02

    Existing project

    Adopt files into a repo with history.

  3. 03

    Copy

    Add the kit files once.

  4. 04

    Check

    Run the CLI check when you want a gate.

  5. 05

    Work

    Write a spec, run it, keep evidence — split into tasks only for parallel work.

choose a path

Pick a setup path

Fresh repo uses greenfield. Existing repo uses brownfield.

  • Greenfieldnew repo, starter kit, first run. Color role: greenfield.
  • Brownfieldexisting project, adoption, migration. Color role: brownfield.

greenfield / starter kit

New repo

Path 01

Template repo with flow folders, templates, and guides already in place.

Best for
Greenfield workspace.
Creates
Templates, local rules, and a board.
GitHub templateUse the starter kit

brownfield / adoption

Existing project

Path 02

Copy the kit into this repo. Keep the app structure.

Best for
Brownfield adoption.
Adds
Suspec records beside the code.
cp -R suspec-starter-kit/* .Read the adopting guide

Starter kit contents

starter kit contents

workspace / committed artifacts

note

Copy the kit once. It gives the repo a shared map: local rules, record templates, flow folders, and a small board.

More setup notes: docs/ADOPTING.md

manifest — copied files

  • AGENTS.md

    local contract

    The file your agent reads before work starts.

  • Core guides

    working method

    Write specs, run tasks, review output, save findings.

  • Nine templates

    record shapes

    Intake, spec, task, review, finding, status, inventory, change plan, ADR.

  • Flow folders

    workspace map

    Specs, tasks, reviews, findings, and related folders.

  • status.md

    active board

    A small workboard for active items.

  • decisions/

    local ADRs

    Decision records for choices that should survive chat.

or scaffold it with the cli

Prefer the command line?

suspec init scaffolds the same workspace into a new or existing repo. It refuses to overwrite existing files. Install it from source for now.

pwrcheckevidence

# install the CLI from source

$ 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, in a new or existing repo

$ suspec init # scaffold the workspace, conflict-safe

$ suspec check # confirm it is well-formed; exit 0/1/2

CLI details: the CLI page.

Need more depth?

Install optional skills for review, fixes, features, and docs.

Browse skills

Using Claude Code?

Copy a worker definition for review, exploration, or authoring.

Browse agents