A Project Template That Fixes Itself

Every new project I start begins the same way: a GitHub repo, an issue template, a CI file copied from whatever the last project used, and a set of instructions in a CLAUDE.md file that goes stale within a week. I have done this setup by hand enough times to know exactly where it breaks. A step gets skipped. A fix I made in one repo three months ago never makes it into the next one, because there was never a way for it to travel there. So I built a template that does the setup once, properly, and then keeps itself in sync with every project it creates.

It is called agent-scaffold: a Copier template you copy into a new project directory, answer a few prompts, and get GitHub scaffolding, a Claude Code baseline, and a working multi-agent orchestration pattern already wired up. The scaffolding itself is not the interesting part. Two design choices underneath it are, and so is the bug that nearly broke the entire point of the project on the day it shipped.

Tasks, not roles

Most multi-agent setups I had used before this assign fixed roles: one agent plans, one agent codes, one agent reviews, each carrying its own persistent identity and its own accumulating slice of context. That works until a task does not fit neatly into one role, or a role's context window fills up with history that has nothing to do with the task actually in front of it. I decided against that pattern on purpose. agent-scaffold keeps no standing roster of agents. Every unit of work is a GitHub Issue, sized from the start to fit inside one agent's context budget. An agent picks up an issue, does the work the issue describes, and closes it. Nothing about it remembers being "the reviewer" from the last task, because there is no "the reviewer." There is only the next issue.

A template that edits itself

The part I actually wanted was a feedback loop. Every project generated from agent-scaffold gets a .copier-answers.yml file recording exactly which version of the template it came from. Run copier update inside that project later and it diffs the project against the template's current state, offering the difference as a local, reviewable patch, the same way a merge conflict works. So if I fix something in one generated project (a broken CI step, a labeling convention that turned out to be wrong) that fix can be pulled back into the template itself, and every other project built from it can pull it forward in turn. The template does not only generate projects. It learns from them.

The bug in the thing whose job was catching bugs

That whole story rests on one small, easy-to-miss detail. Copier only writes .copier-answers.yml, the exact file the propagation loop depends on, if the template ships a specific file of its own: {{ _copier_conf.answers_file }}.jinja. Miss that one file and copier copy still runs without complaint, the project still gets created, everything still looks fine. The only thing missing is the one file that makes the self-improving story actually true.

It was missing. I built this template across ten separate tasks, reviewed each one as I went, and still shipped it without that file. A final, separate review pass, deliberately run in a fresh context that had not written any of the code, caught it before the branch merged. The tool whose entire purpose was giving projects a way to receive fixes could not, itself, have received one.

That is worth sitting with. The bug was not in a feature. It was in the plumbing that made the whole premise of the project true, and it was invisible from inside the same conversation that had built it. Finding it took a second pass, from outside that context. I have started treating that as the real argument for structuring a template this way at all: not that any one agent gets it right the first time, but that a fix like this one, once found, propagates outward to every project built from the template instead of sitting fixed in a single repo while everything else built from it stays broken in exactly the same way.

agent-scaffold is on GitHub now, public and marked as a template, if you want to copy it into a new project or read the design spec behind it.