@babylonjs-toolkit/agent 1.1.0 → 1.1.2

package/README.md

@@ -24,7 +24,7 @@ and instruction files are only read at session start.
 | Command | What it does |
 |---------|--------------|
 | `bt-agent install` | Install skills + persona into every target (the default) |
-| `bt-agent update` | Reinstall, and remove skills this package no longer ships |
+| `bt-agent update` | Fetch the newest release from npm, reinstall it, and prune dropped skills |
 | `bt-agent uninstall` | Remove what it installed — and nothing else |
 | `bt-agent doctor` | Verify the install; prints `INSTALL OK` or lists what is missing |
 | `bt-agent targets` | Show every target and the paths it writes to |
@@ -36,9 +36,30 @@ and instruction files are only read at session start.
 | `--legacy-codex` | Also write `~/.codex/skills` for pre-`.agents` Codex builds |
 | `--no-persona` | Install skills only; leave instruction files alone |
 | `--persona-only` | Install/refresh the Agent Persona only; do not copy skills |
+| `--no-self-update` | `update` only: reinstall the bundled files; do not fetch npm |
 | `--dry-run` | Print what would happen and change nothing |
 | `--json` | Machine-readable output |
 
+### Updating
+
+```bash
+bt-agent update
+```
+
+`update` asks npm for the newest published version. If there is one it upgrades the
+global package for you — with whichever manager installed it (`npm`, `pnpm`, `yarn`
+or `bun`) — then hands over to the freshly installed CLI to copy the new skills,
+refresh the persona, and prune skills the new release no longer ships.
+
+If the upgrade is not possible it says so and continues with what is on disk:
+
+- running through `npx`, from a git checkout, or as a project dependency — there is
+  no global package to upgrade, so it reinstalls the bundled files
+- the registry is unreachable — it reinstalls the version you already have
+- the global install needs elevated permissions — it prints the exact command to run
+
+Use `--no-self-update` to skip the npm check entirely.
+
 ### What it writes
 
 | Target | Skills | Agent Persona |

package/bin/bt-agent.js

@@ -4,7 +4,8 @@
 const { install, uninstall } = require('../lib/install');
 const { doctor } = require('../lib/doctor');
 const { TARGETS, targetIds } = require('../lib/targets');
