kaizen-agent 0.1.0

package/commands/kaizen-install.md

@@ -0,0 +1,5 @@
+---
+description: Install the kaizen workflow itself, globally or per-project
+---
+
+Invoke the `kaizen` skill with argument `install`.

package/commands/kaizen-plan.md

@@ -0,0 +1,6 @@
+---
+description: Start a kaizen run and stop after the plan (plan-only)
+argument-hint: "<request>"
+---
+
+Invoke the `kaizen` skill with argument `plan $ARGUMENTS`.

package/commands/kaizen-reject.md

@@ -0,0 +1,6 @@
+---
+description: Reject the kaizen approval the current run is waiting on — reason decides revise (back to planner) vs kill (abandon)
+argument-hint: "<reason>"
+---
+
+Invoke the `kaizen` skill with argument `reject $ARGUMENTS`.

package/commands/kaizen-review.md

@@ -0,0 +1,6 @@
+---
+description: Review-only kaizen run — audit existing code/work, no plan, no implementation
+argument-hint: "[target]"
+---
+
+Invoke the `kaizen` skill with argument `review $ARGUMENTS`.

package/commands/kaizen-run.md

@@ -0,0 +1,5 @@
+---
+description: Resume the current kaizen run and execute the approved plan
+---
+
+Invoke the `kaizen` skill with argument `run`.

package/commands/kaizen-status.md

@@ -0,0 +1,5 @@
+---
+description: List every kaizen run grouped waiting-on-you / in flight / done / abandoned, plus open backlog count
+---
+
+Invoke the `kaizen` skill with argument `status`.

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "kaizen-agent",
+  "version": "0.1.0",
+  "description": "Staged AI development workflow: plan, human approval, implement, independent review, bounded fix loop.",
+  "type": "module",
+  "bin": {
+    "kaizen-agent": "./cli/install.ts"
+  },
+  "files": [
+    "cli",
+    "skills",
+    "agents",
+    "commands",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "install-links": "bun run cli/install.ts",
+    "check": "bun run cli/install.ts --check"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/hfadhlullah/kaizen.git"
+  },
+  "license": "MIT",
+  "keywords": [
+    "claude-code",
+    "agent",
+    "workflow",
+    "skill",
+    "codex",
+    "antigravity",
+    "code-review"
+  ]
+}

package/skills/kaizen/README.md

