@terreno/agent-plugin 0.0.0-stage → 57.22.0

package/skills/mongoose-schema-safety/SKILL.md

@@ -0,0 +1,164 @@
+---
+name: mongoose-schema-safety
+description: >-
+  Invoke when making any Mongoose schema change: adding/removing/renaming
+  fields, creating a new model, adding indexes, or writing a backfill migration.
+  Provides the five-type pattern, risk matrix, type file checklist, and rollout
+  safety steps for Terreno backends.
+---
+# Mongoose Schema Safety — Terreno
+
+Typical Terreno apps keep models under `backend/src/models/` and types under `backend/src/types/models/`. The Terreno monorepo also uses `example-backend/` and `@terreno/ai` — adjust paths below to match your repo.
+
+## Documentation
+
+1. Read the app's model/API docs before changing schemas, types, or indexes.
+2. Implement against that design.
+3. Update those docs in the same slice. Schema field `description`s are public docs via OpenAPI.
+4. Ship without matching docs is a failed slice.
+
+## Where Schemas and Types Live
+
+| Package | Schemas | Types |
+|---------|---------|-------|
+| `@terreno/api` (built-in models like `User`, `ConsentForm`) | `api/src/models/*.ts` | `api/src/types/*.ts` (or co-located in the model file via `mongoose.Schema<Doc, Model, Methods>` generics) |
+| `example-backend` (`User`, `Todo`, `Configuration`) | `example-backend/src/models/*.ts` | `example-backend/src/types/models/*.ts` (`userTypes.ts`, `todoTypes.ts`, …) |
+| `@terreno/ai` (`AIRequest`, `GptHistory`) | `ai/src/models/*.ts` | `ai/src/types/index.ts` |
+
+Every field in every schema **must** have a `description` (see the API rule `01-model-field-descriptions.md`). Descriptions flow through to the OpenAPI spec via `mongoose-to-swagger`.
+
+## The Five-Type Pattern
+
+Every model has manually-maintained TypeScript types. **Types are NOT auto-generated** — every schema change must include a matching type update in the same commit/PR.
+
+```typescript
+import type {DefaultDoc, DefaultModel, DefaultStatics} from "@terreno/api";
+
+// 1. Instance methods (on the document)
+export type YourModelMethods = {
+  customMethod: (this: YourModelDocument, param: string) => Promise<void>;
+};
+
+// 2. Static methods (on the model class) — extend DefaultStatics for findExactlyOne / findOneOrNone
+export type YourModelStatics = DefaultStatics<YourModelDocument> & {
+  customStatic: (this: YourModelModel, param: string) => Promise<YourModelDocument>;
+};
+
+// 3. Model type combining document + statics
+export type YourModelModel = DefaultModel<YourModelDocument> & YourModelStatics;
+
+// 4. Schema type
+export type YourModelSchema = mongoose.Schema<YourModelDocument, YourModelModel, YourModelMethods>;
+
+// 5. Document type (the shape of a single record)
+export type YourModelDocument = DefaultDoc & YourModelMethods & {
+  fieldName: string;
+  optionalField?: number;
+  enumField: "value1" | "value2";
+};
+```
+
+Follow existing type files in `example-backend/src/types/models/` and `ai/src/types/index.ts` for naming and structure.
+
+## Statics & Methods — Direct Assignment
+
+Define statics and methods by direct assignment on the schema — not via `.method()` / `.static()` / `.add()`:
+
+```typescript
+schema.methods = {
+  getDisplayName(this: YourModelDocument): string {
+    return this.name;
+  },
+};
+schema.statics = {
+  async findByEmail(this: YourModelModel, email: string) {
+    return this.findOneOrNone({email});
+  },
+};
+```
+
+## Critical Mongoose Rules
+
+- **Never use `Model.findOne`** — use `Model.findExactlyOne` (throws on 0 or many) or `Model.findOneOrNone` (throws on many). These come from the `findExactlyOne` / `findOneOrNone` plugins in `@terreno/api`.
+- Apply the standard plugins (`createdUpdatedPlugin`, `isDeletedPlugin`, `findOneOrNone`, `findExactlyOne`) on every new model. Most existing models go through `addDefaultPlugins`.
+- `checkModelsStrict()` runs at non-prod startup (`server.ts`) and validates schema consistency — keep it passing.
+
+## Migration files
+
+Schema and data changes that must run once per environment belong in
+`migrations/<YYYYMMDDHHmmss>-<slug>.ts` with required `up` and optional `down`.
+Generate a draft with `terreno-migrate generate --dir ./migrations --models ./src/models.ts`,
+then `terreno-migrate up --dir ./migrations --dry` before wet apply.
+See [Run MongoDB migrations](../../../../docs/how-to/run-mongodb-migrations.md).
+
+Admin **Scripts** (`ScriptRunner` + `BackgroundTask`) stay for one-off operator
+tools. Do not use Scripts as the primary path for versioned schema backfills.
+
+## Schema Change Risk Matrix
+
+| Change Type | Risk Level | Required Mitigation |
+|-------------|-----------|---------------------|
+| Add optional field | Low | Safe to ship directly (still requires `description`) |
+| Add required field | High | Must provide a default value, OR write a versioned migration (`terreno-migrate generate` / `up`) with a backfill before wet apply |
+| Remove field | Medium | Soft-remove first (mark optional, stop writing); hard-remove in next PR after deploys settle |
+| Rename field | High | Three-step: add new → backfill migration → remove old (separate PRs) |
+| Change field type | Critical | Treat as rename: new field + versioned migration + remove old |
+| Add index | Medium | Prefer `terreno-migrate generate` for the index; build can slow writes on large collections — coordinate with ops |
+| Remove index | Low | Safe to ship directly |
+| Add unique index | High | Dedup in a versioned migration first; otherwise the index build fails on existing duplicates |
+
+## One-off admin scripts
+
+Ad-hoc operator tools (counts, reseeds, support fixes) still live as admin
+Scripts using `ScriptRunner` and `BackgroundTask`:
+
+```typescript
+import type {ScriptContext, ScriptResult, ScriptRunner} from "@terreno/api";
+
+export const run: ScriptRunner = async (wetRun, ctx) => {
+  const results: string[] = [];
+  if (wetRun) {
+    // commit changes
+  }
+  return {success: true, results};
+};
+```
+
+Always run with `wetRun = false` first. Use `ctx.checkCancellation()`,
+`ctx.addLog()`, and `ctx.updateProgress()` for long-running tasks. Do not put
+repeatable schema backfills here — use `migrations/` and `terreno-migrate`.
+
+## Cross-Package Ripple
+
+A schema change in one place often ripples:
+
+- **API surface affected?** Regenerate the SDK with `cd example-frontend && bun run sdk` (or invoke the `generate-sdk` skill). The OpenAPI spec is derived from the schema, so the frontend hooks will go stale otherwise.
+- **`modelRouter` config?** If you added/removed a field, update `queryFields`, `populatePaths`, and `responseHandler` for any router that touches the model.
+- **Admin panel?** If the model is registered in `AdminApp`, update `listFields` so the table reflects the new shape.
+- **Populated refs?** If another model references this one via `ObjectId` + `ref`, and the referenced document shape changed, the consumer's populated type may need updating.
+
+## Post-Change Checklist
+
+- [ ] All new fields have a `description` (flows to OpenAPI)
+- [ ] Type file updated in the same commit/PR — field names, optionality, enum values, array types, refs, statics/methods all match the schema
+- [ ] For a new model: all five types (`Document`, `Methods`, `Statics`, `Model`, `Schema`) created
+- [ ] Statics/methods assigned directly on schema (`schema.statics = {...}`, `schema.methods = {...}`) — not `.static()` / `.method()`
+- [ ] Other model type files checked — any model that populates this one updated if its shape changed
+- [ ] Versioned migration written (`migrations/` + `terreno-migrate`) and dry-run verified for any backfill; unique-index dedup runs before the index is added
+- [ ] `modelRouter` config updated (`queryFields`, `populatePaths`, `responseHandler`) if needed
+- [ ] `AdminApp` `listFields` updated if the model is in the admin panel
+- [ ] `bun run sdk` run from `example-frontend/` if the API response shape changed
+- [ ] Docs updated when the public shape or operator steps changed
+- [ ] Test covers old-format document behavior (missing new field) if the change rolls out before a backfill
+- [ ] Unique index: dedup migration written and run before the index is added
+- [ ] `checkModelsStrict()` still passes (it runs on non-prod startup)
+- [ ] No `Model.findOne` introduced — use `findExactlyOne` / `findOneOrNone`
+
+## Common Pitfalls
+
+- Adding a required field without a default — first deploy fails for documents that pre-date the field
+- Skipping the type file update — TS happily compiles older callers but new ones break at runtime
+- Adding a `unique` index without dedup — index build fails on collections with existing duplicates
+- Renaming a field in one PR — frontend gets old field, backend writes new field, neither side is happy
+- Forgetting to regenerate the SDK after a shape change — frontend types drift from reality
+- Using `.method()` / `.static()` API — terreno's convention is direct assignment, and mixing styles makes types hard to maintain