-const { prettyPath } = require('../lib/paths');
+const { selfUpdate, reexec, upgradeCommand, PACKAGE_NAME } = require('../lib/selfupdate');
+const { prettyPath, resolveTargetPath } = require('../lib/paths');
 const { version } = require('../package.json');
 
 const USAGE = `
@@ -18,7 +19,7 @@ Usage
 
 Commands
   install      Install skills + persona into every target        (default)
-  update       Same as install, and remove skills no longer shipped
+  update       Upgrade this package from npm, then reinstall and prune
   uninstall    Remove what this tool installed, and nothing else
   doctor       Verify the install; prints INSTALL OK or INSTALL FAILED
   targets      List the available targets and their paths
@@ -30,6 +31,7 @@ Options
   --no-persona         Install skills only; do not touch instruction files
   --persona-only       Install/refresh the Agent Persona only; do not copy skills
   --no-migrate         Leave a legacy unmarked persona in place, do not convert it
+  --no-self-update     update: reinstall the bundled files only; do not fetch npm
   --dry-run            Print what would happen; change nothing
   --json               Machine-readable output
   -h, --help           Show this help
@@ -40,6 +42,7 @@ Examples
   bt-agent install --legacy-codex
   bt-agent install --project
   bt-agent doctor
+  bt-agent update
 `;
 
 function parseArgs(argv) {
@@ -51,6 +54,7 @@ function parseArgs(argv) {
     persona: true,
     skills: true,
     migrate: true,
+    selfUpdate: true,
     dryRun: false,
     json: false,
     help: false,
@@ -83,6 +87,9 @@ function parseArgs(argv) {
       case '--no-migrate':
         opts.migrate = false;
         break;
+      case '--no-self-update':
+        opts.selfUpdate = false;
+        break;
       case '--dry-run':
         opts.dryRun = true;
         break;
@@ -146,6 +153,44 @@ function printInstall(report) {
   }
 }
 
+function printSelfUpdate(result) {
+  switch (result.status) {
+    case 'upgraded':
+      console.log(`\nUpgraded ${PACKAGE_NAME} ${result.current} -> ${result.latest}.`);
+      break;
+    case 'current':
+      console.log(`\n${PACKAGE_NAME} ${result.current} is the latest published version.`);
+      break;
+    case 'would-upgrade':
+      console.log(`\nWould upgrade ${PACKAGE_NAME} ${result.current} -> ${result.latest} (${result.command}).`);
+      break;
+    case 'upgrade-failed':
+      console.log(`\nCould not upgrade ${PACKAGE_NAME} ${result.current} -> ${result.latest}: ${result.reason}`);
+      console.log(`Run this yourself (it may need sudo): ${result.command}`);
+      console.log('Reinstalling the currently installed version instead.');
+      break;
+    case 'check-failed':
+      console.log(`\nCould not check npm for a newer version: ${result.reason}`);
+      console.log(`Reinstalling ${PACKAGE_NAME} ${result.current} from disk.`);
+      break;
+    case 'skipped':
+      console.log(`\nSkipping the npm upgrade — ${result.reason}.`);
+      break;
+    default:
+      break;
+  }
+}
+
+/** Name only what this run actually installed. */
+function restartNote(report) {
+  const parts = [];
+  if (report.skillsInstalled !== false) parts.push('skills');
+  if (report.persona.length) parts.push('persona');
+  const what = parts.length === 2 ? 'skills and persona are' : `${parts[0] || 'files'} ${parts[0] === 'skills' ? 'are' : 'is'}`;
+  console.log('\nRestart your agent session (Claude Code, Codex, Copilot, Gemini CLI)');
+  console.log(`so the ${what} picked up.\n`);
+}
+
 function printDoctor(result) {
   const { checked } = result;
   console.log(
@@ -160,6 +205,19 @@ function printDoctor(result) {
   }
 }
 
+function targetsJson(mode, projectRoot) {
+  return TARGETS.map((t) => {
+    const spec = mode === 'project' ? t.project : t.global;
+    return {
+      id: t.id,
+      label: t.label,
+      default: Boolean(t.default),
+      skills: spec.skills ? resolveTargetPath(spec.skills, mode, projectRoot) : null,
+      instructions: spec.instructions ? resolveTargetPath(spec.instructions, mode, projectRoot) : null,
+    };
+  });
+}
+
 function printTargets(mode) {
   console.log('');
   for (const t of TARGETS) {
@@ -197,8 +255,55 @@ function main() {
 
   try {
     switch (opts.command) {
-      case 'install':
       case 'update': {
+        // `update` used to be a plain alias for `install`, which only re-copied the
+        // payload already on disk — so it could never deliver a new release. Bring
+        // the package itself up to date first, then hand over to the new CLI.
+        let selfResult = null;
+        if (opts.selfUpdate) {
+          selfResult = selfUpdate({
+            dryRun: opts.dryRun,
+            log: (msg) => {
+              if (!opts.json) console.log(msg);
+            },
+          });
+          if (!opts.json) printSelfUpdate(selfResult);
+
+          if (selfResult.status === 'upgraded') {
+            const passthrough = process.argv.slice(2).filter((a) => a !== 'update');
+            const code = reexec(['install', ...passthrough], selfResult.latest);
+            if (code !== null) process.exit(code);
+            // Could not re-exec: fall through and install with what is loaded.
+            if (!opts.json) {
+              console.log('\nCould not restart the upgraded CLI — run `bt-agent install` to finish.');
+            }
+          }
+        }
+
+        const report = install(common);
+        const check = doctor(common);
+
+        if (opts.json) {
+          console.log(JSON.stringify({ ...report, selfUpdate: selfResult, doctor: check }, null, 2));
+        } else {
+          printInstall(report);
+          if (!opts.dryRun) {
+            console.log('');
+            if (check.ok) {
+              console.log('INSTALL OK');
+              restartNote(report);
+            } else {
+              printDoctor(check);
+            }
+          } else {
+            console.log('\nDry run — nothing was written.\n');
+          }
+        }
+        process.exit(opts.dryRun || check.ok ? 0 : 1);
+        break;
+      }
+
+      case 'install': {
         const report = install(common);
         const check = doctor(common);
 
@@ -210,8 +315,7 @@ function main() {
             console.log('');
             if (check.ok) {
               console.log('INSTALL OK');
-              console.log('\nRestart your agent session (Claude Code, Codex, Copilot, Gemini CLI)');
-              console.log('so the skills and persona are picked up.\n');
+              restartNote(report);
             } else {
               printDoctor(check);
             }
@@ -246,7 +350,8 @@ function main() {
       }
 
       case 'targets':
-        printTargets(opts.mode);
+        if (opts.json) console.log(JSON.stringify(targetsJson(opts.mode, process.cwd()), null, 2));
+        else printTargets(opts.mode);
         break;
 
       case 'help':

package/lib/manifest.js

@@ -3,7 +3,7 @@
 const fs = require('fs');
 const path = require('path');
 
-const { manifestPath } = require('./paths');
+const { manifestPath, stateDir } = require('./paths');
 
 /**
  * Record of what this tool wrote, so update and uninstall can touch only its own
@@ -30,10 +30,16 @@ function remove(mode, projectRoot) {
   const file = manifestPath(mode, projectRoot);
   try {
     fs.unlinkSync(file);
-    return true;
   } catch {
     return false;
   }
+  // Leave nothing of our own behind: drop the state directory once it is empty.
+  try {
+    fs.rmdirSync(stateDir(mode, projectRoot));
+  } catch {
+    /* the user put something else in there — keep it */
+  }
+  return true;
 }
 
 /** Skill folder names previously installed into `dir`, per the manifest. */

package/lib/selfupdate.js

@@ -0,0 +1,242 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { execFileSync } = require('child_process');
+
+const { PACKAGE_ROOT } = require('./paths');
+const pkg = require('../package.json');
+
+const PACKAGE_NAME = pkg.name;
+const CURRENT_VERSION = pkg.version;
+
+/** Set on the re-executed child so the upgraded CLI does not try to upgrade again. */
+const GUARD_ENV = 'BT_AGENT_SELF_UPDATED';
+
+const IS_WINDOWS = process.platform === 'win32';
+
+function segments(p) {
+  return p.split(/[\\/]+/);
+}
+
+/**
+ * Where is this copy of the CLI running from?
+ *
+ * `update` may only shell out to a package manager when the answer is a global
+ * install. An npx run already fetched the newest version, a git checkout is the
+ * developer's own working tree, and a project dependency belongs to that project's
+ * lockfile — upgrading any of those globally would write files nobody asked for.
+ */
+function detectInstall() {
+  const parts = segments(PACKAGE_ROOT);
+  const lower = parts.map((s) => s.toLowerCase());
+
+  if (fs.existsSync(path.join(PACKAGE_ROOT, '.git'))) {
+    return { kind: 'dev', manager: null, root: PACKAGE_ROOT };
+  }
+  if (lower.some((s) => s === '_npx' || s === '.npx')) {
+    return { kind: 'npx', manager: null, root: PACKAGE_ROOT };
+  }
+
+  const manager = lower.includes('pnpm') || lower.includes('.pnpm')
+    ? 'pnpm'
+    : lower.includes('.yarn') || lower.includes('yarn')
+      ? 'yarn'
+      : lower.includes('.bun')
+        ? 'bun'
+        : 'npm';
+
+  return { kind: isGlobal() ? 'global' : 'local', manager, root: PACKAGE_ROOT };
+}
+
+/** True when PACKAGE_ROOT lives under this machine's global module directory. */
+function isGlobal() {
+  const roots = [];
+  try {
+    roots.push(String(execFileSync(npmBin(), ['root', '-g'], { encoding: 'utf8', timeout: 20000 })).trim());
+  } catch {
+    /* npm unavailable or slow — fall back to path shape below */
+  }
+
+  const norm = (p) => path.resolve(p).toLowerCase().replace(/[\\/]+$/, '');
+  const here = norm(PACKAGE_ROOT);
+  if (roots.some((r) => r && here.startsWith(norm(r) + path.sep.toLowerCase()))) return true;
+
+  // pnpm/yarn/bun global stores never match `npm root -g`; recognise their shapes,
+  // and treat anything outside the current project tree as global rather than local.
+  const parts = segments(PACKAGE_ROOT).map((s) => s.toLowerCase());
+  if (parts.includes('.pnpm') || parts.includes('.yarn') || parts.includes('.bun')) return true;
+  return !here.startsWith(norm(process.cwd()) + path.sep.toLowerCase());
+}
+
+function npmBin() {
+  return IS_WINDOWS ? 'npm.cmd' : 'npm';
+}
+
+function managerBin(manager) {
+  const name = manager === 'npm' ? 'npm' : manager;
+  return IS_WINDOWS && name !== 'bun' ? `${name}.cmd` : name;
+}
+
+/** The exact command a user can copy/paste if the automatic upgrade fails. */
+function upgradeCommand(manager, version) {
+  const spec = `${PACKAGE_NAME}@${version || 'latest'}`;
+  switch (manager) {
+    case 'pnpm': return `pnpm add -g ${spec}`;
+    case 'yarn': return `yarn global add ${spec}`;
+    case 'bun': return `bun add -g ${spec}`;
+    default: return `npm install -g ${spec}`;
+  }
+}
+
+function upgradeArgs(manager, version) {
+  const spec = `${PACKAGE_NAME}@${version || 'latest'}`;
+  switch (manager) {
+    case 'pnpm': return ['add', '-g', spec];
+    case 'yarn': return ['global', 'add', spec];
+    case 'bun': return ['add', '-g', spec];
+    default: return ['install', '-g', spec];
+  }
+}
+
+/** Compare two semver-ish versions. Pre-release tags sort before their release. */
+function compareVersions(a, b) {
+  const split = (v) => {
+    const [core, pre] = String(v).split('-');
+    return { nums: core.split('.').map((n) => parseInt(n, 10) || 0), pre: pre || null };
+  };
+  const x = split(a);
+  const y = split(b);
+  for (let i = 0; i < 3; i += 1) {
+    if ((x.nums[i] || 0) !== (y.nums[i] || 0)) return (x.nums[i] || 0) < (y.nums[i] || 0) ? -1 : 1;
+  }
+  if (x.pre === y.pre) return 0;
+  if (!x.pre) return 1;
+  if (!y.pre) return -1;
+  return x.pre < y.pre ? -1 : 1;
+}
+
+/**
+ * Latest published version, from npm first so the user's registry, proxy and auth
+ * settings are honoured, then from registry.npmjs.org if the npm CLI is missing.
+ */
+function fetchLatestVersion({ timeout = 20000 } = {}) {
+  try {
+    const out = execFileSync(npmBin(), ['view', PACKAGE_NAME, 'version'], {
+      encoding: 'utf8',
+      timeout,
+      stdio: ['ignore', 'pipe', 'pipe'],
+    });
+    const v = String(out).trim().split(/\s+/).pop();
+    if (v) return { version: v };
+  } catch (err) {
+    const reason = (err && (err.stderr || err.message) ? String(err.stderr || err.message) : '').trim();
+    const fallback = fetchLatestFromRegistrySync(timeout);
+    if (fallback) return { version: fallback };
+    return { error: reason.split('\n').filter(Boolean).pop() || 'could not reach the npm registry' };
+  }
+  return { error: 'npm returned no version' };
+}
+
+/** Registry lookup without the npm CLI. Runs in a helper process so it can be sync. */
+function fetchLatestFromRegistrySync(timeout) {
+  const script = `
+    const https = require('https');
+    const url = 'https://registry.npmjs.org/' + encodeURIComponent(${JSON.stringify(PACKAGE_NAME)}).replace('%40','@') + '/latest';
+    const req = https.get(url, { headers: { accept: 'application/json' } }, (res) => {
+      let body = '';
+      res.on('data', (c) => { body += c; });
+      res.on('end', () => {
+        try { process.stdout.write(String(JSON.parse(body).version || '')); } catch { process.stdout.write(''); }
+      });
+    });
+    req.setTimeout(${Math.max(1000, timeout)}, () => req.destroy());
+    req.on('error', () => process.stdout.write(''));
+  `;
+  try {
+    const out = execFileSync(process.execPath, ['-e', script], { encoding: 'utf8', timeout: timeout + 2000 });
+    return String(out).trim() || null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Bring the installed package itself up to date.
+ *
+ * `update` used to be a pure alias for `install`: it re-copied the payload already
+ * on disk, so it could never deliver a newer release and `npm install -g` was the
+ * only way to actually update. This fetches the published version first, upgrades
+ * the global package when there is a newer one, and reports what happened.
+ *
+ * Returns a status object; it never throws.
+ */
+function selfUpdate({ dryRun = false, timeout = 20000, log = () => {} } = {}) {
+  const install = detectInstall();
+  const base = { current: CURRENT_VERSION, install: install.kind, manager: install.manager };
+
+  if (process.env[GUARD_ENV]) {
+    return { ...base, status: 'skipped', reason: 'already upgraded in this run' };
+  }
+  if (install.kind !== 'global') {
+    const why = {
+      npx: 'running via npx — npx already fetched the latest version',
+      dev: 'running from a git checkout — nothing to upgrade',
+      local: 'installed as a project dependency — upgrade it through that project',
+    }[install.kind];
+    return { ...base, status: 'skipped', reason: why };
+  }
+
+  log(`Checking npm for a newer ${PACKAGE_NAME} (installed: ${CURRENT_VERSION})...`);
+  const { version: latest, error } = fetchLatestVersion({ timeout });
+  if (!latest) return { ...base, status: 'check-failed', reason: error };
+
+  if (compareVersions(latest, CURRENT_VERSION) <= 0) {
+    return { ...base, latest, status: 'current' };
+  }
+
+  const command = upgradeCommand(install.manager, latest);
+  if (dryRun) return { ...base, latest, status: 'would-upgrade', command };
+
+  log(`Upgrading ${CURRENT_VERSION} -> ${latest} (${command})`);
+  try {
+    execFileSync(managerBin(install.manager), upgradeArgs(install.manager, latest), {
+      stdio: ['ignore', 'inherit', 'inherit'],
+      timeout: 10 * 60 * 1000,
+    });
+  } catch (err) {
+    const reason = err && err.message ? String(err.message).split('\n')[0] : 'upgrade command failed';
+    return { ...base, latest, status: 'upgrade-failed', command, reason };
+  }
+
+  return { ...base, latest, status: 'upgraded', command };
+}
+
+/**
+ * Hand control to the freshly installed CLI so the skills that get copied are the
+ * new ones. The running process still has the previous release's modules in memory.
+ */
+function reexec(argv, version) {
+  const { spawnSync } = require('child_process');
+  const script = process.argv[1];
+  if (!script || !fs.existsSync(script)) return null;
+
+  const result = spawnSync(process.execPath, [script, ...argv], {
+    stdio: 'inherit',
+    env: { ...process.env, [GUARD_ENV]: version || '1' },
+  });
+  if (result.error) return null;
+  return typeof result.status === 'number' ? result.status : 1;
+}
+
+module.exports = {
+  PACKAGE_NAME,
+  CURRENT_VERSION,
+  GUARD_ENV,
+  detectInstall,
+  compareVersions,
+  fetchLatestVersion,
+  upgradeCommand,
+  selfUpdate,
+  reexec,
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@babylonjs-toolkit/agent",
-  "version": "1.1.0",
+  "version": "1.1.2",
   "description": "Installs the Babylon Toolkit agent skills and Agent Persona for Claude Code, Codex, GitHub Copilot, Gemini CLI and Antigravity.",
   "keywords": [
     "babylonjs",

package/skills/bt-spec/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: bt-spec
 description: "The Babylon Toolkit Spec Skill creates a feature spec file and branch from a short idea. Use when asked to spec out, plan, or scaffold a new feature."
-allowed-tools: Read, Grep, Glob, Write, WebFetch(domain:raw.githubusercontent.com), Bash(git switch:*), Agent, Task
+allowed-tools: Read, Grep, Glob, Write, WebFetch(domain:raw.githubusercontent.com), Bash(git switch:*), AskUserQuestion, Agent, Task
 ---
 
 You are helping to spin up a new feature spec for this application, from a short idea provided in the user input below. Always adhere to any rules or requirements set out in the project's agent instructions (AGENTS.md / CLAUDE.md / .github/copilot-instructions.md) when responding.
@@ -13,14 +13,16 @@ Use the user’s message after the skill name as the `arguments`.
 # Invocation
 
 ```
-/bt-spec <feature-brief>
+/bt-spec [--grill-me] <feature-brief>
 ```
 - **`<feature-brief>`** — the short idea or brief for the feature spec. This is the *variable*.
-- If missing, ask for it before starting. Never guess a file path or URL.
+- **`--grill-me`** *(optional flag)* — interrogate the user relentlessly, one question at a time, until the design tree is actually resolved, instead of drafting the spec in a single pass from the brief. See **Step 2.7**. The flag may appear anywhere in the arguments and is never part of the brief.
+- If the brief is missing, ask for it before starting. Never guess a file path or URL.
 
 Example:
 ```
 /bt-spec → "Generate a detailed implementation plan for the new feature"
+/bt-spec --grill-me "add a settings toggle to mute all game audio"   # interview first, then spec
 ```
 
 ---
@@ -93,7 +95,9 @@ convenience where the tooling happens to support it.
 
 ## Step 2. Parse the arguments
 
-From `arguments`, extract:
+**First, extract and remove any flags — before deriving anything from the text.** Scan `arguments` for `--grill-me`; set `grill_me = true` if present, then **delete it from `arguments`** and collapse the surrounding whitespace. Everything below derives from the flag-stripped remainder. Skipping this produces a spec named `_specs/mute-game-audio-grill-me_spec.md`. Treat an unrecognised `--flag` as part of the brief only if the user clearly meant it as prose; otherwise ask.
+
+From the flag-stripped `arguments`, extract:
 
 1. `feature_title`  
    - A short, human readable title in Title Case.  
@@ -167,6 +171,30 @@ Some features are built on a deterministic pattern **owned by a sibling skill**
 
 If the feature matches no sibling-skill pattern, note that and continue.
 
+## Step 2.7 `--grill-me` — interrogate until the design is decided (ONLY when the flag is present)
+
+Run this step **only if `grill_me` is true**. Skip it entirely otherwise — the default one-shot path is unchanged.
+
+Without the flag this skill drafts a spec from a short brief in a single pass, and every decision it could not make lands in `## Open Questions` — a section nothing downstream is obligated to read or resolve. Grill mode replaces that guessing with a real interview, and its output lands in the sections that *are* read: `## Functional Requirements`, `## Acceptance Criteria`, `## Possible Edge Cases`, and the `## Decisions` log.
+
+Run this **after Step 2.4**, so every question is grounded in the real codebase rather than generic, and **after Step 2.6**, so a sibling skill's own intake questions are folded into this one interview instead of being asked twice.
+
+**The loop:**
+
+> Interview me relentlessly about every aspect of this plan until we reach a shared understanding. Walk down each branch of the design tree, resolving dependencies between decisions one by one. For each question provide your recommended answer. Ask the questions one at a time. If a question can be answered by exploring the codebase, explore the codebase instead.
+
+The rules that make that loop work:
+
+1. **One question at a time.** Use `AskUserQuestion` where you have it, with your recommended answer as the FIRST option, labelled `(Recommended)`. Never batch a wall of questions, and never move on past a question the user has not answered.
+2. **Explore before you ask.** If the answer is discoverable in the repo — an existing convention, how the closest prior feature did it, a dependency already present — go find it and offer what you found as the recommendation, rather than spending a question on it. Reuse the Step 2.4 findings first; a read-only subagent is the right tool only when the search is genuinely broad.
+3. **Depth-first down the design tree.** Resolve a branch's dependencies before opening the next branch — a decision that invalidates three later questions must be asked *before* them. Name the branch you are on, so the user can see the shape of what remains.
+4. **Never ask what is already settled.** The brief, `SPEC.md`, `DESIGN.md`, and a named sibling skill's documented defaults are answers, not questions. Confirm one of them in a single line only where this feature would plausibly override it.
+5. **Record as you go.** Write every answer into the spec body — as a requirement, an acceptance criterion, or an edge case — *plus* a `## Decisions` entry carrying the *why* and the rejected alternative. An answer that exists only in this transcript is gone the moment the plan phase opens a fresh context.
+6. **Stop when the tree is resolved, not when you run out of questions.** You are done when every remaining unknown is genuinely an implementation choice for bt-plan, or something only the user can decide later. Say so explicitly, then continue to Step 3.
+7. **The user can end it at any time** — "that's enough", "you decide the rest". Honor that immediately: record each unexplored branch in `## Open Questions` *with your recommended answer*, note in the spec that grilling ended early, and continue.
+
+**What must be true when this step ends:** `## Decisions` is non-empty and every entry carries a rationale, and `## Open Questions` holds only genuinely-undecided items — never something the user already answered.
+
 ## Step 3. Record the branch name (and switch to it where git is available)
 
 The `branch_name` derived from the `arguments` is **always** recorded in the spec header, so the plan
@@ -179,7 +207,7 @@ and execute phases have a stable name to refer to regardless of host.
 
 ## Step 4. Draft the spec content
 
-Create a markdown spec document that Plan mode can use directly and save it in the _specs folder as `<feature_slug>_spec.md`. Use the exact structure as defined in the feature spec template file @FEATURE.md located at the project root. The template includes a required `spec_impact` header field and a `Project Spec Alignment` section — fill both in from your SPEC.md read above (cite the SPEC.md sections the feature relies on, describe how it fits the architecture, and for `spec_impact: yes` state exactly what will change in SPEC.md and in which section). Do not add technical implementation details such as code examples. If the feature spec template file is missing, create a new feature spec file with the following sections:
+Create a markdown spec document that Plan mode can use directly and save it in the _specs folder as `<feature_slug>_spec.md`. Use the exact structure as defined in the feature spec template file @FEATURE.md located at the project root. **If that project template predates grill mode and has no `## Decisions` section, append one anyway whenever `grill_me` is true** (using the shape in the fallback template below, placed directly before `## Open Questions`) — the rationale must be recorded regardless of which template the project ships. The template includes a required `spec_impact` header field and a `Project Spec Alignment` section — fill both in from your SPEC.md read above (cite the SPEC.md sections the feature relies on, describe how it fits the architecture, and for `spec_impact: yes` state exactly what will change in SPEC.md and in which section). Do not add technical implementation details such as code examples. If the feature spec template file is missing, create a new feature spec file with the following sections:
 ```
 # Feature Spec Template
 
@@ -228,7 +256,19 @@ spec_impact: <yes|no>   # yes if this feature adds/changes a system, convention,
 ## Acceptance Criteria
 - ...
 
+## Decisions  _(the "why" — REQUIRED when run with `--grill-me`)_
+<!-- Mirrors SPEC.md's Decisions log, at feature scope. One entry per settled
+     design decision: what was chosen, why, and what was rejected. bt-plan reads
+     the feature spec in full, so this is how a decision's rationale survives into
+     the plan phase instead of being relitigated there — and for
+     spec_impact: yes features it feeds the final `Update SPEC.md` task directly. -->
+- **<decision>.** <why — the deciding constraint or the precedent in the codebase.>
+  Rejected: <alternative> (<why not>). → <FR-n, AC-n>
+
 ## Open Questions
+<!-- ONLY genuinely-undecided items. Anything answered during grilling belongs in
+     Functional Requirements / Acceptance Criteria / Possible Edge Cases plus a
+     Decisions entry above — never parked here. -->
 - ...
 
 ## Testing Guidelines