@@ -0,0 +1,279 @@
+# Kaizen
+
+Kaizen is a staged workflow for work that is too big to hand an AI in one go. Instead
+of one agent that plans, writes, and then congratulates itself, the work is split into
+three agents that never share a context window, with human approval stops in between.
+You approve a plan before anything is produced, and an independent reviewer that never
+saw the work being made checks it afterwards.
+
+```
+request -> PLAN -> [approval] -> IMPLEMENT -> REVIEW -> [fix loop] -> [approval] -> done
+```
+
+Everything a run knows lives in plain files under `.kaizen/`, so a run can be paused,
+resumed tomorrow, resumed by a different session, or picked up by a different tool.
+
+## Why the reviewer runs in a separate context
+
+This is the one design decision worth understanding before you use it. An agent that
+watched itself write the code will rationalize it — it remembers why every line seemed
+reasonable, and that memory is exactly what stops it from finding the bug. The kaizen
+reviewer starts fresh. It sees the plan, the diff, and the implementation notes, and
+nothing else. It has no reason to defend anything.
+
+The same split is why the planner does not implement: a plan written by the agent that
+is about to do the work bends toward what is easy to write.
+
+## Install
+
+First get the skill onto your machine: copy or clone this directory somewhere Claude
+can read it. Then ask Claude to install kaizen from there, and it will ask where the
+workflow should live:
+
+- **Global** — `~/.claude/skills/kaizen/` and `~/.claude/agents/kaizen-*.md`.
+  Available in every project, not shared with your team.
+- **Per-project** — `.claude/skills/kaizen/` and `.claude/agents/kaizen-*.md`,
+  committed so the team gets the same workflow.
+
+Both can coexist; the project copy wins. Install also offers to write the adapter
+files from [`adapters.md`](adapters.md) so Codex and Antigravity follow the same spec.
+
+The workflow is `SKILL.md`, the split spec (`spec.md` core plus `spec-plan.md`,
+`spec-build.md`, `spec-review.md`, `spec-main.md` — each reader takes core plus one),
+`config.default.yml`,
+`adapters.md`, and this README, plus the three agent definitions `kaizen-planner.md`,
+`kaizen-builder.md`, and `kaizen-reviewer.md`.
+
+To set a repository up for runs, ask for `kaizen init`. That creates `.kaizen/` with a
+copy of the `spec*.md` files, a config, and the gitignore entry.
+
+## Your first run
+
+Say what you want, and say the word kaizen:
+
+> kaizen: add rate limiting to the public API
+
+That is the whole invocation. The skill triggers on the word, so a plain sentence is
+enough — no special syntax, no flags. `SKILL.md` also documents slash forms like
+`/kaizen plan <request>`, `/kaizen status`, and `/kaizen approve`; those are shorthand
+for the same requests, and they only work as literal slash commands if you have
+installed a command file at `~/.claude/commands/kaizen.md`. Nothing here requires one.
+Saying "kaizen status" or "approve the plan" works either way.
+
+Then the run stops twice, and both stops want something specific from you.
+
+**Stop one — the plan.** You get a written plan: what is wrong today, what would be
+true instead, the approach chosen, what was rejected and why, and a plain-bullet
+**Work list** of what will actually be done. If the request had genuine ambiguity, the
+plan ends with open questions, and they reach you as a pick list of two to four
+concrete options rather than an open prompt. You can always type something else.
+
+Three things newcomers do not expect:
+
+- **"Yes, but change X" is a normal answer.** You are not limited to approve or
+  reject. Approving with a modification — a different value, a dropped step — is
+  recorded in the approval file and binds the builder.
+- **Rejecting is not a failure.** The reason is written down and handed back to the
+  stage that produced the artifact, which revises and re-presents.
+- **The planner also lists out-of-scope suggestions** — things it noticed but did not
+  fold into the plan. Each is a separate yes or no. Saying nothing means no.
+
+Nothing is produced until you clear this stop.
+
+**Stop two — the review.** After the work is done, the reviewer reports findings with
+severities, and the run stops before calling the work done. If a finding is below the
+auto-fix threshold, or still open when the fix rounds run out, it is reported to you
+rather than quietly patched.
+
+## What a run decided not to do
+
+Both stops throw things away. The planner's out-of-scope suggestions you did not take,
+the low findings nobody fixed, the "later" you said at an approval — all real work, all
+previously surviving only in the conversation.
+
+Kaizen writes them down instead, into `06-backlog.md` inside the run that produced
+them, so an item sits next to the plan and the review that explain it. You do not
+maintain this file; it is written at the two moments the run already writes to disk —
+recording the plan approval, and marking the run done — so there is nothing to
+remember.
+
+Every item is `open`, `done`, or `rejected`. **Rejected is a real answer**: most
+suggestions are not worth doing, and without a way to decline one it stays on the list
+forever. Rejecting takes a reason, which is what stops the same idea coming back three
+runs later. Closed items stay in their run's file as record and are never printed
+again.
+
+Two commands read across all of it:
+
+- **`kaizen backlog`** — every open item, grouped by the run it came from, newest
+  first, with items rescued from pruned runs last under *Orphaned*. Nothing done,
+  nothing rejected.
+- **`kaizen status`** — every run you have, in four groups: waiting on you, in flight,
+  done, and abandoned, with the open backlog count at the bottom.
+
+A run you abort is abandoned, not outstanding: it sits in its own group and its backlog
+items stop being printed and stop being counted.
+
+Status is read live from each run's `state.json`, so nothing gets renamed or moved when
+a run finishes and no path you have written down elsewhere ever breaks.
+
+One thing to know about pruning: `state.keep_runs` eventually deletes old run
+directories. Before a run goes, its still-open items are moved into
+`.kaizen/backlog.md` — that file exists only as an orphanage. `kaizen backlog` reads it
+too and prints those items last, under *Orphaned*, so nothing outstanding disappears
+just because its run did. Items already done or rejected are deleted with their run,
+which is the point.
+
+## A real run, start to finish
+
+This one actually happened. The whole request was one line, said in passing:
+
+> for this dropdown omarchy terminal can we make it much more to the bottom?
+
+**Intake** wrote that down verbatim in `00-request.md`, along with what it could
+establish on its own: the script is `~/.local/bin/omarchy-dropdown`, bound to
+`SUPER + grave`, and its height comes from `OMARCHY_DROPDOWN_HEIGHT`, default `0.55`.
+
+**The plan** noticed the request had two readings — the panel *extending* further down
+versus the whole panel *sitting* lower — and, rather than asking which, argued for the
+first and said so plainly:
+
+> Reading (2) already has a knob — `GAP` (`omarchy-dropdown:13`) — and it does not do
+> what the phrase wants. [...] Setting `GAP=200` moves the top down to y=230 but shrinks the height to 555,
+> putting the bottom edge at 785 — *higher* than today.
+
+It proposed `HEIGHT_FRACTION` `0.55 → 0.80`, and listed fixing the `GAP` asymmetry as
+an out-of-scope suggestion rather than doing it.
+
+**The approval** is the interesting part, because it was neither yes nor no:
+
+> **Value changed: 0.80 → 0.70.** The user chose a smaller increase than proposed
+> [...] Wherever the plan specifies `HEIGHT_FRACTION=0.80`, use **`0.70`** instead.
+> Nothing else changes: same file, same three steps, same verification.
+
+The out-of-scope `GAP` fix was explicitly not approved, which made it off-limits for
+the rest of the run.
+
+**The implementation** changed one token, verified the geometry arithmetic instead of
+toggling the live window, and reported the thing it did not do:
+
+> Live steps 3-6 of the plan's verification [...] were not run: this run was
+> explicitly instructed not to toggle the live dropdown.
+
+**The review** re-derived the numbers independently, confirmed the file said `0.70` and
+not `0.80`, confirmed the `GAP` code was untouched — and found one thing nobody had
+considered: a second monitor configured as portrait might report an untransformed
+height, in which case the larger fraction could overflow where the old one did not.
+
+> `FINDINGS: 0 critical, 0 high, 0 medium, 1 low`
+
+Low is below the default fix threshold, so it was not auto-fixed. It was reported, with
+the exact command to settle it when that monitor is next plugged in. The reviewer also
+left a line in `memory.md`, which every later run in this directory reads:
+
+> `GAP` cannot — `geometry()` subtracts `gap * 2` from the height but adds `gap` only
+> once to `y`, so raising GAP moves the bottom edge *up*. Unfixed as of 2026-09-02.
+
+One-line request, six files, one real finding, one lesson that outlives the run.
+
+## Kaizen is not only for code
+
+Every stage adapts to the **track** — the kind of work a run is doing, which is what
+decides what *deliverable*, *verification*, and *finding* mean. A chapter, a landing
+page, a migration runbook, and a research memo each get a reviewer that checks the
+right things; a reviewer hunting race conditions in a manuscript is worse than none.
+
+The track is inferred from your request and stated back to you in the plan, so you
+correct a reading instead of categorizing your own work. You are never asked "is this
+software or writing?"
+
+## Configuration
+
+Defaults live in [`config.default.yml`](config.default.yml). Copy it to
+`.kaizen/config.yml` in a repository and override only the keys you care about;
+anything absent falls back to the defaults.
+
+| Key | Default | Change it when |
+|---|---|---|
+| `mode` | `approve` | You want `plan-only` to think without building, `auto` to run unattended, or `review-only` to audit existing work |
+| `approvals.plan` | `true` | Rarely. This is the stop that makes the workflow worth running |
+| `approvals.review` | `false` | Set `true` to add a second human stop after the review; with `auto_fix` on it mostly re-approves a report you are already reading |
+| `approvals.each_file` | `false` | You want to confirm every single file edit. Maximum control, slowest |
+| `auto_fix.enabled` | `true` | Set `false` and every finding becomes your decision instead |
+| `auto_fix.min_severity` | `high` | Lower to `medium` or `low` to have more auto-fixed; raise findings you see instead of auto-fixing |
+| `auto_fix.max_iterations` | `2` | Fix/recheck rounds before whatever is left is escalated to you |
+| `review.memory_max_lines` | `100` | The cap on `memory.md`, which every stage of every run reads. Raise only if the lessons are genuinely all load-bearing |
+| `git.auto_commit` | `false` | Leave it. Kaizen does not commit or push unless you ask |
+| `track.default` | `""` (inferred) | A repo that is always one kind of work, e.g. a docs repo |
+| `backlog.enabled` | `true` | Set `false` to skip both backlog capture points; the run still executes, just without a `06-backlog.md` |
+| `backlog.file` | `06-backlog.md` | The per-run file name. Rarely. |
+| `backlog.statuses` | `[open, done, rejected]` | Rarely. Only `open` items are printed |
+| `backlog.orphan_file` | `backlog.md` | Where open items go when their run is pruned |
+| `state.keep_runs` | `20` | You want a longer or shorter run history |
+
+Mode never overrides a refusal: destructive or irreversible actions still get confirmed
+even in `auto`.
+
+## Where your files live
+
+```
+.kaizen/
+  spec.md                       # core contract, copied in by init
+  spec-plan.md                  # per-stage contracts; each reader takes core + one
+  spec-build.md
+  spec-review.md
+  spec-main.md
+  config.yml
+  memory.md                     # cross-run lessons, appended by the reviewer
+  backlog.md                    # orphanage only: open items rescued before pruning
+  runs/
+    2026-09-02-add-oauth/
+      00-request.md             # the original request, verbatim
+      01-plan.md
+      02-approval.md            # decisions, with reasons and timestamps
+      03-impl.md                # what changed, which files, what was skipped
+      04-review.md              # findings, severity-tagged
+      05-iterations/
+        01-fix.md
+        01-recheck.md
+      06-backlog.md             # what this run deliberately did not do
+      state.json
+```
+
+`state.json` is the resume point — stage, mode, and what the run is waiting on:
+
+```json
+{
+  "id": "2026-09-02-add-oauth",
+  "mode": "approve",
+  "stage": "review",
+  "awaiting": "approvals.review",
+  "iteration": 1,
+  "updated": "2026-09-02T14:31:00+07:00"
+}
+```
+
+If a repository has no `.kaizen/`, state goes to `~/.kaizen/` keyed by working
+directory instead.
+
+Run state is per-person and not worth committing; the workflow itself is. `init` writes
+this gitignore stanza:
+
+```gitignore
+.kaizen/*
+!.kaizen/spec*.md
+!.kaizen/config.yml
+```
+
+## Where to go next
+
+- [`spec.md`](spec.md) + [`spec-plan.md`](spec-plan.md), [`spec-build.md`](spec-build.md),
+  [`spec-review.md`](spec-review.md), [`spec-main.md`](spec-main.md) — the tool-neutral
+  stage contract, split so each reader loads only core plus its own stage: exactly what
+  that stage reads, writes, and must not do. If anything here and the spec disagree, the spec
+  wins.
+- [`config.default.yml`](config.default.yml) — every key with its default and a comment.
+- [`adapters.md`](adapters.md) — running kaizen from Codex or Antigravity, and handing a
+  half-finished run between tools.
+- [`SKILL.md`](SKILL.md) — the instructions the agent itself follows. Read it if you want
+  to know what Claude is doing between your two approval stops.

