Skip to main content

methodology / shipped as skills

Vibes don’t merge.

Structure agent work. State intent, verify output, keep what survives.

Start the loop Read the docs

npx skills add jcosta33/suspec-skills -g

  • Plain markdown

    Readable anywhere.

  • Any agent

    Install once. Repos stay clean.

  • Human review

    Facts, never verdicts.

pwrcheckevidence

# the honesty floor

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

C016 supported-needs-evidence — AC-002 marked Supported, evidence cell empty

review.md

~/.agents/artifacts/acme-api/ · review packet

review

AC-001 supported

Evidence: `npm test auth-refresh` pasted, exit 0.

structured plan mode

Plan mode, with receipts.

Suspec gives agent work a shape: state the work, set the bar, keep the proof. Your planner, tracker, and repo keep their jobs.

what it is

Useful paperwork

  • spec:The work, the bar, and how to verify it
  • review:Evidence checked against the bar
  • findings:The verified lessons worth keeping
what it is not

Another platform

  • runtime:Your agent still does the typing.
  • tracker:Tickets stay where they are.
  • verdict:Facts in. Human decision out.
the method / in full

The loop, without the ceremony.

Start with intent. Add structure only when the work earns it.

010203040506

workflow / six steps

The loop at a glance.

Six steps around the hexagon; the inscribed triangle is the three keys — intent, review, findings: present on virtually every change, at whatever weight it earns. Work named, evidence reconciled, lessons kept.

  1. 01
    Intentcapture the ask

    Name the work before it mutates.

  2. 02
    Specdefine requirements

    Set the bar and how to check it.

  3. 03
    Implementrun the change

    Do the work. Keep the receipts.

  4. 04
    Reviewcompare evidence

    Compare the result with the bar.

  5. 05
    Checkreport facts

    Lint the paperwork. No verdicts.

  6. 06
    Findingskeep lessons

    Keep the lesson. Bin the rest.

Findings feed the next spec — the loop closes

plan, don't compile

Specs are not src.

LLMs are not compilers. Compilers don't cost a fortune to run or lie to you. A spec still gives the agent a plan, reviewers a target, and findings somewhere to land.

Working records stay beside your harness artifacts. Promote the few worth keeping. Code stays king.

spec.md

~/.agents/artifacts/acme-api/ · acceptance criterion

spec

AC-003 — Expired refresh token redirects to login

The client must clear local session state and route the user to `/login`.

Verify with: npm test -- auth-refresh-expired

start / first pass

Try it on one real change.

Install the skills. Set the bar. Keep the receipts.

Start the loop View the skills catalog