package/skills/pick-roast-loop/SKILL.md

@@ -0,0 +1,152 @@
+---
+name: pick-roast-loop
+description: Drive an approved plan through every Pick–Roast cycle until all tasks pass or a genuine human decision is required. Continue through recoverable engineering failures, keep a complete run ledger, and when input is required present the overall state, completed work and evidence, options, recommendation, and exact question. Not for Grow, Brew, Taste, or CI monitoring.
+---
+
+# Pick–Roast loop (outer recovery driver)
+
+Drive an **approved** task list through implementation and independent proof. This is
+an outer recovery loop around Pick's inner loop: normally invoke Pick once and let it
+continue task by task; reinvoke only when Pick or Roast had to exit with actionable
+engineering work remaining.
+
+Read the shared [`lifecycle contract`](../../references/lifecycle-contract.md),
+[`pick-roast inner loop`](../../references/pick-roast-loop.md),
+[`PR deployments`](../../references/pr-deployments.md), and
+[`subagent briefing`](../../references/subagent-briefing.md). The ledger must conform
+to [`execution-state.schema.json`](../../references/execution-state.schema.json).
+
+## Scope
+
+- Included: Pick, each task's Roast, focused retries, execution-state persistence, and
+  one accumulated report.
+- Excluded: Grow/plan approval, Brew/PR submission, Taste/CI/review monitoring, release,
+  deployment, and unrelated cleanup.
+- Never invoke Brew or Taste. Successful completion emits `next: brew`.
+
+## Preconditions
+
+- A human-approved IP/task contract exists.
+- The current branch, task list, and execution-state location are resolvable.
+- At least one task is incomplete or has a non-terminal Roast result.
+
+If the plan is missing or unapproved, stop at a human gate. Do not silently run Grow or
+invent acceptance criteria.
+
+## Run ledger
+
+Create one compact `ledger` array in execution state before invoking a stage. Append one
+schema-valid entry after every Pick/Roast result:
+
+- task id and short outcome
+- attempt number and head SHA
+- files changed
+- Roast verdict and criterion failures
+- focused fix/hypothesis used for each retry
+- checks, artifacts, and docs evidence
+- blockers, decisions, and residual risks
+
+Do not stream a recap after each cycle. Preserve stage evidence, but defer the
+human-facing report until completion or a genuine human gate.
+
+## Drive
+
+1. **Reconstruct once.** Read the approved task graph and execution state. Identify the
+   next incomplete or failed task. Verify branch/head and prior attempts.
+2. **Invoke the named stage.** After reconstructing, invoke `next.stage` only when it is pick or roast.
+   Use Pick for implementation/rework, or Roast when Pick completed the task but
+   exited before proof. Pass the current task, exact prior evidence, and the same
+   task-scoped briefing. Pick owns normal task → Roast → next-task progression.
+   - If `next.stage` is `brew`, or every in-scope task already Roast-passed, finish
+     with `next: brew`. Do not invoke Brew.
+   - If `next.stage` is `taste` or `grow`, stop with `FAIL`. This loop does not run
+     those stages.
+   - If `next.stage` is unset, default to Pick.
+3. **Consume the result.** Update the ledger, then classify:
+   - `PASS` with all tasks Roast-passed → finish with `next: brew`.
+   - `FAIL` with `next: pick` or `next: roast` and a concrete engineering action →
+     reinvoke that stage in a fresh context with prior evidence and the same
+     task-scoped briefing.
+   - `BLOCKED` with a `block` entry whose `kind` is `human`, or `next.human: true` →
+     present the human gate.
+   - `BLOCKED` for environment/access/external state → attempt safe autonomous
+     remediation or a bounded retry when a new hypothesis exists. Never relabel it
+     `human` merely to stop.
+   - A terminal non-human blocker with no safe remediation → stop and report it as
+     blocked; do not ask the human a decision question unless they can actually decide it.
+4. **Bound retries by evidence.** A retry must add a new hypothesis, changed setup, or
+   new evidence. Never repeat the same failed command/approach. After two focused
+   failures for the same task and stage with no new hypothesis, classify the underlying
+   decision or capability honestly instead of looping.
+5. **Continue silently.** Repeat steps 2–4, invoking only the stage named by durable
+   state and passing the same task-scoped briefing every time, until every task passes
+   Roast or a stop condition below is reached.
+
+## Genuine human gate
+
+Ask for input only for:
+
+- unresolved product semantics or acceptance criteria
+- architecture, security, privacy, data ownership, or public compatibility choices
+- destructive/irreversible operations or policy-required approval
+- material scope expansion with multiple valid outcomes
+- credentials/permissions the human can provide and no authorized alternative exists
+
+Before the question, provide this overview in plain language:
+
+1. **Goal and state:** plan name, current task, completed/total tasks, current head.
+2. **What happened:** work completed, Roast results, retries, and decisive evidence.
+3. **Why input is needed:** the exact decision and why engineering evidence cannot
+   choose it.
+4. **Options:** two to four concrete choices with impact and risk.
+5. **Recommendation:** one default and its rationale.
+
+End with **one exact question** the human can answer in one message. Then close with
+PR deployment URLs when a PR has them. Do not expose chain-of-thought, raw transcripts,
+or unexplained stage YAML.
+
+## Completion report
+
+When all tasks Roast-pass, lead with:
+
+`PASS — <passed>/<total> tasks independently verified. Next: Brew.`
+
+Then report:
+
+- `Completed`: every task and shipped behavior
+- `Roast history`: failures found and how each was resolved
+- `Verification`: checks, runtime evidence, artifacts, and docs
+- `Changes`: commits/head and important files
+- `Residual risk`: explicit remaining risk or `None identified`
+- `Next`: `4-brew`
+
+When stopped, use the same report plus `Blocker`. Include everything from the ledger
+once; do not duplicate per-cycle narration. Close wait-for-human and done reports with
+PR deployment URLs when a PR has them.
+
+## Stop conditions
+
+- `PASS`: every in-scope task has Roast `PASS` on the recorded head.
+- `BLOCKED` (human): a genuine human gate above.
+- `BLOCKED` (non-human): retries are exhausted and no safe autonomous action exists.
+- `FAIL`: state is inconsistent/corrupt or the named next stage cannot be invoked.
+
+Ordinary test failures, lint failures, implementation defects, and Roast findings are
+not terminal while a concrete engineering action remains.
+
+## Emit
+
+After the human-facing report, include one collapsed stage-result payload. Since outer
+loops are not stages, set `stage` to the last stage invoked (`pick` or `roast`).
+
+```yaml
+v: 2
+stage: pick
+status: PASS
+next: brew
+action: Submit the fully Roast-verified plan with Brew.
+```
+
+For a human gate, use `status: BLOCKED`, `next: null`, and an `ask` entry containing
+the exact question, recommendation, and options. For a non-human terminal blocker, use
+a `block` array entry with `kind: environment`, `access`, or `external`, and omit `ask`.

