@terreno/agent-plugin 0.0.0-stage → 58.0.0-beta.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Flourish Health, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,58 @@
-# Temporary Holding Version
+# Terreno plugin for Claude Code
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Terreno's agent lifecycle and app-building skills for Claude Code. Grow shapes a request
+into an approved plan, Pick and Roast build and prove it one task at a time, Brew opens the
+pull request, and Taste reacts to review and CI until it is mergeable. The plugin also ships
+Terreno backend, UI, data, admin, docs, upgrade, and deployment skills, plus the
+`pre-commit` and `ui-verifier` agents.
+
+Reference: https://github.com/TerrenoLabs/terreno/blob/master/docs/reference/lifecycle-plugin.md
+
+## Install
+
+Pick one channel and register only that one. Each channel provides a plugin named
+`terreno`, so two channels give duplicate commands.
+
+Latest stable release, installed from npm as `@terreno/agent-plugin`:
+
+```text
+/plugin marketplace add https://raw.githubusercontent.com/TerrenoLabs/terreno/master/plugins/claude-release/.claude-plugin/marketplace.json
+/plugin install terreno@terreno-releases
+```
+
+Every merge to `master`:
+
+```text
+/plugin marketplace add TerrenoLabs/terreno
+/plugin install terreno@terreno-plugins
+```
+
+One release, pinned: add `TerrenoLabs/terreno#<version>` as the marketplace instead.
+
+Then run `/terreno:1-grow`. Claude Code does not auto-update third-party marketplaces by
+default; run `/plugin update terreno@<marketplace>` to pick up a new release.
+
+## What you get
+
+| Command | Does |
+| --- | --- |
+| `/terreno:1-grow` | Research, clarify, and approve an implementation plan and task list |
+| `/terreno:2-pick` | Build one task test-first, then roast it and pick the next |
+| `/terreno:3-roast` | Independently prove or disprove the current task |
+| `/terreno:4-brew` | Final checks, commit, push, open the PR, wait for CI and review bots |
+| `/terreno:5-taste` | React to CI and review on the PR until it is mergeable |
+| `/terreno:pick-roast-loop` | Work an approved plan through every task |
+
+## Maintainers
+
+This directory is generated. Do not hand-edit it; run `bun run skills:sync`.
+
+Claude Code resolves a plugin skill's command from the frontmatter `name`, so the
+shortened names live here instead of in the shared skill files. Cursor, Codex, and
+`npx skills` keep the canonical names from `plugins/terreno-planning/`.
+
+| Source | Owns |
+| --- | --- |
+| `plugins/terreno-planning/skills/` | Lifecycle and Terreno app workflows |
+| `plugins/terreno-planning/agents/` | Reusable verification agents |
+| `plugins/terreno-planning/references/` | Shared lifecycle references |

package/agents/pre-commit.md

@@ -0,0 +1,65 @@
+---
+name: pre-commit
+description: Run lint, type check, and related tests on the current working tree. Fix any failures encountered. Use before commits and after CI fix attempts.
+---
+
+You are the pre-commit checker. Your job is to run lint, type check, and related tests for the current project, fix any issues you find, and report back.
+
+## Steps
+
+1. Find the project root:
+   ```bash
+   git rev-parse --show-toplevel
+   ```
+   `cd` into it for the rest of the run.
+
+2. Run lint:
+   ```bash
+   bun run lint
+   ```
+   If it fails, read the failing files, fix the issues, and re-run until it passes. Do not use `--no-verify` or skip rules.
+
+3. Run type check / compile:
+   ```bash
+   bun run compile
+   ```
+   If it fails, fix the type errors and re-run until it passes.
+
+4. Identify changed files:
+   ```bash
+   git diff --name-only
+   git diff --cached --name-only
+   git diff --name-only origin/master...HEAD 2>/dev/null
+   ```
+
+5. Find and run related tests:
+   - For each changed source file, look for a sibling `*.test.*` / `*.spec.*` or a matching file under `__tests__/`.
+   - Run only the discovered tests:
+     ```bash
+     bun test <files>
+     ```
+   - If changes are concentrated in one package, inspect that package's scripts and
+     prefer its package-level test command.
+   - If no specific tests are found, run the documented affected-package suites.
+   - Fix failures and re-run until all tests pass.
+
+## Output format
+
+Report back as a single concise block:
+
+```
+## Pre-Commit Report
+- **Lint:** [passed | fixed N issues]
+- **Compile:** [passed | fixed N issues]
+- **Tests:** [N passed | fixed N failures | none found]
+- **Files touched while fixing:** [list, or "none"]
+```
+
+If you cannot fix something after a reasonable number of attempts, stop and report the failure with the exact error and the file(s) involved — do not loop forever.
+
+## Rules
+
+- Never use `--no-verify`, `--skip`, or any flag that bypasses checks.
+- Never modify PATH or prepend anything when running `bun` — it is already on PATH.
+- Do not commit, push, or touch git history. Your job is checks + fixes only.
+- Do not create new files unless a fix genuinely requires it.

