@looop-games/cli 0.1.8 → 0.1.9

package/lib/agent-surface.mjs

@@ -1,15 +1,20 @@
 // The agent surface — skills + the Layer-0 managed block — and how an update
 // reaches a repo that already exists (creator-harness Slice 2, decision Q2).
 //
-// The surface ships INSIDE the versioned engine artifact, not the npm CLI: the
-// CLI's template is only a create-time SEED (the engine is login-gated, so a
-// fresh folder can't download one before its first `dev`). From then on the
-// artifact is the source of truth. Without this, a creator's skills are frozen
-// at the version they created the game with — the exact freeze Q2 exists to end.
+// The surface ships INSIDE the versioned engine artifact, and ONLY there — the
+// npm CLI carries no copy of it. That is what makes the ownership record below
+// trustworthy: `create` places the surface by calling straight into this module
+// (against the artifact it just installed), so the bytes on disk and the hashes
+// we record come from the same place, and a fresh repo's first `update` is a
+// genuine no-op. The CLI used to seed the surface from its own bundled
+// `template/`, stamped with the ENGINE's version — a record that was false the
+// moment npm and the engine registry shipped out of step, and that made the
+// first `update` overwrite (or DELETE, via the orphan prune below) skills on a
+// repo minutes old.
 //
-// **This runs ONLY under `looop update`** (2026-07-11) — never on `dev`
-// or `publish`. It COULD run there safely (it can only ever converge a repo to
-// the engine version already pinned in its package.json, never a newer one),
+// **This runs under `looop update` — and under `looop create`** — never on
+// `dev` or `publish`. It COULD run there safely (it can only ever converge a
+// repo to the engine version already pinned in its package.json, never a newer one),
 // but a creator who ran `dev` and then found files they never wrote sitting in
 // `git status` would be right to feel we'd gone through their pockets. Updates
 // are something you ASK for. So this module writes nothing on its own schedule,
@@ -36,7 +41,7 @@
 // everything outside them (their title, their instructions below the end
 // marker) is theirs and is spliced back untouched.
 import { createHash } from 'node:crypto';
