Groundwork
A project operating system for agent-assisted work.
Phases, rituals, and a small shelf of living docs, so your project stays legible as it grows.
Here is Frond, a fictional example project running on Groundwork. Every number below came out of its markdown at the last build, not out of this page.
Watering reminders
8 of 12 tasks done
How it works
Work happens in phases.
A phase is any chunk of work run through the rituals: written steps that fire when it opens and when it closes. It opens a board, a worklist in a markdown file, does the work, and closes by distilling itself away.
The rituals are written for a coding agent to follow. A briefing file is the agent’s standing context, and a session is one chat. The agent does the mechanical parts. You make the calls. All of it is markdown, so it works by hand too.
The opening ritual asks two questions: what does this phase read first, and what may it change? Every phase runs in one of three modes, and the mode is what answers them.
- Queue-shapingShapes what's next
An idea forms and nobody is doing it yet: capture it while it's fresh — a row on the queue and the seed behind it, holding the context the eventual phase will open from. The routine way work of any mode enters the queue when no phase's own open or close is doing it: add a row and write its seed, split one row in two, reorder what comes next, drop a row the project outgrew — or lay out a run: an idea bigger than one phase, shaped as an ordered set of rows with seeds, each seed naming the run and the kinds its board will pass through, inside a stated bound (a week, a date). Runs are editable, not fixed. It ends at the shaped queue — the phase launches in its own session, with fresh eyes on the seed.
- Reads first
- The indexes, then depth only where the idea touches. Shaping is a search problem, not a comprehension one: you need to know what already exists and where to look, not to hold the rule-set in context.
- Can change
- The queue — its rows in the ROADMAP's What's Next and their seeds in planning/queued/ — plus the tracker rows the idea absorbs.
- ProductBuilds the thing
A thesis, the change the phase sets out to make. Then the build, then a walkthrough you drive point by point. The deepest ritual of the four, because this is where the product ships. On its own a product phase runs open → build → close; inside a run it runs open → basic layer → survey → deepen → close, so the basic layer of everything exists before anything is polished (§ The phase pipeline).
- Reads first
- The strategy docs, whole. Then whatever this particular phase answers to.
- Can change
- Product code and feature docs.
- SystemTends the rules
The docs, the work model, and the dashboard itself. Always done together, never solo. It runs open → build → close, and its close has a kind of its own: export, for a fix that ships to adopters who are not in the room. A project built from the template runs one more, upgrade, which takes the template's changes in (§ The upgrade kind).
- Reads first
- The rules themselves — the standing sections whole, and the ones marked Read when only if this work fires them. The decisions log by its headings, opened where the work touches it.
- Can change
- The docs, the rules, the molds, and the code behind the dashboard.
- SideSweeps the small stuff
Small logged fixes, an open question, a research pass. Tracker-born work that runs alongside the other phases, usually several items at once (a sweep) rather than one. Runs as one chat, always — one kind, sweep or research, and never split (§ The phase pipeline). If an item grows a thesis it stops, because that is product work now. A sweep may also export the code it fixes — never the rules or the molds, which cross only from a system board (§ The export band).
- Reads first
- The items it pulled, and the docs for the code they touch.
- Can change
- The code it changes, and the tracker items it pulled.
What a phase may change has a name: its touch bands. Bands are levels of permission, from files a phase owns outright to files it can only suggest a change to. They limit editing, never reading.
Ideas do not arrive on schedule.
One will surface mid-phase that does not belong to the work in front of you. The agent is the one who notices, and it says so rather than quietly building the thing or quietly letting it go.
It proposes where the idea belongs: a small fix, an open question, or a phase of its own. You make the call, the agent records it, and the current work carries on.
Starting a session
Three doors in.
Every session begins with you arriving with something. Name the shape it takes, and the rituals follow from there.
An idea gets planned. The plan gets built. The small stuff gets swept. Three doors cover almost all of it.
Each door opens with a sentence like these. It names the mode and the shape of the work. The exact words are yours.
- Systemqueue-shaping
A new idea nobody is doing yet.
Run a system phase, queue-shaping: exports keep failing and nothing planned covers it.
The lightest door, and the routine way an idea enters the queue: the list of phases planned but not yet started. The idea becomes an entry there, with a seed, a small file that collects context until a later session opens it fresh. It can plan a phase of any mode.
- Any modephase from the queue
The next queued thing, ready to build.
Open [phase name] from the queue.
The seed already names the mode, so the rituals are set. Its notes fold into a fresh board, the entry leaves the queue, and the work gets the session to itself.
- Sidesweep
A pile of small fixes.
Run a side phase, sweep: P04, P07, and the empty-state bug.
P-numbers are punch list IDs, the small things you logged while doing something else. A sweep pulls them onto one light board and works them together. Straight in, no queue.
Every shape of work can go either way. Sweeps and rules fixes usually start now, because you find those rather than schedule them. Builds usually get planned first, because the session that builds then reads the plan fresh instead of grading its own.
Three doors is the short version. Seven ways in all, so here are the other four.
Two more shapes of work
Each can be started now or planned for later, exactly like the doors above.
Something to understand first.
Run a side phase, research: does the light premise hold before we commit?
A research pass. Understanding is the deliverable, not code.
Friction with the rules themselves.
Run a system phase: the close ritual keeps missing X.
The docs, the work model, the dashboard.
Two things that need no door
A board still open from an earlier chat.
Continue the [phase name] board.
Not a new phase. Its mode is already set, so its rituals are too.
Questions, reading, thinking out loud.
No mode and no board. The first edit is the line, and that is where a shape gets named.
Not sure which one you are holding? Open the queue-shaping door and say so. Naming the shape is part of its job.
A kind is a preset inside a mode: the same rituals, with a step or two tuned for work that recurs. Three ship, and you have met them all: sweep, research and queue-shaping. Keep reaching for a shape with no name, and you can add your own.
Rituals are yours to change too. The full model ships in the template, and the dashboard renders whatever version you run: here is Frond’s.
The one rule
Derived, never authored.
One rule holds the whole thing up. To change a page, you change its source doc. If the two ever disagree, the docs win, and the dashboard says so.
A hand-maintained dashboard is a second thing to keep true. That is the exact failure this system exists to prevent.
And the corollary: work leaves.
A closed phase is distilled and deleted. Decisions go to the log. Behavior goes to the feature docs. The board itself is removed.
History lives in git and in a compact archive. It does not sit in your working set, which is why the system stays readable at any size.
Get started
The first thirty minutes.
Copy the repo. The machinery is complete on arrival.
Run it, then open the dashboard. It boots clean against an empty project.
Work the kickoff board. It ships already open, and it is the one-time bootstrap that turns the template into your project.
Close it. The kickoff deletes its guide and replaces the README with your project's own. No onboarding left behind. What remains is your project.
The example
Somebody else's project.
The dashboard at the top could have been ours. It is somebody else’s on purpose.
A landing page for a work system, built with that work system, can only ever show you the work of building the landing page. That is a hall of mirrors, and it teaches you nothing about your own project.
So the demo is Frond instead: a plant-care app, three months in. A board open, decisions logged, questions still unanswered, and work already closed and archived.
A new project starts empty, with the same shelf and nothing on it yet.
The pages below are the same ones your own project would get. Only the docs behind them are different.
Who built this
Shawn Talvacchia
I built Groundwork because my own projects kept going illegible. Context scattered, docs rotted, and the agent rebuilt what it had already forgotten.
This site is built on it too.