buildline 0.3.0 → 0.4.0

package/README.md

@@ -20,7 +20,7 @@ independent verification, and a clear place for developers, designers and produc
 npx buildline
 ```
 
-[Quick start](#quick-start) · [How it works](#how-it-works) · [Models per station](#models-per-station) · [Dashboard](#the-dashboard) · [Docs](#docs)
+**[Website & docs](https://julianoczkowski.github.io/buildline/)** · [Quick start](#quick-start) · [How it works](#how-it-works) · [Models per station](#models-per-station) · [Dashboard](#the-dashboard)
 
 </div>
 
@@ -92,19 +92,20 @@ Role guides: [product managers](docs/for-product-managers.md) · [designers](doc
 
 ## Models per station
 
-Use the strongest model where judgement matters and a fast one where the work is well specified. You can also have a second vendor review the diff.
+Pick the model for each job: Fable to plan, Opus to build, Codex to review, or anything else your tools support. Buildline doesn't ship a model list. The picker reads what's available from your installed Claude Code and the Anthropic API, and you can always type a model in, so new models work on day one.
 
 ```bash
-npx buildline models preset balanced     # Opus specs, designs, plans, reviews · Sonnet builds and verifies
-npx buildline models set review codex    # Codex reviews every diff as a second opinion
-npx buildline models                     # see what each station uses
+npx buildline models                               # pick by phase or per station
+npx buildline models set planning fable            # spec, design, plan
+npx buildline models set building claude-opus-5-5  # build
+npx buildline models check                         # what each choice resolves to today
 ```
 
 ```json
-"models": { "default": "sonnet", "plan": "opus", "review": "codex:gpt-5-codex", "verify": "gemini" }
+"models": { "plan": "fable", "build": "claude-opus-5-5", "review": "codex", "default": "sonnet" }
 ```
 
-Claude Code skills and subagents switch model per station. A station routed to Codex or Gemini is handed off automatically, and `buildline step <station> <id>` opens it in the right tool. [More on models →](docs/models.md)
+Claude Code skills and subagents switch model per station. A station set to Codex or Gemini is handed off automatically, and `buildline step <station> <id>` opens it in the right tool. [More on models →](docs/models.md)
 
 ## Guardrails that hold
 
@@ -181,7 +182,7 @@ npx buildline new "<title>"          open a feature  --type fix|feature|epic
 npx buildline approve <id> <stage>   record an approval (spec | design | plan)
 npx buildline ui                     dashboard
 npx buildline step <station> [id]    open a station on its model  --headless --model
-npx buildline models                 models per station  set <station> <model> · preset <name>
+npx buildline models                 choose models  set <station|phase> <model> · check
 npx buildline run <id>               autopilot with Claude Code /goal  --headless
 npx buildline gates                  run quality gates
 npx buildline doctor                 check the setup
@@ -194,6 +195,8 @@ Full reference: [docs/cli.md](docs/cli.md)
 
 ## Docs
 
+Read them on the **[docs site](https://julianoczkowski.github.io/buildline/)**, or here on GitHub:
+
 | | |
 |---|---|
 | [Getting started](docs/getting-started.md) | new and existing projects |

package/bin/buildline.js

@@ -20,7 +20,7 @@ ${pc.bold('Commands')}
   ${pc.cyan('move')} <id> <station>      move a feature to a station  ${pc.dim('--note "<why>"')}
   ${pc.cyan('ui')}                       open the dashboard in your browser  ${pc.dim('--port <n>  --no-open')}
   ${pc.cyan('step')} <station> [id]      open a station in the CLI and model set for it  ${pc.dim('--model <m>  --headless  --print')}
-  ${pc.cyan('models')}                   show models per station  ${pc.dim('set <station> <model> · preset <name>')}
+  ${pc.cyan('models')}                   choose models per station  ${pc.dim('set <station|phase> <model> · check')}
   ${pc.cyan('run')} [id]                 autopilot: build → verify → review with Claude Code /goal  ${pc.dim('--headless  --print')}
   ${pc.cyan('gates')} [names...]         run the quality gates
   ${pc.cyan('doctor')}                   check the setup
@@ -32,7 +32,7 @@ ${pc.bold('Init options')}
   --agents <list>          claude,codex,cursor,gemini,copilot
   --autonomy <1-4>         1 assist · 2 guided · 3 autopilot · 4 dark factory
   --team <list>            developer,designer,pm
-  --models <preset>        session · balanced · budget · second
+  --models <list>          e.g. planning=fable,building=claude-opus-5-5,checking=codex
   --ci / --no-ci           add the GitHub Actions workflow
   --dry-run                show what would change without writing
   --force                  overwrite managed files even if you edited them
@@ -43,7 +43,7 @@ ${pc.bold('Examples')}
   npx buildline init -y --autonomy 3  ${pc.dim('# non-interactive install')}
   npx buildline new "Saved carts"     ${pc.dim('# open a feature')}
   npx buildline run 004               ${pc.dim('# unattended build loop')}
-  npx buildline models set review codex  ${pc.dim('# Codex reviews every diff')}
+  npx buildline models set planning fable  ${pc.dim('# Fable specs, designs and plans')}
   npx buildline step review 004       ${pc.dim('# run one station on its model')}
 `;
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "buildline",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Install an AI software factory into any project. A spec-driven pipeline for Claude Code (and any AGENTS.md-compatible agent), for developers, designers and product managers.",
   "type": "module",
   "bin": {
@@ -17,8 +17,10 @@
     "node": ">=20.12"
   },
   "scripts": {
-    "test": "node --test test/*.test.js",
-    "start": "node bin/buildline.js"
+    "test": "node --test test/buildline.test.js",
+    "start": "node bin/buildline.js",
+    "site": "node scripts/build-site.mjs",
+    "release": "node scripts/release.mjs"
   },
   "keywords": [
     "claude-code",
@@ -37,10 +39,13 @@
     "type": "git",
     "url": "git+https://github.com/julianoczkowski/buildline.git"
   },
