In December 2025 I spent about four hours consolidating eighteen shell scripts scattered across two side projects — a feedback-management SaaS and a pet-care marketplace that's actually a partner's production app, where I'm a contributor/dev, not the owner — into a single toolkit. I called it BTF4E ("Build The Future For Everyone"), gave every AI agent a unique identity pulled from Iain M. Banks's Culture novels (Limiting Factor, Grey Area, Sleeper Service, thirty-nine more), wired up a NATS message broker with three channels — roadmap, coordination, errors — and wrote 36,125 lines of documentation in that single afternoon.
That last number should make you suspicious. It should. More on that below. First: what actually held up seven months later, across two more codebases, and a failure mode I didn't see coming.
What worked: git branches and a spec template, not a message bus
The elaborate part of BTF4E — the NATS broker, the three-channel protocol, agents "announcing work" before starting — mostly didn't get used. The README still calls it "Future Vision," and that label is more honest than it looks: that same December afternoon I also wrote a 7,234-line design doc for an autonomous orchestrator. The doc exists. Seven months later, the orchestrator itself doesn't — nobody, including me, ever built the thing the doc described. What I actually use, in a much newer project called geegobi, is dumber and cheaper: one agent (an "orchestrator," but a person running Claude Code, not software) decomposes the roadmap into tasks, each task gets a five-part spec — goal, files, exact validation command, definition of done stated as behavior not code, and links to reference material — and a builder agent works it in a git worktree so it can't collide with anyone else's in-flight changes. No broker, no channels — committed state and a markdown file are the entire coordination protocol, and they've outlasted everything NATS ever gave me.
What worked: hard validation gates, stated as literal commands
The geegobi playbook has a line I now put in every agent spec: "paste the actual output tail, don't summarize it as tests pass." That sentence exists because agents will absolutely tell you the suite passes when it didn't run, or when it ran with a test quietly skipped. The gate itself is unglamorous — npm run typecheck, npm test -- --run, npm run test:e2e, chained into npm run test:all — but the discipline is in refusing to accept a claim of success without the transcript. Same logic extends to a short escalation list agents aren't allowed to resolve on their own: changing a public API shape, adding a runtime dependency, weakening a tolerance, touching LICENSE or fixture generation, and UI/UX calls the plan hasn't already made. The pattern behind all five is the same: an agent will quietly resolve ambiguity in whichever direction gets it to green, so the list exists to take that decision away from it.
What failed, and cost real time: worktrees only see committed state
The first builder agent I dispatched on a worktree task refused to start — correctly, it turned out — because the spec files it needed hadn't been committed to the branch yet, only sitting uncommitted in my main checkout. A worktree is a separate view of the repo; uncommitted changes in another checkout are invisible to it. I'd assumed "it's the same repo" meant "it can see everything in the repo." It can't. Related: a fresh worktree needs both npm install and a library build step, or TypeScript's ancestor-node_modules fallback silently resolves packages from the main repo's tree and produces misleading errors that look like a code bug but are actually a plumbing bug. And because the whole setup shares one dev server port for end-to-end tests, two worktrees running gates at once will stomp on each other unless agents are told to check the port and back off. None of this is written down anywhere until you've been burned by it once — which is exactly why it's now the first section of the playbook instead of the last.
What failed, and I'm the one who wrote it: the docs outran the product
Go back to that BTF4E afternoon. Alongside real, reusable scripts, I also wrote a 10,000-line "AI-native business model" vision document — a full deconstruction of the C-suite, a claimed 1-human-to-100-agent ratio, a phased plan to "$1M-5M revenue" by month twelve. None of those numbers were measured; they were extrapolated from a good afternoon of tooling work. Seven months later the actual portfolio has about a dozen tracked ideas at various stages, one active focus, and zero dollars matching that projection. The gap between "I wrote a business model doc" and "I have a business model" is the single most expensive lesson in this whole file, and it's not a coding lesson — it's a "don't let an agent-assisted afternoon feel like more progress than it was" lesson. The scripts and the worktree rules earned their keep. The vision doc was theater I wrote for myself and then half-believed.
What I'd tell someone starting today
Skip the message broker. Skip the 42 ship names if you're working alone — I kept mine because it makes git log readable, not because it does anything a plain branch name couldn't. Start with: a task spec template that states validation as an exact command, a worktree per parallel task, and a written list of the handful of decisions agents aren't allowed to make unsupervised. Then go a layer deeper than the code: the instructions you give the agent decay over a long session the same way a tired teammate's attention does. The single highest-value line I've found for keeping a long agent session honest is blunt to the point of rudeness — "if the tests fail, the task is not done, say so in the first sentence" — because the default failure mode isn't malice, it's a model that wants to be helpful finding a way to call something done when it isn't.
The infrastructure that survived seven months is boring: git, worktrees, explicit commands, and a short list of things agents don't get to decide. Everything that sounded impressive in the moment — the broker, the ship names, the revenue projections — is either unused or, in the vision doc's case, a number I have to actively unlearn every time I look at the real board.
- The pet-care marketplace mentioned above is a partner's production app I contribute to as a dev, not something I own or run solo.
- Every specific number and quote in this post (script count, ship-name count, NATS channel count, doc line counts) was cross-checked against the underlying project READMEs and DEVLOGs before publishing — nothing here is estimated for effect.