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. Propose exactly one next step. 3. Before ending a session: update STATE.md. 4. End every message with ⚓ to confirm these rules are loaded.
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, then move its contents into your project root, minus the four files that
describe a product rather than the framework: keep your own README.md,
LICENSE, .gitignore and index.html. Then say
begin as below. It reads which of the two situations it is: your git history
stays, the interview takes its answers from your code first, and the first run of the
checks counts 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 20 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.