Skip to main content
Suspec
system overview

What is Suspec?

A markdown workflow for turning requests into scoped agent work, review evidence, and saved findings.

  1. 01Intake
  2. 02Spec
  3. 03Task
  4. 04Review
  5. 05Finding
pwrcheckevidence

$ cat what-is-suspec.md

Suspec turns requests into specs, specs into tasks, and task output into review evidence.

agent does the typing

human makes the call

claims need evidence

plain markdown

$ _

artifact chain

intake -> spec -> task -> review -> finding

example

Intent becomes a requirement.

The task bounds what may change.

The run pastes evidence.

The review routes exceptions.

The finding preserves what the next task should know.

what it is

What Suspec is

  • specs humans write and agents work from
  • task packets with scope and checks
  • review packets with evidence per requirement
  • findings that carry lessons forward
  • markdown templates
  • workspace conventions
what it is not

What Suspec is not

  • an agent or agent runtime
  • a Jira/Linear replacement
  • a code generator
  • a replacement for PRs and CI
  • a formal verification system
  • a guarantee that code is correct
  • permission to skip review
nearby tools

Where Suspec sits

  1. 01

    Tickets stay put

    Backlog and conversation remain in Jira, Linear, or GitHub Issues.

  2. 02

    Suspec records the run

    Spec, task, review, and finding files keep the work inspectable.

  3. 03

    Tools keep their jobs

    Agents write code. PRs, CI, and reviewers decide what ships.

  • 01

    execution

    Coding agents

    Claude Code, Cursor, Copilot, …

    Their job
    write the code
    Suspec job
    Suspec gives them scoped tasks and review records.

  • 02

    requirements

    Spec-driven workflows

    Their job
    turn a written spec into an implementation
    Suspec job
    Suspec keeps requirements tied to checks and evidence.

  • 03

    source

    Issue trackers

    Jira, Linear, GitHub Issues

    Their job
    hold the backlog and the conversation
    Suspec job
    Tickets stay there. Suspec snapshots the work into files.

  • 04

    manual

    Docs portals

    wikis, Notion, docs sites

    Their job
    describe the system after the fact
    Suspec job
    A Suspec spec drives a change before it ships.

  • 05

    proof

    Review tooling

    PRs, CI, review bots

    Their job
    check the merge
    Suspec job
    The review packet tells reviewers where to look.

  • 06

    mechanical change

    Refactoring tooling

    codemods, OpenRewrite, …

    Their job
    execute mechanical change
    Suspec job
    A change plan states what must survive and how to check it.
common failure modes

Failure modes you are already seeing

  • Drift

    the agent solves a problem, not the problem

    > write scope and a Do not change list

  • Ambiguous input

    the request hides missing requirements

    > write one requirement per ID, with a check

  • Lost handoff

    the plan lives only in chat

    > handoff through a bounded task packet

  • Hallucinated completion

    'done,' but nothing was checked

    > a Pass needs evidence

  • No resumable trail

    the session ends mid-stride; the next one starts from zero

    > write a spec, record the run in its Execution, and a review packet

  • Repeated mistakes

    the same class of bug returns every few sessions

    > save findings at Close

See how it actually runs

Six steps, each producing a file the next one reads. That is the framework: no runtime, no automatic decision.

Source: docs/01-what-is-suspec.md

See the loop