package/skills/kaizen/SKILL.md

@@ -0,0 +1,281 @@
+---
+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
+  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
+  existing kaizen run. Also use to install the workflow into a repository.
+---
+
+# Kaizen
+
+A staged workflow for non-trivial development work:
+
+```
+request -> PLAN -> [approval] -> IMPLEMENT -> REVIEW -> [fix loop] -> [approval] -> done
+```
+
+Three separate subagents do the work. They never share a context window, which is
+the point: a reviewer that watched the code being written will rationalize it, a
+reviewer that sees only the diff and the plan will not.
+
+The stage contract is split so no reader loads a stage it is not running:
+[`spec.md`](spec.md) is the core (track, intake, resume) and every reader takes it,
+plus exactly one of [`spec-plan.md`](spec-plan.md), [`spec-build.md`](spec-build.md),
+[`spec-review.md`](spec-review.md), or [`spec-main.md`](spec-main.md) — the main
+thread's own file. Read core plus your stage before running it; do not read the
+others. Configuration defaults are in [`config.default.yml`](config.default.yml).
+Porting the workflow to Codex or Antigravity is covered in [`adapters.md`](adapters.md).
+
+## Commands
+
+| Invocation | Action |
+|---|---|
+| `/kaizen <request>` | Start a new run in the configured mode (default: `approve`) |
+| `/kaizen plan <request>` | Start a run and stop after the plan (`plan-only`) |
+| `/kaizen auto <request>` | Start a run in `auto` mode: every stage back to back, no approval stops |
+| `/kaizen run` | Resume the current run and execute the approved plan |
+| `/kaizen review [target]` | Review-only: audit existing code, no plan, no implementation (`review-only`) |
+| `/kaizen status` | List every run grouped waiting-on-you / in flight / done / abandoned, plus the open backlog count |
+| `/kaizen backlog` | Print the open backlog items across all runs, grouped by source run, with rescued items last under `Orphaned` |
+| `/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 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) |
+
+If the user typed `/kaizen` with no argument and a run is in progress, treat it as
+`/kaizen status`. If no run is in progress, ask what they want to build.
+
+## 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)).
+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
+   stage from conversation memory — the run may have been advanced by another tool
+   or another session.
+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.
+
+## Modes
+
+Set by `mode` in config, overridable per invocation.
+
+- **`plan-only`** — produce the plan, write it, stop. No code is touched.
+- **`approve`** (default) — stop at every approval enabled in config and wait for an
+  explicit human decision.
+- **`auto`** — run every stage back to back with no approval, report at the end. The fix
+  loop still respects `max_iterations`.
+- **`review-only`** — skip plan and implementation, run the reviewer against existing
+  code or a diff.
+
+Mode never overrides a refusal: destructive or irreversible actions still get
+confirmed even in `auto`.
+
+## Approvals
+
+Approvals are configured, not hardcoded. Each enabled approval halts the run, writes what it
+is waiting for into `state.json`, and reports to the user. The run only advances on
+an explicit `/kaizen approve` or a clear approval in conversation.
+
+- `approvals.plan` — after the plan, before any code is written. On by default.
+- `approvals.review` — after the review passes, before the work is called done. Off by
+  default: with `auto_fix` on, it mostly asks for approval of a report being read anyway.
+- `approvals.each_file` — confirm each file edit individually. Off by default; slow.
+
+A rejected approval is not a failure, and it is not always the same action. Two shapes:
+**revise** ("do it differently") sends the plan back to the planner, which produces a
+new version and returns to this same approval. **Kill** ("not doing this") means the
+request itself was wrong, not the approach — set `stage: "abandoned"` and stop, no
+revision to make. The reason says which; state the reading taken in `02-approval.md`
+when it is not obvious. See *Plan approval* in [`spec-plan.md`](spec-plan.md) for the full rule.
+
+**Asking the user anything:** use AskUserQuestion with 2–4 concrete options, taken
+from the options the planner wrote into the plan. Subagents cannot prompt the user,
+so every question reaches them through you. Do not add an "other" option — free text
+is always available. Reserve plain prose questions for things that genuinely have no
+discrete answers.
+
+**Before the builder runs:** show the plan's **Work list** — plain bullets of what
+will actually be done. It is the last thing the user sees before anything is
+produced, so show it even when they have already approved the plan in conversation.
+
+## The fix loop
+
+When the reviewer reports findings, behavior depends on config:
+
+- `auto_fix.enabled: false` — always stop and hand every finding to the user as a
+  decision, listed by the reviewer's number so the user can name a subset. Nothing is
+  fixed automatically.
+- `auto_fix.enabled: true` — the builder fixes findings at or above
+  `auto_fix.min_severity` (default `high`), the reviewer re-checks, repeating up to
+  `auto_fix.max_iterations` (default 2). Findings below the threshold, and anything
+  still open when iterations run out, are reported to the user rather than silently
+  dropped.
+
+Every iteration is written to `runs/<id>/05-iterations/` so the loop is auditable.
+
+## Backlog and status
+
+Each run keeps its own backlog at `runs/<id>/06-backlog.md`. You write it, in the main
+thread, at two writes that already happen: `02-approval.md` at the plan approval
+(out-of-scope suggestions not folded into the approved scope, and anything cut at the
+approval) and `stage: "done"` at the final approval (findings still open, findings
+below the fix threshold, and the builder's out-of-scope notes). No subagent writes it.
+The full rules are in [`spec-main.md`](spec-main.md).
+
+Items are one line each, `- <status>: <item text>`, with `<status>` one of `open`,
+`done`, or `rejected`. Findings keep the reviewer's line verbatim. `rejected` always
+carries a reason after a `|`. Closing an item edits its status in place; the line
+stays in the run's file as record.
+
+`/kaizen backlog` reads every `runs/*/06-backlog.md` at read time and prints the `open`
+items only, grouped by source run, newest run first. There is no central backlog file
+to keep in sync. `<state.dir>/backlog.md` is an orphanage and nothing more: before
+`state.keep_runs` prunes a run, move that run's still-open items into it. `/kaizen
+backlog` reads that file too and prints its open items last, under an **Orphaned**
+group, so a rescued item stays visible after its run is gone.
+
+**`/kaizen backlog` and `/kaizen status` are read-only.** They print; they never edit
+a `06-backlog.md` or `state.json`, even when reading one turns up an inconsistency
+(a stale `open` item already closed elsewhere, a duplicate, a bad reference). Report
+what looks wrong as part of the output and ask before touching anything — fixing it
+unasked is exactly the scope creep the rest of this spec exists to prevent, applied to
+kaizen's own bookkeeping instead of a user's code.
+
+`/kaizen status` reads each `runs/*/state.json` live and prints every run in four
+groups:
+
+```
+Waiting on you   — awaiting is non-null and stage is not "abandoned"
+In flight        — awaiting is null and stage is neither "done" nor "abandoned"
+Done             — stage is "done"
+Abandoned        — stage is "abandoned" (set by /kaizen abort)
+
+Backlog: <n> open
+```
+
+The count is every open item across all runs plus the orphanage. An abandoned run's
+backlog items are not open work: leave them in place, and do not print or count them.
+
+Each line is the run id, its stage, and what it is awaiting. Grouping is derived from
+`state.json` at read time, never from the directory name — run directories are flat and
+are never renamed or moved, so a path written into another file cannot break.
+
+## Running a stage
+
+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
+across tools. Name its spec files in the prompt: core `spec.md` plus its own stage
+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 |
+| Review | `kaizen-reviewer` | `04-review.md` |
+
+After a subagent returns, update `state.json` yourself in the main thread. Subagents
+report; the main thread owns the state machine.
+
+**Scope precisely, don't scope narrow.** Each subagent starts cold — no context from
+you carries over except what the prompt names. List exactly the files this stage's
+task actually touches; don't default to "read everything" for safety. But cutting a
+file the task genuinely needs is worse than the tokens it would have cost: a
+under-scoped subagent produces a wrong plan or misses a real defect, which costs a fix
+iteration — more tokens than the read would have. Precise beats narrow.
+
+Relay what matters from each subagent's report to the user — their output is not
+shown automatically.
+
+## State layout
+
+```
+.kaizen/
+  spec.md                       # core contract, copied in by init
+  spec-plan.md                  # per-stage contracts; each reader takes core + one
+  spec-build.md
+  spec-review.md
+  spec-main.md
+  config.yml
+  memory.md                     # cross-run lessons, appended by the reviewer
+  backlog.md                    # orphanage only: open items rescued before pruning
+  runs/
+    2026-09-02-add-oauth/
+      00-request.md             # the original request, verbatim
+      01-plan.md
+      02-approval.md            # decisions, with reasons and timestamps
+      03-impl.md                # what changed, which files, what was skipped
+      04-review.md              # findings, numbered and severity-tagged
+      05-iterations/
+        01-fix.md
+        01-recheck.md
+      06-backlog.md             # what this run deliberately did not do
+      state.json
+```
+
+`state.json` is the resume point:
+
+```json
+{
+  "id": "2026-09-02-add-oauth",
+  "mode": "approve",
+  "stage": "review",
+  "awaiting": "approvals.review",
+  "iteration": 1,
+  "updated": "2026-09-02T14:31:00+07:00"
+}
+```
+
+`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)).
+
+## Install
+
+`/kaizen install` asks where the workflow should live: **global** (this machine, every
+project) or **per-project** (this repo, committed, shared with the team). Both can
+coexist; the project copy wins when present.
+
+**Global.** Kaizen's source of truth is the repo at `~/kaizen` (symlinked in on this
+machine). Installing or updating global kaizen means that repo is current and linked:
+
+```bash
+[ -d ~/kaizen ] && (cd ~/kaizen && git pull) || git clone <kaizen repo url> ~/kaizen
+mkdir -p ~/.claude/skills ~/.claude/agents
+ln -sfn ~/kaizen/skills/kaizen ~/.claude/skills/kaizen
+for f in kaizen-planner kaizen-builder kaizen-reviewer; do
+  ln -sfn ~/kaizen/agents/$f.md ~/.claude/agents/$f.md
+done
+```
+
+Symlinks, not copies — future `git pull` in `~/kaizen` updates every project on this
+machine at once. This only works because `~/kaizen` is a repo the installing user
+controls; it is not something to hand a teammate.
+
+**Per-project.** A teammate cloning this repo does not have access to `~/kaizen` (it
+can be private, or simply not theirs), so the project copy must be self-contained —
+real files, not symlinks, committed into the project:
+
+```bash
+mkdir -p .claude/skills/kaizen .claude/agents
+cp ~/kaizen/skills/kaizen/*.md ~/kaizen/skills/kaizen/*.yml .claude/skills/kaizen/
+cp ~/kaizen/agents/kaizen-*.md .claude/agents/
+git add .claude/skills/kaizen .claude/agents/kaizen-*.md
+```
+
+Then commit. Updating a per-project copy later means re-running the `cp` lines against
+a current `~/kaizen` and committing the diff — there is no live link to keep it in
+sync automatically, by design.
+
+`install` also offers to write the adapter files from [`adapters.md`](adapters.md) so
+Codex and Antigravity follow the same spec, per-project only (a global adapter file has
+nowhere sensible to live).