-import { cpSync, existsSync, mkdirSync, readFileSync, readdirSync, rmSync, statSync, writeFileSync } from 'node:fs';
+import { cpSync, existsSync, mkdirSync, readFileSync, readdirSync, rmSync, writeFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 
 export const SURFACE_DIR = 'agent-surface';
@@ -269,26 +274,3 @@ export function reconcileAgentSurface(projectDir, engineDir, { log = console.log
 
   return result;
 }
-
-// Used by `looop create`: the template seed IS the surface for a brand-new
-// repo, so record it as ours immediately. Without this the first `dev` would
-// treat a two-minute-old scaffold as an unknown pre-existing repo and adopt it.
-export function recordSeededSurface(projectDir, engineVersion) {
-  const placed = {};
-  const add = (rel) => {
-    const abs = join(projectDir, rel);
-    if (existsSync(abs)) placed[rel] = sha(readFileSync(abs));
-  };
-  const walk = (rel) => {
-    const abs = join(projectDir, rel);
-    if (!existsSync(abs)) return;
-    for (const entry of readdirSync(abs)) {
-      const child = join(rel, entry);
-      if (statSync(join(projectDir, child)).isDirectory()) walk(child);
-      else add(child);
-    }
-  };
-  walk(join('.claude', 'skills'));
-  add('AGENTS.md');
-  writeLocal(projectDir, engineVersion ?? null, placed);
-}

package/lib/create.mjs

@@ -2,26 +2,45 @@
 //
 // The create-next-app gesture: one command → a complete folder that is its
 // own repo, where `looop dev` immediately serves a WORKING multiplayer game
-// (the platform is not optional — the template joins a room on line one, no
+// (the platform is not optional — the scaffold joins a room on line one, no
 // "add multiplayer later" tier). The folder name is the slug.
 //
-// The scaffold lives as REAL FILES in ../template/ (creator-harness Slice 1)
-// — edit the template there, not string literals here. `create` copies it
-// with a {{name}} substitution pass. One rename on copy, an npm-pack
-// artifact: `gitignore` → `.gitignore` (npm silently strips .gitignore
-// files from packages). package.json is generated below instead of shipped
-// in the template (nested package.json files confuse npm's packer, and it
-// carries the dynamic cliSpec anyway).
+// ── Where the creator's files come from ─────────────────────────────────────
+//
+// EVERYTHING a creator receives comes from the versioned engine artifact: the
+// starter game (`scaffold/`) and the agent surface (`agent-surface/` — skills
+// plus the Layer-0 managed block). This npm package ships CODE ONLY.
+//
+// It used to ship a `template/` folder, and that was a bug with a long fuse.
+// npm and the engine registry are two independent, immutable release lanes, so
+// the two copies of the surface drifted the moment one shipped without the
+// other — and `create` seeded from the CLI while stamping the ownership record
+// with the ENGINE's version, so that record was a lie the day it was written.
+// The creator paid for it on their first `looop update`: skills they had never
+// touched changed under them, and a skill the CLI shipped but the engine didn't
+// was silently DELETED (agent-surface.mjs prunes files it owns that the
+// artifact no longer lists). On a repo minutes old.
+//
+// One authored copy, one release lane. A skill or scaffold change now ships
+// with an engine release alone; the CLI is released only when the CLI's own
+// code changes.
+//
+// The consequence, and it is deliberate: `create` needs the engine, and the
+// engine download is login-gated — so CREATE SIGNS YOU IN. That gate existed
+// anyway, one command later, at first `dev`. This moves it to where the creator
+// is already waiting and leaves `dev` instant.
 import { execFileSync } from 'node:child_process';
-import { existsSync, mkdirSync, writeFileSync, readdirSync, readFileSync, symlinkSync } from 'node:fs';
+import { existsSync, mkdirSync, writeFileSync, readdirSync, readFileSync, rmSync, symlinkSync } from 'node:fs';
 import { createRequire } from 'node:module';
 import { join, relative, dirname } from 'node:path';
 import { getApiBase } from './config.mjs';
 import { DEFAULT_API_BASE } from './llm-shim.mjs';
 import { runNpm } from './npm.mjs';
-import { recordSeededSurface } from './agent-surface.mjs';
+import { ensureEngine } from './engine.mjs';
+import { reconcileAgentSurface } from './agent-surface.mjs';
 
-export const TEMPLATE_DIR = join(import.meta.dirname, '..', 'template');
+// The starter game, inside the installed engine artifact.
+export const SCAFFOLD_DIR = 'scaffold';
 
 const NAME_OK = /^[a-z0-9][a-z0-9-]{0,40}$/;
 
@@ -48,69 +67,37 @@ const ALLOW_SCRIPTS = { esbuild: true, workerd: true, fsevents: true };
 // what create-time provisioning exists to prevent.
 const PLAYWRIGHT_SPEC = '^1.61.1';
 
-// Resolve the engine pin AT CREATE TIME so the initial commit — the
-// milestone-1 revert baseline — already carries `looop.engine`. Without
-// this, first `looop dev` writes the pin AFTER the baseline: the fresh repo
-// starts dirty, and a milestone-1 reject (`git reset --hard`) deletes the
-// pin, so the next dev re-resolves "latest" and can silently change engine
-// versions under a revert. The version LIST endpoint is public (a version
-// number is not a secret); the engine BYTES stay login-gated at first dev.
-async function resolveEnginePin(apiBase, log) {
-  try {
-    const res = await fetch(`${apiBase}/api/creator/engine`);
-    if (!res.ok) throw new Error(`HTTP ${res.status}`);
-    const { latest } = await res.json();
-    if (!latest) throw new Error('no downloadable releases');
-    return latest;
-  } catch (err) {
-    log(`⚠️  Could not resolve the engine version (${err.message}) — the first \`looop dev\` will pin it instead.`);
-    return null;
+// Copy the starter game out of the artifact. One rename: `gitignore` →
+// `.gitignore` (npm pack silently strips .gitignore files from a package, so
+// the artifact stores it dot-less).
+function copyScaffold(engineDir, dir, name, version) {
+  const root = join(engineDir, SCAFFOLD_DIR);
+  if (!existsSync(root)) {
+    // RELEASE ORDER: the engine must ship the scaffold BEFORE a CLI that expects
+    // it. If this CLI ever reaches a creator ahead of that engine, `create`
+    // resolves the latest engine, finds no starter game, and every create on
+    // earth fails — so say exactly what is wrong, and never blame the creator's
+    // setup for our release ordering.
+    throw new Error(
+      `Looop engine ${version} ships no starter game — it predates engine-owned scaffolding. ` +
+        'This is a platform-side issue, not something you did: please report it (`npx looop feedback`) or retry shortly.',
+    );
   }
-}
-
-function copyTemplate(dir, name) {
-  const entries = readdirSync(TEMPLATE_DIR, { withFileTypes: true, recursive: true }).filter((e) => e.isFile());
-  for (const entry of entries) {
-    const rel = relative(TEMPLATE_DIR, join(entry.parentPath, entry.name));
+  for (const entry of readdirSync(root, { withFileTypes: true, recursive: true })) {
+    if (!entry.isFile()) continue;
+    const rel = relative(root, join(entry.parentPath, entry.name));
     const dest = join(dir, rel === 'gitignore' ? '.gitignore' : rel);
     mkdirSync(dirname(dest), { recursive: true });
-    writeFileSync(dest, readFileSync(join(TEMPLATE_DIR, rel), 'utf8').replaceAll('{{name}}', name));
+    writeFileSync(dest, readFileSync(join(root, rel), 'utf8').replaceAll('{{name}}', name));
   }
 }
 
-export async function create({
-  name,
-  cwd = process.cwd(),
-  install = true,
-  cliSpec = process.env.LOOOP_CREATE_CLI_SPEC || '^0.1.0',
-  apiBase = getApiBase(DEFAULT_API_BASE),
-  log = console.log,
-} = {}) {
-  if (!name || !NAME_OK.test(name)) {
-    throw new Error(
-      `"${name ?? ''}" won't work as a game name — use lowercase letters, digits, and dashes (it becomes the URL: play.looop.games/g/<name>).`,
-    );
-  }
-  const dir = join(cwd, name);
-  if (existsSync(dir)) throw new Error(`${dir} already exists — pick another name or remove it first.`);
-
-  mkdirSync(dir, { recursive: true });
-  copyTemplate(dir, name);
-  // Non-Claude agent CLIs (Codex, Gemini/Antigravity, Cursor, opencode)
-  // discover project skills at .agents/skills/ — alias it to the same files.
-  // Created here, not shipped in the template: npm pack can't carry symlinks.
-  try {
-    mkdirSync(join(dir, '.agents'), { recursive: true });
-    symlinkSync(join('..', '.claude', 'skills'), join(dir, '.agents', 'skills'), 'dir');
-  } catch {
-    // e.g. Windows without symlink rights — Claude Code (and any tool that
-    // reads .claude/skills/ directly) still works.
-  }
-  // The engine is deliberately NOT a dependency (Q4 revision): it installs
-  // from the platform's login-gated registry on first `looop dev`. The
-  // VERSION is pinned here at create time (public lookup, warn-fallback) so
-  // the initial commit already carries it — see resolveEnginePin above.
-  const enginePin = await resolveEnginePin(apiBase, log);
+async function scaffold({ dir, name, install, cliSpec, apiBase, log, ensure, reconcile }) {
+  // Written FIRST, and without the engine pin: npm needs a package.json to
+  // install into, and `ensureEngine` writes the pin itself once it knows which
+  // version it actually installed. ONE writer for the pin — the old code had
+  // `create` resolve it and `ensureEngine` resolve it again, which is precisely
+  // how they came to disagree.
   writeFileSync(
     join(dir, 'package.json'),
     JSON.stringify(
@@ -121,28 +108,50 @@ export async function create({
         scripts: { dev: 'looop dev', publish: 'looop publish', test: 'looop test' },
         devDependencies: { '@looop-games/cli': cliSpec, playwright: PLAYWRIGHT_SPEC },
         allowScripts: ALLOW_SCRIPTS,
-        ...(enginePin ? { looop: { engine: enginePin } } : {}),
       },
       null,
       2,
     ) + '\n',
   );
 
-  // The template we just copied IS this repo's agent surface, so record it as
-  // ours now (Slice 2 / Q2). Without this, the first `looop dev` would meet a
-  // two-minute-old scaffold with no ownership record, treat it as a legacy
-  // pre-Slice-2 repo, and noisily "adopt" it. From here the artifact drives it.
-  recordSeededSurface(dir, enginePin);
-
   if (install) {
     log(`Installing the CLI (npm install in ${name}/)…`);
     runNpm(['install', '--no-audit', '--no-fund'], { cwd: dir, stdio: 'pipe' });
+  }
+
+  // The engine — and with it the starter game and the agent skills. Signs the
+  // creator in via the device flow if this machine has no token yet, and writes
+  // the `looop.engine` pin.
+  const engine = await ensure(dir, { apiBase, log });
+
+  copyScaffold(engine.dir, dir, name, engine.version);
+
+  // The agent surface is PLATFORM-owned and reconciled on every `looop update`,
+  // so it is placed here by the very code that will later update it — reading
+  // the artifact, recording the real hash of what landed. That identity is the
+  // whole point: a fresh repo's first `update` is now a genuine no-op, because
+  // the bytes on disk and the bytes in the ownership record came from the same
+  // artifact.
+  reconcile(dir, engine.dir, { log });
+
+  // Non-Claude agent CLIs (Codex, Gemini/Antigravity, Cursor, opencode)
+  // discover project skills at .agents/skills/ — alias it to the same files.
+  // After reconcile, so the link is never dangling.
+  try {
+    mkdirSync(join(dir, '.agents'), { recursive: true });
+    symlinkSync(join('..', '.claude', 'skills'), join(dir, '.agents', 'skills'), 'dir');
+  } catch {
+    // e.g. Windows without symlink rights — Claude Code (and any tool that
+    // reads .claude/skills/ directly) still works.
+  }
+
+  if (install) {
     // Fetch the smoke-test browser NOW (cached machine-wide per version) so
     // the first `looop test` never stalls on a surprise download mid-build.
     // Resolved + run via node directly — NEVER a nested `npx`: when create
-    // itself runs under `npm exec --package=<tarball>` (the stranger
-    // gesture), the inherited npm_config_* env makes an inner npx try to
-    // re-install the tarball and cancel (caught live, 2026-07-10).
+    // itself runs under `npm exec --package=<tarball>` (the stranger gesture),
+    // the inherited npm_config_* env makes an inner npx try to re-install the
+    // tarball and cancel (caught live, 2026-07-10).
     try {
       log('Fetching the test browser (Chromium — one-time download, cached for every game)…');
       const req = createRequire(join(dir, 'package.json'));
@@ -152,12 +161,14 @@ export async function create({
       log('⚠️  Could not fetch Chromium (offline?) — `looop test` will fetch it when first needed.');
     }
   }
+
   try {
     execFileSync('git', ['init', '-q'], { cwd: dir, stdio: 'pipe' });
-    // Commit the scaffold: the initial commit is the first revert baseline
-    // (rejecting milestone 1 resets to it) and what lets `git worktree add`
-    // work — on a never-committed repo it silently creates an empty orphan
-    // lane instead.
+    // The initial commit is the first revert baseline (rejecting milestone 1
+    // resets to it) and what lets `git worktree add` work — on a never-committed
+    // repo it silently creates an empty orphan lane instead. It carries the
+    // engine pin AND the true agent surface, so a reset to baseline cannot
+    // silently change either.
     execFileSync('git', ['add', '-A'], { cwd: dir, stdio: 'pipe' });
     const msg = ['commit', '-q', '-m', 'initial scaffold (looop create)'];
     try {
@@ -175,8 +186,43 @@ export async function create({
   }
 
   log('');
-  log(`✅ ${name} is ready.`);
-  log(`   cd ${dir} && npx looop dev`);
-  log('   (first run downloads the Looop engine — it will ask you to sign in)');
-  return { dir };
+  log(`✅ ${name} is ready (Looop engine ${engine.version}).`);
+  log(`   cd ${name} && npx looop dev`);
+  return { dir, engineVersion: engine.version };
+}
+
+export async function create({
+  name,
+  cwd = process.cwd(),
+  install = true,
+  cliSpec = process.env.LOOOP_CREATE_CLI_SPEC || '^0.1.0',
+  apiBase = getApiBase(DEFAULT_API_BASE),
+  log = console.log,
+  // Seams, mirroring `looop update` — the tests drive a real artifact on disk
+  // through the real reconciler, with no network and no account.
+  ensure = ensureEngine,
+  reconcile = reconcileAgentSurface,
+} = {}) {
+  if (!name || !NAME_OK.test(name)) {
+    throw new Error(
+      `"${name ?? ''}" won't work as a game name — use lowercase letters, digits, and dashes (it becomes the URL: play.looop.games/g/<name>).`,
+    );
+  }
+  const dir = join(cwd, name);
+  if (existsSync(dir)) throw new Error(`${dir} already exists — pick another name or remove it first.`);
+
+  mkdirSync(dir, { recursive: true });
+  try {
+    return await scaffold({ dir, name, install, cliSpec, apiBase, log, ensure, reconcile });
+  } catch (err) {
+    // ATOMIC. Everything a creator receives now arrives over the network behind
+    // a login, so a failure anywhere leaves a folder with no game, no skills and
+    // no initial commit — one that `looop dev` cannot run, and that `create`
+    // would refuse to retry into ("already exists"). A folder that looks like a
+    // game and isn't one is worse than no folder at all: it fails later,
+    // somewhere more confusing. Take it back, and say so.
+    rmSync(dir, { recursive: true, force: true });
+    log(`\n⚠️  Could not finish creating ${name} — removed the incomplete folder so you can retry cleanly.`);
+    throw err;
+  }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@looop-games/cli",
-  "version": "0.1.8",
+  "version": "0.1.9",
   "description": "Looop game development CLI — dev server, login, and publishing for standalone Looop games.",
   "type": "module",
   "license": "Apache-2.0",
@@ -10,7 +10,6 @@
   "files": [
     "bin",
     "lib",
-    "template",
     "!lib/**/*.test.mjs"
   ],
   "engines": {

package/template/.claude/skills/build/SKILL.md

@@ -1,266 +0,0 @@
----
-name: build
-description: The Looop build loop — the one way game work happens in this repo. Use when the creator wants to make their game, add or change a feature, start something new, or continue where a previous session left off ("let's build", "keep going", "add X", "make it so Y"). Runs from a plan in notes/plans/ — continues the plan if one exists, creates one if not.
----
-
-# /build — the loop that builds this game
-
-You are building for a creator who is probably not a developer. They bring the
-vision and the judgment calls; you bring everything else. This skill is the
-process — one repo, one game, one loop:
-
-> **plan → discuss → build in milestones of auto-verified steps → the creator
-> playtests → offer publish**
-
-Two words carry this loop, sized by the words themselves:
-
-- A **milestone** is a big, vertical increment the creator can actually play —
-  the loop's unit of *their* attention. **The creator playtests at every
-  milestone.**
-- A **step** is a small build increment inside a milestone. **Every step is
-  auto-verified by you** — the creator is never asked to approve steps.
-
-## When to collapse the ceremony
-
-A trivial direct request ("make the ball a bit faster") doesn't need the full
-loop: make the change, verify it, one line in the plan's log if a plan exists.
-The loop is for real increments — new mechanics, features, session-scale work.
-The tell: if the creator will want to *play* the result to judge it, it's a
-milestone and it runs through the loop.
-
-**Collapse never applies when there is no plan yet.** Starting something new
-runs through the §2 discussion — the plan records the creator's answers, so
-it cannot exist before they've answered.
-
-## 1. Anchor on the plan
-
-Every build runs from a **plan** — a file in `notes/plans/`. A build without a
-plan doesn't exist; the plan is the loop's spine and the next session's recap.
-
-- **A plan exists** (look in `notes/plans/`) → CONTINUE it. Read it fully —
-  vision, decisions, the milestone checklist, the log — and pick up exactly
-  where it left off. Don't make the creator repeat themselves.
-- **No plan** → START one (create `notes/plans/<YYYY-MM-DD-HHMM>-<short-name>.md`
-  — creation datetime first, always, so plans list in order and the newest is
-  findable at a glance), through the discussion below. A `/todo` being
-  promoted becomes a plan the same way.
-
-Plan shape (keep it lean — decisions and why, never pasted code):
-
-```markdown
----
-status: in_progress   # in_progress | done | paused | abandoned
-created: YYYY-MM-DD
-updated: YYYY-MM-DD
----
-# <What we're building>
-
-## Vision
-What this wants to be at its best, in the creator's words.
-
-## Decisions
-- **<choice>** — what was decided and why (one entry per real decision).
-
-## Out of scope
-- **<cut>** — why it's out (one line per cut). As load-bearing as Decisions:
-  every "we could also…" that got trimmed lands here, so it stays trimmed.
-
-## Milestones
-### Milestone 1 — <name>  _(playtest: what the creator checks)_
-- [x] step
-- [ ] step
-
-## Log
-- YYYY-MM-DD — what happened, in a few lines. Newest first.
-```
-
-## 2. Discuss before building
-
-Before code, get the shape right with the creator — and record it in the plan.
-
-**Building (§3) runs only from a plan whose decisions are settled — and a
-decision is settled by the creator answering, never by you choosing for
-them.** A new build request therefore starts as a conversation, one decision
-at a time:
-
-- **One decision per turn.** Pose it, resolve it fully, record it in the
-  plan, then move to the next. Never a batch of questions — and never a
-  finished plan (or code, or tests) as your opening move.
-- **Explain the problem before the options.** The creator can't choose
-  between options they don't have the picture for. If they ask "what is X?",
-  stop and explain X cleanly; the decision waits. If they say "I don't
-  understand", don't restate the options louder — back up and re-explain the
-  underlying problem from scratch, with concrete examples.
-- **2–3 options with honest pros/cons, and your lean stated** — make it easy
-  to say "do that" or override you. Don't stack the deck, and don't fake
-  confidence on a genuine 50/50: phrase the case for the other option clearly
-  enough that the creator can pick it up if they disagree.
-- **Lock it in visibly** — say "Locking in: <choice>" and write it into the
-  plan's Decisions as it lands, so the record never lags the conversation.
-
-**Every decision that shapes the game reaches the creator, framed by its
-consequences** — the way an engineer briefs a product manager. Not "authority
-vs. client prediction?" but "if X, joining mid-game is instant but scores can
-briefly disagree; with Y it's the reverse — which matters more here?" Give 2–3
-options with honest trade-offs and your lean. The technical detail stays
-available underneath for whoever pulls the thread.
-
-**Silently decide only what is consequence-free for the creator** — naming,
-file layout, code structure. The test is *"is the creator the right person to
-answer this?"*, not "is this technical?" A technical fork with a consequence
-they'd care about (feel, fairness, what can break) goes to them; one with no
-creator-visible consequence does not. Never hide a real fork to keep things
-simple — there is always a non-confusing way to ask it.
-
-**The shape decisions are ALWAYS the creator's** — never a default you carry in
-on their behalf, and never something you mention in passing as already settled:
-
-- **Camera and perspective** — top-down, side-on, isometric, first-person, 3D.
-  There is no house camera; see `/engine`'s render paths.
-- **Art direction and look** — the Looop iso kit is *available*, not mandatory.
-- **The core verb** — what the player actually does, moment to moment.
-- **How conflict works** — combat, avoidance, puzzles, none of the above.
-- **Single-player vs. co-op vs. competitive** feel (the *plumbing* is always
-  multiplayer-first; what the game is *about* is theirs).
-
-**NEVER invent a platform constraint.** Do not tell the creator "the engine
-only does X", "Looop doesn't support Y", or "that would take months" unless you
-have just checked and can point at what says so. A Looop game is a web page;
-the library is a bag of conveniences, not a fence (`/engine` — "The library is
-NOT the limit"). This failure is worse than a silent default: a creator can
-argue with "that's a lot of work", but they cannot argue with "the platform
-can't", so a fabricated limit kills their idea and looks like physics while
-doing it. If a thing is genuinely unbuilt, that is a **cost to price honestly**
-and hand them — never a "no" you issue on Looop's behalf.
-
-Watch for this specifically when scope pressure and a gap in the library point
-the same way: **"default to the smallest build" is never a licence to narrow
-the creator's vision** — that's the scope-narrowing this skill forbids two
-paragraphs down, wearing a technical disguise.
-
-**Default to the smallest build that meets the creator's ask — never inflate
-scope.** Every "we could also…" and every richer-than-asked option is scope
-YOU are injecting; the creator can't push back on over-building they didn't
-ask for. Surface extras as explicitly optional, record what was ruled out in
-the plan (an "Out of scope" line per cut), and when a discussion has stacked
-several decisions, recap the accumulated size so the creator can trim.
-
-Then cut the work into **milestones**: each one vertical, end-to-end, playable
-on its own. The FIRST milestone is the thinnest playable thing that proves the
-riskiest idea — if the core bet is wrong, the creator learns it after one
-milestone, not after the whole build. Write the milestones into the plan, each
-with its `_(playtest: …)_` note.
-
-## 3. Build a milestone
-
-Run the steps **autonomously — no approval gates between steps**, just brief
-progress notes:
-
-1. Consult what's already known before writing new systems: `handbook/`
-   (this game's locked truths), the engine practices
-   (`node_modules/@looop-games/engine/shared/practices/`), and `/engine` for
-   components that already exist — don't reinvent a library.
-2. Where a behaviour has a real contract, write the failing test/smoke first,
-   then the code.
-3. **After every step, verify it yourself — run `/qa` on what the step
-   changed.** The steps themselves live in the engine's master QA doc
-   (`node_modules/@looop-games/engine/shared/practices/qa.md`); `/qa` reads
-   and runs them — **including the review rows: fresh sub-agent reviewers
-   (code-quality + test-thoroughness) on the step's diff, findings resolved
-   red→green before the step counts as done.** Every automated step runs at
-   step cadence; only the playtest is per-milestone. You are the only tester
-   inside a milestone — act like it.
-4. **If a fix doesn't land on the first re-test, diagnose — don't
-   second-guess.** Revert it, add instrumentation, find the actual cause;
-   never ship a second guess stacked on the first.
-5. **A real fork discovered mid-step goes to the creator**, framed by its
-   consequences like every other game-shaping decision — never silently
-   resolved just because the build is rolling.
-6. **Never narrow scope silently.** Build the full milestone that was agreed;
-   if a constraint forces something smaller, surface it at the gate — don't
-   quietly ship the lesser version.
-7. Tick the step off in the plan as it lands.
-
-## 3½. Close the milestone — before the creator ever sees it
-
-Every step already passed its own `/qa` — including the per-step review
-sub-agents. The milestone close is the whole-greater-than-parts check before
-the ONE manual gate: run the full **`npx looop test`** suite (everything, not
-just what the last step touched), re-drive the milestone's headline behaviour
-end-to-end yourself, and for anything LLM-authored/generative run the
-**verdict-mix** row (judged scenarios, never a green check). Anything found
-here is fixed **red→green** — the failing test first, then the fix. Only then
-hand back.
-
-## 4. The playtest gate
-
-When the milestone's steps are done and verified, hand it to the creator —
-this is the one place the loop stops for a human:
-
-- **The game is already RUNNING when you hand back — you run the server,
-  never the creator.** If the dev stack isn't up, start it yourself
-  (`npx looop dev`, backgrounded) and confirm the game URL answers before
-  handing over; if one is already running, reuse it. The creator gets a
-  **link to click** — `http://localhost:8000/games/<name>/index.html` (plus
-  the phone/LAN URL when touch is part of the playtest) — never a command
-  to paste. Asking them to run a server is asking them to learn infra.
-- **A minimal checklist of genuinely human-judgment items** — feel, look,
-  "does this play the way you imagined". Never hand them a check you could
-  have run yourself; you already ran those, report the results instead.
-
-Outcomes:
-
-- **It lands** → save it (a commit — `milestone: <name>`), check it off in
-  the plan, update the log, move on. The saves at accepted milestones are the
-  game's restore points.
-- **Close, needs iteration** → adjust within the milestone and hand back.
-- **Wrong direction** → offer the revert plainly, no sunk-cost defence:
-  back to the last save (`git reset --hard` — nothing was saved mid-milestone,
-  so that's the last accepted state).
-- **The playtest caught a defect you missed** → that's a hole in the
-  verification, not just a bug. Fix it, then run `/handbook` so this
-  class of defect gets an automated check and never reaches a playtest again.
-
-## 5. Offer publish — never publish on your own
-
-After a milestone lands, offer it: `npx looop publish` puts the game live at
-`play.looop.games/g/<name>`. Publishing is **always the creator's explicit
-call** — `/build` never runs it unprompted. For a variant the creator wants to
-compare against the live game, `npx looop publish --slug <alt>` publishes an
-isolated A/B copy (own URL, own room) without touching the real one.
-
-## Parallel lanes (advanced)
-
-A creator can run several `/build` experiments on one game at once. A lane is
-just this loop in a git worktree:
-
-```bash
-# in the main checkout. git worktree needs the repo to have at least one
-# commit (on a never-saved repo it silently creates an EMPTY orphan lane) —
-# this saves ONLY in that case, and is a no-op otherwise:
-git rev-parse HEAD >/dev/null 2>&1 || { git add -A && git commit -m "save: initial"; }
-
-git worktree add ../<name>-<lane>       # one folder per experiment
-cd ../<name>-<lane> && npm install      # node_modules is gitignored — without
-                                        # this, npx falls through to a WRONG
-                                        # public 'looop' package and crashes
-                                        # with a misleading error
-npx looop dev --port 8010               # DISTINCT --port per lane (8010, 8020, …)
-```
-
-- **The lane serves `/games/<worktree-folder-name>/…`** — the folder name, not
-  the original game slug. Use the URL the dev banner prints. The folder name
-  also keys the lane's multiplayer room.
-- Every lane needs its own `--port`: the port shifts the whole stack together
-  — game, multiplayer, services — so lanes are fully isolated (distinct
-  server processes per lane; `looop test` inside one lane picks its own free
-  ports and doesn't disturb the others).
-- Each lane keeps its own plan progress; save/playtest semantics are
-  unchanged inside a lane.
-- Compare lanes live with `publish --slug <lane>` variants.
-- Land the winner: save it in the lane (`git add -A && git commit`), then from
-  the main checkout `git merge <lane-branch>`, then
-  `git worktree remove ../<name>-<lane>` and delete the lane branch.
-- **If the merge conflicts, stop — never auto-resolve.** Show the creator
-  what collided (in game terms: "both lanes changed how jumping feels") and
-  resolve it with them.