-  "homepage": "https://github.com/julianoczkowski/buildline#readme",
+  "homepage": "https://julianoczkowski.github.io/buildline/",
   "bugs": "https://github.com/julianoczkowski/buildline/issues",
   "dependencies": {
     "@clack/prompts": "^1.8.1",
     "picocolors": "^1.1.1"
+  },
+  "devDependencies": {
+    "marked": "^15.0.12"
   }
 }

package/src/cli.js

@@ -6,7 +6,7 @@ import pc from 'picocolors';
 import { detect, describeStack } from './detect.js';
 import { AGENTS, AUTONOMY, VERSION, makeConfig, plan, apply, removePlan, applyRemove, defaultGates } from './install.js';
 import { loadManifest } from './files.js';
-import { PRESETS, MODEL_STATIONS, CLIS, modelFor, parseModel, describeModel, stationPrompt, launchArgs, externalClis } from './models.js';
+import { PHASES, MODEL_STATIONS, CLIS, modelFor, parseModel, parseModelList, describeModel, discoverModelOptions, checkModel, stationPrompt, launchArgs, externalClis } from './models.js';
 import { listFeatures, findFeature, createFeature, approve, setStatus, nextAction, STATIONS, TYPES } from './features.js';
 
 const LOGO = [
@@ -95,7 +95,7 @@ export async function init(root, opts) {
     team: parseList(opts.team) || ['developer', 'designer', 'pm'],
     ci: opts.ci ?? (stack.git && fs.existsSync(path.join(root, '.github'))),
     gates: defaultGates(stack),
-    models: PRESETS[opts.models]?.models || {},
+    models: parseModelList(opts.models),
   };
 
   if (interactive) {
@@ -127,14 +127,7 @@ export async function init(root, opts) {
       }),
     );
 
