kaizen-agent 0.1.0

package/skills/kaizen/spec.md

@@ -0,0 +1,130 @@
+# Kaizen workflow specification
+
+This file is the tool-neutral contract. Claude Code, Codex, and Antigravity all
+follow this document; only the way stages are dispatched differs per tool. If an
+adapter and this file disagree, this file wins.
+
+A stage may only start when the previous stage's artifact exists on disk and the approval
+between them, if enabled, has been resolved.
+
+---
+
+## The track
+
+Kaizen is not a software workflow. The stage structure — frame, approve, produce,
+review independently, fix under a bound — holds for a book, a marketing campaign, a
+migration runbook, or a research memo just as well as for code. What changes per kind
+of work is what the words *deliverable*, *verification*, and *finding* mean.
+
+That meaning is fixed once, at intake, and recorded as the run's **track**. Every
+later stage reads it and adapts. A reviewer hunting race conditions in a book
+manuscript is worse than no reviewer at all, and a track is what prevents it.
+
+**The track is inferred, never asked.** Reading a request and recognizing what kind
+of work it is — an app, a chapter, a campaign, a runbook — is the workflow's job, not
+the user's. Asking "is this software or writing?" hands back the analysis they came
+here to have done, and a request almost always says which it is: what it names, the
+verbs it uses, where the material lives, what the person is evidently trying to
+produce. Read it and decide.
+
+Do not classify against a fixed taxonomy of work types; the sixth kind of work will
+not be on the list. Establish the track by answering three questions from the request
+itself, and only then ask about what genuinely cannot be read from it:
+
+1. **What is the deliverable?** A merged code change, a chapter, a landing page, a
+   decision memo, a set of ad variants, a runbook someone else will execute.
+2. **What counts as done?** The concrete, checkable condition. Tests pass. The
+   chapter reads end to end without contradicting chapter two. A colleague can follow
+   the runbook without asking a question. Someone in the audience understands the
+   offer in one read.
+3. **What would make it wrong?** The failure this work must not have. A security
+   hole. A claim that is not true. A tone that alienates the reader. A step that
+   silently loses data.
+
+Answer three is what the reviewer becomes. Answer two is what the builder must
+demonstrate. Draft all three yourself from the request, then state them back as
+conclusions — "this is a book chapter; done means it reads end to end without
+contradicting chapter two; wrong means a claim that is not true" — so the user
+corrects a reading rather than performing a classification. A wrong reading stated
+plainly is easy to fix; a question about categories is work handed back.
+
+Only where the request genuinely leaves the outcome open — two plausible readings
+with materially different work behind them — does this become a question, and even
+then ask about the outcome the user wants, never about which category the work
+belongs to.
+
+Common shapes, as illustration only — never as a menu to force a request into:
+
+| Shape | Deliverable | Done means | Wrong means |
+|---|---|---|---|
+| Enhancing existing software | A change in this repo | Tests and the plan's checks pass | Regression, security hole, scope creep |
+| Building something new | A working first version | It runs and does the named thing | Wrong foundation, unnecessary complexity |
+| Writing and documentation | A document | Complete, accurate, follows its own structure | False claim, contradiction, unusable for its reader |
+| Marketing and communication | Copy, campaign, positioning | The audience takes the intended meaning | Overclaim, wrong audience, off-brand |
+| Operations and process | A runbook, a config, a migration | Someone else can execute it unaided | Missing rollback, unstated prerequisite |
+| Research and analysis | Findings and a recommendation | The conclusion follows from evidence shown | Unsupported leap, cherry-picked data |
+
+A run may be a mix. Record it as a mix — the honest description beats the nearest
+label.
+
+Record the track in `state.json` as `track`, with the three answers written into
+`00-request.md`. Every subsequent stage reads them before starting, and the words
+*build*, *verify*, and *finding* below are always to be read in the track's terms.
+
+---
+
+## Stage 0 — Intake
+
+**Input:** the user's request.
+**Output:** `runs/<id>/00-request.md`, `state.json`.
+
+Create the run id as `YYYY-MM-DD-<short-kebab-slug>`. Write the request verbatim —
+do not summarize it, since later stages read this instead of the conversation and a
+summary is where requirements quietly disappear.
+
+Verbatim includes the mess. Requests arrive as thinking out loud: half-formed,
+out of order, self-correcting, with the decisive constraint tucked into an aside near
+the end. Capture all of it, in the order it was said, including the parts that were
+later revised — the revision only makes sense next to what it revised. Making sense
+of that material is the planner's work, not the user's, and the user is never asked
+to restate a request more precisely.
+
+Then read the request and infer the track, per the section above. This is the one
+moment where the direction of the whole run is set: whether it is an enhancement, a
+build from nothing, a document, or work with no code in it at all. Getting it wrong
+here is not recoverable later — every stage will do good work aimed at the wrong
+target.
+
+The inference is stated in the plan's Framing and confirmed at the plan approval along with
+everything else. That is the correction point, and it is enough: the user reads one
+sentence and either nods or says "no, this is a blog post". They are never asked to
+categorize their own request up front.
+
+Write into `00-request.md`: the verbatim request, the deliverable, what done means,
+and what wrong means. Record in `state.json`: `id`, `mode`, `track`,
+`stage: "plan"`, `awaiting: null`.
+
+If the request remains ambiguous enough that a plan would be guesswork, ask now. One
+round of questions here is cheaper than a rejected plan.
+
+---
+
+## Stage files
+
+Read core (this file) plus the one file for the stage being run. Nothing else.
+
+| Reader | Reads |
+|---|---|
+| Planner | `spec.md` + [`spec-plan.md`](spec-plan.md) |
+| Builder | `spec.md` + [`spec-build.md`](spec-build.md) |
+| Reviewer | `spec.md` + [`spec-review.md`](spec-review.md) |
+| Main thread | `spec.md` + [`spec-main.md`](spec-main.md), plus the stage file for an approval it is presenting |
+
+---
+
+## Resume semantics
+
+Any tool picking up a run reads `state.json` and continues from `stage`, honoring
+`awaiting`. A run whose `awaiting` is non-null must not be advanced without a
+recorded decision in `02-approval.md`. This is what makes a run safe to hand between
+Claude Code, Codex, and Antigravity mid-flight.

