There is no template repo behind this. A selection goes through five stages,
each one a file in packages/core/src, and a whole repo comes out the other
end. The same selection gives the same bytes every time.
The stages, in order:
registry/ -> loader -> resolver -> mergers -> compiler -> generator -> your repo
registry.ts resolver.ts merge.ts compile.ts generate.ts
Each section names the real file and function, so you can read the source alongside this page.
1. The registry is the product
registry/ holds every plugin. A plugin is a folder: a stack, a battery or a
design. The generator has no idea what your battery is called. It reads the
folder, sorts it, and merges whatever it finds.
registry/<stacks|batteries|designs>/<id>/
manifest.yaml required
template/ copied into the generated repo
agent/
rules/*.md path-scoped conventions
skills/*.md slash commands
agents/*.md subagents
hooks/*.md hook definition plus its inline script
solutions/*.md long-form docs, also published at /cookbook
design.yaml designs only: the token set
DESIGN.md designs only
Today that is 1 stack, 26 batteries and 31 designs, plus 3 presets.
loadRegistry(root) in packages/core/src/registry.ts walks that tree and
turns it into the typed Registry in types.ts. It parses the manifests and
reads markdown frontmatter through parseFrontmatter from markdown.ts. It
sorts arrays by id and normalises text (BOM stripped, CRLF folded). It is
tolerant on purpose. A
broken manifest is kept, not dropped, so validateRegistry in schema.ts can
report every problem in one pass instead of dying on the first one.
toIndex(registry) makes the RegistryIndex: manifests, per-plugin counts,
presets and the tested pairs, with no template bodies and no absolute paths.
That is what the browser gets, which is how the builder re-resolves your picks
on every click with no round trip.
2. The resolver decides what is legal
packages/core/src/resolver.ts takes a raw Selection and returns a
ResolvedPlan. It is the only stage that says no. It also runs in the browser,
so it has no filesystem, no clock and no randomness.
resolve(selection, index) runs these passes:
- Auto-add from
requires. Better Auth needs an ORM, a database and email, so picking it adds Drizzle, Neon and Resend. Each addition comes with anauto-addedexplanation and a sentence saying why, which the builder shows inline. The pass runs until nothing changes, and a cycle is reported asrequires-cycleinstead of looping. - Stack compatibility, from each manifest's
compatibleStacks. - Declared conflicts. A
conflictsentry names a plugin. Supabase Auth conflicts with Neon, so you getconflict, not a repo with two databases. - One choice per category, reported as
category-conflict. - The admin panel needs an auth provider:
admin-needs-auth. - The tested set. Covered below.
- Recommendations.
recommendsnever adds anything. It emits awarn.
The plan carries the final selection, the plugin ids in a fixed order (stack,
then batteries by category then id, then design), every explanation, the six
counts behind the counters, and ok. When ok is false, generate refuses to
run rather than write a repo that can't boot.
isSelectable(batteryId, selection, index) is the same machinery pointed
sideways. It resolves your selection with and without a battery and reports the
first blocking reason that battery adds. That is where the greyed-out options
and their reasons come from. Nothing in the UI decides what is legal on its own.
3. The mergers assemble the files
packages/core/src/merge.ts holds the ways two plugins can add to the same
output.
Token substitution. templateVars(selection) builds the token table and
substitute(text, vars) applies it to every template file, every
contributes.scripts value and every markdown body.
| Token | bun | pnpm | npm |
|---|---|---|---|
{{pm}} | bun | pnpm | npm |
{{pmx}} | bunx | pnpm exec | npx |
{{pmDlx}} | bunx | pnpm dlx | npx |
{{pmRun}} | bun run | pnpm run | npm run |
{{pmAdd}} | bun add | pnpm add | npm install |
{{tsRun}} | bun | tsx | tsx |
{{tsServer}} | bun --conditions=react-server | tsx --conditions=react-server | tsx --conditions=react-server |
{{pmx}} runs a binary the repo already installed (prisma, drizzle-kit, tsx).
{{pmDlx}} fetches a one-off tool the repo doesn't depend on (neonctl, a CLI
pinned @latest). They differ under pnpm on purpose: pnpm dlx prisma ignores
node_modules and downloads the latest release.
Plus {{projectName}}, {{design}}, {{mode}} and the link tokens. A plugin
that writes npm run dev or npx prisma in a doc fails the template lint,
because that string is wrong for two thirds of users. The docs you are reading
use the same tokens: the tab strip above each command is substitute running
three times.
JSON deep merge. deepMergeJson(base, patch) owns package.json and
tsconfig.json. Keys are sorted on the way out, and arrays are concatenated
with primitives deduped, so two plugins adding dependencies give one stable
file.
MCP servers merge by name into one list, and a later plugin wins a shared name. The compiler writes that list into each agent's own config.
Slot fill. findSlots and fillSlots handle injection. Everything else is
a plain file copy with collision checks: two plugins writing the same path
raises CollisionError, not a last-writer race.
Slots
A stack template can leave a named hole:
{/* @slot providers */}
// @slot providers in TypeScript and <!-- @slot providers --> in markdown
work the same way. A battery fills one by name from its manifest:
contributes:
slots:
providers: "template/slots/provider.tsx"
Two rules keep this predictable. A slot a battery fills but nothing declares
fails bun run validate (slot-missing). It is never a silent skip. And an
unfilled slot line is deleted with its blank line, so a stack template reads
cleanly with zero batteries.
4. The compiler writes the layer for every agent
The agent layer is written once in a neutral format (the frontmatter shapes in
docs/architecture/CONTRACT.md). compileAgentLayer in
packages/core/src/compile.ts writes it out in two parts.
Every repo gets the shared layer, whatever you pick:
AGENTS.mdat the root, and one per rule folder (buildAgentsMdinagents-md.ts). The root file says what the app is, points atSETUP.mdfirst, then lists the agent setup and the repo-wide rules..agents/rules/<id>.md: every rule in full..agents/skills/<name>/SKILL.md: every skill, in the Agent Skills format..agents/agents/<id>.md: every subagent's prompt..agents/hooks/: one copy of every guard script, plusrun.mjs,guards.jsonand a README.
Then one block per agent target you picked. A target adds only what its agent
can't read from the shared layer. The list lives in targets.ts:
| Target | Output |
|---|---|
| Claude Code | .claude/rules/agents-md.md (imports AGENTS.md), .claude/rules/<id>.md with paths:, .claude/skills/, .claude/agents/, .claude/settings.json, .mcp.json |
| Codex | .codex/hooks.json, .codex/agents/<id>.toml, .codex/config.toml |
| Cursor | .cursor/hooks.json, .cursor/agents/, .cursor/mcp.json, .cursor/rules/<id>.mdc for linked rules |
| GitHub Copilot | .github/hooks/agentic-guards.json, .github/agents/<id>.agent.md, .github/copilot/settings.json, .mcp.json |
| Antigravity | .agents/hooks.json, .agents/mcp_config.json |
| Gemini CLI | .gemini/settings.json, .gemini/agents/ |
| OpenCode | opencode.json, .opencode/agents/ |
| JetBrains AI | .aiassistant/rules/agents-md.md, .junie/mcp/mcp.json |
| Windsurf | .devin/hooks.v1.json, .mcp.json |
| Kiro | .kiro/skills/, .kiro/settings/mcp.json, .kiro/steering/<id>.md for linked rules |
agentLayerPaths in agent-paths.ts lists the same paths without writing
them. That is how the builder draws the file tree in the browser, and a test
holds the two to the same list.
Path scoping is what gets translated. A rule's paths: becomes a folder:
ruleFolders takes the literal prefix of each glob, and the rule is written
into a nested AGENTS.md there. Claude Code gets the exact globs in
.claude/rules/ instead, and claudeMdExcludes keeps it from loading the
nested files as well. Each AGENTS.md chain, root down to a folder, stays under
30 KiB, inside the 32 KiB Codex reads. A rule that does not fit is linked to
.agents/rules/<id>.md, and Cursor, Kiro, Antigravity and (when Claude Code is
not picked) Copilot get a copy scoped to exactly the globs it was linked for.
Hooks are wired in the config of each agent that runs them. Every command
calls .agents/hooks/run.mjs <guard> --from <agent>, on bun in a bun repo or
node in a pnpm or npm repo. The launcher runs the TypeScript guard with Bun or
the repo's own tsx. Where the agent allows it, the command is anchored on the
project root ($CLAUDE_PROJECT_DIR in Claude Code,
git rev-parse --show-toplevel in Codex), so a guard still fires after the
agent runs cd.
See the agentic layer for which agents run which
guards.
MCP servers go out in each agent's own format (agent-mcp.ts). .mcp.json
stays in Claude Code's shape, with no tools key: Claude Code drops an HTTP
server that has one. Copilot and Devin Local read the same file.
5. The generator writes the repo
generate(plan, registry) in packages/core/src/generate.ts puts it together.
Order matters. Templates land first so slot markers exist to be filled. The
merged files go on top. The content hash is taken last, over everything except
agentic.config.json, which then carries it.
Along the way it builds the files no single plugin owns:
package.jsonwith the base scripts (dev,build,start,typecheck,lint,lint:fix,format,test,test:e2e,verify,verify:hooks) plus each battery's own..env.examplefrom every battery's declared env vars.SETUP.mdfrom their onboarding steps, sorted byorder, plus how to connect each MCP server in each agent you picked.README.md, with a table of the agents the repo is set up for.docs/solutions/seeded with each plugin's solution docs.docs/plans/with a README and a plan template.scripts/verify.tsandscripts/verify-hooks.ts, filled in for your picks.
Three small modules finish the job:
hash.ts(hashFiles): sha256 over the sorted path and content pairs.write.ts(writeRepo): writes to a folder, for the CLI and the matrix.zip.ts(zipRepo): builds the zip for the web download.
The tested set
The resolver refuses any battery pair that is not in registry/tested.yaml, a
sorted list of pairs. A set that exactly matches a preset skips the pair check,
because the matrix runs every preset whole. Everything else is checked pair by
pair, and a missing pair is an untested error, not a warning.
So the promise is per pair. Pick three batteries and each of the three pairs has passed the matrix. That exact trio may never have run together.
Only bun run matrix writes that file. For each combination it generates the
repo outside this monorepo, installs it, typechecks it, lints it and runs its
unit tests. With --build it also runs next build with no env set, boots the
app and loads every static route. --update-tested and --add-tested need
--build, and they write back only the pairs that passed. Edit the file by hand
and you claim a check that never happened. The resolver believes it completely,
and someone gets a repo that doesn't boot.
Two lanes go further than booting:
--dbgives each combo a fresh database on local Postgres. It runs the repo's own migrations and seeds (each seed twice, to prove it is safe to rerun), builds with that env and loads every route against the live database.--browserthen runs the repo's own Playwright specs against that server: sign-up and sign-in, the app shell,/pricingand checkout with no provider keys, and the admin pages. A spec that has no environment to run in skips with a reason, and the lane prints every reason.
With either lane the matrix adds 8 lane combos, which between them cover every
auth, ORM, database and payments battery. No Docker: Neon runs through the
repo's own db:proxy and Supabase Auth through its GoTrue and PostgREST
binaries.
shell
bun run matrix --db --browser --preset indie-saasIf the pair you want is greyed out, it isn't certified yet. From a clone of the generator (it runs on Bun), run the matrix for that battery's pairs and commit the result:
shell
bun run matrix --battery <id> --pairs --build --add-testedLeave out --pairs and no pair runs, so nothing new gets certified.
Determinism, and why it replaces sync
The output has no timestamps, no random ids and no absolute paths. Keys are
sorted before they are written, and files are sorted by path.
agentic.config.json in the generated repo records the full selection, the
plugin ids, the counts and the sha256 of the output.
That file is the V1 answer to "how do I get updates". There is no sync. Months
later you regenerate from the same agentic.config.json on a newer registry and
diff it against your repo. You see exactly what changed and take what you want.
bun run snapshot in this repo generates every preset twice in one process and
fails if the hashes differ, so the property that makes this work is itself
tested.
Read it yourself
| File | What it owns |
|---|---|
packages/core/src/types.ts | Every shared type. Never redefined elsewhere. |
packages/core/src/registry.ts | loadRegistry, toIndex |
packages/core/src/schema.ts | validateManifest, validateRegistry |
packages/core/src/resolver.ts | resolve, isSelectable, defaultSelection, selectionFromPreset |
packages/core/src/merge.ts | substitute, deepMergeJson, appendMarkdownSection, fillSlots |
packages/core/src/compile.ts | compileAgentLayer, hookCommand |
packages/core/src/agents-md.ts | buildAgentsMd, ruleFolders: the root and nested AGENTS.md |
packages/core/src/targets.ts | The 10 agent targets and what each one adds |
packages/core/src/agent-hooks.ts · agent-mcp.ts · agent-subagents.ts | Each agent's hook config, MCP config and subagent files |
packages/core/src/agent-paths.ts | agentLayerPaths: every agent file, for the builder's tree |
packages/core/src/generate.ts | generate |
packages/core/src/markdown.ts | parseFrontmatter, serializeFrontmatter, extractScriptBlock |
packages/core/src/hash.ts · write.ts · zip.ts | hashFiles, writeRepo, zipRepo |
Next: the agentic layer, which is what all of this exists to install.