Most of the notes in this garden are variations on the same three lessons. Write the plan before the code. Verify the outcome, not the machinery. Write the mistake down where the next session will read it.
I know all three. I have written all three up. And I still skip them when a task looks small and the day is short.
So I stopped treating them as things to remember and turned them into a set of commands. It is called Shipline. It lives in my Claude Code config and works in any project on the machine.
What it actually does
Six phases, and three places where it stops and waits for me.
plan -> build -> verify -> test -> retro -> deliver
| | |
I approve I run the test I permit
the plan script the commit
The gates are the entire point. An agent that pauses for approval is not slower in any way that matters, because the alternative is reviewing a thousand lines after the fact and pretending that is the same thing.
Four documents or it is not done
Every piece of work produces the same set, and the agent is told that a missing one means the work is incomplete rather than nearly complete.
| File | What it has to contain |
|---|---|
plan.md | Ordered steps, acceptance criteria a stranger could judge, risks, and what is explicitly out of scope |
testscript.md | Numbered cases I run by hand, failure paths included |
retro.md | The actual error, the actual fix, and the command that proved it |
runbook.md | Cold-start instructions for someone who has never opened the repo |
The test script matters more than it looks. The agent does not grade its own work. If the only verification is the thing that wrote the code telling me it checked, I have a confidence report, not a test.
The part that compounds
Every retrospective has to answer one question: what rule, written down in advance, would have prevented this?
If there is an answer, it becomes a numbered guardrail in a project file, phrased as a standalone instruction to whoever reads it next. Those load back into context before every future plan and build. The file is append-only.
- id: G4
title: Check the full config precedence chain before debugging
severity: warning
discovered_in: S02
injection: >
When configuration does not take effect after editing appsettings,
check the precedence chain BEFORE changing code: user secrets,
then environment overrides, then appsettings.{Environment}.json.
User secrets persist across sessions and are invisible to git grep.
This is the CLAUDE.md footguns idea with the collection step made mandatory instead of remembered. A mistake that costs an hour costs it once.
If that file is still empty after four or five pieces of work, it does not mean nothing went wrong. It means the retros are being written to look good.
What I deliberately left out
I adapted this from a heavier framework that had eight specialist agent personas, confidence scores and an evidence-validation protocol. All of it read impressively and none of it did any work. It was documentation describing documentation.
What survived is small: a config file that is the single source of truth, three artifacts per story plus a runbook, gates that actually stop the agent, and the guardrails loop.
I also made a point of keeping my own habits out of the tool. Commit style, date format, how far it may go on a remote, emoji, whether every story gets a branch: all of that is a config block that starts empty and permissive. Someone else installing it gets the pipeline and none of my preferences. A workflow that smuggles in its author's taste as though it were engineering is a worse workflow.