kaizen-agent 0.5.1 → 0.7.0

package/README.md

@@ -239,9 +239,14 @@ Agent Skills standard, so the same workflow runs under any of them:
 | Antigravity | Skills | Parallel agents where available, else sequentially |
 | OpenCode, Cursor, Gemini CLI | Skills | Sequentially, one session |
 
-Only directories that already exist are touched — installing does not create
-`~/.opencode` for someone who does not use OpenCode. Install again after adding an
-agent and it picks the new one up.
+An agent counts as present if it has a config directory or a command on your PATH.
+Only what is already there is touched — installing does not create `~/.opencode` for
+someone who does not use OpenCode. Install again after adding an agent and it picks
+the new one up.
+
+**No agent yet?** kaizen does nothing on its own — it is a workflow an agent runs.
+If none is found, the installer says so and offers the list above, opening the
+install page for whichever you pick. Install it, run `kaizen` again, and carry on.
 
 The stage agents and slash commands are Claude Code's own formats and are not copied
 elsewhere; under the others you invoke the skill by name. `.kaizen/` is plain files

package/cli/install.ts

@@ -27,18 +27,75 @@ const c = {
 // 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 },
+  { name: "Claude Code", dir: ".claude", cmd: "claude", full: true,
+    docs: "https://docs.claude.com/en/docs/claude-code" },
+  { name: "Codex", dir: ".codex", cmd: "codex", full: false,
+    docs: "https://github.com/openai/codex" },
+  { name: "Antigravity", dir: ".agents", cmd: "agy", full: false,
+    docs: "https://antigravity.google" },
+  { name: "OpenCode", dir: ".opencode", cmd: "opencode", full: false,
+    docs: "https://opencode.ai" },
+  { name: "Cursor", dir: ".cursor", cmd: "cursor", full: false,
+    docs: "https://cursor.com" },
+  { name: "Gemini CLI", dir: ".gemini", cmd: "gemini", full: false,
+    docs: "https://github.com/google-gemini/gemini-cli" },
 ];
 
