kaizen-agent 0.7.4 → 1.1.0

package/README.md

@@ -5,6 +5,7 @@
 <p align="center"><i>Your AI agent shows you the plan before it does the work,<br>and a second agent checks what it did.</i></p>
 
 <p align="center">
+  <a href="https://github.com/hfadhlullah/kaizen/stargazers"><img alt="stars" src="https://img.shields.io/github/stars/hfadhlullah/kaizen?style=social"></a>
   <a href="https://www.npmjs.com/package/kaizen-agent"><img alt="npm" src="https://img.shields.io/npm/v/kaizen-agent?color=2d50a5&label=npm"></a>
   <a href="https://github.com/hfadhlullah/kaizen/blob/main/LICENSE"><img alt="license" src="https://img.shields.io/npm/l/kaizen-agent?color=2d50a5"></a>
   <img alt="dependencies" src="https://img.shields.io/badge/dependencies-0-2d50a5">
@@ -13,6 +14,16 @@
 
 ---
 
+```bash
+# 1. Install Bun (prerequisite)
+curl -fsSL https://bun.sh/install | bash
+
+# 2. Install Kaizen
+bunx kaizen-agent
+```
+
+---
+
 ## The problem
 
 You ask an AI to do something real — write the launch email, draft the policy,
@@ -217,12 +228,28 @@ kaizen Done, and reviewed. Two things found:
 
 ## Install
 
+### Prerequisites: Bun
+
+Kaizen's installer and interactive dashboard require [Bun](https://bun.sh). If you don't have Bun installed yet:
+
+```bash
+# macOS, Linux, WSL
+curl -fsSL https://bun.sh/install | bash
+
+# or via Homebrew
+brew install oven-sh/bun/bun
+
+# or via npm
+npm install -g bun
+```
+
+### Install Kaizen
+
 ```bash
 bunx kaizen-agent
 ```
 
-It walks you through where to install, then tells you what to type next. Works with
-`npx` too. Restart your editor afterwards.
+It walks you through where to install, prompts for your workflow preset (`medium`, `low`, or `ultra`), then tells you what to type next. Restart your editor afterwards.
 
 Run from inside a project it asks whether to install globally or for that project
 alone; anywhere else — your home directory, a plain folder, a script — it installs

package/cli/dashboard.ts

@@ -41,6 +41,80 @@ const WORDMARK = [
   "█ █  █ █  █  █▄▄  █▄▄  █  █",
 ];
 
