kaizen-agent 1.6.8 → 1.7.0

package/skills/kaizen/spec-review.md

@@ -1,121 +1,121 @@
-# Kaizen — review stage
-
-Read with [`spec.md`](spec.md) (core: track, intake, resume). This file is the
-reviewer's contract. The planner and builder do not read it.
-
----
-## Stage 3 — Review
-
-**Agent:** reviewer, with a context that has never seen the builder's reasoning.
-**Input:** `01-plan.md` (its File manifest names what to read), `03-impl.md`, the
-track, and the work produced.
-**Output:** `04-review.md`.
-
-The track's third answer — *what would make it wrong* — is the reviewer's primary
-brief. It reads that first and hunts for it specifically.
-
-Five checks are universal, in every track:
-
-1. **Correctness** — is it true, and does it hold up? For code: logic errors,
-   unhandled cases, broken error paths, races, leaks. For a document: false claims,
-   internal contradictions, unsupported conclusions. For communication: overclaims,
-   and meaning the audience will not take as intended.
-2. **Plan conformance** — did the work do what was approved, no more and no less?
-   Scope creep is a finding. So is a step quietly skipped.
-3. **Blast radius** — what else touches what changed. A diff shows the lines that
-   moved; it does not show who depended on them. For every changed function, export,
-   schema field, config key, endpoint, or shared string, find its other callers and
-   readers and check each one still holds. This is the check a diff cannot contain,
-   and skipping it is how a run that passes its own verification breaks a feature
-   nobody looked at. In a non-code track the same question is "what else quoted,
-   linked to, or depended on the part that changed".
-4. **Regression** — the builder's before-and-after results from `03-impl.md`, verified
-   rather than trusted: re-run the checks. A check that passed at baseline and fails
-   now is a `high` finding at minimum, whatever else the work achieved. If the builder
-   recorded no baseline, that absence is itself the finding.
-
-5. **The plan's gate** — every `G-nn` item from the plan's Verification section,
-   re-answered against the work rather than against `03-impl.md`. A gate item the
-   builder marked `PASS` with no evidence behind it, or with evidence that only
-   restates the item, is treated as unproven and re-checked here; if it does not hold,
-   that is the finding. A `reason`-tier item fails when the technique is present and
-   the written reason is not.
-
-Then the track's own checks. For software work: security, reuse and simplification,
-test coverage. For a document: completeness against its own structure, accuracy of
-every checkable claim, whether its intended reader can actually use it. For
-operational work: missing prerequisites, absent rollback, steps that cannot be
-executed as written. The plan's Verification section says what was promised; the
-reviewer checks that promise was kept.
-
-**Keep the working transcript small.** Everything the reviewer reads stays in its
-context and is re-read on every request that follows, so the re-run suite dumped in
-full at check 4 is paid for again at every check after it. Pipe long output through a
-filter that keeps the decisive lines — the failure count, the failing test names, the
-first error — and read the full output only where a check actually fails, which is the
-only place the detail becomes a finding. The same holds for the work under review: open
-the manifest's paths at the ranges the plan names, and read the diff rather than the
-whole file wherever the finding would cite a changed line. `04-review.md` records the
-findings, not the transcript.
-
-This does not apply to check 3. Blast radius is the check whose whole point is what
-the diff does not contain, so it reads as widely as it needs to — every caller, every
-reader, whole files where that is what it takes. A cheaper blast-radius pass is not a
-cheaper review, it is the check not happening.
-
-Each finding is one line, numbered from 1 within the review:
-`<n>. <where>: <severity>: <problem>. <fix>. [G-nn]` Where is a `path:line` for code,
-and a section, page, or step reference otherwise. Severity is one of `critical`,
-`high`, `medium`, `low`. The number is what the user approves fixes by, and what the
-fix loop and the backlog refer to afterward, so it never changes once written.
-
-**A finding against a gate item cites it, and takes its severity from that item's
-tier** — `block` is `critical` or `high`, `reason` is `medium`, `lock` is `low`. This
-is what keeps the same class of problem from being graded differently run to run, and
-it is not a judgment the reviewer re-litigates: the tier was set at the plan, which
-the user approved. A finding outside the gate carries no id and is graded on its own
-merits.
-
-The reviewer verifies before reporting: a finding it cannot construct a concrete
-failing input or scenario for is dropped, not softened into a maybe. No praise, no
-summary of what the code does, no style nits that do not change meaning.
-
-The reviewer also appends any durable lesson about this material to `memory.md` —
-a recurring bug pattern, a non-obvious constraint, a convention worth keeping. Not
-run-specific detail; only what the next run would want to know.
-
-`memory.md` is read by every stage of every future run, so its size is a tax on all of
-them. Keep it under `review.memory_max_lines` (default 100): before appending, drop
-any lesson that is now wrong, already enforced by a test or a lint rule, or restated
-by a newer entry. A memory file that only grows stops being read carefully.
-
----
-
-## Stage 4 — Fix loop
-
-Governed by `auto_fix`. See the skill's fix-loop section for the exact behavior.
-
-Each iteration writes `05-iterations/NN-fix.md` (what the builder changed) and
-`NN-recheck.md` (what the reviewer found afterward). The loop ends when the reviewer
-reports nothing at or above the threshold, or `max_iterations` is reached.
-
-A finding the loop could not close is escalated to the user with the reviewer's
-description intact — never quietly downgraded to make the run look clean.
-
-**A recheck is not a second review.** Re-answer the findings it was meant to close,
-the gate items the change could plausibly touch, and the regression check. Nothing
-else. State which items were skipped and why, in one line, so the reader can disagree
-with the judgement — a skipped item is a claim that the change could not have reached
-it, and that claim is checkable.
-
-Answering all of them again is not thoroughness, it is the same evidence gathered
-twice. A fix that touched one line of a message string cannot have broken an item
-about which directories the installer writes to, and re-running that item's live
-setup to prove it costs more than the fix did. Where a change genuinely could have
-reached everything — a rename across the run's files, a shared helper — say so and
-re-answer everything.
-
-The exception is the regression check, which runs every iteration whatever the fix
-touched. It is cheap, and it is the one that catches a fix breaking something nobody
-thought to connect it to.
-
+# Kaizen — review stage
+
+Read with [`spec.md`](spec.md) (core: track, intake, resume). This file is the
+reviewer's contract. The planner and builder do not read it.
+
+---
+## Stage 3 — Review
+
+**Agent:** reviewer, with a context that has never seen the builder's reasoning.
+**Input:** `01-plan.md` (its File manifest names what to read), `03-impl.md`, the
+track, and the work produced.
+**Output:** `04-review.md`.
+
+The track's third answer — *what would make it wrong* — is the reviewer's primary
+brief. It reads that first and hunts for it specifically.
+
+Five checks are universal, in every track:
+
+1. **Correctness** — is it true, and does it hold up? For code: logic errors,
+   unhandled cases, broken error paths, races, leaks. For a document: false claims,
+   internal contradictions, unsupported conclusions. For communication: overclaims,
+   and meaning the audience will not take as intended.
+2. **Plan conformance** — did the work do what was approved, no more and no less?
+   Scope creep is a finding. So is a step quietly skipped.
+3. **Blast radius** — what else touches what changed. A diff shows the lines that
+   moved; it does not show who depended on them. For every changed function, export,
+   schema field, config key, endpoint, or shared string, find its other callers and
+   readers and check each one still holds. This is the check a diff cannot contain,
+   and skipping it is how a run that passes its own verification breaks a feature
+   nobody looked at. In a non-code track the same question is "what else quoted,
+   linked to, or depended on the part that changed".
+4. **Regression** — the builder's before-and-after results from `03-impl.md`, verified
+   rather than trusted: re-run the checks. A check that passed at baseline and fails
+   now is a `high` finding at minimum, whatever else the work achieved. If the builder
+   recorded no baseline, that absence is itself the finding.
+
+5. **The plan's gate** — every `G-nn` item from the plan's Verification section,
+   re-answered against the work rather than against `03-impl.md`. A gate item the
+   builder marked `PASS` with no evidence behind it, or with evidence that only
+   restates the item, is treated as unproven and re-checked here; if it does not hold,
+   that is the finding. A `reason`-tier item fails when the technique is present and
+   the written reason is not.
+
+Then the track's own checks. For software work: security, reuse and simplification,
+test coverage. For a document: completeness against its own structure, accuracy of
+every checkable claim, whether its intended reader can actually use it. For
+operational work: missing prerequisites, absent rollback, steps that cannot be
+executed as written. The plan's Verification section says what was promised; the
+reviewer checks that promise was kept.
+
+**Keep the working transcript small.** Everything the reviewer reads stays in its
+context and is re-read on every request that follows, so the re-run suite dumped in
+full at check 4 is paid for again at every check after it. Pipe long output through a
+filter that keeps the decisive lines — the failure count, the failing test names, the
+first error — and read the full output only where a check actually fails, which is the
+only place the detail becomes a finding. The same holds for the work under review: open
+the manifest's paths at the ranges the plan names, and read the diff rather than the
+whole file wherever the finding would cite a changed line. `04-review.md` records the
+findings, not the transcript.
+
+This does not apply to check 3. Blast radius is the check whose whole point is what
+the diff does not contain, so it reads as widely as it needs to — every caller, every
+reader, whole files where that is what it takes. A cheaper blast-radius pass is not a
+cheaper review, it is the check not happening.
+
+Each finding is one line, numbered from 1 within the review:
+`<n>. <where>: <severity>: <problem>. <fix>. [G-nn]` Where is a `path:line` for code,
+and a section, page, or step reference otherwise. Severity is one of `critical`,
+`high`, `medium`, `low`. The number is what the user approves fixes by, and what the
+fix loop and the backlog refer to afterward, so it never changes once written.
+
+**A finding against a gate item cites it, and takes its severity from that item's
+tier** — `block` is `critical` or `high`, `reason` is `medium`, `lock` is `low`. This
+is what keeps the same class of problem from being graded differently run to run, and
+it is not a judgment the reviewer re-litigates: the tier was set at the plan, which
+the user approved. A finding outside the gate carries no id and is graded on its own
+merits.
+
+The reviewer verifies before reporting: a finding it cannot construct a concrete
+failing input or scenario for is dropped, not softened into a maybe. No praise, no
+summary of what the code does, no style nits that do not change meaning.
+
+The reviewer also appends any durable lesson about this material to `memory.md` —
+a recurring bug pattern, a non-obvious constraint, a convention worth keeping. Not
+run-specific detail; only what the next run would want to know.
+
+`memory.md` is read by every stage of every future run, so its size is a tax on all of
+them. Keep it under `review.memory_max_lines` (default 100): before appending, drop
+any lesson that is now wrong, already enforced by a test or a lint rule, or restated
+by a newer entry. A memory file that only grows stops being read carefully.
+
+---
+
+## Stage 4 — Fix loop
+
+Governed by `auto_fix`. See the skill's fix-loop section for the exact behavior.
+
+Each iteration writes `05-iterations/NN-fix.md` (what the builder changed) and
+`NN-recheck.md` (what the reviewer found afterward). The loop ends when the reviewer
+reports nothing at or above the threshold, or `max_iterations` is reached.
+
+A finding the loop could not close is escalated to the user with the reviewer's
+description intact — never quietly downgraded to make the run look clean.
+
+**A recheck is not a second review.** Re-answer the findings it was meant to close,
+the gate items the change could plausibly touch, and the regression check. Nothing
+else. State which items were skipped and why, in one line, so the reader can disagree
+with the judgement — a skipped item is a claim that the change could not have reached
+it, and that claim is checkable.
+
+Answering all of them again is not thoroughness, it is the same evidence gathered
+twice. A fix that touched one line of a message string cannot have broken an item
+about which directories the installer writes to, and re-running that item's live
+setup to prove it costs more than the fix did. Where a change genuinely could have
+reached everything — a rename across the run's files, a shared helper — say so and
+re-answer everything.
+
+The exception is the regression check, which runs every iteration whatever the fix
+touched. It is cheap, and it is the one that catches a fix breaking something nobody
+thought to connect it to.
+

