Open source · MIT · the flagship
Groundwork
An agent that isnot allowed to say “done”until the work has been checked.
The problem
Plausible is not the same as correct
Every safeguard below exists because the failure it prevents happened first.
“An agent will happily write plausible code and just as happily report that it is done. Groundwork makes the checking part of the process.”The design principle the plugin is built on
- 01
It guesses about other people’s APIs
An agent asked what a payment provider returns will produce a confident, well-formatted, entirely invented answer. Groundwork requires a citation from official documentation, or a sandbox result — anything else is recorded as unknown rather than assumed.
- 02
It plans from the files it was shown
The change looks contained because nobody looked outward. Discovery maps the blast radius first — callers, events, jobs, policies, cascade relationships, the tests that cover any of it — so the plan is built on connections rather than on the three files in the prompt.
- 03
It answers the question it was asked
Which is not always the question worth answering. A separate pass predicts what nobody thought to ask, and the interview puts those decisions back to the person who owns them instead of settling them quietly.
- 04
It reports success
“It works” is a claim, and a claim is not evidence. A reviewer whose only job is to refute the claim gets to look before it is believed.
The design
Weight scales with risk
A typo and a change to how VAT is calculated do not deserve the same ceremony. Applying the full process to everything is how a process stops being used — so the level decides what runs.
| Level | What it covers | Review agents | Approval |
|---|---|---|---|
| L0 | Typo, comment, documentation | None | Not required |
| L1 | Small bug fix | None — a targeted self-trace | Unless told to apply now |
| L2 | Normal feature | Impact map, conformance | Required |
| L3 | Permissions, migrations, public contracts, financial visibility | All five | Required |
| L4 | Financial calculation, order lifecycle, the permission model, destructive migrations | All five, plus an adversarial panel | Human, always |
Pick a task. Watch the process resize.
Zero JavaScript — radio inputs and CSS. Keyboard: Tab into the group, then arrow keys. Works with scripting disabled.
L0 — Tiny
No spec. No plan. No review agents. No approval. The automatic gates are the entire Definition of Done.
Who reviews
Nobody — and that is deliberate.
What is required
- The gates that fire on their own
L1 — Small fix
A regression test that fails first, then one live exercise of the single thing fixed — not a sweep of every consumer.
Who reviews
No agents — a targeted self-trace instead.
What is required
- Short inline spec
- Fail-first regression test
- Live check of the one thing fixed
L2 — Feature
Discovery fans out before anything is planned. The blast radius is mapped, not assumed, and nothing is written before the plan is agreed.
Who reviews
- impact-mapper — what will this break
- conformance-reviewer — does the diff satisfy the criteria
What is required
- Spec, plan, approval
- Up to 2 rounds of questions
- Tests written before the code
L3 — High risk
Permissions, migrations, public contracts, financial visibility. Here the intent gets challenged, not only the code.
Who reviews
- impact-mapper
- blind-spot-map — what nobody thought to ask
- grounded-researcher — what the provider actually does, cited
- conformance-reviewer
- adversarial-verifier — is “it works” true
What is required
- Spec, plan, requirements check, deployment notes
- Up to 4 rounds of questions
- An ADR when the decision is cross-cutting
L4 — Critical
Financial calculation, order lifecycle, the permission model, destructive migrations. Being approximately right here is being wrong.
Who reviews
- Everything L3 engages
- An adversarial panel — at least two independent skeptics on the riskiest claims
What is required
- Everything L3 requires
- Rollback notes
- Human approval, always
- format on edit
- static analysis
- test suite
- OpenAPI contract
- defect scan
- coverage claim
- estimate claim
- task intent
- agent contract
- enforced runner
- migrations locked
- edits locked in discovery
- unpushed work
Review
Five specialists, one job each
Each runs in a fresh context, so the reasoning that produced a mistake cannot quietly reproduce it.
impact-mapper
What will this break? Traces outward from every touched symbol — callers, events, listeners, jobs, scheduled commands, policies, cascade relationships, and the tests covering any of it.
blind-spot-mapper
What did nobody think to ask? Predicts the omitted dimension rather than the existing coupling: unintended consequences, missing requirements, the domain angle the requester is not the expert in.
grounded-researcher
What does the provider actually do? Reads the official documentation and returns findings that each carry a source, or are marked unknown. It is not allowed to guess instead of check.
adversarial-verifier
Is the “it works” claim true? Tries to refute it against real code, official docs and sandbox results. Defaults to skeptical.
conformance-reviewer
Does the diff satisfy the acceptance criteria that were agreed? Judges implementation against spec in a fresh context, and reports gaps rather than style.
Evidence
What a finished task leaves behind
Green gates prove the code compiles and the suite passes. These four exist because the expensive claims are the other ones — how long it took, what was actually verified, and what the standard said while the code did something else.
Estimates are measured, not felt
“How long will this take?” is answered from a ledger of the agent’s own active minutes — a median with the sample size it rests on, idle gaps excluded. Human time is a separate line with its owner, and an hour-sized number has to name the slow thing beside it.
The receipt, and the line nobody signed
A substantial task leaves a file beside its spec, in three blocks that cannot be confused: measured — commit, exit codes, minutes, each copied from a command’s output; claimed by the agent — every acceptance criterion with its file and its covering test; and reviewed by, left empty for a person. Its last line states that an unsigned receipt is not a review.
A rule beats a paragraph
Five defect classes found in real repositories — money kept as a float, configuration read outside the config layer, an irreversible effect inside a transaction — had been written down as standards for months and violated anyway. They are a gate now. Prose is what failed; the check is the retry.
Plain language first
Every text where the person decides — the discovery report, each question, the list of blind spots — opens with the lived consequence in everyday words, and keeps the field name and the status code after it. Nothing technical is removed. It just stops being the opening.
Adoption
In daily use, not in a demo
Numbers are approximate and point-in-time, which is why they carry a date.
- 7
- production codebases
- 340
- procedure runs
- 160
- written specs
- 27
- frontend hand-offs
- 1 in 3
- stopped before code
Approximate, as of August 2026
The number worth arguing about
Roughly one task in three never reaches code. Not because the tooling refused, but because writing the specification showed the request was mis-scoped, already solved elsewhere, or cheaper to handle without development at all.
Install
Three lines
`init` derives thin, domain-only contracts from the code itself and labels anything it had to assume.
/plugin marketplace add YasMax91/groundwork
/plugin install groundwork@yasmax
/groundwork:init