Why Groundwork
AI agents write code fast. On a real project, speed isn't the bottleneck — keeping the project on course is.
A chat window starts every session from zero. The plan lives in scrollback, "done" is a claim, and the rules you agreed yesterday are gone by tomorrow. Groundwork puts those things in files the whole team can see — you, your agent, and your version control — and gives the agent a process to follow.
What Groundwork changes
The project lives in files, not in the chat
The spec, the plan, the cards, the decisions, the proof, and the lessons are all plain files in
.groundwork/. Any session can pick up from the handoff file alone, with any tool and any model.
Close the laptop mid-card; the next session continues instead of restarting.
Evidence, not claims
A card is built test-first: the tester writes failing tests and saves the output, the implementer makes them pass, and the reviewer re-runs everything with fresh context before it reaches you. Approval is refused while the evidence is missing. "Done" is what the proof shows, not what the agent says.
Roles with different jobs
The tester can't write the implementation. The implementer can't edit the tests. The reviewer can't fix code — it sends the card back. The planner can't write code or choose your stack. In tools with subagents each role runs in a fresh context, so review really is review.
You set the pace
Approve every card before it's committed (the default), or let a phase's cards commit as they pass review and approve the phase as a whole. Every stop tells you what changed, how to check it yourself, and the caveats — in plain words, without reading a diff.
Mistakes become rules, then guards
When something goes wrong, it's written down as a lesson with the mistake that caused it. If it
happens again, the lesson becomes a rule the agent sees in every session. If it still happens, it
becomes a guard that blocks the action outright. /gw-retro proposes each promotion; nothing
changes without your OK.
Right-sized, and small
A typo goes through the quick path in one pass. A bug needs a failing test and a stated cause before
any fix. A feature gets a spec, a plan and cards. The always-loaded part of Groundwork is about 400
tokens; groundwork doctor measures it and flags bloat.
What it is not
- Not another framework to learn. The one command to remember is
/gw. - Not autonomous. Groundwork stops for your approval, by design.
- Not a stack picker. Choices are laid out as options with trade-offs; you decide, and the decision is recorded.
- Not a task-level skill pack. It's the project layer — spec, cards, approvals, handoff and lessons. How the agent handles a single task stays with your tool.
One-shot prompting vs a process
Prompt engineering shapes a single response. Groundwork shapes the process that produces and verifies every response, across sessions:
| Failure mode | One long prompt | Groundwork |
|---|---|---|
| The session ends | Start over, re-explain everything | Handoff file resumes the work in any tool |
| The agent says "done" | You take its word | Tests first, a fresh reviewer, saved evidence, a human gate |
| A rule is forgotten | Reword the prompt and hope | Notes become rules, then guards that block the action |
| Scope grows quietly | You notice at the end | Cards with fixed criteria; extras are stated as caveats |
| Every task costs the same | One heavy ritual for a typo and a feature | Try / quick / card, said out loud, overridable |
Prompts still matter — every role in Groundwork is a carefully written prompt. But a prompt is a suggestion. The process adds the things a prompt can't: state that survives, proof that can be checked, and rules that can be enforced.
Who it's for
- Vibecoders who want to build real things without learning a methodology: specific questions, plain-language approvals, and a check they can click through themselves.
- Experienced developers who want an agent to run a card at a time with a real review step, a commit trail, and control over every merge.