+const KNOWN_AGENTS = [
+  { name: "Claude Code", dir: ".claude", cmd: "claude" },
+  { name: "Antigravity", dir: ".agents", cmd: "agy" },
+  { name: "Codex", dir: ".codex", cmd: "codex" },
+  { name: "OpenCode", dir: ".opencode", cmd: "opencode" },
+  { name: "Gemini CLI", dir: ".gemini", cmd: "gemini" },
+  { name: "Cursor", dir: ".cursor", cmd: "cursor" },
+];
+
+function detectDefaultAgent(projectDir: string): { name: string; cmd: string } {
+  const cfgFile = existsSync(join(projectDir, ".kaizen", "config.yml"))
+    ? join(projectDir, ".kaizen", "config.yml")
+    : join(home, ".kaizen", "config.yml");
+  if (existsSync(cfgFile)) {
+    const text = readFileSync(cfgFile, "utf8");
+    const m = /^\s*agent:\s*\n\s*default:\s*(\S+)/m.exec(text) || /^\s*agent\.default:\s*(\S+)/m.exec(text);
+    if (m && m[1] && m[1] !== "auto") {
+      const found = KNOWN_AGENTS.find((a) => a.cmd === m[1] || a.name.toLowerCase() === m[1].toLowerCase());
+      if (found && Bun.which(found.cmd)) return found;
+    }
+  }
+
+  for (const a of KNOWN_AGENTS) {
+    if (existsSync(join(projectDir, a.dir)) && Bun.which(a.cmd)) return a;
+  }
+  if (Bun.which("claude")) return { name: "Claude Code", cmd: "claude" };
+  for (const a of KNOWN_AGENTS) {
+    if (Bun.which(a.cmd)) return a;
+  }
+  return { name: "Claude Code", cmd: "claude" };
+}
+
+function findTerminal(cwd: string, fullCmd: string[]): { cmd: string[]; detached: boolean } | null {
+  const hasDisplay = Boolean(process.env.WAYLAND_DISPLAY || process.env.DISPLAY);
+  const inTmux = Boolean(process.env.TMUX);
+
+  if (process.env.TERMINAL && Bun.which(process.env.TERMINAL)) {
+    const term = process.env.TERMINAL;
+    if (term.includes("kitty")) return { cmd: [term, "--directory", cwd, ...fullCmd], detached: true };
+    if (term.includes("alacritty")) return { cmd: [term, "--working-directory", cwd, "-e", ...fullCmd], detached: true };
+    if (term.includes("ghostty")) return { cmd: [term, `--working-directory=${cwd}`, "-e", ...fullCmd], detached: true };
+    if (term.includes("foot")) return { cmd: [term, "-D", cwd, ...fullCmd], detached: true };
+    return { cmd: [term, "-e", ...fullCmd], detached: true };
+  }
+
+  if (hasDisplay && Bun.which("xdg-terminal-exec")) {
+    return { cmd: ["xdg-terminal-exec", `--dir=${cwd}`, "--", ...fullCmd], detached: true };
+  }
+
+  if (hasDisplay) {
+    if (Bun.which("kitty")) return { cmd: ["kitty", "--directory", cwd, ...fullCmd], detached: true };
+    if (Bun.which("ghostty")) return { cmd: ["ghostty", `--working-directory=${cwd}`, "-e", ...fullCmd], detached: true };
+    if (Bun.which("alacritty")) return { cmd: ["alacritty", "--working-directory", cwd, "-e", ...fullCmd], detached: true };
+    if (Bun.which("foot")) return { cmd: ["foot", "-D", cwd, ...fullCmd], detached: true };
+    if (Bun.which("wezterm")) return { cmd: ["wezterm", "start", "--cwd", cwd, "--", ...fullCmd], detached: true };
+    if (Bun.which("gnome-terminal")) return { cmd: ["gnome-terminal", `--working-directory=${cwd}`, "--", ...fullCmd], detached: true };
+    if (Bun.which("xfce4-terminal")) return { cmd: ["xfce4-terminal", `--default-working-directory=${cwd}`, "-x", ...fullCmd], detached: true };
+    if (Bun.which("konsole")) return { cmd: ["konsole", "--workdir", cwd, "-e", ...fullCmd], detached: true };
+    if (Bun.which("xterm")) return { cmd: ["xterm", "-e", `cd "${cwd}" && ${fullCmd.join(" ")}`], detached: true };
+  }
+
+  if (inTmux && Bun.which("tmux")) {
+    const cmdStr = fullCmd.map((a) => (a.includes(" ") ? JSON.stringify(a) : a)).join(" ");
+    return { cmd: ["tmux", "new-window", "-c", cwd, cmdStr], detached: false };
+  }
+
+  if (process.platform === "darwin") {
+    const cmdStr = fullCmd.map((a) => (a.includes(" ") ? `\\"${a}\\"` : a)).join(" ");
+    const script = `tell application "Terminal" to do script "cd \\"${cwd}\\" && ${cmdStr}"\ntell application "Terminal" to activate`;
+    return { cmd: ["osascript", "-e", script], detached: true };
+  }
+
+  return null;
+}
 
 export async function dashboard(
   repo: string,
@@ -101,16 +175,19 @@ export async function dashboard(
 
   // An action that has something to say says it here, on its own screen, rather
   // than printing to a terminal the dashboard is about to paint over.
-  async function report(lines: string[]) {
+  async function report(lines: string[], footer = "any key to go back"): Promise<string> {
     stdout.write("\x1b[?1049h\x1b[?25l\x1b[H\x1b[2J");
     stdout.write("\n");
     for (const line of lines) stdout.write(`  ${line}\n`);
-    stdout.write(`\n  ${c.dim("any key to go back")}\n`);
+    stdout.write(`\n  ${c.dim(footer)}\n`);
     stdin.setRawMode(true);
     stdin.resume();
+    let key = "";
     await new Promise<void>((resolve) => {
       const once = (chunk: Buffer) => {
-        if (chunk.toString().includes("\x03")) process.exit(130);
+        const s = chunk.toString();
+        if (s.includes("\x03")) process.exit(130);
+        key = s;
         stdin.off("data", once);
         resolve();
       };
@@ -119,6 +196,7 @@ export async function dashboard(
     stdin.setRawMode(false);
     stdin.pause();
     stdout.write("\x1b[?25h\x1b[?1049l");
+    return key;
   }
 
   // ---------------------------------------------------------------- views
@@ -338,17 +416,84 @@ export async function dashboard(
       }
     }
     for (;;) {
-      const { index } = await pick(from ? `Backlog — ${label(from)}` : "Backlog — open items",
-        rows, "enter read · backspace back", (n) => full[n] === null);
+      const { index, key } = await pick(
+        from ? `Backlog — ${label(from)}` : "Backlog — open items",
+        rows,
+        "enter read · r run in agent · backspace back",
+        (n) => full[n] === null,
+        "rR",
+      );
       if (index === null) return;
       // Rows are cut to the window, so reading one means opening it.
       const it = full[index];
       if (!it) continue;
-      await report([
+      if (key === "r" || key === "R") {
+        await startBacklogItem(it, from ?? state!);
+        continue;
+      }
+      const k = await report([
         c.bold(it.where ?? "Backlog item"),
         it.severity ? c.dim(`  ${it.severity}`) : "",
         "",
         ...wrap(it.raw.replace(/`/g, ""), 2),
+      ], "r run in agent · any other key to go back");
+      if (k === "r" || k === "R") {
+        await startBacklogItem(it, from ?? state!);
+      }
+    }
+  }
+
+  async function startBacklogItem(it: Item, from: string) {
+    const projectDir = from === join(home, ".kaizen")
+      ? process.cwd()
+      : (from.endsWith(".kaizen") ? dirname(from) : from);
+    const agent = detectDefaultAgent(projectDir);
+    const agentBin = Bun.which(agent.cmd) ?? agent.cmd;
+    const prompt = it.where ? `/kaizen ${it.text} (${it.where})` : `/kaizen ${it.text}`;
+    const fullCmd = [agentBin, prompt];
+
+    const term = findTerminal(projectDir, fullCmd);
+    if (!term) {
+      await report([
+        c.bold("Could not open terminal"),
+        "",
+        c.dim("No supported terminal emulator found (xdg-terminal-exec, kitty, ghostty, alacritty, tmux)."),
+        "",
+        "Run manually:",
+        `  ${c.cyan(`cd "${projectDir}" && ${agent.cmd} "${prompt}"`)}`,
+      ]);
+      return;
+    }
+
+    try {
+      const proc = Bun.spawn(term.cmd, {
+        cwd: projectDir,
+        stdin: "ignore",
+        stdout: "ignore",
+        stderr: "ignore",
+        detached: term.detached,
+      });
+      if (term.detached) proc.unref();
+
+      await report([
+        c.bold("Started in new terminal"),
+        "",
+        `  ${c.cyan("Agent")}     ${agent.name} (${c.bold(agent.cmd)})`,
+        `  ${c.cyan("Project")}   ${tilde(projectDir)}`,
+        `  ${c.cyan("Task")}      ${it.text}`,
+        ...(it.where ? [`  ${c.cyan("File")}      ${it.where}`] : []),
+        ...(it.severity ? [`  ${c.cyan("Severity")}  ${it.severity}`] : []),
+        "",
+        c.dim(`Opened in new window running: ${agent.cmd} "${prompt}"`),
+      ]);
+    } catch (err: any) {
+      await report([
+        c.bold("Failed to spawn terminal"),
+        "",
+        c.dim(err?.message ?? String(err)),
+        "",
+        "Run manually:",
+        `  ${c.cyan(`cd "${projectDir}" && ${agent.cmd} "${prompt}"`)}`,
       ]);
     }
   }
@@ -482,7 +627,7 @@ export async function dashboard(
         ? `  ${c.cyan("›")} ${c.bold(a.label.padEnd(20))}${c.dim(a.hint)}\n`
         : `    ${c.dim(a.label)}\n`);
     }
-    stdout.write(`\n  ${c.dim("↑↓ move · enter choose · q or backspace quit")}\n`);
+    stdout.write(`\n  ${c.dim("↑↓ move · enter choose · q quit")}   ${c.dim("⭐ github.com/hfadhlullah/kaizen")}\n`);
   };
 
   stdout.write("\x1b[?1049h\x1b[?25l");

package/cli/settings.ts

@@ -109,6 +109,7 @@ const SETTINGS: Setting[] = [
   { 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" },
+  { key: "agent.default", values: ["auto", "claude", "codex", "agy", "opencode", "gemini"], help: "Default coding agent to launch from dashboard backlog" },
 ];
 
 const c = {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kaizen-agent",
-  "version": "0.7.4",
+  "version": "1.1.0",
   "description": "Staged workflow for AI agents \u2014 code, writing, research, operations: plan, human approval, build, independent review, bounded fix loop.",
   "type": "module",
   "bin": {

package/skills/kaizen/SKILL.md

@@ -94,6 +94,7 @@ whichever the user picks.
 | `review.write_memory` | `true`, `false` | Let the reviewer append lessons to `memory.md` |
 | `git.auto_commit` | `true`, `false` | Commit the work when a run finishes |
 | `git.branch_before_implement` | `true`, `false` | Branch before building when on the default branch |
+| `agent.default` | `auto`, `claude`, `codex`, `agy`, `opencode`, `gemini` | Coding agent to launch from dashboard backlog |
 
 Rules for writing the file:
 

package/skills/kaizen/config.default.yml

@@ -128,3 +128,9 @@ git:
   # Create a branch before the implement stage when on the default branch.
   # Ignored when the project is not a git repository.
   branch_before_implement: true
+
+agent:
+  # Default coding agent to launch from dashboard backlog (auto | claude | codex | agy | opencode | gemini).
+  # auto picks Claude Code if installed, otherwise the first agent found on PATH.
+  default: auto
+

package/skills/kaizen/spec-build.md

@@ -47,6 +47,15 @@ change works" into "nothing else broke". A check already failing before the chan
 not this run's finding; a check that passed before and fails after is, and it stops
 the stage.
 
+**Keep the working transcript small.** Everything the builder reads stays in its
+context and is re-read on every request that follows, so a full test-suite dump at the
+start of the stage is paid for again at every step after it. Pipe long output through
+a filter that keeps the decisive lines — the failure count, the failing test names, the
+first error — and read the full output only when a check actually fails. The same holds
+for reading material: open the manifest's paths at the ranges the plan names, not whole
+files, and never re-read a file this stage already changed. `03-impl.md` records the
+result, not the transcript.
+
 **Read the plan's File manifest instead of searching.** The planner already located
 every path this run touches. Search the material only for what the manifest does not
 cover, and note in `03-impl.md` what was missing from it.

package/skills/kaizen/spec-plan.md

@@ -66,11 +66,27 @@ The planner reads code but writes none. Its plan must contain:
    item; "every new query path has a covering test" is. A tier fixes the severity
    before the reviewer has an opinion, which is what stops the same class of problem
    being `high` in one run and `medium` in the next.
-7. **Risks** — what could break, what is irreversible, what needs a migration or a
+7. **Design direction, for any work with a visual surface** — a website, a landing
+   page, a UI, a deck, a printed piece. The direction is settled before the builder
+   starts, because it is the one decision that cannot be changed afterwards without
+   redoing the work: copy survives a re-skin, markup does not.
+
+   Look for it in the material first — a `design.md`, a design system, a brand or style
+   guide, an existing stylesheet with established tokens. Where one exists, the plan
+   names it and follows it, and asks nothing; the answer is already in the repository.
+
+   Where none exists, the direction is an *Open question* with 3-4 concrete options,
+   each named for what it signals rather than for its palette, so the user chooses a
+   positioning rather than a color. Bringing one direction and building it is the
+   failure this item exists to prevent: the planner has an opinion here as everywhere
+   else, but a visual direction chosen silently is a decision taken from the user, not
+   a proposal made to them.
+
+8. **Risks** — what could break, what is irreversible, what needs a migration or a
    backup taken first.
-8. **Open questions** — assumptions that survived the interview. If this list is
+9. **Open questions** — assumptions that survived the interview. If this list is
    non-empty, the approval must ask the user about it rather than defaulting.
-9. **Out of scope suggestions** — worthwhile things noticed but not asked for, each
+10. **Out of scope suggestions** — worthwhile things noticed but not asked for, each
    its own proposal. Never folded into a step.
 
 The plan is a proposal, not a decision. It never edits files, runs migrations, or
@@ -80,7 +96,7 @@ installs packages.
 fix loop reads it again per iteration, so a line written once is read five or six
 times. Sections 3 to 6 — the material to reuse, the file manifest, the steps, the
 verification — earn their length: they are what stop every later stage searching the
-material again, and cutting them costs more than it saves. Sections 0, 1, 7 and 9 are
+material again, and cutting them costs more than it saves. Sections 0, 1, 8 and 10 are
 read once by a human at the approval and should be as short as they can be and still
 be correct: a paragraph of framing, a paragraph of goal, the risks that are real, the
 questions that are open. An alternative rejected gets a line saying what and why, not

package/skills/kaizen/spec-review.md

@@ -48,6 +48,21 @@ operational work: missing prerequisites, absent rollback, steps that cannot be
 executed as written. The plan's Verification section says what was promised; the
 reviewer checks that promise was kept.
 
+**Keep the working transcript small.** Everything the reviewer reads stays in its
+context and is re-read on every request that follows, so the re-run suite dumped in
+full at check 4 is paid for again at every check after it. Pipe long output through a
+filter that keeps the decisive lines — the failure count, the failing test names, the
+first error — and read the full output only where a check actually fails, which is the
+only place the detail becomes a finding. The same holds for the work under review: open
+the manifest's paths at the ranges the plan names, and read the diff rather than the
+whole file wherever the finding would cite a changed line. `04-review.md` records the
+findings, not the transcript.
+
+This does not apply to check 3. Blast radius is the check whose whole point is what
+the diff does not contain, so it reads as widely as it needs to — every caller, every
+reader, whole files where that is what it takes. A cheaper blast-radius pass is not a
+cheaper review, it is the check not happening.
+
 Each finding is one line, numbered from 1 within the review:
 `<n>. <where>: <severity>: <problem>. <fix>. [G-nn]` Where is a `path:line` for code,
 and a section, page, or step reference otherwise. Severity is one of `critical`,

package/skills/kaizen-help/SKILL.md

@@ -94,6 +94,7 @@ Each iteration is written to `runs/<id>/05-iterations/`.
 | `state.keep_runs` | `20` | Completed runs kept before pruning oldest (rescues open backlog first) |
 | `git.auto_commit` | `false` | Never commit/push/PR unless the user explicitly asks |
 | `git.branch_before_implement` | `true` | Branch before implement stage when on the default branch |
+| `agent.default` | `auto` | Coding agent to launch from dashboard backlog |
 
 `.kaizen/config.yml` overrides only the keys it sets; everything else falls back to
 this skill's `config.default.yml`.