kaizen-agent 0.3.0 → 0.5.0

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.3.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"
   ]
 }

package/skills/kaizen/SKILL.md

@@ -1,12 +1,14 @@
 ---
 name: kaizen
 description: >
-  Staged AI development workflow: plan, human approval, implementation, then
-  independent bug/security review with a bounded fix loop. Each stage runs as its own
+  Staged workflow for any kind of work: plan, human approval, build, then independent
+  review with a bounded fix loop. Not only for code — a run infers its own track (code,
+  writing, communication, operations, research) and every stage reads "deliverable",
+  "verification", and "finding" in that track's terms. Each stage runs as its own
   subagent with clean context, and all state lives in a portable `.kaizen/` directory so
   a run can be resumed later, by another session, or by another AI tool (Codex,
   Antigravity). Use when the user says "kaizen", "/kaizen", asks to plan-then-build-then-review
-  a change, wants approval steps before code is written, or wants to resume or check an
+  something, wants approval steps before work begins, or wants to resume or check an
   existing kaizen run. Also use to install the workflow into a repository.
 ---
 
@@ -44,6 +46,7 @@ Porting the workflow to Codex or Antigravity is covered in [`adapters.md`](adapt
 | `/kaizen approve` | Approve whatever the current run is waiting on |
 | `/kaizen reject <reason>` | Reject it; the reason is fed back to the stage that produced it |
 | `/kaizen abort` | Mark the current run abandoned |
+| `/kaizen config` | Show this project's settings and change them, one picker per setting |
 | `/kaizen init` | Install `.kaizen/` with the `spec*.md` files, config, and the gitignore entry into the current repository |
 | `/kaizen install` | Install the workflow itself globally or per-project (see below) |
 
@@ -64,6 +67,48 @@ If the user typed `/kaizen` with no argument and a run is in progress, treat it
 4. Read `.kaizen/memory.md` if present. It holds cross-run lessons and carries real
    weight: it is what previous reviewers learned about this codebase.
 
+## Settings
+
+`/kaizen config` reads `.kaizen/config.yml`, falling back to `config.default.yml` for
+anything it does not set, and prints the current value of each setting below with a
+one-line meaning. Then it offers the settings as choices — the tool's structured
+question mechanism, one option per legal value, never free text — and writes back
+whichever the user picks.
+
+| Setting | Values | What it decides |
+|---|---|---|
+| `mode` | `approve`, `auto`, `plan-only`, `review-only` | Where a run stops |
+| `build.executor` | `subagent`, `inline`, `ask` | Who carries out the approved plan |
+| `approvals.plan` | `true`, `false` | Stop and show the plan before anything is built |
+| `approvals.review` | `true`, `false` | Stop after the review, before the run is called done |
+| `approvals.each_file` | `true`, `false` | Confirm every individual edit |
+| `auto_fix.enabled` | `true`, `false` | Fix findings without asking, or hand every one over |
+| `auto_fix.min_severity` | `critical`, `high`, `medium`, `low` | How bad a finding must be to be fixed automatically |
+| `auto_fix.max_iterations` | `1`–`5` | Fix and recheck rounds before what is left is escalated |
+| `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 |
+
+Rules for writing the file:
+
+- **Change the value in place.** `config.yml` ships with a comment above every key
+  explaining it; rewriting the file from a parsed object throws all of them away.
+  Edit the one line.
+- **Only what the user picked.** A key the user did not touch stays absent if it was
+  absent — an absent key inherits the default, and writing every key out freezes
+  today's defaults into the project forever.
+- If `.kaizen/` does not exist yet, run `init` first, then continue.
+- After writing, print the setting and its new value, and nothing else. No summary of
+  the whole file.
+
+Settings not in the table — the review checks, backlog and state paths — are edited by
+hand in `config.yml`, which is commented throughout. Say so rather than offering a
+picker with thirty options.
+
+`kaizen settings` in a terminal opens the same settings as a full-screen browser, for
+someone who would rather see the whole file at once. Mention it when the user is
+changing several at a time.
+
 ## Modes
 
 Set by `mode` in config, overridable per invocation.
@@ -171,6 +216,13 @@ are never renamed or moved, so a path written into another file cannot break.
 
 ## Running a stage
 
+**If the tool you are running in has no subagents** — Codex, and anything else that
+runs one session at a time — do not try to fake them. Run the stages sequentially in
+the one session, following [`adapters.md`](adapters.md): start each stage by reading
+only its declared inputs, write its artifact before moving on, and when reviewing,
+judge the work on its own terms rather than defending the reasoning you used writing
+it. Everything else in this file holds unchanged.
+
 Each stage runs as a subagent via the Agent tool, with the agent type named below.
 Pass it the run directory path and let it read its own inputs from there — do not
 paste plans or diffs into the prompt, since the file is the shared source of truth
@@ -180,9 +232,15 @@ file, never the whole set.
 | Stage | Agent type | Writes |
 |---|---|---|
 | Plan | `kaizen-planner` | `01-plan.md` |
-| Implement | `kaizen-builder` | `03-impl.md` + the actual code changes |
+| Implement | `kaizen-builder`, or the main thread when `build.executor` is `inline` | `03-impl.md` + the actual changes |
 | Review | `kaizen-reviewer` | `04-review.md` |
 
+`build.executor` decides who implements: `subagent` (default), `inline` — the main
+thread does it against the same contract in `spec-build.md` — or `ask`, which puts
+the choice at the plan approval. Building inline does not make the review less
+independent: the reviewer is a separate agent in every case, and never sees the
+conversation the work happened in.
+
 After a subagent returns, update `state.json` yourself in the main thread. Subagents
 report; the main thread owns the state machine.
 

package/skills/kaizen/config.default.yml

@@ -14,6 +14,19 @@ approvals:
   # Confirm every individual file edit. Maximum control, slowest.
   each_file: false
 
+build:
+  # Who carries out the approved plan.
+  #   subagent - dispatch the builder as its own agent. The main thread keeps its
+  #              context and the work is reported back. The default, and the only
+  #              sane option for a large run.
+  #   inline   - the main thread does the work itself, against the same plan and the
+  #              same contract. You watch it happen and can interrupt mid-step, at
+  #              the cost of main-thread context.
+  #   ask      - offer the choice at the plan approval.
+  # The reviewer is a separate agent in every case; that is not configurable, because
+  # an agent reviewing work it just did will defend it.
+  executor: subagent
+
 auto_fix:
   # false: every finding stops the run and becomes a user decision.
   # true:  findings at or above min_severity are fixed and re-reviewed automatically.

package/skills/kaizen/spec-build.md

@@ -10,7 +10,17 @@ builder's contract. The planner and reviewer do not read it.
 **Output:** the deliverable itself, plus `03-impl.md`.
 
 The builder produces whatever the track's deliverable is — code, a chapter, the
-campaign copy, the runbook — and nothing else. Rules:
+campaign copy, the runbook — and nothing else.
+
+This file is the contract whether the builder is a dispatched agent or the main
+thread working inline (see `build.executor`). Working inline changes who is typing,
+not what is owed: the plan is still the scope, a step that turns out wrong still
+stops the stage instead of being improvised around, and `03-impl.md` is still written
+before the reviewer is called. The temptation inline is to skip the file because the
+work is already visible in the conversation — but the reviewer never sees that
+conversation, and reads the file instead.
+
+Rules:
 
 - Work only within the plan's scope. Something out of scope that clearly needs doing
   is written to `03-impl.md` as a note, not produced.

package/skills/kaizen/spec-plan.md

@@ -90,6 +90,23 @@ Present to the user, in this order:
    be readable on its own, without the plan's reasoning around it.
 3. The open questions, **as a pick list** — see below.
 
+**Who builds it.** Governed by `build.executor`. On `subagent` or `inline` the
+approval says which is about to happen in one line and moves on; on `ask` it is one
+more choice at this approval:
+
+- **subagent** (default) — dispatch the builder as its own agent. The main thread
+  keeps its context, and the work is reported back rather than watched. Right for
+  most runs, and the only sane option for a large one.
+- **inline** — the main thread does the work itself, against this plan. You watch it
+  happen and can interrupt mid-step, and it already holds the conversation the plan
+  came out of. It costs main-thread context, and a long run will exhaust it.
+
+Either way the builder's contract is unchanged: the plan is the scope, `03-impl.md`
+is written the same way, and the gate is answered with the same evidence. **The
+reviewer is always a separate agent, in both.** Its independence is what the review
+is worth, and it is not the user's to trade away — an inline build is judged by an
+agent that never saw it happen, exactly as a dispatched one is.
+
 Do not dump the whole plan into the terminal; point at its path for the detail.
 
 **Ask with options, not open prose.** Every question the plan raises is put to the

package/skills/kaizen-help/SKILL.md

@@ -30,6 +30,7 @@ anything.
 | `/kaizen approve` | Approve whatever the current run is waiting on |
 | `/kaizen reject <reason>` | Reject it; the reason decides revise (back to planner) vs kill (abandon) |
 | `/kaizen abort` | Mark the current run abandoned |
+| `/kaizen config` | Show this project's settings and change them, one picker per setting |
 | `/kaizen init` | Install `.kaizen/` with `spec.md`, config, and the gitignore entry into the current repository |
 | `/kaizen install` | Install the workflow itself globally or per-project |
 
@@ -74,11 +75,12 @@ Each iteration is written to `runs/<id>/05-iterations/`.
 |---|---|---|
 | `mode` | `approve` | Default run mode |
 | `approvals.plan` | `true` | Stop after the plan |
-| `approvals.review` | `true` | Stop after the review |
+| `approvals.review` | `false` | Stop after the review |
 | `approvals.each_file` | `false` | Confirm every file edit |
+| `build.executor` | `subagent` | Who builds: `subagent`, `inline` (main thread), or `ask` at the approval |
 | `auto_fix.enabled` | `true` | Auto-fix findings vs. escalate everything |
 | `auto_fix.min_severity` | `high` | Threshold for auto-fix (`critical\|high\|medium\|low`) |
-| `auto_fix.max_iterations` | `3` | Fix/recheck rounds before escalating remaining findings |
+| `auto_fix.max_iterations` | `2` | Fix/recheck rounds before escalating remaining findings |
 | `track.default` | `""` (empty, inferred per run) | Pin a track for a repo that is always one kind of work |
 | `review.write_memory` | `true` | Let the reviewer append lessons to `.kaizen/memory.md` |
 | `backlog.enabled` | `true` | Capture what a run deliberately did not do |