-// 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)));
+// An agent counts as present if it has a directory or a command. The directory
+// alone misses someone who installed the agent and has not run it yet; the command
+// alone misses one that is not on this shell's PATH.
+const onPath = new Set(
+  AGENTS.filter((a) => Bun.which(a.cmd)).map((a) => a.dir),
+);
+const found = (r: string) =>
+  AGENTS.filter((a) => existsSync(join(r, a.dir)) || onPath.has(a.dir));
+
+// Nothing to install into. kaizen is a workflow an agent runs; on its own it does
+// nothing, so send them to the agent first rather than laying out files no reader
+// will ever load.
+if (!found(home).length && !args.has("--force")) {
+  await noAgent();
+  process.exit(0);
+}
+
+async function noAgent() {
+  console.log(`  ${c.bold("No AI coding agent found on this machine.")}\n`);
+  console.log(`  ${c.dim("kaizen is a workflow that an agent runs — it plans, you approve, it builds,")}`);
+  console.log(`  ${c.dim("and a second agent reviews. So an agent has to be installed first.")}\n`);
+
+  if (!interactive) {
+    for (const a of AGENTS) console.log(`    ${a.name.padEnd(14)} ${a.docs}`);
+    console.log(`\n  ${c.dim("Install one, then run this again.")}`);
+    return;
+  }
+
+  const pick = await select("Which one would you like to install?", [
+    ...AGENTS.map((a) => ({ label: a.name, hint: a.docs, value: a as (typeof AGENTS)[number] | null })),
+    { label: "None of these — just show me the list", hint: "", value: null },
+  ]);
+
+  if (!pick) {
+    for (const a of AGENTS) console.log(`    ${a.name.padEnd(14)} ${a.docs}`);
+    console.log(`\n  ${c.dim("Install one, then run this again.")}`);
+    return;
+  }
+
+  console.log(`  ${c.bold(pick.name)}`);
+  console.log(`  ${c.cyan(pick.docs)}\n`);
+  const opened = await openUrl(pick.docs);
+  console.log(opened
+    ? `  ${c.dim("Opened in your browser. Install it, then run")} ${c.cyan("kaizen")} ${c.dim("again.")}`
+    : `  ${c.dim("Open that page to install it, then run")} ${c.cyan("kaizen")} ${c.dim("again.")}`);
+}
+
+// Best effort: a headless box or a locked-down desktop has no opener, and the URL
+// is printed either way.
+async function openUrl(url: string) {
+  const opener = process.platform === "darwin" ? "open"
+    : process.platform === "win32" ? "start" : "xdg-open";
+  if (!Bun.which(opener)) return false;
+  try { await Bun.$`${opener} ${url}`.quiet(); return true; } catch { return false; }
+}
 
 if (wantSettings) {
   const { settings } = await import("./settings.ts");
@@ -52,7 +109,7 @@ if (wantSettings) {
 if (interactive && !upgrade && Bun.argv.length === 2) {
   const repoDir = await resolveRepoQuietly();
   const here = found(home);
-  const linked = here.every((a) =>
+  const linked = here.length > 0 && here.every((a) =>
     ["kaizen", "kaizen-help"].every((n) => existsSync(join(home, a.dir, "skills", n))));
   if (linked) {
     const { dashboard } = await import("./dashboard.ts");
@@ -230,10 +287,10 @@ 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.
+  // directory it is the global install under another name; any other folder is
+  // a project worth installing into, git repository or not.
   const cwd = process.cwd();
-  if (cwd === home || !existsSync(join(cwd, ".git"))) return home;
+  if (cwd === home) return home;
 
   const names = (r: string) => found(r).map((a) => a.name).join(", ");
   return select("Install kaizen for", [
@@ -333,22 +390,43 @@ function installLauncher() {
   }
 }
 
-const inGitRepo = existsSync(join(process.cwd(), ".git"));
+const inProject = process.cwd() !== home;
 const kaizenDir = join(process.cwd(), ".kaizen");
 
-if (inGitRepo && !existsSync(kaizenDir)) {
+// A .kaizen/ in a parent already owns this folder's state, and setting up a child
+// would shadow it, hiding the parent's runs and leaving the child out of the root
+// .gitignore. Deliberately not shared with cli/dashboard.ts locate(): that one
+// resolves which state directory to read and so falls back to a global ~/.kaizen,
+// while this one decides whether a folder is already owned and must stop *before*
+// $HOME — a global ~/.kaizen would otherwise suppress the setup offer for every
+// non-repo folder under the home directory. Do not re-sync the two walks.
+function kaizenAbove() {
+  let dir = process.cwd();
+  for (;;) {
+    if (dir === home) return false;
+    if (existsSync(join(dir, ".kaizen"))) return true;
+    if (existsSync(join(dir, ".git"))) return false;
+    const up = dirname(dir);
+    if (up === dir) return false;
+    dir = up;
+  }
+}
+
+if (inProject && !kaizenAbove()) {
   const now = interactive
     ? await select(`Set up ${basename(process.cwd())}/ for kaizen now`, [
-        { label: "Yes", hint: "writes .kaizen/ and a CLAUDE.md line so it runs by default", value: true },
+        // "Not now" leads: the offer now appears in any folder outside home, so the
+        // safe answer is the one under the cursor.
         { label: "Not now", hint: "the first /kaizen run will do it", value: false },
+        { label: "Yes", hint: "writes .kaizen/ and a CLAUDE.md line so it runs by default", value: true },
       ])
     : false;
-  if (now) initRepo();
+  if (now) initProject();
 } else if (existsSync(kaizenDir)) {
   step(`${basename(process.cwd())}/.kaizen already set up`);
 }
 
-function initRepo() {
+function initProject() {
   mkdirSync(kaizenDir, { recursive: true });
   for (const f of readdirSync(join(repo, "skills/kaizen")).filter((f) => f.startsWith("spec"))) {
     copyFileSync(join(repo, "skills/kaizen", f), join(kaizenDir, f));
@@ -356,13 +434,18 @@ function initRepo() {
   copyFileSync(join(repo, "skills/kaizen/config.default.yml"), join(kaizenDir, "config.yml"));
 
   // Run state is local; the workflow itself is shared, so those files stay tracked.
-  const rules = ".kaizen/*\n!.kaizen/spec*.md\n!.kaizen/config.yml\n";
-  const gi = join(process.cwd(), ".gitignore");
-  const current = existsSync(gi) ? readFileSync(gi, "utf8") : "";
-  if (!current.includes(".kaizen/*")) {
-    appendFileSync(gi, (current && !current.endsWith("\n") ? "\n" : "") + "\n# kaizen run state\n" + rules);
+  // Nothing to ignore where there is no git, so a plain folder gets no .gitignore.
+  let ignored = false;
+  if (existsSync(join(process.cwd(), ".git"))) {
+    const rules = ".kaizen/*\n!.kaizen/spec*.md\n!.kaizen/config.yml\n";
+    const gi = join(process.cwd(), ".gitignore");
+    const current = existsSync(gi) ? readFileSync(gi, "utf8") : "";
+    if (!current.includes(".kaizen/*")) {
+      appendFileSync(gi, (current && !current.endsWith("\n") ? "\n" : "") + "\n# kaizen run state\n" + rules);
+      ignored = true;
+    }
   }
-  step("wrote .kaizen/ and the gitignore entry");
+  step(ignored ? "wrote .kaizen/ and the gitignore entry" : "wrote .kaizen/");
   writePointer();
 }
 

package/cli/release.sh

@@ -0,0 +1,34 @@
+#!/bin/sh
+# Runs after `npm publish`: tag the published version and open a GitHub release
+# for it, so a version can never exist on npm with nothing to read on GitHub.
+#
+# Never fails the publish. The package is already public by the time this runs;
+# exiting non-zero here would report a failure that did not happen.
+set -u
+v="${npm_package_version:-$(node -p "require('./package.json').version" 2>/dev/null)}"
+[ -n "$v" ] || { echo "release: no version, skipping"; exit 0; }
+tag="v$v"
+
+git rev-parse --git-dir >/dev/null 2>&1 || { echo "release: not a git checkout, skipping"; exit 0; }
+
+if git rev-parse "$tag" >/dev/null 2>&1; then
+  echo "release: $tag already tagged"
+else
+  git tag -a "$tag" -m "kaizen-agent $tag" || { echo "release: could not tag"; exit 0; }
+  git push origin "$tag" >/dev/null 2>&1 || echo "release: tag made but not pushed"
+fi
+
+command -v gh >/dev/null 2>&1 || { echo "release: gh not installed — tag pushed, write the release by hand"; exit 0; }
+gh auth status >/dev/null 2>&1 || { echo "release: gh not logged in — tag pushed, write the release by hand"; exit 0; }
+
+if gh release view "$tag" >/dev/null 2>&1; then
+  echo "release: $tag already released"
+  exit 0
+fi
+
+# --generate-notes lists the commits since the last tag. Good enough to never be
+# empty; rewrite it with what actually changed when the release matters.
+gh release create "$tag" --title "$tag" --generate-notes >/dev/null 2>&1 \
+  && echo "release: published $tag  https://github.com/hfadhlullah/kaizen/releases/tag/$tag" \
+  || echo "release: tag pushed, release not created"
+exit 0

package/commands/kaizen-init.md

@@ -1,5 +1,5 @@
 ---
-description: Install .kaizen/ (spec, config, gitignore entry) into the current repository
+description: Set up this project folder for kaizen (spec, config, and a gitignore entry when it is a git repo)
 ---
 
 Invoke the `kaizen` skill with argument `init`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kaizen-agent",
-  "version": "0.5.1",
+  "version": "0.7.0",
   "description": "Staged workflow for AI agents \u2014 code, writing, research, operations: plan, human approval, build, independent review, bounded fix loop.",
   "type": "module",
   "bin": {
@@ -17,7 +17,8 @@
   ],
   "scripts": {
     "install-links": "bun run cli/install.ts",
-    "check": "bun run cli/install.ts --check"
+    "check": "bun run cli/install.ts --check",
+    "postpublish": "sh cli/release.sh"
   },
   "repository": {
     "type": "git",

package/skills/kaizen/SKILL.md

@@ -47,7 +47,7 @@ Porting the workflow to Codex or Antigravity is covered in [`adapters.md`](adapt
 | `/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 init` | Set up this project folder: `.kaizen/` with the `spec*.md` files, config, and — in a git repo — the gitignore entry |
 | `/kaizen install` | Install the workflow itself globally or per-project (see below) |
 
 If the user typed `/kaizen` with no argument and a run is in progress, treat it as
@@ -55,10 +55,11 @@ If the user typed `/kaizen` with no argument and a run is in progress, treat it
 
 ## Before doing anything
 
-1. Locate the state directory: `.kaizen/` in the repository root, else `~/.kaizen/`
-   keyed by working directory. If neither exists and the user is starting work, run
-   `/kaizen init` first: it creates `.kaizen/` with a copy of the `spec*.md` files, a config, and
-   the gitignore entry (see [`adapters.md`](adapters.md)).
+1. Locate the state directory: `.kaizen/` in the project folder's root, else
+   `~/.kaizen/` keyed by working directory. If neither exists and the user is starting
+   work, run `/kaizen init` first: it creates `.kaizen/` with a copy of the `spec*.md`
+   files, a config, and — where the folder is a git repository — the gitignore entry
+   (see [`adapters.md`](adapters.md)).
 2. Read `.kaizen/config.yml`, falling back to `config.default.yml` in this skill for
    any key it does not set.
 3. Read `.kaizen/runs/<current>/state.json` if a run is active. Never assume the
@@ -293,9 +294,11 @@ shown automatically.
 }
 ```
 
-`init` adds a gitignore entry that ignores run state but keeps the workflow: it
-ignores `.kaizen/*` and un-ignores `.kaizen/spec*.md` and `.kaizen/config.yml`, which
-are meant to be committed (see [`adapters.md`](adapters.md)).
+In a git repository, `init` also adds a gitignore entry that ignores run state but
+keeps the workflow: it ignores `.kaizen/*` and un-ignores `.kaizen/spec*.md` and
+`.kaizen/config.yml`, which are meant to be committed (see
+[`adapters.md`](adapters.md)). A project folder that is not a repository gets no
+gitignore.
 
 ## Install
 

package/skills/kaizen/adapters.md

@@ -64,8 +64,9 @@ completes. A stale `state.json` is the one way this breaks.
 
 ## Installing the adapter files
 
-`/kaizen init` writes `.kaizen/` with the `spec*.md` files, `config.yml`, and the gitignore
-entry. `/kaizen install` additionally offers to append the `AGENTS.md` block above.
+`/kaizen init` writes `.kaizen/` with the `spec*.md` files and `config.yml` into the
+project folder, plus the gitignore entry when that folder is a git repository.
+`/kaizen install` additionally offers to append the `AGENTS.md` block above.
 `.kaizen/spec*.md` and `.kaizen/config.yml` should be committed even though run state
 is ignored — the workflow is shared, the run data is not:
 

package/skills/kaizen/config.default.yml

@@ -55,12 +55,27 @@ review:
   # Additional checks per track, chosen by what the run actually is. The planner may
   # name a track not listed here; the reviewer then derives its checks from the
   # track's "what would make it wrong".
+  # Each check below is one question the reviewer asks; the line beside it says which.
   track_checks:
+    # security - no new way in, no secret or user data exposed
+    # reuse_simplification - nothing rebuilt that the codebase already had
+    # test_coverage - the changed behaviour has a check that fails when it breaks
     software: [security, reuse_simplification, test_coverage]
     # blast_radius and regression are universal — see spec-review.md — not listed here.
+    # completeness - every part the piece promises is actually present
+    # claim_accuracy - every checkable claim traced to a source
+    # reader_usability - its intended reader can act on it without asking
     writing: [completeness, claim_accuracy, reader_usability]
+    # audience_fit - written for the people who will actually read it
+    # voice_consistency - reads as the same voice as the surrounding material
     communication: [claim_accuracy, audience_fit, voice_consistency]
+    # prerequisites - everything needed before step one is stated
+    # rollback - a way back exists for every step that changes something
+    # executability - someone else can run it start to finish unaided
     operations: [prerequisites, rollback, executability]
+    # evidence_support - the conclusion follows from evidence shown, not asserted
+    # selection_bias - the evidence was not picked to fit the answer
+    # alternatives - the readings that were rejected are named and why
     research: [evidence_support, selection_bias, alternatives]
   # Let the reviewer append durable lessons to .kaizen/memory.md.
   write_memory: true
@@ -90,6 +105,8 @@ state:
 
 git:
   # Never commit, push, or open a PR unless the user explicitly asks.
+  # Ignored when the project is not a git repository.
   auto_commit: false
   # 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

package/skills/kaizen/spec-build.md

@@ -35,6 +35,9 @@ Rules:
   abstraction, a new file, a new section — is allowed, and costs one written line
   saying what it serves. The line is the price of the technique, not a request for
   permission. No line means the reviewer records a finding.
+- The `git.*` settings apply only where the work sits in a git repository. In a plain
+  folder there is no branch to make and no commit to skip, and that absence is not a
+  finding.
 
 **Baseline first, in any track with an existing suite of checks.** Before changing
 anything, run whatever already proves the existing material correct — the test suite,

package/skills/kaizen-help/SKILL.md

@@ -31,7 +31,7 @@ anything.
 | `/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 init` | Set up this project folder: `.kaizen/` with `spec.md`, config, and — in a git repo — the gitignore entry |
 | `/kaizen install` | Install the workflow itself globally or per-project |
 
 `/kaizen` with no argument: `status` if a run is in progress, else ask what to build.