Open source · Any tool

Spec, proof, approval.
A workflow your AI agent can’t skip.

Your agent writes the code. Groundwork is the project layer: it owns the spec, the cards, the evidence and the approvals, in files, so any session can pick up where the last one stopped.

The problem

A chat gets heavier with every message.

AI models don’t remember anything between calls. To answer your next message, the tool sends the model the entire conversation again: every earlier message, every file it opened, every command’s output. Then a little more on top.
re-sent: already read on an earlier callnew this call
  1. message 11 turn
  2. message 22 turns
  3. message 33 turns
  4. message 44 turns
  5. message 55 turns
  6. message 66 turns
The model keeps no memory between calls, so every call sends the whole conversation again: the tool’s instructions (the dashed block), every message, every file it read, every command’s output. Message 1 is read on every call after it. Double the conversation and you re-read about four times as much.

Measured, one real chat

60×

The first phase of our calculator build ran in one chat: 120 calls produced 293k tokens of new work and re-read 17.6M tokens to do it. By the end, each call carried 280k tokens of history.

measurements

Caching makes re-reads cheaper, not free. Every re-read token still takes up room in the model’s window, and a window has an end. When it fills, the tool summarizes the chat to make space, and details from early on can be lost.

What your AI tool does about it

Claude Code and OpenCode both manage the window for you, and both load a rules file into every session. What neither keeps is the state of your project: what’s done, what’s next, what was agreed. That’s the part Groundwork adds, working inside either tool.

Claude CodeOpenCode+ Groundwork
When the chat fills upClears older tool outputs, then summarizes the conversation. Early detailed instructions may be lost.Compacts the session automatically when the context is full; can also prune old tool outputs.Keeps the heavy work out of your chat: each card’s roles run in fresh sessions, and a new session each phase starts small.
A new session starts withA fresh context window, plus CLAUDE.md and auto memory: your rules and preferences.A fresh context, plus AGENTS.md: your rules.Those, plus HANDOFF.md: where the project stands and the very next step, in a few lines.
Where progress livesIn the conversation, and whatever git history shows.In the conversation, and whatever git history shows.In files: the spec, one card per piece of work, the proof, and the handoff.

From each tool’s documentation: Claude Code · OpenCode.

The plan lives in scrollback

When the chat is summarized to make room, or you open a new one, what was decided goes with it. The next session starts from zero.

“Done” is a claim

The model says it works. Whether anything was checked, and how you would check it yourself, is left to you.

Yesterday’s rules are gone

The mistake you corrected comes back, because nothing wrote it down where the next session will read it.

Before and after

The difference isn’t answer quality. It’s that the project survives the session.

Starting a feature

without groundwork

youAdd voting to my book club app.

agentDone! A clean voting page with results and a summary.

Is it tested? What was I doing yesterday? Which parts moved?

with groundwork

you/gw a page where my book club votes on next month’s book

agentWho can vote? One vote or rank several? Hide results until it closes?

youAnyone with the link. One vote. Hide results.

agentSpec saved. Card 1.1: tests written, code passing, review passed. waiting for you

you/gw-approve

agentCommitted [1.1] Book list page. Next up: card 1.2 Voting.

The next day, a new session

a real run on the finished calculator · one run each

groundwork removed

youWhere does this project stand and what should we do next? Look around and tell me.

→ list the files in the repo→ git log --oneline -15; git status→ read folders outside the project… 50 tool calls in all

agentThere is no README, spec, handoff, or any file that says what the project is or what’s next — everything below had to be reconstructed from git history.

calls
27
tokens read
956k
cost
$0.0229
with groundwork

you/gw

→ read .groundwork/HANDOFF.md→ read the two phase 2 cards… 11 tool calls in all

agentWhere things stand: Phase 2 Browser UI is built — cards 2.1 and 2.2 are done and committed, the full suite is green (58/58), and the deploy is live. Nothing is in progress; it’s waiting on your phase review.

calls
9
tokens read
141k
cost
$0.0086

How it works

Small pieces of work, each proven, each approved by you.

