kaizen-agent 1.11.1 → 1.12.0

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kaizen-agent",
-  "version": "1.11.1",
+  "version": "1.12.0",
   "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.