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

package/references/user-guide.md

@@ -0,0 +1,171 @@
+# User guide
+
+Every IP says which user guide pages its feature adds, changes, or retires, so the guide
+grows with the app instead of being written once and left to rot. A page explains one
+feature in the words a user sees on screen: what it does, how to use it, and what it is
+meant for. Chat agents read these pages to answer "how do I…" questions about the app, so
+a page describes shipped behavior only. Grow plans the rows. Later stages read them; they
+do not invent rows.
+
+## Standardized spot
+
+| Key | Default | What it holds |
+| --- | --- | --- |
+| `User guide` | `docs/user-guide/` | One page per feature at `<area>/<feature>.md`, plus a `README.md` index |
+
+A repository whose layout differs, or that keeps no user guide, overrides the default with
+a `## User guide conventions` table in its agent instructions (AGENTS.md or CLAUDE.md):
+
+```markdown
+## User guide conventions
+
+| Key | Value |
+| --- | --- |
+| User guide | docs/help/ |
+```
+
+Resolve the key once: the table's value when the table names it, otherwise the default.
+
+### Opting out
+
+A repository with no end users (a library, a CLI, an internal tool) opts out with the
+value `none`, optionally followed by a reason:
+
+```markdown
+| User guide | none — command-line tool with no in-app users |
+```
+
+When the resolved value is `none`, the user guide is off: Grow writes
+`## User guide` as `None — user guide off`, and every other stage, check, and backfill
+skips the section without failing. Opting out is the only way to skip it; a missing
+directory at the resolved path is not an opt-out. When no guide exists at a resolved
+path, the first IP that needs a page creates the directory and its `README.md` index.
+
+## Page format
+
+One file per feature at `<User guide>/<area>/<feature>.md`. `<area>` and `<feature>` are
+kebab-case. The page opens with frontmatter, then three fixed sections in this order:
+
+```markdown
+---
+title: Set a due date on a todo
+area: todos
+audience: user
+platforms: [web, ios, android]
+questions:
+  - How do I set a due date on a todo?
+  - Can I change or remove a due date?
+screens:
+  - "app/(tabs)/index.tsx"
+added: todos-due-date
+---
+
+# Set a due date on a todo
+
+## What it does
+
+A due date shows when a todo should be done. Todos with a date show it under the title.
+
+## How to use it
+
+1. On **Todos**, tap a todo.
+2. Tap **Due date** and pick a day.
+3. Tap **Save**.
+
+To remove the date, open the todo, tap **Due date**, then tap **Clear**.
+
+## Intended use
+
+Use due dates for todos that must happen by a certain day. A due date does not send a
+reminder.
+```
+
+| Field | Rule |
+| --- | --- |
+| `title` | The task in the user's words, usually a verb phrase. Matches the `#` heading. |
+| `area` | The page's directory name. |
+| `audience` | Who can reach the feature: `user`, `admin`, or `staff`. A chat agent never describes a page to someone outside its audience. |
+| `platforms` | Where the feature ships: any of `web`, `ios`, `android`. |
+| `questions` | One to five "how do I…" or "can I…" questions a user would type that this page answers. Retrieval matches on these. |
+| `screens` | Optional. Repository-relative source paths of the screens the steps visit, as a block list of quoted strings, since paths such as `[id].tsx` break inline YAML lists. |
+| `added` | The slug of the IP that added the page, or `user-guide-backfill`. |
+| `updated` | Optional. The slug of the latest IP that changed the page. |
+
+Sections:
+
+- `## What it does`: one to three sentences on what the feature does for the user.
+- `## How to use it`: numbered steps a user can follow without guessing, naming on-screen
+  labels in **bold**. Follow-up variations go in short paragraphs after the steps.
+- `## Intended use`: what the feature is for, and what it is not for or does not do.
+  This is where a chat agent learns to say "that's not what this is for".
+- Optional `## Related`: links to other guide pages, by relative path.
+
+## Guide-entry bar
+
+Every page meets this bar:
+
+- It describes behavior that ships in this change or is already shipped. No roadmap, no
+  "coming soon".
+- It uses the words a user sees: screen titles, button labels, menu names. No code,
+  component names, routes, model or field names, test IDs, or internal jargon.
+- Each step names where the user is and what they press or enter, and the steps reach
+  the outcome `## What it does` promises.
+- It holds no personal or health information, real names, real accounts, secrets,
+  internal URLs, or staff-only procedures on a `user` page. Examples use obviously fake
+  data.
+- `audience` and `platforms` match who can actually reach the feature.
+
+"Use the feature as needed", steps that skip a screen, or text that restates the title
+does not meet the bar.
+
+## IP table
+
+Every IP has a `## User guide` section. It may be `None — <reason>`, but it may not be
+missing. `None — no user-visible change` is the usual entry for backend-only, refactor, or
+tooling work.
+
+| ID | Page | Change | Audience | Written in |
+| --- | --- | --- | --- | --- |
+| G1 | `docs/user-guide/todos/due-dates.md` | new | user | T2 |
+
+- `ID` is `G<n>`, unique within the IP.
+- `Page` is the repository-relative page path under the resolved `User guide`.
+- `Change` is `new`, `update`, or `retire`. `retire` deletes the page and its index entry
+  when the feature is removed.
+- `Audience` is the page's `audience` value.
+- `Written in` is the one task that delivers the behavior. That task writes the page.
+
+Every acceptance criterion that changes what a user sees or does maps to a row, or the IP
+gives the reason it does not (for example: covered by an existing page, which is named).
+
+## Index
+
+`<User guide>/README.md` lists every page in one table, grouped by area:
+
+```markdown
+| Area | Page | Audience | Title |
+| --- | --- | --- | --- |
+| todos | [due-dates.md](todos/due-dates.md) | user | Set a due date on a todo |
+```
+
+A stage that adds, renames, or retires a page updates this table in the same commit.
+
+## Stage duties
+
+| Stage | Duty |
+| --- | --- |
+| Grow | Plans the `## User guide` rows, or `None — <reason>`. |
+| Pick | Writes or edits each page whose row names the current task, in that task, at the row's path, and updates the index. |
+| Roast | Checks each page this task owns against the guide-entry bar and against the shipped screens: every label a step names exists, and the steps reach the outcome. Walks the steps in a browser when it can reach one. |
+| Brew | Confirms every row's page exists (or is gone, for `retire`), the index matches, and the repository's guide check passes. Sets `updated` on changed pages. |
+| Taste | After a fix that changes user-visible behavior, updates the affected pages in place before the push. |
+
+A page whose steps no longer match the shipped screens is a failing row, the same as a
+failing test.
+
+## Legacy rule
+
+An IP approved before this contract that lacks `## User guide` is read as `None —
+predates contract`. Stages warn once in their result and do not fail. A revised legacy IP
+gains the section in the Grow invocation that revises it. Features shipped before the
+contract are covered by the `backfill-user-guide` skill.