package/agents/ui-verifier.md

@@ -0,0 +1,93 @@
+---
+name: ui-verifier
+description: Verify UI changes end to end when the parent briefing lists UI files. Compile, lint, UI tests, bring up a stack you own, log in, exercise the named feature under the required checks, run the matching Maestro flow (or direct simulator commands when the app has no Maestro) for mobile-focused work, report only and never edit the tree, capture screenshots/videos. Do not run on backend-only slices. Do not diff the whole frontend tree when a file list is provided.
+---
+
+You are the UI verifier. Use the parent's task-scoped briefing (changed screens/components,
+named commands, expected evidence). Follow the `/verify-ui-changes` skill only for the
+steps the briefing still needs; do not reload the whole skill when the briefing already
+names the flow.
+
+## Steps
+
+1. Identify changed frontend files from the briefing. If none were listed, inspect the
+   branch and keep rendered UI files (`*.tsx`, `*.jsx`, `*.html`, `*.css`, stories,
+   routes, theme/layout/navigation config):
+   ```bash
+   git diff --name-only origin/master...HEAD
+   ```
+   If that list is empty, return "not applicable — no UI files" and stop.
+
+2. Run only the named automated checks from the briefing. If the parent already ran
+   compile/lint/tests, do not rerun the full monorepo. Otherwise inspect the nearest
+   changed package's `package.json` and run its compile/typecheck, lint, and UI test
+   scripts. Do not invent script names.
+   You are report-only: never edit the tree, including adding `testID`s or Maestro
+   flows. A missing `testID` or flow, or a failure, is FAIL with the evidence.
+
+3. State the flow in one sentence (`<entry point> -> <action> -> <expected visible
+   result>`), then read the repository's app-launch and test-user instructions. Start
+   the documented backend/frontend or demo target **on ports nothing else holds**; when
+   the repository ships a `verify-ui` stack script, use it. If a port is already taken by
+   something you did not start, stop and report the ports: do not test through it and
+   do not kill it, it may be a backend on staging. Seed only through a documented
+   command and log in with documented test credentials. If required instructions or
+   credentials are absent, report the exact blocker rather than guessing.
+
+4. Navigate to the changed feature and exercise its primary flow end to end, then the
+   adversarial paths: invalid input, wrong credentials, empty and error and loading
+   states the change touches. For admin changes, use a documented admin test account.
+   Prefer an existing Playwright flow and repository selector rules (`testID`s) where
+   available; never add arbitrary sleeps.
+
+5. For component/story-only changes, use the repository's documented component demo or
+   story host and exercise the changed states.
+
+6. For mobile-focused changes (native screens, gestures, navigation stacks, keyboard,
+   safe areas, permissions, `*.native.tsx`, `Platform.OS` branches, or a ticket that says
+   "mobile" or "app"), verify on the app's simulator. When the app has Maestro configured
+   (`<app>/maestro/`), run the matching flow there, using the repository's `verify-ui`
+   Maestro runner when it exists, and do not script taps outside Maestro. When it does
+   not, drive the simulator with the direct `xcrun simctl` / `idb` / `adb` commands in
+   the skill's "Simulator leg", from a script outside the tree. Web alone is not enough.
+
+7. **Score the required checks** on every run: right page, not blank, no error overlay,
+   console clean, DOM assertion, interaction proof, screenshot. A console error in the
+   changed code path fails the run even when the screenshot looks right.
+
+8. **Capture and save evidence** (mandatory when manual verification runs), outside the
+   source tree:
+   - Save screenshots to `/opt/cursor/artifacts/screenshots/` (or your scratchpad)
+   - Save screen recordings to `/opt/cursor/artifacts/`
+   - Use `RecordScreen` for interaction-flow videos in Cursor Cloud.
+   - Seed or QA data only; never capture real user data or PHI.
+   - Report artifact paths and what each proves so the parent agent can add only the
+     decisive artifact to the PR `Verification` table, or the secret gist link the
+     repository's publish script printed.
+
+## Output format
+
+```
+## UI Verification Report
+- **Result:** [PASS | FAIL | UNVERIFIED — blocker] (worst outcome across every required leg, including Simulator)
+- **Flow under test:** [entry point -> action -> expected visible result]
+- **Compile:** [pass | fail — error | skipped — parent already ran]
+- **Lint:** [pass | fail — error | skipped — parent already ran]
+- **Tests:** [pass | fail — which | skipped]
+- **Environment:** [app URL(s), viewport(s), credentials used (names only), stack you started or ports taken]
+- **Checks:** [per app × viewport: right page / not blank / no error overlay / console clean / DOM assertion / interaction proof / screenshot — pass | fail — detail]
+- **Simulator:** [Maestro flow(s) or direct commands run, device: PASS | FAIL — failure | UNVERIFIED — blocker | n/a — change matches none of the mobile-focused triggers in step 6]
+- **Interaction:** [the steps taken and the assertion after each]
+- **Evidence artifacts:** [paths or links to screenshots/videos/gist, or none if blocked]
+- **Remaining risk:** [states or platforms the change does not require; a required leg that did not run is UNVERIFIED, not risk]
+```
+
+Prefix each verified item with pass, warning, or fail. If an environment limitation prevented verification (no browser, no MongoDB, ports taken, no simulator), say exactly what could not be verified rather than implying it passed.
+
+## Rules
+
+- Never use `waitForTimeout()` in any Playwright code you write.
+- Leave dev servers running only if the caller asked for manual follow-up testing; otherwise stop them, and stop only what you started.
+- Report outcomes faithfully — a required check you could not run is UNVERIFIED with its blocker, and makes the Result UNVERIFIED, never PASS.
+- Login + feature exercise is required for authenticated apps; do not treat app-start-only as complete verification.
+- Do not spawn nested reviewers.

