I have two side projects running. One is a personal knowledge graph. You send it documents, emails, notes, and it builds a temporal graph in Neo4j with semantic search on top, plus an agent that can query across all of it. The other is a family app. My wife, my kids and I use it to coordinate, track what needs to get done, keep a shared calendar, and pull things off the school site that we would otherwise miss.
Different stacks. Different scope. Same first two days.
Both times, before I wrote a line of the actual project, I was writing a CLAUDE.md. Deciding which subagents exist. Deciding how they hand work to each other. Deciding what has to be true before a change is accepted. None of that is the project. It is the scaffolding you need before you can build the project with agents at all, and I was rebuilding it by hand every time.
What kept breaking
Three things, and they showed up on both projects.
The session boundary. I open a new session and the agent has no idea what was done, what is half-finished, or where to start. I spend the first ten minutes explaining my own project back to it. Sometimes it decides on its own where to start, which is worse.
Context growth. It grows until the agent can no longer hold the whole change in one pass. That is the point where it starts filling gaps with plausible fiction, and the fiction reads exactly as confident as the parts it actually knows. Nobody can tell later, including me.
Scope. I ask for one change. It edits three other files it was never asked to touch, does not mention it, and breaks something that was working. I find out two commits later.
None of these is a model problem. Every one of them is a control problem. The agent has no durable memory of the plan, no boundary on what it is allowed to touch, and no obligation to verify anything before it reports done.
The harness fixes it, and then does not transfer
The fix is a harness. A state file that survives the session boundary. Stories scoped small enough that the change fits in context. A check that runs after every change and is allowed to fail. An implementer that is not the same agent as the reviewer.
I have built these by hand. They work. The problem is the next project.
A harness does not transfer. The one I wrote for the knowledge graph knows Neo4j, knows my check command, knows my migration path. Point it at the family app and every instruction in it goes soft. A vague instruction to an agent is not a weaker instruction. It is an invitation to improvise, which is the failure I was trying to prevent.
The generic version has the same problem in a different shape. Write a harness abstract enough to fit any project and you get a scoper that does not know your ORM, so it writes briefs that could mean anything.
Size is the other half of it. A heavyweight harness on a small project gets bypassed. You skip the review step because it is Sunday and the change is two lines. That is worse than having no review step, because the harness still says the change was reviewed. A gate you route around lies about what is being checked, and you believe it, because you wrote it.
The part I got wrong first
My first instinct was to build a harness generator. Feed it the idea, get the harness.
That does not work, and the reason is not obvious until you try it. A harness is a set of instructions about a thing. If the thing does not exist yet, the instructions have nothing to point at. The scoper has no design to cite. The reviewer has no acceptance criteria to check against. You get a harness that is fluent and empty.
So the generator has to do the design work first. It stopped being a harness generator and became a setup chain. I call it Project Setup Kit.
What it does
You install it into an empty repo and run one command. It interviews you about the idea until it has enough to write a brief. It locks the stack and records why, as ADRs, so the decision does not get re-argued in month two. It writes a technical design document against a fixed section map, so that every agent downstream can cite section 4 and mean the same section 4. It scaffolds the repo with a check command that is green from cold and red when something is broken.
Then it generates the harness. Before the plan exists, which sounds backwards until you see the audit step. Because the design already exists, the harness is specific. It knows the check command. It knows the database and the migration tool. It knows the commit format and the file paths. It has a migration review gate only if there are migrations. A design token lint only if there are design tokens. No ORM, no migration gate.
It is sized to the build. Under about fifteen stories you get a single build loop and no gates. Fifteen to fifty you get a scoper, an implementer, an independent reviewer, and a regression gate. Fifty and up adds epic boundaries and the full gate set.
Then it writes the plan: epics, stories, dependencies, acceptance criteria that can actually be tested. And then it audits what it just wrote. The plan gets checked for dependency cycles, for acceptance criteria that cannot be tested, and for a story count that says the harness was sized wrong. In that case the chain goes back and re-forges the harness before going on. The harness gets audited twice, once when it is forged and again at the end against the assembled repo, for skills that demand a tool their agent was never granted, files that are written and never read, gates that can never be reached. Setup does not finish until both come back clean.
After that the plugin is done. The harness belongs to the project and runs the build without it.
The decisions I would defend hardest
The register of what is not specified. The design step will hit things the interview never answered. It has to be allowed to say so, in a section built for it, rather than inventing something plausible. That much I expected.
What I did not expect was the first real run. The design step honestly refused to specify a mechanism it had no information about. Correct. But nothing enforced that refusal, so the next step happily wrote acceptance criteria for the missing mechanism anyway. The honest gap gets laundered into a confident requirement one step downstream, an engineer builds it, and a reviewer passes it. So now every register entry is marked blocking or deferrable, and the backlog step refuses to run while anything is blocking.
Every machine loop is capped. The human loop is not. Three rounds, then it stops and tells you. The one loop that waits on a human answer is deliberately uncapped, because a person taking three passes to decide what they want is not the failure mode. An agent retrying against itself is.
A glossary, not just a section map. Fixed section numbers mean two agents can cite the same place. They do not mean two agents use the same word for the same thing. So the design doc carries a glossary: the term, what it means, the synonyms to avoid, and the name it goes by in the code. Now "the reviewer used the wrong word" is a defect you can check, not a matter of taste.
Signals live in files, not in replies. Any verdict that exists only in an agent's return message evaporates. The next step runs in fresh context and never sees it. This one is small and it cost me more time than anything else in the build. A verdict has to be a marker written into a file, or it did not happen.
Where it is
The full chain runs end to end. I proved it on a deliberately small test project, small in scope but real in structure: a database, an API, one architectural decision that could plausibly have gone the other way, and one thing I genuinely had not decided. A toy with none of those tests nothing.
That is one run, not a year of production use.
The repo is here: https://github.com/santiagodsm/project-setup-kit. Install it into an empty repo, run the command, and point it at an idea you actually care about. I want to know where it breaks. Three things specifically: whether the interview asks enough, whether the design doc it produces is genuinely citable or just reads well, and whether the harness it hands you is one you would keep or one you would immediately start deleting.