package/skills/kaizen/spec.md

@@ -1,153 +1,153 @@
-# 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`, `runner`, `agent`, `track`,
-`stage: "plan"`, `awaiting: null`.
-
-`stage` takes exactly one of five words, and boards key their columns on them:
-`plan`, `build`, `review`, `done`, `abandoned`. Set it when the stage starts —
-`build` before the builder touches anything, `review` before the reviewer reads — as
-its own write, not tacked onto a longer command that may not finish. Any other word
-(`implement`, `fix`, `building`) is unknown to every reader and shows as still planning.
-
-`awaiting` is `null` or the config key of the approval being waited on —
-`approvals.plan`, `approvals.review`, `approvals.each_file` — or `findings` when the
-run has stopped for the user to pick which review findings to fix. Boards read it to
-say what a run is waiting for and where it sits; a word outside this list is shown but
-not understood.
-
-`agent` is the tool this run is happening in — `claude`, `codex`, `agy`, `opencode`,
-`gemini`, or `cursor` — written once at intake and never changed, so a board can say
-which agent to look for when a run is waiting. The tool running this stage knows what
-it is; no detection is needed.
-
-`runner` is read from config at intake and written down here, because it decides
-whether the stages that follow are separate agents or this one. A run resumed later
-keeps the runner it started with: a review done in the same session as the work is a
-different thing from an independent one, and which happened should not depend on what
-the config said the day someone came back to it.
-
-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.
+# 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`, `runner`, `agent`, `track`,
+`stage: "plan"`, `awaiting: null`.
+
+`stage` takes exactly one of five words, and boards key their columns on them:
+`plan`, `build`, `review`, `done`, `abandoned`. Set it when the stage starts —
+`build` before the builder touches anything, `review` before the reviewer reads — as
+its own write, not tacked onto a longer command that may not finish. Any other word
+(`implement`, `fix`, `building`) is unknown to every reader and shows as still planning.
+
+`awaiting` is `null` or the config key of the approval being waited on —
+`approvals.plan`, `approvals.review`, `approvals.each_file` — or `findings` when the
+run has stopped for the user to pick which review findings to fix. Boards read it to
+say what a run is waiting for and where it sits; a word outside this list is shown but
+not understood.
+
+`agent` is the tool this run is happening in — `claude`, `codex`, `agy`, `opencode`,
+`gemini`, or `cursor` — written once at intake and never changed, so a board can say
+which agent to look for when a run is waiting. The tool running this stage knows what
+it is; no detection is needed.
+
+`runner` is read from config at intake and written down here, because it decides
+whether the stages that follow are separate agents or this one. A run resumed later
+keeps the runner it started with: a review done in the same session as the work is a
+different thing from an independent one, and which happened should not depend on what
+the config said the day someone came back to it.
+
+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.