package/package.json

@@ -1,6 +1,34 @@
 {
+  "description": "Terreno lifecycle and app workflows: Grow, Pick/Roast, Brew, Taste, continuous outer loops, backend/API, UI, data, schema, admin, docs, upgrades, deployment, and verification agents.",
+  "files": [
+    ".claude-plugin/",
+    "agents/",
+    "references/",
+    "skills/",
+    "CHANGELOG.md",
+    "LICENSE",
+    "README.md"
+  ],
+  "homepage": "https://github.com/TerrenoLabs/terreno/blob/master/plugins/README.md",
+  "keywords": [
+    "claude-code",
+    "claude-plugin",
+    "terreno",
+    "planning",
+    "sdlc",
+    "implementation",
+    "review",
+    "tdd"
+  ],
+  "license": "MIT",
   "name": "@terreno/agent-plugin",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "directory": "plugins/terreno-claude",
+    "type": "git",
+    "url": "git+https://github.com/TerrenoLabs/terreno.git"
+  },
+  "version": "58.0.0-beta.2"
+}

package/references/async-review-bots.md

@@ -0,0 +1,76 @@
+# Async review bots
+
+Brew and Taste **wait in-process** until async review bots on the current head have
+reported, then continue the stage so they can react. Product test CI is a separate
+Taste wait: follow [`product-ci.md`](product-ci.md) after this procedure, using GitHub
+CLI or CircleCI CLI in a watch loop until jobs are terminal or that wait times out.
+
+## What counts
+
+A review bot is an automated GitHub actor that posts a check run, code-scanning alert,
+or PR review/comment after a push. Match by check name, app slug, or review author.
+Examples:
+
+- Cursor Bugbot
+- GitHub CodeQL / code scanning
+- Copilot or other review bots when they appear on the PR
+
+Do not treat ordinary product CI as a review bot. Product CI is lint, typecheck, unit,
+e2e, and build work on **any** host (GitHub Actions, CircleCI, Buildkite, GitLab CI,
+Jenkins, Azure Pipelines, Bitbucket Pipelines, and similar). Observe those jobs with
+[`product-ci.md`](product-ci.md).
+
+## When to wait
+
+Wait after Brew has pushed or created the PR, and whenever Taste's current head has a
+matched bot queued, in progress, or still inside the startup grace.
+
+**Do not exit while a matched bot is queued or in progress.**
+
+## Procedure
+
+1. Record the current head SHA.
+2. **Startup grace (90 seconds).** Use a provider-native hook only when it can await the
+   **matched bot**, not arbitrary checks for this SHA. GitHub CLI has no targeted
+   check-creation watch, so prefer the harness PR-event subscription. If no targeted
+   hook can detect new checks, reviews, and comments, sleep 30 seconds and re-fetch.
+   Stop the grace when a matched bot appears or 90 seconds elapse. If none appeared,
+   continue.
+3. **Completion wait.** Use a provider-native hook only when it targets the matched bot,
+   not all PR checks. For a bot backed by a resolved GitHub Actions run, prefer
+   `gh run watch <run-id> --interval 30`. Its exit code is a wait result, not a Brew
+   verdict; always re-fetch and classify the bot outcome. Do **not** use unfiltered
+   `gh pr checks --watch`: it also waits for ordinary product CI. For check-run-only or
+   review/comment bots, prefer a harness PR-event subscription. If no targeted hook is
+   available, sleep 30 seconds and re-fetch the matched bot state. Continue until every
+   matched bot is terminal, or 20 minutes have elapsed.
+   Terminal means the check completed (success, failure, cancelled, skipped, timed out)
+   or the bot posted a completed review/comment batch for this head.
+4. **Timeout.** If still running at 20 minutes, **stop**. Do not continue the stage
+   procedure. Emit `PENDING` with `next: taste` and `wait: 120`. Record which bots are
+   still running.
+5. **Re-observe, then continue — only after a completed wait.** When every matched bot
+   is terminal or none appeared after the grace period, use that snapshot. Brew records
+   bot outcomes and does not implement fixes. Taste classifies bot findings and acts on
+   actionable ones in this invocation.
+
+Never hand-roll a sleep loop when the provider CLI or harness supplies a bounded
+watch/subscription hook. If fallback polling is necessary, use the harness sleep
+primitive and record why no hook applied. Do not busy-spin.
+
+## Address every finding
+
+Waiting is not the goal; answering is. Taste handles every bot thread and finding on
+the PR per [`push ownership`](push-ownership.md#bot-comments): fixed and resolved,
+declined with a one-sentence reply and resolved, or left open only as a human
+decision. An unanswered bot thread blocks Taste `PASS`.
+
+## Bounds
+
+- This wait is only for review bots, never "until all CI is green."
+- After Taste pushes a fix, wait again for review bots on the new head, then run the
+  product-CI wait loop, then act on those results **once** in this invocation. A further
+  push after that second act emits `PENDING` (`next: taste`); the outer loop owns later
+  cycles.
+- Product CI uses Taste's bounded watch loop (`gh` / `circleci`), not this review-bot
+  procedure. Unfiltered `gh pr checks --watch` belongs there, not here.

package/references/documentation-contract.md

@@ -0,0 +1,61 @@
+# Documentation contract
+
+Human-facing docs are the architecture source. Code implements them. Skills never treat
+docs as optional commentary.
+
+## Always read docs first
+
+Before shaping, implementing, verifying, or submitting:
+
+1. Open the repository's architecture and domain docs for the affected area.
+2. Prefer tutorials, how-to guides, reference, and explanation over tribal comments.
+3. Reconstruct current behavior from those docs plus code/tests. If they disagree, the
+   change must resolve the disagreement in the same slice.
+4. Do not invent architecture from the diff alone when docs exist.
+
+If the repository has no docs for the affected area, create them in this slice.
+
+## Always update docs
+
+Update docs in the same slice as the behavior when any of these change:
+
+- public API, CLI, env, config, routes, models, permissions
+- user-visible UI or operator workflow
+- architecture, data flow, ownership, or runtime topology
+- verification, rollout, or compatibility rules
+
+A user-visible change also updates its end-user page in the
+[`user guide`](user-guide.md), unless the repository opts out.
+
+Skip docs only for a pure internal refactor that does not change those. Record that skip
+in the stage result `done` list. Missing docs for a user-visible or architectural change is `FAIL`,
+not a follow-up.
+
+## How to write
+
+Use the repository's docs layout when one exists. Otherwise use Diátaxis:
+
+| Kind | Put |
+| --- | --- |
+| Task a new user must complete | tutorial |
+| Task an operator already understands | how-to |
+| Facts: APIs, props, commands, env | reference |
+| Why the system is shaped this way | explanation |
+
+Rules:
+
+- Lead with the next action or the canonical fact.
+- Use the repository's standard headings. Do not invent parallel outlines.
+- Prefer tables for options, ownership, and verification.
+- Show one minimal example. Do not paste implementation chronology.
+- Keep a page scannable: short sections, no recap, no preamble.
+- Update the existing page in place. Split only when a page covers two jobs.
+- Generated reference must be regenerated; never hand-edit generated output.
+- Agent-facing rules/skills stay in their canonical source and are regenerated after.
+
+## Done when
+
+- A stranger can find the behavior from docs without reading the PR.
+- Architecture docs match the shipped design.
+- Examples and commands in docs are current.
+- The stage result `done` list names every docs file created or updated.

package/references/execution-state.schema.json

@@ -0,0 +1,77 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://terreno.dev/schemas/execution-state.schema.json",
+  "title": "Terreno lifecycle execution state",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["v", "stage", "attempt", "next"],
+  "properties": {
+    "v": {"const": 2},
+    "ip": {"type": "string"},
+    "task": {"type": "string"},
+    "stage": {"enum": ["grow", "pick", "roast", "brew", "taste"]},
+    "attempt": {"type": "integer", "minimum": 1},
+    "branch": {"type": "string"},
+    "sha": {"type": "string"},
+    "pr": {"type": "string"},
+    "skills": {"type": "array", "items": {"type": "string"}},
+    "last": {
+      "anyOf": [
+        {"type": "null"},
+        {"$ref": "stage-result.schema.json"}
+      ]
+    },
+    "artifacts": {"type": "array", "items": {"type": "string"}},
+    "tried": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["stage", "attempt", "why", "status", "ev"],
+        "properties": {
+          "stage": {"enum": ["grow", "pick", "roast", "brew", "taste"]},
+          "attempt": {"type": "integer", "minimum": 1},
+          "why": {"type": "string"},
+          "status": {"enum": ["PASS", "FAIL", "BLOCKED", "PENDING"]},
+          "ev": {"type": "string"}
+        }
+      }
+    },
+    "ledger": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["task", "stage", "attempt", "sha", "status", "summary", "ev"],
+        "properties": {
+          "task": {"type": "string"},
+          "stage": {"enum": ["pick", "roast"]},
+          "attempt": {"type": "integer", "minimum": 1},
+          "sha": {"type": "string"},
+          "status": {"enum": ["PASS", "FAIL", "BLOCKED"]},
+          "summary": {"type": "string"},
+          "hypothesis": {"type": "string"},
+          "files": {"type": "array", "items": {"type": "string"}},
+          "checks": {"type": "array", "items": {"type": "string"}},
+          "artifacts": {"type": "array", "items": {"type": "string"}},
+          "docs": {"type": "array", "items": {"type": "string"}},
+          "risks": {"type": "array", "items": {"type": "string"}},
+          "ev": {"type": "string"}
+        }
+      }
+    },
+    "next": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["stage", "why", "human"],
+      "properties": {
+        "stage": {
+          "type": ["string", "null"],
+          "enum": ["grow", "pick", "roast", "brew", "taste", null]
+        },
+        "why": {"type": "string"},
+        "human": {"type": "boolean"}
+      }
+    }
+  }
+}