package/skills/planning-loop/SKILL.md

@@ -0,0 +1,161 @@
+---
+name: planning-loop
+description: Drive the planning plugin from the current task list, optionally restricting which stages run (Grow, Pick, Roast, Brew, Taste). Not a sixth stage — an outer loop that invokes existing stage skills. Use when asked to run the planning loop, walk the task list, or restrict work to selected phases.
+---
+
+# Planning loop (outer driver)
+
+Not a stage. The five stages stay Grow, Pick, Roast, Brew, Taste. This skill
+walks the **current** task list and invokes those stage skills in order.
+
+Pick owns the inner **pick → roast → next-task → brew** loop (see
+`plugins/terreno-planning/references/pick-roast-loop.md`). This outer loop
+must **not** Pick then Roast per task as a second driver. If `pick` is in
+the requested phases, invoke Pick **once**; Pick roasts each task and
+continues. If `roast` is requested **with** `pick`, do not start a second
+Roast driver.
+
+## When to use
+
+- The user asks to run the planning loop, walk the task list, or keep going
+  until the list is empty.
+- The user names phases (`grow`, `pick`, `roast`, `brew`, `taste`) and wants
+  only those stages.
+- Default when the user says "planning loop" with no phases:
+  **Grow, then Pick** (Pick includes Roast for each task, then Brew).
+
+## Parse phases
+
+Read the user message for a phase list, in this order:
+
+1. `phases=` (comma-separated, case-insensitive)
+2. A bare comma-separated list of allowed tokens (`grow,roast` or
+   `grow, pick, brew`)
+3. Tokens after `/planning-loop` or the skill name
+
+Allowed tokens: `grow`, `pick`, `roast`, `brew`, `taste`.
+
+Ignore unknown tokens. Deduplicate while preserving order.
+
+If nothing remains after filtering, use `grow,pick,roast`.
+That default still means Grow then Pick — Roast is owned by Pick, not a
+second outer-loop pass.
+
+## Read first
+
+Read the shared [`lifecycle contract`](../../references/lifecycle-contract.md),
+[`loop engineering`](../../references/loop-engineering.md),
+[`pick-roast inner loop`](../../references/pick-roast-loop.md), and
+[`PR deployments`](../../references/pr-deployments.md). When Brew or Taste is
+selected, also read [`product CI`](../../references/product-ci.md). Then:
+
+1. `plugins/README.md` — Hosts and stage skills
+2. Each selected stage skill under `plugins/terreno-planning/skills/`
+
+## Drive the selected phases
+
+Stay on the current branch. Do not start a nested PR. One logical commit
+per completed unit of work.
+
+### Grow (`grow`)
+
+If `grow` is selected and the task list is empty or missing, invoke
+`1-grow` once (shape / confirm the list). Skip Grow when a current
+list already exists unless the user asked to reshape.
+
+If Grow emits `FAIL`, stop. Do not invent tasks.
+
+### Pick (`pick`) — includes Roast
+
+If `pick` is selected, invoke `2-pick` **once**. Pick:
+
+1. Takes the next unchecked task
+2. Implements it
+3. Invokes Roast for that task
+4. On Roast `PASS`, continues to the next unchecked task
+5. After the last task, emits `next: brew` (unless `brew` was excluded — then
+   stop after the last Roast `PASS` and tell the user Brew is the next
+   human/agent step)
+
+Do not wrap Pick in an outer per-task loop. Do not invoke Roast yourself
+when Pick is in the phase list.
+
+If Pick emits `FAIL`, stop.
+
+Honor Pick's `next` / `wait` when it yields.
+
+### Roast (`roast`) without Pick
+
+If `roast` is selected and `pick` is **not**, invoke `3-roast`
+once for the current in-progress task (prove / tests). Do not start Pick's
+inner loop.
+
+If Roast emits `FAIL`, stop.
+
+### Skip Roast when Pick is selected
+
+If both `pick` and `roast` appear in `phases=`, treat Roast as already
+owned by Pick. Do not invoke `3-roast` as a second driver.
+
+### Brew (`brew`)
+
+If `brew` is selected, invoke `4-brew` after the selected pre-submit stages.
+Pick emits `next: brew` at the end of its inner loop; it does not invoke Brew itself.
+
+If Brew emits `FAIL`, **do not stop the outer loop**. Read Brew's `next`
+field and continue with that stage in the same invocation:
+
+- `next: pick` — invoke `2-pick` (which will Roast again as part of
+  its inner loop)
+- `next: roast` — invoke `3-roast` (only when Pick is not driving)
+- `next: brew` — invoke `4-brew` again for a submission-only retry; honor
+  `wait` when provided
+
+Keep following Brew `FAIL` → `next` until Brew emits `PASS` or `FAIL` with
+no recoverable `next`, or a non-Brew stage emits `FAIL`. Then stop.
+
+If Brew emits `PASS`, continue to Taste only when `taste` is selected.
+
+### Taste (`taste`)
+
+If `taste` is selected, invoke `5-taste` after Brew `PASS` (or
+after the last selected earlier stage if Brew was omitted). Taste reacts
+to review on the current PR; it does not walk the task list.
+
+If Taste emits `PASS`, stop. If Taste emits `FAIL` with a new evidence-based
+hypothesis, invoke fresh Taste; a `FAIL` without one is `BLOCKED`. On `BLOCKED`, stop
+and escalate per [`push ownership`](../../references/push-ownership.md#escalation).
+Never stop on a red PR without that escalation. If Taste emits `PENDING`, honor
+`wait` / `next`. During that bound, prefer the product-CI provider's native watch hook
+or a harness event subscription; use a timer only when no hook applies. Invoke fresh
+Taste as soon as the hook returns. Taste already waited in-process for CI on the
+previous invocation; `PENDING` means that wait timed out or a second push landed.
+
+## Isolation and hosts
+
+Same rules as the stage skills: one git checkout, no nested worktrees for
+the loop itself, no extra `gh` auth, no `git config`. Cursor, Claude,
+Codex, and Gemini all invoke this the same way — only the skill path
+differs (see Hosts in `plugins/README.md`).
+
+## Emit (required)
+
+After the last stage you ran, emit **only** a YAML object in a collapsed
+Markdown `<details>` block. Use `status: PASS` when every selected stage
+that ran emitted `PASS` (or Brew `FAIL` that you recovered by following
+`next` through to a later `PASS`). Use `FAIL` if any stage stopped the
+loop. Use `PENDING` if a stage asked you to wait.
+
+```yaml
+v: 2
+stage: pick
+status: PASS
+next: brew
+action: Planning loop finished selected phases.
+```
+
+Set `stage` to the last stage skill you invoked (`grow` | `pick` |
+`roast` | `brew` | `taste`). Required keys are `v`, `stage`, `status`,
+`next`, and `action`. Omit `wait` unless the last stage asked you to
+wait (`wait` is a positive integer). After that YAML, close with PR
+deployment URLs when the current PR has them.

package/skills/prd/SKILL.md

@@ -0,0 +1,138 @@
+---
+name: prd
+description: Interview the app owner and write a full product requirements document (problem, why now, solution, user stories, measurable success metrics, constraints, rollout, out of scope), then publish it where the repository tracks work. Sized for one owner and one or two developers. Runs ahead of Grow; explicit invocation only.
+disable-model-invocation: true
+---
+
+# PRD — seed
+
+Interview the person who owns the app, then write a full product PRD that Grow can shape
+into an implementation plan without re-asking product questions.
+
+Assume a small team: one owner who is also PM, designer, and final approver, plus one or
+two developers. Skip ceremony a team that size does not need (stakeholder sign-off, RACI,
+persona decks). Keep what it does need: a clear problem, measurable success, and the
+constraints a developer would otherwise discover mid-build.
+
+Adapted from [to-spec](https://github.com/mattpocock/skills/blob/main/skills/engineering/to-spec/SKILL.md)
+(MIT, © Matt Pocock), keeping only the product half. The interview and the success-metric
+rule are adapted from the [awesome-copilot prd skill](https://github.com/github/awesome-copilot/blob/main/skills/prd/SKILL.md)
+(MIT). Implementation decisions, test seams, and testing decisions belong to Grow.
+
+## Process
+
+1. **Gather before asking.** Read the conversation, any linked prototype, demo, mock, or
+   ticket, and enough of the repository to know how the product behaves today in the
+   affected area. Use the project's domain vocabulary. Never ask what you can look up.
+   If a prototype exists, it is the source for the solution; link it instead of
+   re-describing it.
+2. **Interview.** Follow Grow's [grilling procedure](../1-grow/references/grilling.md)
+   for the mechanics: frontier rounds, selectable options with a recommended default, the
+   structured question tool when the harness has one, get to the bottom of every vague
+   answer, and confirm shared understanding before writing. Use the product tree below
+   instead of Grow's design tree. Ask at least one round even when the conversation looks
+   complete; confirm what you inferred instead of assuming it.
+3. **Write the PRD** with the template below, from the user's perspective. No file paths,
+   modules, schemas, or code.
+4. **Apply the success-metric rule.** Every success metric and guardrail is concrete and
+   measurable: a quantity, a threshold, and how it is measured. Replace adjectives
+   ("fast", "easy", "intuitive", "better") with numbers. If the owner cannot set a target
+   after you pressed once, write `TBD` and name what decides it. Never invent a number.
+5. **Publish.** Follow the repository's existing tracking convention (issue tracker,
+   planning directory, or spec folder). If none exists, open an issue in the repository's
+   tracker. Do not apply readiness labels; Grow owns approval.
+6. **Hand off.** Return the PRD link and any `TBD` items. Recommend Grow with the PRD as
+   its input.
+
+## Product tree
+
+Work the frontier in this order of parents. Children unlock when the parent is
+executable.
+
+| Branch | Settle before writing |
+| --- | --- |
+| **Problem** | Who hits it, how often, what they do today instead, and what it costs them |
+| **Why now** | What makes this worth doing before the rest of the backlog, and what it pushes back |
+| **Solution** | The user-visible behavior and main flows; which prototype, if any, is the reference |
+| **Success** | Metrics with targets, how and when they are measured, and guardrails that would make you turn it off |
+| **Constraints** | Data, privacy, safety, performance, cost (including AI model cost), platforms, and the people who must learn the change |
+| **Rollout** | Behind a flag or experiment, or straight to everyone; who to tell or train; whether a developer must review it or agent review is enough |
+| **Scope** | What is explicitly out, and what is deferred to a later version |
+
+Push hardest on **Success**. "Users like it" is not done. Ask what number would make the
+owner call it a win, what number would make them roll it back, and where the number comes
+from.
+
+<prd-template>
+
+## Problem Statement
+
+The problem the user faces, from the user's perspective: who, how often, today's
+workaround, and its cost.
+
+## Why Now
+
+Why this beats the rest of the backlog, and what it displaces.
+
+## Solution
+
+The solution, from the user's perspective: the behavior and the main flows. Link the
+reference prototype or demo when one exists.
+
+## User Stories
+
+A LONG, numbered list of user stories. Each story uses the format:
+
+1. As an <actor>, I want a <feature>, so that <benefit>
+
+<user-story-example>
+1. As a mobile bank customer, I want to see balance on my accounts, so that I can make better informed decisions about my spending
+</user-story-example>
+
+The list is extensive and covers every aspect of the feature, including edge cases and
+error states.
+
+## Success Metrics
+
+A numbered list. Each metric states what is measured, the target, how it is measured, and
+when it is evaluated.
+
+<success-metric-example>
+1. Search returns results within 200 ms at p95 for a 10k-record dataset, measured by the load test before launch.
+2. At least 85% of new users finish onboarding within 3 minutes, measured by the analytics funnel 30 days after launch.
+3. Weekly active editors: TBD — owner sets the target after two weeks of baseline data.
+</success-metric-example>
+
+**Guardrails.** Measurable thresholds that mean turn it off or roll it back.
+
+<guardrail-example>
+1. Support tickets about checkout rise above 5 per week, measured in the help desk.
+</guardrail-example>
+
+## Constraints
+
+Limits the solution must respect: data and privacy, safety, performance, cost, platforms,
+and the change load on the people who use it.
+
+## Rollout
+
+Flag or experiment versus full launch, who must be told or trained, and the review level:
+developer review required, or low-risk enough for agent review.
+
+## Out of Scope
+
+What this PRD does not cover, and what is deferred to a later version.
+
+</prd-template>
+
+## Success conditions
+
+- The owner confirmed shared understanding before the PRD was written.
+- The PRD has every template section and no implementation detail.
+- Every success metric and guardrail is measurable or `TBD` with its decider.
+- The PRD is published and its link is returned.
+
+## Blocked conditions
+
+- The owner cannot state the problem or who has it. Stop after that round; do not write a
+  PRD around a guessed problem.