An AI does its best work when the whole task fits in view. So Groundwork never hands it “build the app”. It breaks your idea into pieces small enough to finish and check in one sitting, and runs each piece through the same steps.
  1. 01

    Spec: say what you want

    You describe the idea in a sentence. The agent asks a few specific questions, suggesting the smallest useful version first, and writes the answers into SPEC.md. Choices like the language or framework are yours: it lays out options with trade-offs and records your pick.

  2. 02

    Plan: phases of cards

    A card is one small piece of work, named after the cards on a task board. It says what “done” looks like as a short list of checkable promises. Each card is small enough for one session, so the AI starts every card with a small, focused context.

    A phase is a group of cards that together give you something you can try, like a milestone. You can approve card by card, or once at the end of each phase.

    the calculator’s real plan

    Phase 1 · Arithmetic engine

    you can try: the math works, tested

    • card 1.1

      Number entry

    • card 1.2

      Operations and equals

    • card 1.3

      Clear and error state

    • card 1.4

      Result formatting

    Phase 2 · Browser app

    you can try: a working calculator page

    • card 2.1

      Page and keypad

    • card 2.2

      Wire it up

  3. 03

    Build: three roles per card

    Your main chat, the runner, never builds anything itself. It hands each card to three roles in turn. Each role runs as a separate session that reads only the card, its own instructions and the code the card touches, so none of them inherits a heavy chat.

    1. 1

      Tester

      Writes the checks first, before any code exists, one for each thing the card promises. Then runs them and confirms they fail, and fail for the right reason.

      why · A check that can’t fail proves nothing. “The right reason” means it fails because the feature is missing, not because the check itself is broken (a typo, a wrong file name). Then, when it passes later, you know the new code is what made it pass.

      card 1.1: all checks failed with “module not found”, because the calculator’s code didn’t exist yet.

    2. 2

      Implementer

      Writes the code, the smallest change that makes those checks pass, then runs every check in the project so nothing else broke.

      why · It isn’t allowed to edit the checks. So it can’t make them pass by quietly weakening them, a common shortcut when one AI both writes and grades its own work.

      card 1.1: wrote src/calc.js until all 11 checks passed.

    3. 3

      Reviewer

      Starts fresh, having never seen the work. Reruns everything itself, checks each promise on the card against what changed, and writes down what it couldn’t verify.

      why · Fresh eyes catch what the builder talked itself into. It can’t fix code, only pass the card or send it back with the problems listed.

      card 1.1: “Live browser check: attempted, not possible”, listed as a caveat for you.

  4. 04

    Approve: nothing is saved until you say so

    The runner stops and tells you, in plain words, what changed, how to check it yourself, and any caveats. /gw-approve saves it to your project’s history and moves to the next card. /gw-reject sends it back with your reason.

Every card moves through, in order

  1. 1to doplanned
  2. 2being testedtester
  3. 3being builtimplementer
  4. 4in reviewreviewer
  5. 5waiting for youyour turn
  6. 6donecommitted

↺ sent back: by the reviewer to the implementer, or by you with a reason. It goes around again.

Watch it happen on a real build →

What you get

You don’t need to read code to know what your AI did.

Groundwork keeps a plain-language record of the project that you, your AI and anyone you work with can read. Here’s what that means day to day.

You always know where things stand

A short note in your project says what’s done, what’s in progress and what’s next, in plain sentences. Every new chat reads it first.

“Card 1.1 Number entry is built and waiting for your approval.”

Nothing is “done” without proof

The AI writes the checks before the code, and a second AI that never saw the work reruns them. You get the proof, not a promise.

58 checks passing, each written before its code.

You stay in charge

Nothing is saved to your project’s history until you say so. Every stop tells you what changed, how to try it yourself, and what to watch out for.

What changed · How to check · Caveats → /gw-approve

Big ideas, small steps

Your idea is broken into small pieces you can follow one at a time. A typo fix stays a quick fix; a feature gets a plan.

a calculator → 2 phases → 6 cards

It learns from its mistakes

When something goes wrong, it’s written down. If it happens again it becomes a rule; if it keeps happening, it gets blocked outright.

note → rule → guard

Use the AI you already have

Works in Claude Code, OpenCode, or any AI tool that can read files. Switch tools or models halfway through; the project stays the same.

plain markdown files in your repo

What it costs

Catching up shouldn’t mean re-reading the project.

A fresh session in the finished calculator, asked where the project stands. Without Groundwork the agent has to rebuild the picture from files and git history; with it, it reads a short note.
Groundwork removed956,066 tokens read

27 model calls · 50 tool calls · $0.0229

With Groundwork140,682 tokens read

9 model calls · 11 tool calls · $0.0086

6.8×

fewer tokens to answer “where are we?”, and the answer was right. Without written state, catching up costs whatever there is to read, and a bigger project has more. One run each, on a small app, so read it as the shape to expect. measurements

Building has a cost too: three roles and a review per card. On a small app, a single chat is cheaper. See the full breakdown →

Start with one command.

Run it in a new folder or an existing project, then open your AI tool and type /gw. The docs cover the rest.

Read the docs →