kaizen-agent 0.4.0 → 0.5.0

package/cli/install.ts

@@ -1,7 +1,7 @@
 #!/usr/bin/env bun
 import {
   symlinkSync, mkdirSync, readdirSync, lstatSync, readlinkSync, unlinkSync,
-  existsSync, copyFileSync, readFileSync, appendFileSync,
+  existsSync, copyFileSync, readFileSync, appendFileSync, rmSync, writeFileSync,
 } from "node:fs";
 import { join, dirname, basename } from "node:path";
 import { homedir } from "node:os";
@@ -9,10 +9,12 @@ import { homedir } from "node:os";
 const home = homedir();
 const REPO_URL = "https://github.com/hfadhlullah/kaizen.git";
 const args = new Set(Bun.argv.slice(2));
+const upgrade = args.has("upgrade") || args.has("--upgrade");
+const wantSettings = args.has("settings") || args.has("config");
 const check = args.has("--check");
 const force = args.has("--force");
 const verbose = args.has("--verbose");
-const interactive = process.stdin.isTTY && !check && !args.has("--yes");
+const interactive = process.stdin.isTTY && !check && !upgrade && !args.has("--yes");
 
 const c = {
   dim: (s: string) => `\x1b[2m${s}\x1b[0m`,
@@ -21,19 +23,187 @@ const c = {
   green: (s: string) => `\x1b[32m${s}\x1b[0m`,
 };
 
-if (!check) {
+// Where each agent reads skills from. The skill folders follow the open Agent
+// Skills standard, so every one of these can run the workflow; agents/ and
+// commands/ are Claude Code's own formats and go nowhere else.
+const AGENTS = [
+  { name: "Claude Code", dir: ".claude", full: true },
+  { name: "Codex", dir: ".codex", full: false },
+  { name: "Antigravity", dir: ".agents", full: false },
+  { name: "OpenCode", dir: ".opencode", full: false },
+  { name: "Cursor", dir: ".cursor", full: false },
+  { name: "Gemini CLI", dir: ".gemini", full: false },
+];
+
+// Install into an agent that is actually present. Creating ~/.opencode for someone
+// who does not use OpenCode leaves litter that looks like configuration. Claude Code
+// is always a target: it is the one this is installed from.
+const found = (r: string) => AGENTS.filter((a) => a.dir === ".claude" || existsSync(join(r, a.dir)));
+
+if (wantSettings) {
+  const { settings } = await import("./settings.ts");
+  await settings(await resolveRepoQuietly());
+  process.exit(0);
+}
+
+// Bare `kaizen` on a machine where it is already installed is not an install --
+// show what the project is doing instead, and offer the things you would have
+// opened a terminal for.
+if (interactive && !upgrade && Bun.argv.length === 2) {
+  const repoDir = await resolveRepoQuietly();
+  const here = found(home);
+  const linked = here.every((a) =>
+    ["kaizen", "kaizen-help"].every((n) => existsSync(join(home, a.dir, "skills", n))));
+  if (linked) {
+    const { dashboard } = await import("./dashboard.ts");
+    await dashboard(repoDir, here.map((a) => a.name), async (action) => {
+      if (action === "settings") {
+        const { settings } = await import("./settings.ts");
+        await settings(repoDir, false);
+      } else if (action === "upgrade") {
+        return await runUpgrade(repoDir);
+      } else if (action === "init") {
+        const out = await Bun.$`bun run ${join(repoDir, "cli/install.ts")} --yes`.text();
+        return clean(out);
+      }
+    });
+    process.exit(0);
+  }
+}
+
+if (upgrade) await clearBunxCache();
+if (!check && !upgrade) await welcome();
+
+async function welcome() {
+  const rgb = (r: number, g: number, b: number, s: string) =>
+    `\x1b[38;2;${r};${g};${b}m${s}\x1b[0m`;
+
+  // Fuji: snow on the peak, deepening blue down the slope.
+  const WORD = [
+    "██╗  ██╗ █████╗ ██╗███████╗███████╗███╗   ██╗",
+    "██║ ██╔╝██╔══██╗██║╚══███╔╝██╔════╝████╗  ██║",
+    "█████╔╝ ███████║██║  ███╔╝ █████╗  ██╔██╗ ██║",
+    "██╔═██╗ ██╔══██║██║ ███╔╝  ██╔══╝  ██║╚██╗██║",
+    "██║  ██╗██║  ██║██║███████╗███████╗██║ ╚████║",
+    "╚═╝  ╚═╝╚═╝  ╚═╝╚═╝╚══════╝╚══════╝╚═╝  ╚═══╝",
+  ];
+  const W = 69, C = 34, SNOW = 3;
+  // One constant slope, three columns per row, all the way down. The rows behind
+  // the wordmark keep the same rate, so the edge that goes in above the letters
+  // comes out below them on the same line -- vary it and the cone reads broken.
+  const H = [1, 4, 7, 10, 13, 16, 19, 22, 25, 28, 31, 34];
+
+  // Anything that would wrap is worse than the smaller thing that fits: the
+  // mountain needs the full width, the wordmark needs 47, below that use words.
+  const cols = process.stdout.columns || 80;
+  const wide = cols >= W + 4;
+  if (cols < 49) {
+    console.log(`\n  ${c.bold("kaizen")}`);
+  } else {
+
+  const cell: string[][] = H.map(() => Array(W).fill(" "));
+  const isWord: boolean[][] = H.map(() => Array(W).fill(false));
+
+  if (wide) {
+    for (const [i, h] of H.entries()) {
+      const l = C - h, r = C + h;
+      if (i < SNOW) {                       // solid cap
+        cell[i]![l] = "▄"; cell[i]![r] = "▄";
+        for (let x = l + 1; x < r; x++) cell[i]![x] = "█";
+      } else {                              // slope, drawn as two edges
+        // Below the wordmark's top row the letters own the middle, so draw an
+        // edge only where all three of its characters clear them.
+        const band = i >= H.length - WORD.length;
+        const gap = Math.floor((W - 45) / 2) - 2;
+        if (!band || l + 2 < gap) {
+          cell[i]![l] = "▄"; cell[i]![l + 1] = "█"; cell[i]![l + 2] = "▀";
+          cell[i]![r - 2] = "▀"; cell[i]![r - 1] = "█"; cell[i]![r] = "▄";
+        }
+      }
+    }
+  }
+
+  const top = H.length - WORD.length, left = Math.floor((W - 45) / 2);
+  for (let r = top; r < H.length; r++)      // air around the letters
+    for (let x = left - 2; x < left + 47; x++) if (x >= 0 && x < W) cell[r]![x] = " ";
+  for (const [r, line] of WORD.entries())
+    for (const [x, ch] of [...line].entries())
+      if (ch !== " ") { cell[top + r]![left + x] = ch; isWord[top + r]![left + x] = true; }
+
+  console.log();
+  for (const [i, row] of cell.entries()) {
+    if (!wide && i < top) continue;          // no mountain to draw, no blank rows
+    const slope = Math.max(0, i - SNOW) / (H.length - SNOW);
+    const mountain: [number, number, number] = i < SNOW
+      ? [255 - i * 8, 255 - i * 5, 255]
+      : [Math.round(150 - slope * 105), Math.round(190 - slope * 110), Math.round(245 - slope * 80)];
+
+    // With no mountain there is nothing to sit under, so drop its left margin.
+    const off = wide ? 0 : left;
+    const chars = row.slice(off), flags = isWord[i]!.slice(off);
+
+    let out = "  ", run = "", runWord = flags[0]!;
+    const flush = () => {
+      if (!run) return;
+      const t = (i - top) / (WORD.length - 1);
+      const col: [number, number, number] = runWord
+        ? [Math.round(214 - t * 150), Math.round(232 - t * 130), Math.round(255 - t * 45)]
+        : mountain;
+      out += rgb(col[0], col[1], col[2], run);
+      run = "";
+    };
+    for (const [x, ch] of chars.entries()) {
+      if (flags[x] !== runWord) { flush(); runWord = flags[x]!; }
+      run += ch;
+    }
+    flush();
+    console.log(out.replace(/\s+$/, ""));
+  }
+  if (wide) console.log("  " + rgb(38, 66, 130, "▀".repeat(W)));
+  }
+
   console.log(`
-  ${c.bold("kaizen")} ${c.dim("改善")}
-  ${c.dim("plan  ->  approve  ->  build  ->  review  ->  fix")}
+  ${c.bold("改善")}  ${c.dim("kaizen — continuous improvement")}
+
+  ${c.dim("A staged workflow for AI agents — code, writing, research, operations:")}
+  ${c.dim("plan  ->  you approve  ->  build  ->  independent review  ->  bounded fix loop")}
 `);
+
+  if (interactive) await anyKey();
+}
+
+// A pause before anything touches the filesystem, and the place to back out.
+async function anyKey() {
+  const { stdin, stdout } = process;
+  stdout.write(`  ${c.dim("press")} ${c.cyan("enter")} ${c.dim("to install, or")} ${c.cyan("ctrl-c")} ${c.dim("to leave")}`);
+  stdin.setRawMode(true);
+  stdin.resume();
+  await new Promise<void>((resolve) => {
+    const onData = (chunk: Buffer) => {
+      if (chunk.toString().includes("\x03")) { stdout.write("\n\n  nothing installed\n"); process.exit(130); }
+      stdin.off("data", onData);
+      resolve();
+    };
+    stdin.on("data", onData);
+  });
+  stdin.setRawMode(false);
+  stdin.pause();
+  stdout.write("\r\x1b[2K");
 }
 
 const repo = await resolveRepo();
 const root = await chooseRoot();
-const base = join(root, ".claude");
+const targets = found(root);
 
 // ---------------------------------------------------------------- repo
 
+// Settings only needs the clone's default config, not a pull.
+async function resolveRepoQuietly() {
+  const here = dirname(import.meta.dir);
+  if (existsSync(join(here, ".git"))) return here;
+  return process.env.KAIZEN_HOME ?? join(home, "kaizen");
+}
+
 async function resolveRepo() {
   const here = dirname(import.meta.dir);
   if (existsSync(join(here, ".git"))) return here;
@@ -59,9 +229,16 @@ async function resolveRepo() {
 async function chooseRoot() {
   if (args.has("--project")) return process.cwd();
   if (args.has("--global") || !interactive) return home;
+  // A project install only means something in a project. Standing in the home
+  // directory it is the global install under another name, and outside a
+  // repository there is nothing for it to belong to.
+  const cwd = process.cwd();
+  if (cwd === home || !existsSync(join(cwd, ".git"))) return home;
+
+  const names = (r: string) => found(r).map((a) => a.name).join(", ");
   return select("Install kaizen for", [
-    { label: "Every project", hint: tilde(join(home, ".claude")), value: home },
-    { label: "This project only", hint: join(".claude"), value: process.cwd() },
+    { label: "Globally", hint: `every project \u2014 ${names(home)}`, value: home },
+    { label: "This project only", hint: `${basename(cwd)}/ \u2014 ${names(cwd)}`, value: cwd },
   ]);
 }
 
@@ -73,11 +250,13 @@ function dirEntries(sub: string) {
     .map((f) => join(repo, sub, f));
 }
 
-const links = [
-  ...["kaizen", "kaizen-help"].map((n) => [join(repo, "skills", n), "skills"] as const),
-  ...dirEntries("agents").map((f) => [f, "agents"] as const),
-  ...dirEntries("commands").map((f) => [f, "commands"] as const),
-];
+const links = targets.flatMap((a) => [
+  ...["kaizen", "kaizen-help"].map((n) => [join(repo, "skills", n), join(a.dir, "skills")] as const),
+  ...(a.full ? [
+    ...dirEntries("agents").map((f) => [f, join(a.dir, "agents")] as const),
+    ...dirEntries("commands").map((f) => [f, join(a.dir, "commands")] as const),
+  ] : []),
+]);
 
 function linkState(src: string, dest: string) {
   try {
@@ -91,7 +270,7 @@ function linkState(src: string, dest: string) {
 
 let blocked = 0, wrote = 0, already = 0;
 for (const [src, sub] of links) {
-  const dir = join(base, sub);
+  const dir = join(root, sub);
   const dest = join(dir, basename(src));
   const state = linkState(src, dest);
   const name = `${sub}/${basename(src)}`;
@@ -119,22 +298,49 @@ if (check) {
   process.exit(blocked ? 1 : 0);
 }
 
+const into = targets.map((a) => a.name).join(", ");
 step(
-  wrote && already ? `linked ${wrote} new, ${already} already in place`
-  : wrote ? `linked ${wrote} skills, agents, and commands into ${tilde(base)}`
-  : `already installed in ${tilde(base)} ${c.dim("(nothing to change)")}`,
+  wrote && already ? `linked ${wrote} new, ${already} already in place — ${into}`
+  : wrote ? `linked ${wrote} files into ${into}`
+  : `already installed for ${into} ${c.dim("(nothing to change)")}`,
 );
+if (targets.length === 1) {
+  console.log(`    ${c.dim("Codex, Antigravity, OpenCode, Cursor and Gemini CLI get it too,")}`);
+  console.log(`    ${c.dim("if their directory exists when you install.")}`);
+}
 
 // ---------------------------------------------------------------- repo setup
 
+if (!args.has("--project")) installLauncher();
+
+// bunx runs from a temp copy and leaves nothing behind, so there is no `kaizen` to
+// type afterwards. A launcher pointed at the clone gives one, and keeps working
+// after the clone updates.
+function installLauncher() {
+  const binDir = join(home, ".local", "bin");
+  const bin = join(binDir, "kaizen");
+  const script = `#!/bin/sh\n# kaizen launcher -- installed by kaizen-agent\nexec bun run ${join(repo, "cli/install.ts")} "$@"\n`;
+  try {
+    if (existsSync(bin) && readFileSync(bin, "utf8") === script) return;
+    mkdirSync(binDir, { recursive: true });
+    writeFileSync(bin, script, { mode: 0o755 });
+    const onPath = (process.env.PATH ?? "").split(":").includes(binDir);
+    step(onPath
+      ? `${c.cyan("kaizen upgrade")} is now on your PATH`
+      : `wrote ${tilde(bin)} ${c.dim("— add ~/.local/bin to PATH to use it")}`);
+  } catch {
+    /* a read-only home is not worth failing the install over */
+  }
+}
+
 const inGitRepo = existsSync(join(process.cwd(), ".git"));
 const kaizenDir = join(process.cwd(), ".kaizen");
 
 if (inGitRepo && !existsSync(kaizenDir)) {
   const now = interactive
     ? await select(`Set up ${basename(process.cwd())}/ for kaizen now`, [
-        { label: "Yes", hint: "writes .kaizen/ — spec, config, gitignore entry", value: true },
-        { label: "Not now", hint: "run /kaizen-init in the repo later", value: false },
+        { label: "Yes", hint: "writes .kaizen/ and a CLAUDE.md line so it runs by default", value: true },
+        { label: "Not now", hint: "the first /kaizen run will do it", value: false },
       ])
     : false;
   if (now) initRepo();
@@ -157,23 +363,112 @@ function initRepo() {
     appendFileSync(gi, (current && !current.endsWith("\n") ? "\n" : "") + "\n# kaizen run state\n" + rules);
   }
   step("wrote .kaizen/ and the gitignore entry");
+  writePointer();
+}
+
+// Claude Code loads a skill by matching its description, so an ordinary request
+// ("add a discount cap") does not reach kaizen unless the project says it should.
+// One line in the agent instructions is what makes it the default here.
+function writePointer() {
+  const block = `\n## Kaizen workflow\n\nNon-trivial work in this repository follows the staged workflow in\n\`.kaizen/spec.md\`: plan, human approval, build, independent review, bounded fix\nloop. Invoke the \`kaizen\` skill for it — do not carry the stages out inline.\n\nNon-trivial means work worth a plan: a change across more than one file, anything\nwith a migration or a rollback, or a document someone else will act on. Answering a\nquestion, reading code, or a one-line fix is not, and should not start a run.\n\nRun state lives in \`.kaizen/runs/<id>/\`. Read \`state.json\` first and continue from\nthe stage it names; never advance a run whose \`awaiting\` field is non-null without a\nrecorded human decision.\n`;
+
+  for (const name of ["CLAUDE.md", "AGENTS.md"]) {
+    const f = join(process.cwd(), name);
+    const current = existsSync(f) ? readFileSync(f, "utf8") : "";
+    if (current.includes("## Kaizen workflow")) continue;
+    if (!current && name === "AGENTS.md") continue;   // do not create one that was never there
+    const text = current ? (current.endsWith("\n") ? "" : "\n") + block : block.slice(1);
+    appendFileSync(f, text);
+    step(`${existsSync(f) && current ? "added to" : "wrote"} ${name} ${c.dim("— kaizen now runs without being asked for")}`);
+  }
 }
 
 // ---------------------------------------------------------------- done
 
-console.log(`
+if (upgrade) {
+  let version = "";
+  try { version = JSON.parse(readFileSync(join(repo, "package.json"), "utf8")).version; } catch {}
+  console.log(`
+  ${c.bold("Up to date")}${version ? c.dim(`  —  kaizen ${version}`) : ""}
+  ${c.dim("Restart Claude Code to pick up any new slash commands.")}
+`);
+} else {
+  console.log(`
   ${c.bold("Next")}
     1  restart Claude Code ${c.dim("— skills load live, slash commands only at session start")}
-    2  ${c.cyan("/kaizen-init")} ${c.dim("in any repo you want to use it on")}
-    3  ${c.cyan("/kaizen-plan <what you want built>")}
+    2  ${c.cyan("/kaizen <what you want done>")} ${c.dim("in any project — it sets itself up on first run")}
 
-  ${c.dim("/kaizen-help lists every command.")}
+  ${c.dim("/kaizen-help lists every command.  kaizen upgrade updates all of this.")}
 `);
+}
 if (blocked) process.exit(1);
 
 // ---------------------------------------------------------------- helpers
 
 function step(msg: string) { console.log(`  ${c.green("+")} ${msg}`); }
+
+// Runs the upgrade and reports what it actually did, version to version, so the
+// dashboard can show a result rather than the user wondering whether it worked.
+async function runUpgrade(repoDir: string) {
+  const before = versionOf(repoDir);
+  const out = await Bun.$`bun run ${join(repoDir, "cli/install.ts")} upgrade`.text().catch(() => "");
+  const after = versionOf(repoDir);
+  const latest = await npmLatest();
+
+  const lines = [
+    before === after
+      ? `${c.bold("Already up to date")}  ${c.dim(after)}`
+      : `${c.bold("Upgraded")}  ${c.dim(before)} → ${c.green(after)}`,
+    "",
+    // Only the step lines: the captured run's own heading and restart notice
+    // repeat what this panel already says above them.
+    ...clean(out)
+      .filter((l) => l.trim().startsWith("+") || l.trim().startsWith("skip"))
+      .map((l) => c.dim(l.trim())),
+  ];
+  if (latest && latest !== after) {
+    lines.push("", c.dim(`npm publishes ${latest}; this install follows the git clone.`));
+  }
+  lines.push("", c.dim("Restart your agent to pick up new slash commands."));
+  return lines;
+}
+
+function versionOf(dir: string) {
+  try { return JSON.parse(readFileSync(join(dir, "package.json"), "utf8")).version as string; }
+  catch { return "?"; }
+}
+
+async function npmLatest() {
+  try {
+    const r = await fetch("https://registry.npmjs.org/kaizen-agent/latest", {
+      signal: AbortSignal.timeout(4000),
+    });
+    return ((await r.json()) as { version?: string }).version ?? null;
+  } catch { return null; }        // offline is not an upgrade failure
+}
+
+// Captured output still carries its own colour codes, which stop any test on the
+// text from matching and would nest inside this panel's own styling.
+function clean(out: string) {
+  return out.split("\n").map((l) => l.replace(/\x1b\[[0-9;]*m/g, "").replace(/\r$/, "").trimEnd());
+}
+
+// bunx keeps an extracted copy per package under the temp directory and reuses it
+// without re-resolving, so an upgrade that only pulls the clone still leaves the
+// next `bunx kaizen-agent` running whatever was cached the first time.
+async function clearBunxCache() {
+  const tmp = process.env.TMPDIR ?? "/tmp";
+  let removed = 0;
+  try {
+    for (const name of readdirSync(tmp)) {
+      if (/^bunx-.*kaizen-agent/.test(name)) {
+        rmSync(join(tmp, name), { recursive: true, force: true });
+        removed++;
+      }
+    }
+  } catch { /* an unreadable temp directory is not worth failing an upgrade over */ }
+  step(removed ? `cleared ${removed} cached copy of the installer` : "no installer cache to clear");
+}
 function tilde(p: string) { return p.startsWith(home) ? "~" + p.slice(home.length) : p; }
 
 // Arrow-key picker. Raw mode delivers keys unbuffered; the alternative is a

package/cli/settings.ts

@@ -0,0 +1,160 @@
+// Full-screen settings browser for .kaizen/config.yml.
+// Arrow keys move and change; every change is written straight to the file.
+import { existsSync, readFileSync, writeFileSync, copyFileSync, mkdirSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { homedir } from "node:os";
+
+type Setting = { key: string; values: string[]; help: string };
+
+const SETTINGS: Setting[] = [
+  { key: "mode", values: ["approve", "auto", "plan-only", "review-only"], help: "Where a run stops" },
+  { key: "build.executor", values: ["subagent", "inline", "ask"], help: "Who carries out the approved plan" },
+  { key: "approvals.plan", values: ["true", "false"], help: "Stop and show the plan before anything is built" },
+  { key: "approvals.review", values: ["true", "false"], help: "Stop after the review, before the run is done" },
+  { key: "approvals.each_file", values: ["true", "false"], help: "Confirm every individual edit" },
+  { key: "auto_fix.enabled", values: ["true", "false"], help: "Fix findings without asking" },
+  { key: "auto_fix.min_severity", values: ["critical", "high", "medium", "low"], help: "How bad a finding must be to be fixed automatically" },
+  { key: "auto_fix.max_iterations", values: ["1", "2", "3", "4", "5"], help: "Fix and recheck rounds before escalating" },
+  { key: "review.write_memory", values: ["true", "false"], help: "Let the reviewer append lessons to memory.md" },
+  { key: "review.memory_max_lines", values: ["50", "100", "200", "400"], help: "Size cap on memory.md, a tax on every run" },
+  { key: "track.default", values: ["", "software", "writing", "communication", "operations", "research"], help: "Pin a track, or leave empty to infer per run" },
+  { key: "state.keep_runs", values: ["5", "10", "20", "50"], help: "Completed runs kept before the oldest is pruned" },
+  { key: "git.auto_commit", values: ["false", "true"], help: "Commit the work when a run finishes" },
+  { key: "git.branch_before_implement", values: ["true", "false"], help: "Branch before building when on the default branch" },
+];
+
+const c = {
+  dim: (s: string) => `\x1b[2m${s}\x1b[0m`,
+  bold: (s: string) => `\x1b[1m${s}\x1b[0m`,
+  cyan: (s: string) => `\x1b[36m${s}\x1b[0m`,
+  green: (s: string) => `\x1b[32m${s}\x1b[0m`,
+  inv: (s: string) => `\x1b[7m${s}\x1b[0m`,
+};
+
+export async function settings(repoRoot: string, standalone = true) {
+  const file = locate();
+  if (!existsSync(file)) {
+    mkdirSync(dirname(file), { recursive: true });
+    copyFileSync(join(repoRoot, "skills/kaizen/config.default.yml"), file);
+  }
+
+  const { stdin, stdout } = process;
+  if (!stdin.isTTY) { console.log(`Settings live in ${file}`); return; }
+
+  let active = 0, saved = "";
+  const draw = () => {
+    const text = readFileSync(file, "utf8");
+    const rows = SETTINGS.map((s) => ({ s, value: read(text, s.key) ?? c.dim("(default)") }));
+    const width = Math.max(...SETTINGS.map((s) => s.key.length)) + 4;
+
+    stdout.write("\x1b[H\x1b[2J");           // home, clear
+    stdout.write(`\n  ${c.bold("kaizen settings")}   ${c.dim(tilde(file))}\n\n`);
+    for (const [i, { s, value }] of rows.entries()) {
+      const on = i === active;
+      const name = s.key.padEnd(width);
+      stdout.write(on
+        ? `  ${c.cyan("›")} ${c.bold(name)}${c.inv(` ${value} `)}\n`
+        : `    ${c.dim(name)}${value}\n`);
+    }
+    stdout.write(`\n  ${c.dim(SETTINGS[active]!.help)}\n`);
+    stdout.write(`\n  ${c.dim("↑↓ move · ←→ change · backspace back")}   ${saved}\n`);
+  };
+
+  stdout.write("\x1b[?1049h\x1b[?25l");      // alternate screen, hide cursor
+  stdin.setRawMode(true);
+  stdin.resume();
+  draw();
+
+  await new Promise<void>((resolve) => {
+    const onData = (chunk: Buffer) => {
+      const keys = chunk.toString();
+      for (let i = 0; i < keys.length; i++) {
+        const rest = keys.slice(i);
+        // esc, q, backspace, and left-at-the-edge all mean "back to where I came
+        // from" -- the settings screen is always something you opened from
+        // somewhere else.
+        if (rest.startsWith("\x03") || rest.startsWith("q") || rest === "\x1b"
+            || rest.startsWith("\x7f") || rest.startsWith("\b")) {
+          stdin.off("data", onData); return resolve();
+        }
+        if (rest.startsWith("\x1b[A")) { active = (active - 1 + SETTINGS.length) % SETTINGS.length; i += 2; }
+        else if (rest.startsWith("\x1b[B")) { active = (active + 1) % SETTINGS.length; i += 2; }
+        else if (rest.startsWith("\x1b[C") || rest.startsWith("\x1b[D") || rest.startsWith("\r")) {
+          const step = rest.startsWith("\x1b[D") ? -1 : 1;
+          const s = SETTINGS[active]!;
+          const text = readFileSync(file, "utf8");
+          const now = read(text, s.key) ?? s.values[0]!;
+          const at = s.values.indexOf(now);
+          const next = s.values[((at < 0 ? 0 : at) + step + s.values.length) % s.values.length]!;
+          writeFileSync(file, write(text, s.key, next));
+          saved = c.green(`saved ${s.key} = ${next || '""'}`);
+          if (!rest.startsWith("\r")) i += 2;
+        } else if (rest.startsWith("k")) active = (active - 1 + SETTINGS.length) % SETTINGS.length;
+        else if (rest.startsWith("j")) active = (active + 1) % SETTINGS.length;
+        else continue;
+        draw();
+      }
+    };
+    stdin.on("data", onData);
+  });
+
+  stdin.setRawMode(false);
+  stdin.pause();
+  stdout.write("\x1b[?25h\x1b[?1049l");      // restore cursor and screen
+  // Returning to the dashboard means returning to its alternate screen, where a
+  // line printed here would never be seen.
+  if (standalone) console.log(`  ${c.green("+")} settings saved to ${tilde(file)}\n`);
+}
+
+// The nearest .kaizen wins, exactly as the workflow resolves it.
+function locate() {
+  let dir = process.cwd();
+  for (;;) {
+    if (existsSync(join(dir, ".kaizen"))) return join(dir, ".kaizen", "config.yml");
+    if (existsSync(join(dir, ".git"))) break;
+    const up = dirname(dir);
+    if (up === dir) break;
+    dir = up;
+  }
+  return join(homedir(), ".kaizen", "config.yml");
+}
+
+// Read and write a dotted key by walking indentation, so the comment above every
+// key survives. Parsing to an object and dumping it back would delete all of them.
+function lineOf(text: string, key: string) {
+  const parts = key.split(".");
+  const lines = text.split("\n");
+  let depth = 0, from = 0;
+  for (const [pi, part] of parts.entries()) {
+    const want = new RegExp(`^ {${depth}}${part}:`);
+    let found = -1;
+    for (let i = from; i < lines.length; i++) {
+      if (want.test(lines[i]!)) { found = i; break; }
+      if (pi > 0 && /^\S/.test(lines[i]!) && i > from) break;   // left the parent block
+    }
+    if (found < 0) return { lines, index: -1, indent: depth };
+    from = found + 1; depth += 2;
+  }
+  return { lines, index: from - 1, indent: depth - 2 };
+}
+
+function read(text: string, key: string) {
+  const { lines, index } = lineOf(text, key);
+  if (index < 0) return null;
+  const v = lines[index]!.split(":").slice(1).join(":").split("#")[0]!.trim();
+  return v.replace(/^["']|["']$/g, "");
+}
+
+function write(text: string, key: string, value: string) {
+  const { lines, index, indent } = lineOf(text, key);
+  if (index < 0) return text;
+  const name = key.split(".").pop()!;
+  const shown = value === "" ? '""' : value;
+  lines[index] = `${" ".repeat(indent)}${name}: ${shown}`;
+  return lines.join("\n");
+}
+
+function tilde(p: string) {
+  const h = homedir();
+  return p.startsWith(h) ? "~" + p.slice(h.length) : p;
+}

package/commands/kaizen-config.md

@@ -0,0 +1,5 @@
+---
+description: Show the kaizen settings for this project and change them interactively
+---
+
+Invoke the `kaizen` skill with argument `config`.

package/package.json

@@ -1,10 +1,11 @@
 {
   "name": "kaizen-agent",
-  "version": "0.4.0",
-  "description": "Staged AI development workflow: plan, human approval, implement, independent review, bounded fix loop.",
+  "version": "0.5.0",
+  "description": "Staged workflow for AI agents \u2014 code, writing, research, operations: plan, human approval, build, independent review, bounded fix loop.",
   "type": "module",
   "bin": {
-    "kaizen-agent": "./cli/install.ts"
+    "kaizen-agent": "./cli/install.ts",
+    "kaizen": "./cli/install.ts"
   },
   "files": [
     "cli",
@@ -30,6 +31,8 @@
     "skill",
     "codex",
     "antigravity",
-    "code-review"
+    "code-review",
+    "writing",
+    "research"
   ]
 }