package/references/github-attention-contract.md

@@ -0,0 +1,165 @@
+# GitHub attention contract
+
+Human attention is the scarcest resource. A PR must be understandable in one glance.
+Put detail behind disclosure controls and post comments only when they cause a human
+decision or preserve context that the diff cannot.
+
+## Pull request title
+
+Format: `[ticket] Short feature title`
+
+- `ticket` is the attached tracker id, copied in that tracker’s own form:
+  Linear `TEAM-n` (`[FH-1632]`) or GitHub `#n` (`[#412]`).
+- Prefer Linear when both are attached. If none is attached, omit the brackets
+  and use only the feature title.
+- The feature title names what the change does, short and memorable.
+- Use at most 72 characters including the ticket prefix.
+- Do not use conventional-commit prefixes (`feat:`, `docs:`, `fix:`, `chore:`).
+- Do not use lifecycle labels (`IP Approved`, `Task list`) or other status words.
+- Do not put implementation detail in the title.
+
+Use:
+
+```text
+[FH-1632] Standardize planning PR titles
+[#412] Windowed admin table sync
+Rate-limit Better Auth sign-in
+```
+
+Do not use:
+
+```text
+IP Approved: Task list for syncdb
+feat: add PR title format
+[FH-1632] IP Approved — Grow artifacts
+docs: update attention contract
+```
+
+## Pull request body
+
+Use exactly these top-level headings, in this order:
+
+```markdown
+## Why
+
+<The IP's initial justification: problem, user/repository impact, and canonical issue/spec.>
+
+Implements `<plan path>` (T1–T3). Closes #<n>.
+
+## What changed
+
+- <Brief overview of the approved IP and its intended outcomes; maximum five bullets.>
+
+## Verification
+
+| Status | Scope | Evidence / action |
+| --- | --- | --- |
+| ✅ Tested | <behavior or risk> | `<command>` or artifact link |
+| 🧭 Test instructions | <feature or workflow> | <exact steps a reviewer can follow> |
+| ⚠️ Not tested | <remaining risk> | <exact reviewer test or action> |
+| ⚠️ Not tested | Regression cases `<AREA-NNN>`, `<AREA-NNN>` | Walk them in [`<suite file>`](<link>) |
+```
+
+Rules:
+
+- Keep the visible body under 250 words.
+- Spell the headings exactly `## Why`, `## What changed`, and `## Verification`. The
+  approval bot reads sections by heading; a `What`, `Summary`, or `Testing` heading reads
+  as a missing section and raises the PR's risk level.
+- When the PR implements a plan, end `Why` with one line naming the plan file's
+  repository path in backticks and the task ids it delivers (`T1–T3`, `Tasks 2.1–2.2`).
+  When it closes an issue, add `Closes #<n>`. The approval bot finds the plan only from a
+  literal path, the stage result's `ip`, or a plan file changed in the diff; without one it
+  scores plan match at most 1 out of 3.
+- Initialize `Why` from the IP's original justification. Preserve the problem and
+  motivation that caused the IP to exist; do not replace them with recent-turn context.
+- Initialize `What changed` with a short overview of the approved IP and intended
+  outcomes. Explain the feature, not the implementation chronology or last agent turn.
+- Keep `Why` and `What changed` stable while the PR's purpose and scope remain
+  accurate. Update them only for an approved scope change, a factual correction, or a
+  human edit.
+- Always include executable testing instructions in `Verification`, even after all
+  automated tests pass. A reviewer must be able to reproduce the important behavior.
+- Update testing instructions, evidence, and remaining-risk rows whenever verification
+  changes. Do not regenerate the rest of the body from the latest turn.
+- Omit empty rows and optional sections. If nothing remains untested, omit the
+  `Not tested` row.
+- When the PR adds or changes manual regression cases in the testing-plan suite
+  files, list every such case ID in one row that links its suite file. Use
+  `⚠️ Not tested`, with walking the cases as the reviewer action, until a person walks
+  every listed case on this branch; then use `✅ Tested`, naming who walked them and
+  the evidence. Omit the row when the PR adds or changes no case.
+- Put the most decision-relevant verification first.
+- Name what a check proves; a command alone is not evidence. Write the outcome next
+  to the command (`` `bun test api` → 412 pass ``).
+- Use only the three-column table, with the status mark (`✅`, `🧭`, or `⚠️`) in the
+  first cell of every row. The approval bot reads verification from those marks; a
+  bullet list or a `| Check | Result |` table without them reads as no verification.
+- Link one canonical issue/spec in `Why`; do not add a separate metadata section.
+- Embed only the minimum screenshot/video needed to prove user-visible behavior.
+- Put migration notes, full check logs, compatibility matrices, unusual implementation
+  detail, and the stage-result YAML in one optional block after the table:
+
+  ```html
+  <details>
+  <summary>Details</summary>
+  Concise supporting detail.
+  <details>
+  <summary>Stage result</summary>
+  Compact v2 YAML for the next skill. Never duplicate it in the visible body.
+  </details>
+  </details>
+  ```
+
+- In the stage-result YAML, set `ip` to the plan's filename without `.md` (for
+  `<plans dir>/2026-10-01-post-cache.md`, `ip: 2026-10-01-post-cache`), and
+  start each `done` entry with its task id (`T2 Roast PASS`). A later stage that rewrites
+  the block keeps `ip` and the delivered task ids.
+- Never put stage-result YAML in the visible body or a comment. Omit the inner Stage
+  result toggle when this PR is not a lifecycle handoff.
+
+- Do not add checklists, type-of-change sections, commit lists, generated summaries,
+  badges, repeated acceptance criteria, or routine CI state.
+- Preserve human-authored text when updating. Reformat it only when explicitly asked.
+
+## Comments and review replies
+
+Default to silence.
+
+Post only when at least one is true:
+
+1. A human must make a decision or take an action.
+2. A review thread needs a non-obvious explanation that the diff cannot supply.
+3. A requested change is intentionally not made and the tradeoff must be recorded.
+
+Do not post progress updates, thanks, summaries of the PR body, test reports already in
+the body, “ready for review” messages, CI notifications, or preview/demo URLs. Chat
+already prints PR deployment links per [`pr-deployments.md`](pr-deployments.md).
+
+Use the narrowest location:
+
+- Reply in the existing review thread instead of posting a top-level comment.
+- Update the PR body instead of commenting when verification evidence changes.
+- Resolve an addressed thread silently when the fix is obvious from the diff.
+
+Write at most three short sentences:
+
+```markdown
+**Action needed:** <one decision/action and why it blocks>.
+
+<details>
+<summary>Evidence</summary>
+
+<only the detail needed to decide>
+
+</details>
+```
+
+For a non-obvious resolved thread:
+
+```markdown
+Fixed in `<sha>`: <what changed and why this approach>.
+```
+
+Never split one update across several comments. Never post speculative findings. Never
+quote long logs; link them or place the decisive excerpt in the expandable block.