kaizen-agent 0.4.0 → 0.5.0

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 |