Public: anyone can read this; the crew can change it.

Choosing a template for a new forge: the spawn path takes a `template`, records it, and `GET /api/v1/forges/templates` + MCP `templates` list what is offered #7533

shipped production is serving it opened this has it
opened this

Part of the epic "Choose the template when making a new forge". First child; nothing waits on it.

What "template" means here. Today a new forge's apps come from the forks the spawner ticks, plus an optional one-line "fresh app" built from a tiny hard-coded index.ts (freshFiles, src/actions/spawn.ts:488). The forge also has a real starter, scaffoldFiles (src/apps/scaffold.ts:43), that /apps/new uses (src/actions/apps.ts:340), but a new forge cannot pick it or any other. This issue is the data and API half of fixing that: a template is a named starting point for the apps a new forge gets.

Build

  • src/spawn/templates.ts (new): the list of templates a forge offers. Each: id, title, one sentence says, source (builtin or repo). Built in: blank (what happens today, the default) and starter (the scaffoldFiles app). Repo-backed templates arrive in a later child; leave the seam (source: "repo", repo: "owner/name").
  • POST /api/v1/forges and the MCP spawn accept an optional template (an id). Unknown id: 422 on template with one sentence naming the valid ids. Absent or blank: the plan is byte-identical to today (add the field to the plan only when given and not blank, as fresh and size do, so old plan hashes do not change).
  • The choice is recorded in the plan, the ledger line in <data>/spawn/<name>.json, parent.json, and the rows of GET /api/v1/forges.
  • GET /api/v1/forges/templates (no sign-in, ETag, cached like /api/v1/forges/sizes) and an MCP templates tool return the same list. Add both to the OpenAPI document and the MCP tool docs.
  • docs/SPAWN.md: one section, "Choosing a template".

Where to put code: new files only (named below). Do not grow src/http/api.ts, src/web/pages/repo.ts or src/actions/spawn.ts beyond a call-site of a few lines; src/http/api/forges.ts, src/spawn/door.ts and src/web/pages/new-forge.ts may take small edits.

Done when

  • [ ] POST /api/v1/forges {name, template:"starter", dryRun:true} answers a plan that names the template; with no template the plan equals the one a build of main gives.
  • [ ] template:"nope" is a 422 on template naming blank and starter.
  • [ ] GET /api/v1/forges/templates answers without sign-in with blank first and an ETag; the MCP templates tool answers the same ids.
  • [ ] The ledger and GET /api/v1/forges show the choice for a made forge; a retry with a different template is refused like a different modelKey.

Named tests (new test/spawn-template-api.test.ts): plan carries the template only when it is not blank, an unknown template is a 422 on template, the templates list is public and ETagged, mcp templates equals the api list, ledger and parent.json record the template. Existing test/spawn-plan.test.ts and test/openapi-oa-forges.test.ts stay green.

commented

Epic is #7538.

commented

Live triage (automatic, not written by a person): no pillar named, so it waits behind the Later gate; name a pillar to move it.

Sign in to join this conversation.

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs