From idea to product, without the mess
Groundwork is one folder of rules that steers any AI assistant: memory on disk, built-in discipline and automated checks, at enterprise level.
## Session protocol 1. Read the handoff block at the top of docs/state/STATE.md before anything else. 2. Work one task at a time. Decide what is not the owner's; ask the rest, one question per reply. 3. Reply in the owner's language: what changed, what you decided, the one next step, then ⚓. 4. Before ending a session: update STATE.md.
Real fragment, shortened. Copy the folder, say "begin", and this protocol steers every session.
AI is powerful, but without structure it builds a mess
An AI assistant writes code fast. But it forgets what happened yesterday, sometimes guesses from outdated knowledge, drifts into work nobody asked for, and can leave your data lying in the wrong place. Groundwork fixes exactly those four things.
Five simple parts that work together
You do not need to read a line of code. At its core, Groundwork is a set of agreements and automated checks that force the assistant to work cleanly and safely.
Six reasons, honestly explained
No promises, only built-in working methods: every reason below can be found in the folder itself.
Skills, each an expert for one task
A skill is a written-out working method the assistant picks up at the right moment, grouped along the route from idea to maintenance.
One continuous route
Groundwork guides the whole life of a product, not only the building. Click a phase.
Checks that let nothing through
These run automatically at every commit and every publish. They cost no tokens, and the rulebook forbids bypassing them: a closed gate is information, not an obstacle.
What Groundwork is not
Trust comes from honesty. These are the limits, said plainly.
How to start
Groundwork is a template. Copy it and your project starts with the rulebook, the skills and the checks already in place. Pick one of the three routes, and start with a clean history: your project deserves its own first commit, not ours.
On GitHub
Click Use this template on the repository. You get your own repo with one initial commit and none of our history.
From the command line
One command copies the latest snapshot without history:
npx degit Tradebaas/Groundwork my-project
degit drops the .claude/skills symlink. Restore it once,
or let begin repair it:
ln -sfn ../.agents/skills .claude/skills
As a ZIP
Rather not install tooling? Download the folder with the green Code button and unzip it. Unpacking drops the same symlink, and the same one line above restores it.
Already have a project?
Groundwork lays over a repo that exists, without touching its history. Take a copy the same way, next to your project, and run the one command the README gives: it adds the framework and skips every file you already have, so your own README, licence, ignore file, changelog and page stay yours. Then say begin as below. It checks the framework landed whole, reads which of the two situations it is, keeps your git history, takes the interview's answers from your code first, and counts the first run of the checks as a measurement of where you stand, not as a verdict.
Then open the folder in your editor or assistant and say
begin (or load the skill begin). Already have a PRD, a project description
or only a vague idea? Paste it in: begin uses that as the source and asks only for what
it leaves open. From there it sets up git and the checks, and proposes the first real step.
You need Node.js 22 or newer for the checks; the rest is your AI assistant.
Versions, and taking later improvements
Groundwork keeps moving after you copy it. Nothing changes under your feet: from its first commit the copy is your own repo. What you do get is a way to see what moved since, and to take only the parts you want.
Every release is tagged. Each version carries a git tag and a section in the changelog, so a copy can say which Groundwork it holds and what has happened since: releases and changelog.
Improvements travel by hand. Read the changelog from your version forward, copy in the files you want, and keep everything you have made your own. There is no updater, and there will not be one: by then your copy has edited skills, tuned checks and rules of its own, and merging that safely is a package manager rather than a framework. The reasoning is recorded as a decision.