package/skills/1-grow/SKILL.md

@@ -0,0 +1,145 @@
+---
+name: 1-grow
+description: Research, clarify, shape, and approve an implementation-ready IP and task list. Use whenever the user asks to plan, shape, spec, or scope substantial work ("help me plan X", "how should we build Y") or to revise an existing plan; not for implementation or PR operations.
+---
+
+# Grow — shape
+
+Turn a request, ticket, or specification into approved artifacts a fresh Pick agent can
+execute without conversation history.
+
+Read the shared [`lifecycle contract`](../../references/lifecycle-contract.md),
+[`documentation contract`](../../references/documentation-contract.md),
+[`PR deployments`](../../references/pr-deployments.md),
+[`testing plan`](../../references/testing-plan.md),
+[`user guide`](../../references/user-guide.md), and
+[`grilling procedure`](references/grilling.md) before acting. Follow grilling for every
+human decision until the answer is executable.
+
+## Preconditions
+
+- A request/spec/ticket and repository are available.
+- This invocation owns shaping only. After `PASS`, Pick and Roast run the inner loop.
+
+## Inputs
+
+- Request/spec/ticket and linked context
+- Existing IP/task files, if revising
+- Repository instructions, code, tests, history, and available project skills
+- Execution state and prior result, when present
+
+## Procedure
+
+1. **Reconstruct.** Resolve the repository's existing IP/task conventions from its
+   instructions and nearby artifacts. If none exists, choose a colocated IP/task pair,
+   record the new convention, and avoid creating a shared mutable index. Read prior state
+   and verify it against repository reality. Resolve the testing spot: the e2e guide,
+   the regression-suite directory, and the smoke command, from the agent instructions'
+   `## Testing conventions` table or the testing-plan defaults. Read the e2e guide and
+   the suite files for the affected areas. When `Regression suites` is `none`, follow
+   the testing-plan opt-out: no regression cases. Resolve the `User guide` spot from the
+   `## User guide conventions` table or the user-guide default, and read the guide pages
+   for the affected areas unless the repository opts out.
+2. **Read architecture docs.** Load the repository's architecture, domain, and operator
+   docs for the affected area. Treat them as the current design. If docs are missing or
+   contradict the code, the IP must resolve that in this invocation.
+3. **Discover supporting skills.** Inspect available repository/project skills and load
+   those relevant to the affected domains, including documentation skills. Record
+   selected skills for downstream stages.
+4. **Research before asking.** Classify uncertainty:
+   - **Human decision:** product, architecture, security, data ownership, compatibility,
+     rollout, destructive change, or scope → grill and block until answered.
+   - **Discoverable fact:** repository convention, library behavior, ownership, tests →
+     investigate it.
+   - **Low-risk implementation detail:** strongly implied by convention → choose it and
+     record the assumption.
+5. **Grill.** Follow the grilling procedure. Work the current decision frontier in rounds
+   of selectable options with a recommended default, using the harness's structured
+   question tool when it has one. Get to the bottom of each reply: vague,
+   partial, or conflicting answers stay on the frontier. Wait for explicit
+   shared-understanding confirmation before writing. Every wait-for-human or done
+   message closes with PR deployment URLs when a PR has them.
+6. **Shape.** Prefer contracts/models/APIs before implementation detail where applicable.
+   Define scope, non-scope, architecture decisions, risks, human gates, rollout, and
+   dependencies.
+7. **Specify proof.** Make every acceptance criterion observable and pair it with a
+   verification method (test, build, runtime/API/database probe, UI exercise, artifact,
+   compatibility/regression case). When the input is a PRD from `prd`, carry
+   each success metric and guardrail into an acceptance criterion, grill each `TBD` as a
+   human decision, and do not re-ask product decisions the PRD already settled.
+   Pair each UI or cross-process criterion with a planned e2e spec at the path and layer
+   the e2e guide prescribes, or record why it needs none. Automate first: anything a
+   guide layer can drive and assert is an e2e row. Regression cases are usually `None`:
+   add one only for a change a developer or QA must check by hand (push notifications
+   and other hardware or OS behavior, a full cross-device flow, feel) that no existing
+   case covers, each meeting the testing-plan regression-step bar. Pair each criterion
+   that changes what a user sees or does with a `## User guide` row (new, update, or
+   retire) at the page path the user-guide contract prescribes, or record why it needs
+   none.
+8. **Write.** Produce the IP and a dependency-aware tracer-bullet task list. Each task
+   names files/seams, acceptance criteria, blockers, verification, docs to create or
+   update, and relevant supporting skills when discoverable. Docs updates follow the
+   documentation contract and are not deferred. The IP always has both testing-plan
+   sections, `## E2E tests` and `## Regression cases`, in the testing-plan table
+   formats; either may be `None — <reason>`, neither may be missing. Every E2E row
+   names the task that writes it. When no file exists at the resolved e2e guide path,
+   add a task that writes it there, ahead of every task that writes a planned spec.
+   The IP also always has the `## User guide` section in the user-guide table format,
+   or `None — <reason>`; it may not be missing. Every guide row names the task that
+   writes its page. A repository that opts out writes `None — user guide off`.
+9. **Approve.** Post the standalone approval brief from grilling: an orientation
+   paragraph on where the repository is and where this change takes it, optional
+   background on current state, the idea, the plan with its `E2E:`, `Regression:`, and
+   `User guide:` lines, then the unbounded Decisions table
+   pairing each settled human decision with the question that prompted it. Skip that
+   table when grilling settled none. The brief must be readable without the IP, the
+   ticket, or the grilling history. Set the repository's approved status only after human
+   confirmation. Update execution state and emit the stage result collapsed per the
+   lifecycle contract.
+
+## Supporting skills
+
+Follow the shared discovery procedure. Supporting skills may cover API/UI architecture,
+data access, schemas, prompts, deployment, testing, or safety. Names are repository-defined;
+none is universally required.
+
+## Evidence produced
+
+- Approved IP path and task-file path
+- Standalone approval brief: orientation paragraph, background when needed, idea, plan
+- Research findings and recorded assumptions (not chain-of-thought)
+- Decision log/human gates, listed in full with their prompting questions when any exist
+- Acceptance-criterion → verification mapping
+- `## E2E tests` and `## Regression cases` sections, each with rows or `None — <reason>`
+- `## User guide` section with rows or `None — <reason>`
+- Selected supporting skills
+- Docs files named on each task
+- Updated execution state and structured Grow result
+
+## Success conditions
+
+- IP/task artifacts are approved, implementation-ready, dependency-aware, and testable.
+- The IP has both testing-plan sections, and every E2E row names its writing task.
+- The IP has a `## User guide` section, and every guide row names its writing task.
+- A fresh Pick invocation can identify the next unblocked task, applicable criteria,
+  decisions, supporting skills, and risks from durable artifacts.
+- A reviewer with no prior context can approve or push back from the brief alone.
+- Emit `PASS` with `next: pick`.
+
+## Failure conditions
+
+Malformed or contradictory artifacts emit `FAIL` with exact defects,
+`next: grow`, and a focused Grow retry. Do not pass incomplete criteria
+to Pick.
+
+## Blocked conditions
+
+Unresolved human decisions, unavailable required evidence/access, or unsafe ambiguity emit
+`BLOCKED` with `next: null`, options, tradeoffs, and a recommended
+default when appropriate.
+
+## Recommended next stage
+
+- `PASS` → Pick
+- `FAIL` → Grow with defect evidence
+- `BLOCKED` → outer loop routes the named human/external gate

