kaizen-agent 1.11.1 → 1.12.1

package/README.md

@@ -171,6 +171,46 @@ kaizen Done, and reviewed. Two things found:
 
 <img src="https://raw.githubusercontent.com/hfadhlullah/kaizen/c858bb6d666a65780d09c06032c8819489b87da5/assets/board.png" alt="kaizen web board" width="760">
 
+## Kaizen Bot
+
+A chat front end for your board, with AI teammates for every division. Ask **Chief** what's
+waiting on you, what's running, and what a plan or review says. Hand Sales Outbound,
+Marketing, Customer Service or Account Manager their team's asks, and they turn them into board ideas
+and runs. The board still does the real work: plan, approval, build, review.
+
+- **Nothing happens behind your back.** An agent may read the board, add an idea or a note, remember a fact and draft a message. Starting a run, approving a plan or fixing findings waits on a card until you click Approve. It never turns on Yolo and never commits.
+- **Nothing is ever sent.** Emails, posts and replies are drafts: approve one, then copy it or export them all as Markdown.
+- **Teammates and routines.** One agent can ask another, and any agent can run a task on a schedule: *every weekday at 7, brief me on the board*.
+
+<img src="https://raw.githubusercontent.com/hfadhlullah/kaizen/main/assets/bot.png" alt="Kaizen Bot: Account Manager holds a drafted email on a card until you approve it" width="760">
+
+Kaizen Bot lives in the repo's `bot/` folder, not the npm package. With the board running (`kaizen web`):
+
+```sh
+git clone https://github.com/hfadhlullah/kaizen && cd kaizen/bot
+cp .env.example .env      # set PROVIDER, MODEL and that provider's key
+bun start                 # http://127.0.0.1:7430
+```
+
+### Download the app
+
+Kaizen Bot also runs as a single app file for Linux, macOS and Windows, with no Bun or repo needed.
+Download yours from the [latest release](https://github.com/hfadhlullah/kaizen/releases/latest)
+(or build all five with `bun run build` in `bot/`):
+
+| OS | File |
+|---|---|
+| Linux | `kaizen-bot-linux-x64`, `kaizen-bot-linux-arm64` |
+| macOS | `kaizen-bot-darwin-arm64` (Apple Silicon), `kaizen-bot-darwin-x64` (Intel) |
+| Windows | `kaizen-bot-windows-x64.exe` |
+
+Open it. The first time, it creates `~/.kaizen-bot/.env` for your provider and key. After that it
+starts the board if `kaizen` is installed, and opens the chat in its own window. The files are
+unsigned, so macOS and Windows warn on first open. How to get past that is in
+[Download the app](https://github.com/hfadhlullah/kaizen/blob/main/bot/README.md#download-the-app).
+
+Anthropic, OpenAI and Requesty are supported. Setup, privacy and settings are in the [Kaizen Bot README](https://github.com/hfadhlullah/kaizen/blob/main/bot/README.md).
+
 ## Commands
 
 | Command | |
@@ -193,6 +233,7 @@ In a terminal: `kaizen` (dashboard), `kaizen web` (board), `kaizen settings`, `k
 ## Learn more
 
 - **[The guide](https://github.com/hfadhlullah/kaizen/blob/main/docs/guide.md)**: the board, request sources, notebook, settings, installer flags, uninstall
+- [Kaizen Bot](https://github.com/hfadhlullah/kaizen/blob/main/bot/README.md): the chat front end, its agents, routines and privacy
 - [`spec.md`](https://github.com/hfadhlullah/kaizen/blob/main/skills/kaizen/spec.md): the contract every stage follows
 - [`adapters.md`](https://github.com/hfadhlullah/kaizen/blob/main/skills/kaizen/adapters.md): running outside Claude Code, with Codex and Antigravity as the worked examples. OpenCode, Cursor and Gemini CLI load the same skill folder
 - Found a bug? `kaizen issue`, or *Report an issue* on the board, opens a GitHub bug form with your system details filled in. Nothing is sent until you press Submit on GitHub.

package/agents/kaizen-planner.md

@@ -165,10 +165,15 @@ Write `01-plan.md` with exactly these sections:
 - **Track** — one or two sentences opening the plan: what kind of work this is, the
   deliverable, what done means, what wrong means. Stated as your reading of the
   request, so it can be corrected in a breath.
-- **Framing** — the problem in your own words: what is wrong now, what would be true
-  instead, and why it matters. Then the approach you chose, and the alternatives you
-  rejected with one line each on why. This section is what the human checks first; if
-  your restatement is off, everything after it is off too.
+- **Framing** — the problem in your own words, as short labelled bullets, not a
+  paragraph: **Problem** (what is wrong now, as the user meets it), **Fix** (what will
+  be true instead, and the approach you chose), **Rejected** (each alternative, one
+  line on why). This section is what the human checks first; if your restatement is
+  off, everything after it is off too.
+- **Work list** — the plan in plain bullets, one line per thing that will actually be
+  done, no jargon. It sits right after Framing and is shown again right before the
+  builder starts, so write it for someone who has not read the rest of the plan. Five
+  bullets is usually plenty; if it needs fifteen, the run is too big.
 - **Goal** — one paragraph in the user's terms describing what will be true when done.
 - **Scope** — bullets for what is included, then an explicit **Not included** list.
 - **Reuse** — existing material to build on: `path:line` for code, a section or page
@@ -182,10 +187,6 @@ Write `01-plan.md` with exactly these sections:
   it unaided for a runbook. Real and checkable, never a placeholder.
 - **Risks** — what could break, what is irreversible, what needs a backup or
   migration first. Call out anything touching data, auth, or production config.
-- **Work list** — the plan in plain bullets, one line per thing that will actually be
-  done, no jargon. This is shown to the user right before the builder starts, so
-  write it for someone who has not read the rest of the plan. Five bullets is usually
-  plenty; if it needs fifteen, the run is too big.
 - **Open questions** — every assumption that survived your analysis. Leave the list
   empty only if it genuinely is.
 
@@ -210,6 +211,13 @@ Write `01-plan.md` with exactly these sections:
   run's backlog, so write each as a standalone one-liner that still makes sense read
   months later with no plan around it.
 
+Write Track, Framing, Work list, Goal, Scope, Risks and Out of scope suggestions for a
+person deciding whether to approve, often on a narrow panel: everyday words, short
+sentences, one idea per bullet, things named by what the user sees rather than by
+function, file, CSS value or gate id. Code names, `path:line` and gate ids belong in
+Reuse, Steps and Verification, where the builder and reviewer need them exact. If a
+sentence only makes sense to someone who has read the code, it is in the wrong section.
+
 ## The goals are the user's, the solution is yours
 
 Expanding a one-liner into a clear problem statement is your job. Deciding what is

package/cli/release.sh

@@ -26,6 +26,16 @@ if gh release view "$tag" >/dev/null 2>&1; then
   exit 0
 fi
 
+# Kaizen Bot as one app file per OS, attached so users can download it. A failed
+# build still publishes the release, just without the app files.
+rm -rf bot/dist
+assets=""
+if (cd bot && bun run build >/dev/null 2>&1); then
+  assets="$(ls bot/dist/kaizen-bot-* 2>/dev/null)"
+else
+  echo "release: Kaizen Bot app build failed, releasing without it"
+fi
+
 # --generate-notes only lists pull requests, and this repo merges none, so the
 # notes are built here: the title from the release commit's subject, the body from
 # every commit since the previous tag with its message, oldest first.
@@ -38,7 +48,7 @@ git log --reverse --format='### %s%n%n%b' ${prev:+"$prev.."}"$tag" \
   | grep -vE '^### Release [0-9.]+:' \
   | cat -s > "$notes"
 [ -n "$prev" ] && printf '\n**Full Changelog**: https://github.com/hfadhlullah/kaizen/compare/%s...%s\n' "$prev" "$tag" >> "$notes"
-err="$(gh release create "$tag" --title "$title" --notes-file "$notes" 2>&1 >/dev/null)" \
+err="$(gh release create "$tag" --title "$title" --notes-file "$notes" $assets 2>&1 >/dev/null)" \
   && echo "release: published $tag  https://github.com/hfadhlullah/kaizen/releases/tag/$tag" \
   || echo "release: tag pushed, release not created: $err"
 rm -f "$notes"

package/package.json

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

package/skills/kaizen/spec-plan.md

@@ -44,10 +44,17 @@ scope suggestions* for a separate decision.
 
 The planner reads code but writes none. Its plan must contain:
 
-0. **Framing** — the problem in the planner's own words: what is wrong now, what
-   would be true instead, why it matters, the approach chosen, and the alternatives
-   rejected with a reason each. The human checks this first; a wrong restatement
-   makes everything after it wrong.
+0. **Framing** — the problem in the planner's own words, as a few short labelled
+   bullets rather than a paragraph: **Problem** (what is wrong now, as the user meets
+   it), **Fix** (what will be true instead, and the approach), **Rejected** (each
+   alternative with its reason, one line), then the track in one line. The human
+   checks this first; a wrong restatement makes everything after it wrong.
+
+   Right below it, the **Work list**: plain bullets, one line per thing that will
+   actually be done, written for someone who has not read the rest of the plan.
+   Five bullets is usually plenty. It sits second so the reader learns what will
+   happen before the detail; the plan approval shows it verbatim and the builder
+   tracks progress against it.
 1. **Goal** — one paragraph, in the user's terms, on what will be true when done.
 2. **Scope** — what is included, and an explicit *not included* list. The second list
    is what prevents the builder from wandering.
@@ -115,12 +122,22 @@ 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, 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
+material again, and cutting them costs more than it saves. Sections 0 (Framing and the
+Work list), 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 few labelled lines of framing, a short
+work list, 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
 a case against it.
 
+**Write the parts a person reads for a person.** Framing, the Work list, Goal, Scope,
+Risks and Out of scope suggestions are read by someone deciding whether to approve,
+often on a narrow panel. Write them in everyday words: short sentences, one idea per
+bullet, things named by what the user sees ("the chat bubble", "the Plan tab") rather
+than by function, file, CSS value or gate id. Code names, `path:line` and gate ids
+belong in Reuse, the File manifest, Steps and Verification, where the builder and
+reviewer need them exact. If a sentence only makes sense to someone who has read the
+code, it is in the wrong section.
+
 A plan whose framing is longer than its steps is a plan that spent the run's budget
 explaining itself.
 
@@ -133,8 +150,8 @@ Controlled by `approvals.plan` (default on), skipped in `auto`.
 Present to the user, in this order:
 
 1. The track, the goal, and the top risk — a few lines, not the whole plan file.
-2. **The work list**, verbatim from the plan: plain bullets of what will actually be
-   done. This is the last thing the user sees before anything is produced, so it must
+2. **The work list**, verbatim from the plan, where it sits right after Framing:
+   plain bullets of what will actually be done. This is the last thing the user sees before anything is produced, so it must
    be readable on its own, without the plan's reasoning around it.
 3. The open questions, **as a pick list** — see below.