-    const preset = bail(
-      await p.select({
-        message: 'Which models should each station use?',
-        options: Object.entries(PRESETS).map(([value, x]) => ({ value, label: x.label, hint: x.hint + (externalClis({ models: x.models }).some((c) => !hasCommand(c)) ? ' (needs ' + externalClis({ models: x.models }).join(', ') + ')' : '') })),
-        initialValue: 'session',
-      }),
-    );
-    answers.models = PRESETS[preset].models;
+    answers.models = await pickModels({ models: answers.models });
 
     const gateChoice = bail(
       await p.select({
@@ -354,35 +347,109 @@ export async function step(root, station, ref, opts = {}) {
   return launch(root, cmd, args);
 }
 
-/** Show or change per-station models. */
-export async function models(root, args, opts) {
-  const config = loadConfig(root);
-  const [action, station, value] = args;
-  if (action === 'set' || action === 'preset') {
-    if (action === 'preset') {
-      if (!PRESETS[station]) throw new Error(`Unknown preset "${station}". Use one of: ${Object.keys(PRESETS).join(', ')}.`);
-      config.models = { ...PRESETS[station].models };
-    } else {
-      if (!station || !['default', ...MODEL_STATIONS].includes(station)) throw new Error(`Usage: buildline models set <default|${MODEL_STATIONS.join('|')}> <model|inherit>`);
-      if (!value) throw new Error('Give a model: opus, sonnet, haiku, a model id, codex[:model], gemini[:model], or inherit.');
-      config.models = { ...(config.models || {}) };
-      if (value === 'inherit') delete config.models[station];
-      else config.models[station] = value;
+/** One model, chosen from what's available right now or typed in. */
+async function pickOne(message, current, options) {
+  const initial = options.some((o) => o.value === (current || 'inherit')) ? current || 'inherit' : '__other';
+  const choice = bail(await p.select({ message, options, initialValue: initial, maxItems: 10 }));
+  if (choice !== '__other') return choice;
+  const typed = bail(
+    await p.text({
+      message: `${message}: model name or id`,
+      placeholder: 'e.g. claude-opus-5-5, fable, codex:gpt-5-codex, gemini:gemini-2.5-pro',
+      initialValue: initial === '__other' ? current || '' : '',
+      validate: (v) => (v?.trim() ? undefined : 'Type a model, or press Esc to go back'),
+    }),
+  );
+  return typed.trim();
+}
+
+/** Interactive model routing: one model everywhere, per phase, or per station. Returns the new models map. */
+export async function pickModels(config) {
+  const current = config.models || {};
+  const spin = p.spinner();
+  spin.start('Looking up available models');
+  const options = await discoverModelOptions(config);
+  spin.stop(`Models available: ${options.filter((o) => !['inherit', '__other'].includes(o.value)).map((o) => o.label).join(', ') || 'none found, type one in'}`);
+  const scope = bail(
+    await p.select({
+      message: 'Which models should the stations use?',
+      options: [
+        { value: 'session', label: 'The session model everywhere', hint: 'whatever you start Claude Code (or another agent) with' },
+        { value: 'phase', label: 'Choose for planning, building and checking', hint: 'e.g. Fable plans, Opus builds' },
+        { value: 'station', label: 'Choose for every station' },
+        Object.keys(current).length && { value: 'keep', label: 'Keep the current setup' },
+      ].filter(Boolean),
+      initialValue: Object.keys(current).length ? 'keep' : 'session',
+    }),
+  );
+  if (scope === 'keep') return current;
+  if (scope === 'session') return {};
+  const models = {};
+  const set = (stations, value) => stations.forEach((st) => value !== 'inherit' && (models[st] = value));
+  if (scope === 'phase') {
+    for (const [key, phase] of Object.entries(PHASES)) {
+      const now = key === 'default' ? current.default : current[phase.stations[0]];
+      set(key === 'default' ? ['default'] : phase.stations, await pickOne(`${phase.label} ${pc.dim('(' + phase.hint + ')')}`, now, options));
     }
-    fs.writeFileSync(configPath(root), JSON.stringify(config, null, 2) + '\n');
-    apply(root, plan(root, config));
-    console.log(`${pc.green('✔')} models updated; skills and subagents refreshed.`);
-  } else if (action) {
-    throw new Error('Usage: buildline models [set <station> <model> | preset <name>]');
+  } else {
+    for (const st of MODEL_STATIONS) set([st], await pickOne(st, current[st] ?? current.default, options));
   }
-  if (opts.json) return console.log(JSON.stringify(Object.fromEntries(MODEL_STATIONS.map((s) => [s, modelFor(config, s)])), null, 2));
+  const missing = externalClis({ models }).filter((c) => !hasCommand(c));
+  if (missing.length) p.log.warn(`Not installed: ${missing.map((c) => `${CLIS[c].label} (${CLIS[c].install})`).join(', ')}`);
+  return models;
+}
+
+function saveModels(root, config, models) {
+  config.models = models;
+  fs.writeFileSync(configPath(root), JSON.stringify(config, null, 2) + '\n');
+  apply(root, plan(root, config));
+}
+
+function printModels(config) {
   console.log(`\n${pc.bold('Models per station')} ${pc.dim('(.buildline/buildline.json › models)')}\n`);
   for (const s of MODEL_STATIONS) {
     const m = modelFor(config, s);
     const missing = m.cli !== 'claude' && !hasCommand(m.cli) ? pc.red(` ${m.cli} not installed`) : '';
     console.log(`  ${s.padEnd(9)} ${m.model || m.cli !== 'claude' ? pc.cyan(describeModel(m)) : pc.dim(describeModel(m))}${missing}`);
   }
-  console.log(`\n  ${pc.dim('Change one:')} buildline models set review codex   ${pc.dim('Presets:')} ${Object.keys(PRESETS).join(', ')}\n`);
+  console.log();
+}
+
+/** Show, pick, set or check per-station models. */
+export async function models(root, args, opts) {
+  const config = loadConfig(root);
+  const [action, target, value] = args;
+  if (action === 'set') {
+    if (!target || !value) throw new Error(`Usage: buildline models set <station|phase> <model>   stations: default, ${MODEL_STATIONS.join(', ')}; phases: planning, building, checking`);
+    const next = { ...(config.models || {}) };
+    const changes = parseModelList(`${target}=${value === 'inherit' ? 'x' : value}`);
+    for (const st of Object.keys(changes)) value === 'inherit' ? delete next[st] : (next[st] = value);
+    saveModels(root, config, next);
+    console.log(`${pc.green('✔')} ${Object.keys(changes).join(', ')} → ${value}. Skills and subagents refreshed.`);
+  } else if (action === 'check') {
+    const values = [...new Set(MODEL_STATIONS.map((s) => modelFor(config, s)).filter((m) => m.model || m.cli !== 'claude').map(describeModel))];
+    if (!values.length) return console.log('Every station uses the session model; nothing to check.');
+    console.log(`\nAsking each tool what these resolve to today ${pc.dim('(one tiny request per Claude model)')}\n`);
+    let bad = 0;
+    for (const v of values) {
+      const r = checkModel(v, { cwd: root });
+      if (!r.ok) bad++;
+      console.log(`  ${r.ok ? pc.green('✔') : pc.red('✘')} ${v.padEnd(24)} ${r.ok ? pc.dim('→ ' + r.resolved + (r.note ? ` (${r.note})` : '')) : pc.red(r.error)}`);
+    }
+    console.log();
+    if (bad) process.exitCode = 1;
+    return;
+  } else if (action) {
+    throw new Error('Usage: buildline models [set <station|phase> <model> | check]');
+  } else if (!opts.json && process.stdout.isTTY && process.stdin.isTTY) {
+    printModels(config);
+    const next = await pickModels(config);
+    saveModels(root, config, next);
+    p.log.success('Saved. Skills and subagents refreshed.');
+  }
+  if (opts.json) return console.log(JSON.stringify(Object.fromEntries(MODEL_STATIONS.map((s) => [s, modelFor(config, s)])), null, 2));
+  printModels(config);
+  console.log(`  ${pc.dim('Change:')} buildline models   ${pc.dim('or')} buildline models set planning fable   ${pc.dim('Verify:')} buildline models check\n`);
 }
 
 export async function run(root, ref, opts) {
@@ -485,6 +552,7 @@ export async function home(root) {
           features.length && { value: 'open', label: 'Work on a feature', hint: 'approve, move, autopilot, open in Claude' },
           { value: 'ui', label: 'Open the dashboard', hint: 'browser UI for PMs and designers' },
           hasCommand('claude') && { value: 'claude', label: 'Open Claude Code at the front door', hint: '/buildline' },
+          { value: 'models', label: 'Choose models per station', hint: 'which model plans, builds and checks' },
           { value: 'gates', label: 'Run quality gates' },
           { value: 'doctor', label: 'Check setup (doctor)' },
           { value: 'update', label: 'Update Buildline files' },
@@ -496,6 +564,7 @@ export async function home(root) {
     if (action === 'new') await newFeature(root, null, {});
     if (action === 'ui') return (await import('./server.js')).serve(root, {});
     if (action === 'claude') return launchClaude(root, ['/buildline']);
+    if (action === 'models') saveModels(root, loadConfig(root), await pickModels(loadConfig(root)));
     if (action === 'gates') gates(root, []);
     if (action === 'doctor') doctor(root);
     if (action === 'update') await update(root, {});

package/src/models.js

@@ -1,9 +1,20 @@
 // Per-station model routing. `models` in buildline.json maps a station (or
-// "default") to a Claude Code model (opus, sonnet, haiku, a full model id) or to
-// another CLI: "codex", "codex:<model>", "gemini", "gemini:<model>".
+// "default") to whatever the user picked: a Claude Code alias (opus, fable, …)
+// or full model id, or another CLI: "codex", "codex:<model>", "gemini", "gemini:<model>".
+// Buildline never validates names against a list of its own: new models work the
+// day the underlying CLI accepts them. Picker choices are discovered at runtime.
+import { spawnSync } from 'node:child_process';
 
 export const MODEL_STATIONS = ['onboard', 'new', 'spec', 'design', 'plan', 'build', 'verify', 'review', 'ship'];
 
+// How the wizard groups stations when choosing by phase.
+export const PHASES = {
+  planning: { label: 'Planning', hint: 'spec, design, plan', stations: ['spec', 'design', 'plan'] },
+  building: { label: 'Building', hint: 'build: writing the code', stations: ['build'] },
+  checking: { label: 'Checking', hint: 'verify, review', stations: ['verify', 'review'] },
+  default: { label: 'Everything else', hint: 'onboard, intake, ship, and anything unset', stations: [] },
+};
+
 export const CLIS = {
   claude: { label: 'Claude Code', install: 'https://code.claude.com' },
   codex: { label: 'Codex CLI', install: 'npm i -g @openai/codex' },
@@ -19,15 +30,6 @@ export const STATION_SUBAGENTS = {
   review: 'buildline-reviewer',
 };
 
-const BALANCED = { spec: 'opus', design: 'opus', plan: 'opus', build: 'sonnet', verify: 'sonnet', review: 'opus' };
-
-export const PRESETS = {
-  session: { label: 'Same model everywhere', hint: 'every station uses the model you start the agent with', models: {} },
-  balanced: { label: 'Balanced', hint: 'Opus for spec, design, plan and review; Sonnet builds and verifies', models: BALANCED },
-  budget: { label: 'Budget', hint: 'Sonnet everywhere, Haiku for intake', models: { default: 'sonnet', new: 'haiku' } },
-  second: { label: 'Second opinion', hint: 'Balanced, and Codex reviews every diff', models: { ...BALANCED, review: 'codex' } },
-};
-
 /** "opus" → { cli: 'claude', model: 'opus' }; "codex:gpt-5" → { cli: 'codex', model: 'gpt-5' }. */
 export function parseModel(value) {
   const v = String(value ?? '').trim();
@@ -44,6 +46,89 @@ export function modelFor(config, station) {
 
 export const describeModel = ({ cli, model }) => (cli === 'claude' ? model || 'session model' : `${cli}${model ? ':' + model : ''}`);
 
+/** "planning=fable,build=claude-opus-5-5" → { spec, design, plan: 'fable', build: '…' }. Phases expand to their stations. */
+export function parseModelList(text) {
+  const models = {};
+  for (const pair of String(text || '').split(',').map((s) => s.trim()).filter(Boolean)) {
+    const [key, ...rest] = pair.split('=');
+    const value = rest.join('=').trim();
+    if (!value) throw new Error(`"${pair}": use station=model, e.g. plan=fable`);
+    const targets = PHASES[key] && key !== 'default' ? PHASES[key].stations : [key];
+    for (const t of targets) {
+      if (t !== 'default' && !MODEL_STATIONS.includes(t)) throw new Error(`Unknown station or phase "${key}". Use ${[...Object.keys(PHASES), ...MODEL_STATIONS].join(', ')}.`);
+      if (value !== 'inherit') models[t] = value;
+    }
+  }
+  return models;
+}
+
+const has = (cmd) => spawnSync(process.platform === 'win32' ? 'where' : 'which', [cmd], { stdio: 'ignore' }).status === 0;
+
+/** Model aliases the installed Claude Code advertises in `claude --help` (each tracks the newest model in its family). */
+export function claudeAliases() {
+  const res = spawnSync('claude', ['--help'], { encoding: 'utf8', timeout: 10000, shell: process.platform === 'win32' });
+  const help = (res.stdout || '').replace(/\s+/g, ' ');
+  const desc = help.match(/--model <model>(.*?)(?= --[a-z])/)?.[1] || '';
+  return [...new Set([...desc.matchAll(/'([a-z][\w.-]*)'/g)].map((m) => m[1]))];
+}
+
+/** Current Claude models from the Anthropic API, when an API key is available. */
+export async function anthropicModels() {
+  const key = process.env.ANTHROPIC_API_KEY;
+  if (!key) return [];
+  try {
+    const res = await fetch('https://api.anthropic.com/v1/models?limit=100', {
+      headers: { 'x-api-key': key, 'anthropic-version': '2023-06-01' },
+      signal: AbortSignal.timeout(4000),
+    });
+    if (!res.ok) return [];
+    return ((await res.json()).data || []).map((m) => ({ id: m.id, name: m.display_name || m.id }));
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Everything the picker can offer right now: aliases from the installed Claude
+ * Code, models from the API, other installed CLIs, and values already in the
+ * config. Each option is { value, label, hint }; "__other" means type one in.
+ */
+export async function discoverModelOptions(config = {}) {
+  const options = [{ value: 'inherit', label: 'Session model', hint: 'whatever model the agent was started with' }];
+  const seen = new Set(['inherit']);
+  const push = (o) => {
+    if (!seen.has(o.value)) seen.add(o.value), options.push(o);
+  };
+  const aliases = has('claude') ? claudeAliases() : [];
+  // If this Claude Code doesn't list aliases in --help, fall back to the long-standing ones.
+  for (const a of aliases.length ? aliases : ['opus', 'sonnet', 'haiku']) push({ value: a, label: a, hint: 'newest model in this family, follows Claude Code updates' });
+  for (const m of await anthropicModels()) push({ value: m.id, label: m.id, hint: m.name });
+  for (const v of Object.values(config.models || {})) push({ value: v, label: v, hint: 'already in your config' });
+  for (const cli of ['codex', 'gemini']) if (has(cli)) push({ value: cli, label: cli, hint: `${CLIS[cli].label}, its default model (or type ${cli}:<model>)` });
+  options.push({ value: '__other', label: 'Other…', hint: 'type any model name or id, e.g. claude-opus-5-5 or codex:gpt-5-codex' });
+  return options;
+}
+
+/**
+ * Ask the CLI which model a name resolves to today. Claude: one tiny headless
+ * request, reporting the model that actually answered. Others: installed or not.
+ */
+export function checkModel(value, { cwd } = {}) {
+  const m = parseModel(value);
+  if (m.cli !== 'claude') return has(m.cli) ? { ok: true, resolved: describeModel(m), note: 'installed, not called' } : { ok: false, error: `${CLIS[m.cli].label} not installed: ${CLIS[m.cli].install}` };
+  if (!has('claude')) return { ok: false, error: 'Claude Code not installed' };
+  const args = ['-p', 'Reply with OK.', '--output-format', 'json', '--max-turns', '1', ...(m.model ? ['--model', m.model] : [])];
+  const res = spawnSync('claude', args, { cwd, encoding: 'utf8', timeout: 120000, shell: process.platform === 'win32' });
+  try {
+    const out = JSON.parse(res.stdout);
+    const used = Object.keys(out.modelUsage || {});
+    if (out.is_error || !used.length) return { ok: false, error: String(out.result || 'no response').slice(0, 160) };
+    return { ok: true, resolved: used.join(', ') };
+  } catch {
+    return { ok: false, error: (res.stderr || res.stdout || 'no output').trim().split('\n').pop().slice(0, 160) };
+  }
+}
+
 /** Prompt that starts a station in the given CLI. */
 export function stationPrompt(cli, station, id) {
   const arg = id ? ` ${id}` : '';