From Playground to Builder — rebuilding the QuadKit Builder

The QuadKit Playground proved a simple idea: you can draw an application on a canvas and generate a real, standalone QuadKit project from it. This week, that workbench starts becoming the QuadKit Builder, with a rebuild aimed at one question — can you trust what it generates?

What it already is

The Playground is a visual node canvas: draw framework-shaped nodes, wire typed edges, and run one-way codegen — the canvas graph is the source of truth, and the output is a real project tree, not a mock. The generated project uses the same layout quadkit new project writes, so there is still exactly one project shape to learn.

It also lives inside the framework monorepo as a workspace member, which is why it could move fast: a framework change and the builder change that needs it land in the same commit, with no vendored copy and no patch protocol.

And the builder is a QuadKit application itself — its backend runs on the same framework it draws projects for, assembled from the same providers, contracts, and services the canvas generates. The tool and its output share one architecture, which keeps the generator honest: a feature the builder relies on is a feature the builder can draw.

What the rebuild is for

Right now the story ends at “generated files.” The rebuild moves it to “generated files you can check”:

• Project state, stated once. A summary and lifecycle derived from the backend — what this application is and what state it is really in.
• A completion list. What remains unfinished, and why — unknown emitted stubs default to implementation-required rather than being quietly counted as done.
• Generation proof. A durable record of what the last generation actually resolved, produced, and tested. A preview is never called tested; only a real generation pipeline can create proof.
• A run-locally handoff. The same facts the generated README and environment file use, so “run this next” is one step, not an archaeology exercise.

The same honest-preview rule applies to the module and stamp drawers: before anything is placed, you see its actual graph consequences — not a marketing summary.

On the roadmap: agents you can draw

The most interesting part of the plan is agent authoring. New node kinds join the palette — agent, tool, model, knowledge, guard, and approval — under an Agents category next to the existing entity, use-case, and route nodes. Wire them on the canvas and the same chain runs:

1. Validate the graph — kinds, ports, and cross-node rules, with refusals that say why.
2. Preflight the distributions it needs, so a missing package is a blocker up front rather than a failed install at the far end.
3. Generate a standalone project with the CLI’s own generators, plus the glue the agent nodes need.
4. Prove it — deterministic offline tests and a completion record, exactly like the existing entity and route chain.

That last point is the design bet: agent authoring is an extension of the builder’s existing chain, not a parallel product. The same graph, the same proof requirements — draw an agent graph, receive a runnable, tested QuadKit project built on the QuadKit packages.

Try it

The rebuild lands over the coming weeks at builder.quadkit.dev; the current workbench keeps running until then. Under all of it, the stable architecture rules are the contract — the builder draws projects, it does not invent a second layout.