manual page/ Start here
What is Suspec?
- Sections
- 5
- Format
- Markdown
- Order
- 01 / 156
Suspec is a markdown workflow for agent-assisted code changes.
It gives you:
- specs with acceptance criteria
- task packets for agents or people
- review packets with evidence per requirement
- findings for lessons worth keeping
- a workspace layout for those files
It does not replace your agent, issue tracker, PRs, CI, or docs site.
Why use it
Agent output is easy to generate and hard to review. Suspec puts a small record between each step:
| Problem | Suspec record |
|---|---|
| Vague ticket | intake/ snapshot plus a spec |
| Repeated prompt context | workspace files the agent can read |
| Scope drift | task packet with scope and Do not change |
| Large PR | review packet with coverage and exceptions |
| Lost lesson | finding saved at Close |
The loop
Pull -> Spec -> Task -> Run -> Review -> Close
Two steps are conditional:
- Inventory: map existing code before brownfield work.
- Change Plan: plan migrations, rewrites, schema changes, or high-risk refactors.
See the basic workflow.
What the files do
- Intake captures the upstream ask without interpretation.
- Spec states intended behavior, non-goals, open questions, and
Verify with:lines. - Task gives one bounded unit of work to an agent or person.
- Run summary records changed files, commands run, output, blocked questions, and findings.
- Review records requirement results and what needs human attention.
- Finding saves durable knowledge for future work.
- Status board shows the current state and links closed work to review packets.
Tooling
The markdown workflow works without tooling.
suspec-cli is optional. It scaffolds, checks, launches, and reconciles files.
It does not write code or decide whether work is correct.
See the CLI reference.
Suspec keeps the functions of heavyweight engineering (explicit intent, verification, review, traceability, change control) while dropping the document stack — see lineage.
Start here
- Read the basic workflow.
- Check where files live.
- Walk the tutorial.
Starter kit: Set up a workspace