Overview
Groundwork is the project layer for building software with AI agents: it owns the spec, the cards, the evidence and the approvals, so any session can pick up where the last one stopped.
Your AI tool writes the code. Groundwork gives it a process it can't skip, and keeps the state of the project in files instead of the chat:
One cardrunner hands it on · never does the work
- Testerwrites tests that fail for the right reason
- Implementermakes them pass, nothing more
- Reviewerfresh context, reruns everything
- Youapprove, or send back with a reason
- committed ✓
↺ reviewer finds a problem → back to the implementer↺ you reject, with a reason → back into the loop
cd your-project
npx groundwork-ai init # Claude Code, OpenCode, or plain markdownThen open your AI tool in the project and type /gw.
Where to start
Installation
Node 22+, one command, three tool choices.
Your first 10 minutes
From /gw to your first approved card.
Walkthrough
A real calculator build, clip by clip.
What it costs
Where the tokens go, and when it pays off.
New in 0.7.0
Most of these came straight out of measuring the calculator run:
- A lighter runner. Short hand-offs, no rerunning checks between roles, and a fresh session suggested when each phase closes. The build loop →
- Roles record their own calls. The tester and implementer write their own History and
call:lines, and every role treats anything missing from its files as not agreed. Cards and phases → doctorshows what a session costs before it starts, flags cards long enough to be worth trimming, and finds evidence files saved as UTF-16. CLI →- OpenCode sessions know where things stand. On OpenCode 2.x, every new session gets the handoff lines at start, like Claude Code. OpenCode →
no-ai-trailersis on by default for new projects. Configuration →- Measure your own run with
checks/session-costs.mjs. What it costs → gw-ui-specnames what tests look for (an id, label or role), so testers don't guess selectors. UI and animation →