Driving the factory

This is the part no other starter can write, because writing it requires having watched agents build on the thing repeatedly and having measured what came out.

Seven products have been built on this template by independent agents — three in the first round, three re-running those same specs against a later release, and one more after that. What follows is what actually worked, what did not, and the failures that were green the whole way through.

Seven is a small number and worth saying out loud. It is enough to see a pattern repeat across independent agents given identical material, which is what most of the claims below rest on; it is not enough to be sure about anything subtle.

The one thing to internalise

A green check is evidence about the checks, not about the code.

Every serious bug found across those builds passed every automated gate:

• A date form that silently blanked the field it was editing. lq check green, generated tests green.
• A comment form that hung on "Posting…" from the second submission onward. 252 unit and integration tests green; an e2e that posted one comment would have been green too.
• Three products that came out looking like the same unfinished app. Every gate green, because nothing measured how it looked.
• A schema transform that would have filed every $12.50 invoice for $1,250.

The gates are good and they are not sufficient. Everything below follows from that.

Give the agent a definition of done it cannot fake

lq check and pnpm test are the definition this template teaches, and both are mandated in AGENTS.md. Two things that matter more than they look:

Say that a feature with pages ships an e2e. pnpm test does not run Playwright, so a slice can be entirely green with its whole UI untested. Three agents in Round 1 shipped three complete UIs and not one wrote a UI test — not from laziness, but because the definition of done they were given never mentioned it. One sentence in AGENTS.md changed that: in the next round all three wrote their own specs unprompted.

Feedback timing beats feedback quality. The PostToolUse hook runs lq check --changed after every edit. Feedback arriving in the same turn as the mistake gets fixed; feedback arriving at review time gets argued with. That is the single highest-leverage piece of the whole setup.

Ask for the thing you actually want measured

The clearest result across the rounds came from a one-line change to the prompt, not from better tooling.

Round 1 produced three correct products that looked identical — byte-identical src/components/, the same globals.css, every page max-w-3xl. Nobody had asked how it should look, so nobody decided.

After the design system shipped, the same three specs were re-run and the products were better but still all on the default theme. Adding two sentences to AGENTS.md — pick a preset, delete the example slice — produced an agent that chose dense for a helpdesk queue and deleted the demo outright.

The lesson generalises: an agent optimises what you named. If the spec does not mention how it looks, you get whatever the template makes easiest.

Make it read a screenshot

The design failures were invisible to every automated check and obvious in a picture. Two ways to get that:

• Run pnpm test:e2e with a spec that screenshots the pages you care about, and look at the images yourself
• Point the design-critic and copy-reviewer agents at those screenshots

Both are cheap. Neither is a substitute for opening the app, and the second is worth distrusting when it finds nothing.

Keep the spec short and checkable

The specs that produced the best products were about ten numbered requirements, each independently verifiable. Not user stories, not a PRD — a list where every line can be confirmed or denied by looking at the running app.

Two specifics that paid off:

Name the rules the product actually has. "Deleting is allowed only for draft invoices, and the server must enforce it, not just the UI" produced a policy module and a test. "Handle deletion sensibly" would not have.

Say what is out of scope. Every spec ended with a short list — no PDFs, no real emails, no multi-currency. Agents will build what you did not exclude.

Let the generator do the boring twenty files

lq generate feature writes around twenty files that have to agree with each other, and generated shape is what makes the upgrade path possible at all. Hand-rolling a slice produces something no codemod can find later.

The measured effect is larger than it sounds. Between two rounds the generator learned to emit tone-mapped badges, sortable tables, detail layouts and a money field type — and every product in the next round got those without any agent deciding to. The floor moved, not the ceiling.

The corollary: if the generator emits it wrong, every product gets it wrong. A generator that emitted a delete affordance its own component library documents as an anti-pattern put that pattern in three products at once.

Have it keep a friction log

Every agent in every round kept a FRICTION.md — one dated line for anything that slowed it down, confused it, or forced a workaround.

This is the highest-value artefact of the whole exercise and it costs nothing. The troubleshooting guide is made of them. Almost every generator fix in the last two releases came from one.

Ask for specificity, and ask for the agent's own mistakes to be included and labelled. A friction log that only blames the tools is not much use to whoever maintains them.

Expect to be the one who looks

The honest summary: the automation catches what it was built to catch, and a person still has to open the app, read the copy, and ask whether this looks like a product someone would pay for.

Everything on this page is about narrowing what that person has to check — not removing them.