roadkeep
A CLI and Claude Code plugin that owns the writes to a project's planning files, run this way from its first days.
1,946 commits over 45 active days · Python
A practical guide for anyone who wants to run a software project with an AI agent as the main author. It says what to set up, what to watch for, and why, and every piece of advice links to what actually happened in the projects it came from.
Claude Code wrote most of the code in the 5 projects below, with one person deciding what to build. Their histories were read commit by commit, and every failure that repeated, and every fix that held, was written down as a finding. The rules on this site are built from those findings, and each rule says which findings it rests on.
A CLI and Claude Code plugin that owns the writes to a project's planning files, run this way from its first days.
1,946 commits over 45 active days · Python
A Claude Code plugin for making 3D assets on Blender, Godot and a generative mesh service, run this way from its first days.
132 commits over 3 active days · Python
A free Docker desktop for Windows, run this way from its first days.
444 commits over 21 active days · C# (.NET, WPF)
A library and Claude Code plugin that drives a Windows desktop application from a test, run this way from its first days.
708 commits over 23 active days · C# (.NET)
A content management system, adopted the practice after years of history.
3,446 commits over 515 active days · Java (Spring), JavaScript (React)
An agent will tell you a task is done, a test passes or a rule was followed, and it believes it. Across these projects, those claims were often wrong in ways nobody saw until later. So the practice moves trust away from what the agent says and onto things that can be checked: files, tools, tests and the person.
The loop, as the specification describes it. Each box is a chapter: the human role, planning, guards, verification and commits.
Each card is one lesson in plain words. The tags under it are the proof: an F tag opens a finding with its sources, and a rule tag opens the rule that turns it into something you can adopt.
Claude Code reads CLAUDE.md, and everything it imports, at the start
of every conversation, so every line in it is paid for on every turn. In the
projects studied it kept growing until an automatic check refused the next
addition. A note saying "keep this short" did not stop it.
What worked: make it an index, move what only some tasks need into skills that load when needed, and give those files a size limit of their own.
Rules that lived only as sentences were broken, including by the repository that wrote them. An instruction to keep planning notes brief was ignored; a limit that refused the text at the moment it was written held.
What worked: for every rule the agent actually broke, add a hook or a test that fails when it breaks again, and let the sentence point to it.
The backlog, the changelog and the decisions live in the repository, where the next session can read them, and a tool writes them so their shape cannot drift. Agents also file tasks that describe nothing wrong, and designs written up front were often overturned once the work began.
What worked: record the problem rather than the planned fix, and file a task only when something is actually wrong or missing.
A written "one task per commit" rule did not prevent commits that shipped several tasks. Commit tools that stage everything swept in logs and other sessions' work, and two sessions sharing a folder committed each other's changes.
What worked: close each task before starting the next, and add files by path,
never git add -A.
Checks that ran only on one machine let failing tests reach the main branch without anyone noticing. Tasks were closed with no check covering what was committed, and some checks reported a pass over work that never ran.
What worked: run the checks in CI on every push, treat "could not run" as a failure, and never call a task done before its checks pass.
A count or a list written by hand goes stale without a sound when the thing it describes changes. This happened in all five projects.
What worked: generate figures from the source, or check them against it. Every number on this page is computed when the site is built.
Work that needs a person's judgement, or hardware the machine does not have, cannot be finished by the agent. Tasks recorded as shipped were later found not to work, because the record held the agent's own claim.
What worked: let that work wait with its reason written down, and let the person set the bar for "good enough".
Text passing through a Windows shell, a codec or a line-ending conversion changed silently, in all five projects. Where several copies of a tool were installed, sessions ran an old or unintended one without noticing.
What worked: declare line endings and encodings, check them byte by byte, and make sure exactly one copy of each tool answers.
Two projects ran the same jobs twice: once through a path built for the agent, and once through the ordinary API the application already had. The agent's path cost a fraction of the tokens. The saving came from asking fewer, narrower questions, such as finding a page by its path or getting one verdict instead of reading every page. It did not come from REST, a CLI or MCP as such: in one project the cheaper path was REST as well, and cleaning up the ordinary API narrowed the gap.
What worked: keep a few real tasks, run them both ways in a test, and fail the build when a task gets more expensive. Where the agent has a shell, a command can do the job of an MCP tool without adding to what every session loads. Editing files instead of calling an API was cheaper in one measured task, mostly in what the agent had to write, since it must read each file before changing it; that is one measurement, not yet a rule. What a project's own sessions cost per task can now be counted too, but no one has yet shown a budget on it catching anything.
Estimated tokens in the every-turn instruction files, paid on every turn (bytes divided by four), counted at each project's pinned commit. Lesson 1, finding F1.
| Project | Bytes | Tokens (estimate) |
|---|---|---|
| Shio | 27,831 | 6,957 |
| roadkeep | 8,628 | 2,157 |
| polyweave | 4,362 | 1,090 |
| freewilly | 2,169 | 542 |
| winwright | 1,192 | 298 |
The order matters: each step protects the next. The guards exist before the first plan file, and the checks exist before the first feature. The repository ships templates for every file, so you fill them in rather than write them.
One script writes the instruction file, settings, skills, ignore rules, line-ending rules and a CI workflow.
Hooks refuse hand edits of the planning files and ask before a push or a hard reset.
The planning tool writes the backlog, changelog and decisions, with length limits on what goes in them.
Describe the project in a short index, then set its size budget just above where it landed.
A commit skill (one task per commit, stage by path) and a writing skill (language, style).
Choose how far to go, 1, 2 or 3, and record it where the checker reads it.
Your build and tests run on every push, before the first feature is written.
Run the conformance checker, fix what it reports, and make a first commit with no code in it.
Six choices are yours, not the agent's, such as whether commits name the agent and how broad its permissions are. The full walkthrough, with the commands, is the new-project guide. For an existing codebase, or one that has drifted, see the existing-project and realignment guides.
You do not have to adopt everything at once. Each level includes the one before it.
The agent is told little and precisely, planning goes through tool-written files, and each task lands as its own commit. Costs a config file, a planning tool and a habit.
Nothing is done until a check passes, checks run in CI on every push, and guards stand behind the rules the agent broke. Most recorded failures were stopped here.
What the project says about itself is generated or checked: figures, lists and size limits. Costs the most, and pays off as the project grows.
Every rule of the specification, counted by chapter and level. The agent-facing profile applies only to projects that ship tools for other agents.
| Chapter | Level 1 | Level 2 | Level 3 | Agent-facing profile | Total |
|---|---|---|---|---|---|
| IS Instruction surface and context economy | 3 | 0 | 3 | 0 | 6 |
| PG Planning governance | 6 | 0 | 0 | 0 | 6 |
| CD Change discipline | 6 | 0 | 0 | 0 | 6 |
| VG Verification gates | 0 | 7 | 2 | 0 | 9 |
| GH Guards and hooks | 0 | 5 | 1 | 0 | 6 |
| PS Permissions and safety | 2 | 1 | 0 | 0 | 3 |
| EP Environment portability | 0 | 6 | 0 | 0 | 6 |
| AP Agent-facing product surfaces | 0 | 0 | 0 | 6 | 6 |
| HR The human role | 1 | 1 | 0 | 0 | 2 |
| CS Concurrent sessions | 0 | 4 | 1 | 0 | 5 |
| AW Agent-written prose | 1 | 0 | 2 | 0 | 3 |
Each finding gets two grades. Recurrence says how widely it was seen, from R1 (once, in one project) to R4 (in all five). Strength says how well it was established, from S1 (someone wrote it down) through S2 (an incident was recorded) and S3 (it was counted) to S4 (a test fails when it stops holding).
Each cell counts the findings with that pair of grades; the stronger the shade, the more findings. The top right is the strongest evidence.
Rows: recurrence, R4 seen in all five projects. Columns: strength, S4 held by a test that fails.