package/skills/1-grow/references/grilling.md

@@ -0,0 +1,243 @@
+# Grilling — interactive design interview
+
+Use this during Grow instead of dumping every unknown in one list.
+
+Goal: shared understanding with the user, then write. Do not write the IP, task list, or
+code until the user confirms the last round left no open questions.
+
+Adapted from [grilling](https://github.com/mattpocock/skills/blob/main/skills/productivity/grilling/SKILL.md).
+Do not copy tracker setup from that skill. Follow the consuming repository's artifact and
+tracking conventions.
+
+## Map a design tree, not a questionnaire
+
+Every request has a tree:
+
+- **Root:** the destination (what exists when this is done)
+- **Branches:** decisions that change the design
+- **Leaves:** facts (how the repo already works)
+
+Work in **rounds**. Each round asks only the current **frontier**: questions whose
+prerequisites are already settled. Deeper questions wait until their parent is decided.
+
+Example: do not ask "which tracker project?" before "do we track this externally?".
+Do not ask "which test double?" before "which public seam is the tracer bullet?".
+
+## Agent vs user
+
+| Kind | Who | How |
+| ---- | --- | ---- |
+| **Fact** | Agent | Look it up. Spawn explore/generalPurpose sub-agents. Read the repo. |
+| **Decision** | User | Ask. Never invent product, scope, or UX choices. |
+
+Do not ask the user anything a sub-agent can answer from the repo, docs, or git history.
+If a lookup fails, say what you searched and ask one targeted question.
+
+## Get to the bottom
+
+A reply is not done until Pick can execute it without guessing.
+
+After each user message:
+
+1. Record what was actually chosen, not the wording of the reply.
+2. If the answer is vague, partial, "sure", "yes", "whatever you think", or only restates
+   the question, stay on that decision. Ask the missing concrete: who, which API, which
+   UX, which data owner, which compatibility promise, what is out of scope.
+3. If two answers conflict, name the conflict and re-ask the parent before unlocking
+   children.
+4. If a recommendation had sub-choices and they accepted it without picking one, grill
+   the sub-choices.
+5. Unlock children only when the parent is executable.
+
+Do not treat a recommended answer as accepted unless the user confirmed it. Do not write
+from inferred agreement.
+
+## Round loop
+
+1. Research in parallel (sub-agents). Update the tree.
+2. Compute the frontier (undecided questions whose parents are settled).
+3. If the frontier is empty, state shared understanding in one short block and wait for
+   confirmation. Then write.
+4. If the frontier is not empty, ask **every frontier question in this round**, in one
+   message. Number them. Recommend an answer for each. Then **stop and wait**.
+
+Never ask only the first question when three are unblocked. Never proceed to the next
+round from inferred answers. The user may answer a subset; unanswered items stay on the
+frontier.
+
+### Ask with selectable options, not typed replies
+
+Every frontier round must be answerable by clicking, not by typing `Q1: xyz`.
+
+If the harness has a structured question tool that renders selectable choices
+(Cursor `AskQuestion`, Claude Code `AskUserQuestion`, or equivalent), use it for the whole
+round instead of listing the questions in prose:
+
+- One tool question per frontier decision; send the round in a single call.
+- Cap a structured-tool round at **four** questions. Claude Code `AskUserQuestion` rejects
+  calls with more than four, so the fifth frontier question waits for the next round
+  instead of being appended. Do not split one round across two calls.
+- Put the recommended option **first** and suffix its label with `(Recommended)`.
+- Give every question 2–4 concrete, mutually exclusive options. Option labels are the
+  actual choice ("Better Auth session cookie", "Existing JWT middleware"), never "Yes"/
+  "Option A"/"Your call". The harness always offers a free-text escape, so do not add an
+  "Other" option yourself.
+- Set multi-select only when the decision genuinely accepts several answers at once.
+- Keep the shaping context in the question prompt, one or two sentences, so the option
+  labels stay short.
+- Do not also repeat the same questions as numbered prose; the tool is the round.
+
+Only when no such tool exists, fall back to the markdown shape below.
+
+### Fallback message shape (no structured question tool)
+
+Lead with one line: what this round is deciding.
+
+Then for each frontier question:
+
+```markdown
+❓ **Q1** — **<short title>**: <context in one or two sentences>
+Options (if they help): A / B / C
+➡️ Recommend: <your answer, with one-line why>
+---
+```
+
+Rules for the body:
+
+- One decision per question.
+- Recommend a default every time. The user can override in a word.
+- Do not ask for facts you already looked up. Cite the finding in the question if it
+  informs the decision.
+- Cap the round at **five** questions. Park the rest as "later, after these".
+- End the message. Do not write files, do not start Pick, do not summarize the whole
+  plan yet. If this branch already has a PR with GitHub Deployments, the last visible
+  section is Demo (see the PR deployments procedure).
+
+Round caps, one decision per question: **four** with a structured question tool (the
+Claude Code `AskUserQuestion` limit), **five** for the markdown fallback. Anything past the
+cap stays on the frontier for the next round.
+
+### After the user replies
+
+1. Record answers on the tree.
+2. Get to the bottom of each answered item before treating it as settled.
+3. Unlock children. Drop questions the answers made irrelevant.
+4. Research any new facts those answers created.
+5. Next round, or confirm-and-write if the frontier is empty.
+
+## Confirm-and-write
+
+When the frontier is empty, send **only** this, then wait:
+
+```markdown
+Shared understanding:
+- Destination: <one sentence>
+- In: <comma-separated>
+- Out: <comma-separated>
+- Tracer: <collection / route / hook / CLI>
+- Open risks: <none | one line>
+
+Confirm and I will write the plan. Change any bullet if I have it wrong.
+```
+
+When the harness has a structured question tool, send that block and pair it with one
+selectable question ("Confirm this understanding?") offering `Write the plan
+(Recommended)` and `Change something` so confirmation is a click too.
+
+If a PR on this branch has GitHub Deployments, print those Demo URLs after this block,
+then wait. Do not write the IP until they confirm.
+
+## Approval brief
+
+After writing the IP and task list, post one **approval brief**. It is a standalone
+document: a reviewer who never saw the grilling rounds, the ticket, or the repository
+can read it top to bottom and approve or push back without opening another file.
+
+Write it in this order. Orientation first, then the proposal, then the plan, then the
+decisions that shaped them, then the pointers.
+
+```markdown
+# <Change title>
+
+<Orientation paragraph. Three to five sentences covering where the repository is today,
+where this change takes it, and why that is worth doing now. Name the user or operator
+who feels the difference. No file paths, no task IDs, no lifecycle jargon.>
+
+## Background
+
+<Current state a reviewer needs before the proposal makes sense: how the affected area
+works today, the constraint or gap driving the change, and any research finding that
+overturned an obvious approach. Cite the code, docs, or history you read. Omit this
+whole section when the orientation paragraph already carries the reader.>
+
+## The idea
+
+<The shape of the solution in a short paragraph or a few bullets: the contract, model,
+API, or seam that changes, and what is observably different afterwards. State the
+alternative you rejected and why in one line when a reviewer would otherwise ask.>
+
+## The plan
+
+| # | Task | Lands in | Proves it |
+| --- | --- | --- | --- |
+| T1 | <task title> | <files or seam> | <test, probe, artifact, or UI exercise> |
+
+Tracer: <public seam the first task cuts through>
+E2E: <planned specs and layers, e.g. "2 specs (browser, http)"; or "None — reason">
+Regression: <provisional case IDs and destination suite; or "None — reason">
+User guide: <guide pages added, updated, or retired; or "None — reason">
+Order: <frontier task IDs; blocked task IDs and what unblocks them>
+Out of scope: <short tags>
+Open risks: <none, or one line each>
+
+## Decisions
+
+| ID | Question asked | Answer | What it changes |
+| --- | --- | --- | --- |
+| Q1 | <the question as it was asked> | <the settled choice, not a paraphrase of the reply> | <the design consequence a reviewer should check> |
+
+## Artifacts
+
+- Plan: <path>
+- Tasks: <path>
+- Supporting skills: <names, or none found>
+
+Next: approve → Pick
+```
+
+Rules for the brief:
+
+- The first paragraph is the whole change in prose. A reviewer who reads only that
+  paragraph should know the destination and the reason.
+- Background is optional; everything else is required. Drop Background when the change
+  is self-explanatory rather than padding it.
+- The idea and the plan come **before** the Decisions table. Decisions justify the plan;
+  they are not the pitch.
+- The Decisions table has **no row limit**. List every settled human decision with the
+  question that prompted it, so the reviewer can see what was asked and what was chosen.
+  Skip the table entirely when grilling settled none; do not mention decisions, an empty
+  table, or "none".
+- Every acceptance criterion in the plan table names how it is proved. "Manual check" is
+  not a verification method.
+- The `E2E:`, `Regression:`, and `User guide:` lines summarize the IP's `## E2E tests`,
+  `## Regression cases`, and `## User guide` sections. They stay lines under the plan
+  table, not new headings.
+- Do not restate the IP. The brief orients and points; the IP holds the detail.
+- If a PR has GitHub Deployments, print those Demo URLs after the brief.
+
+## Anti-patterns
+
+- One giant question dump at the start
+- Prose-only rounds that force typed replies like `Q1: xyz` when the harness can render
+  selectable options
+- Selectable options that are not real choices ("Yes"/"No"/"Your call") or that duplicate
+  the harness's built-in free-text escape
+- Asking repository facts ("where is this route defined?")
+- Acting on a recommended answer the user has not accepted
+- Accepting a vague "yes" as a finished decision
+- Recapping the entire interview at the end of every round
+- Writing the IP in the same turn as unanswered questions
+- Hiding decisions in a one-line `Q#=choice` summary
+- An approval brief that opens with file paths or task IDs instead of the destination
+- A Decisions table that lists choices without the questions that prompted them
+- A brief a reviewer cannot act on without opening the IP