package/skills/kaizen-help/SKILL.md

@@ -0,0 +1,119 @@
+---
+name: kaizen-help
+description: >
+  Quick-reference card for the kaizen workflow: commands, modes, approvals,
+  fix loop, config knobs, state layout, backlog/status rules. One-shot
+  display, not a persistent mode. Trigger: /kaizen-help, "kaizen help",
+  "what kaizen commands", "kaizen cheat sheet".
+---
+
+# Kaizen Help
+
+**Print the content of this card into your reply.** The user cannot see this file —
+it loads into your context only, so summarizing it or saying "see above" shows them
+nothing. Output the tables themselves.
+
+One-shot: do NOT change kaizen's active mode, write to `state.json`, or persist
+anything.
+
+## 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 |
+| `/kaizen status` | List every run grouped waiting-on-you / in flight / done / abandoned, plus open backlog count |
+| `/kaizen backlog` | Print open backlog items across all runs, grouped by source run, rescued items last under `Orphaned` |
+| `/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 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 |
+
+`/kaizen` with no argument: `status` if a run is in progress, else ask what to build.
+
+## Modes
+
+Set by `mode` in config, overridable per invocation.
+
+| Mode | What it does |
+|---|---|
+| `plan-only` | Produce the plan, write it, stop. No code touched. |
+| `approve` (default) | Stop at every enabled approval, wait for an explicit decision. |
+| `auto` | Run every stage back to back, no approval, report at the end. 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/irreversible actions still confirm even in `auto`.
+
+## Approvals
+
+- `approvals.plan` — after the plan, before any code is written.
+- `approvals.review` — after the review passes, before the work is called done.
+- `approvals.each_file` — confirm each file edit individually. Off by default; slow.
+
+A rejection is written to the run directory, and is one of two things — the reason
+says which. **Revise** ("do it differently") goes back to the planner, which produces
+a new plan and returns to the same approval. **Kill** ("not doing this") means the
+request itself was wrong: set `stage: "abandoned"` and stop, nothing to revise toward.
+
+## Fix loop
+
+- `auto_fix.enabled: false` — every finding stops the run, becomes a user decision.
+- `auto_fix.enabled: true` — builder fixes findings at or above `auto_fix.min_severity`,
+  reviewer re-checks, up to `auto_fix.max_iterations` rounds. Findings below threshold,
+  and anything still open when iterations run out, are reported to the user.
+
+Each iteration is written to `runs/<id>/05-iterations/`.
+
+## Config knobs (`config.default.yml` defaults)
+
+| Key | Default | Meaning |
+|---|---|---|
+| `mode` | `approve` | Default run mode |
+| `approvals.plan` | `true` | Stop after the plan |
+| `approvals.review` | `true` | Stop after the review |
+| `approvals.each_file` | `false` | Confirm every file edit |
+| `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 |
+| `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 |
+| `backlog.file` | `06-backlog.md` | Per-run backlog file |
+| `backlog.orphan_file` | `backlog.md` | Where a pruned run's open items are rescued to |
+| `state.dir` | `.kaizen` | State directory |
+| `state.keep_runs` | `20` | Completed runs kept before pruning oldest (rescues open backlog first) |
+| `git.auto_commit` | `false` | Never commit/push/PR unless the user explicitly asks |
+| `git.branch_before_implement` | `true` | Branch before implement stage when on the default branch |
+
+`.kaizen/config.yml` overrides only the keys it sets; everything else falls back to
+this skill's `config.default.yml`.
+
+## State layout
+
+```
+.kaizen/{spec.md, config.yml, memory.md, backlog.md (orphanage)}
+.kaizen/runs/<id>/{00-request,01-plan,02-approval,03-impl,04-review}.md,
+  05-iterations/, 06-backlog.md, state.json (id, mode, stage, awaiting, iteration, updated)
+```
+
+## Backlog and status
+
+Backlog items: `- <status>: <item text>`, `<status>` one of `open`, `done`, `rejected`
+(`rejected` carries a reason after `|`). `/kaizen backlog`/`status` are **read-only** —
+never edit `06-backlog.md` or `state.json`, even to fix a spotted inconsistency; report
+it and ask.
+
+`/kaizen status` groups every run by `state.json` at read time: **Waiting on you**
+(awaiting non-null, not abandoned), **In flight** (awaiting null, not done/abandoned),
+**Done**, **Abandoned**, plus `Backlog: <n> open` (all runs + orphanage; abandoned
+runs' items excluded).
+
+## More
+
+Full walkthrough and rationale: `~/.claude/skills/kaizen/README.md`. Full stage
+contract: `~/.claude/skills/kaizen/spec.md`. Codex/Antigravity porting:
+`~/.claude/skills/kaizen/adapters.md`.