@stacksjs/defaults 0.72.103 → 0.73.0

package/ai/skills/stacks-domain-modeling/FORMATS.md

@@ -0,0 +1,123 @@
+# CONTEXT.md and ADR formats
+
+## CONTEXT.md
+
+```md
+# {Context name}
+
+{One or two sentences on what this context is and why it exists.}
+
+## Language
+
+**Order**:
+A customer's committed request for goods, priced and payable.
+_Avoid_: Purchase, transaction
+
+**Invoice**:
+A request for payment sent to a customer after delivery.
+_Avoid_: Bill, payment request
+
+**Customer**:
+A person or organization that places orders.
+_Avoid_: Client, buyer, account
+```
+
+Rules:
+
+- **Be opinionated.** When several words exist for one concept, pick the best and
+  list the others under `_Avoid_`.
+- **Keep definitions tight.** One or two sentences. Define what it *is*, not what
+  it does.
+- **Only terms specific to this project.** General programming concepts
+  (timeouts, error types, utility patterns) do not belong even if the project
+  uses them constantly. Before adding a term, ask whether it is unique to this
+  context.
+- **Match the code.** A term here should be the name of the model, the event and
+  the route that carry it. Where it is not, either rename the code or fix the
+  entry, and say which.
+- **Group under subheadings** when natural clusters emerge. A flat list is fine
+  when every term belongs to one cohesive area.
+
+## Single versus multi-context
+
+**Single context**, which is almost every repo: one `CONTEXT.md` at the root.
+
+**Multiple contexts**: a `CONTEXT-MAP.md` at the root lists them, where they
+live, and how they relate:
+
+```md
+# Context map
+
+## Contexts
+
+- [Ordering](./app/Ordering/CONTEXT.md): receives and tracks customer orders
+- [Billing](./app/Billing/CONTEXT.md): generates invoices and processes payments
+- [Fulfillment](./app/Fulfillment/CONTEXT.md): manages picking and shipping
+
+## Relationships
+
+- **Ordering to Fulfillment**: Ordering emits `order:placed`, Fulfillment
+  consumes it to start picking
+- **Fulfillment to Billing**: Fulfillment emits `shipment:dispatched`, Billing
+  consumes it to generate invoices
+- **Ordering and Billing**: share the `CustomerId` and `Money` types
+```
+
+Infer which structure applies: if `CONTEXT-MAP.md` exists, read it to find the
+contexts. If only a root `CONTEXT.md` exists, single context. If neither exists,
+create the root file lazily when the first term is resolved.
+
+A Stacks app with 90+ models is not automatically multi-context. Reach for the
+map only when the app genuinely has separate languages, for instance a commerce
+context and a CMS context that both say "author" and mean different things.
+
+## ADRs
+
+ADRs live in `docs/adr/` with sequential numbering: `0001-slug.md`,
+`0002-slug.md`. Scan the directory for the highest existing number and increment.
+Create the directory lazily, only when the first ADR is needed.
+
+```md
+# {Short title of the decision}
+
+{One to three sentences: the context, what was decided, and why.}
+```
+
+That is the whole template. An ADR can be a single paragraph. The value is in
+recording *that* a decision was made and *why*, not in filling out sections.
+
+Optional sections, only when they add genuine value:
+
+- **Status** frontmatter (`proposed | accepted | deprecated | superseded by
+  ADR-NNNN`), useful when decisions get revisited.
+- **Considered options**, only when the rejected alternatives are worth
+  remembering.
+- **Consequences**, only when non-obvious downstream effects need calling out.
+
+### What qualifies
+
+- **Architectural shape.** "The write model is event sourced, the read model is
+  projected into Postgres."
+- **Integration patterns between contexts.** "Ordering and Billing communicate
+  via domain events, not synchronous HTTP."
+- **Technology choices that carry lock-in.** Database, message bus, auth
+  provider, deployment target. Not every library, just the ones that would take a
+  quarter to swap.
+- **Boundary and scope decisions.** "Customer data is owned by the Customer
+  context, other contexts reference it by ID only." The explicit no is as
+  valuable as the yes.
+- **Deliberate deviations from the obvious path.** "We hand-write this migration
+  instead of generating it because X." Anything where a reasonable reader would
+  assume the opposite. These stop the next engineer from fixing something that
+  was deliberate.
+- **Constraints not visible in the code.** "We cannot use AWS here for compliance
+  reasons." "Responses must stay under 200ms because of the partner contract."
+- **Rejected alternatives when the rejection is non-obvious.** Otherwise someone
+  suggests the same thing again in six months.
+
+### What does not
+
+Anything easy to reverse, unsurprising, or with no real alternative. If a
+decision is easy to reverse you will just reverse it. If it is not surprising,
+nobody will wonder why. If there was no alternative, there is nothing to record
+beyond "we did the obvious thing".

package/ai/skills/stacks-domain-modeling/SKILL.md

@@ -0,0 +1,109 @@
+---
+name: stacks-domain-modeling
+description: Use when building or sharpening a Stacks project's domain language - challenging a fuzzy or overloaded term, naming a model or event, writing or editing CONTEXT.md, or recording an architecture decision as an ADR under docs/adr/.
+license: MIT
+compatibility: Bun >= 1.3.0, TypeScript
+allowed-tools: Read Edit Write Bash Grep Glob
+---
+
+# Domain modeling
+
+Actively build and sharpen the project's domain model as you design. This is the
+*active* discipline: challenging terms, inventing edge-case scenarios, and
+writing the glossary and the decisions down the moment they crystallise. Merely
+*reading* `CONTEXT.md` for vocabulary is not this skill, that is a one-line habit
+any skill can do. This skill is for when you are changing the model.
+
+In a Stacks app the domain language is not decoration. It becomes the model name,
+the table name, the route URI, the event name (`article:created`), the action
+file name and the stx component name, all at once. A term settled badly is a
+rename across five layers later.
+
+Credit: adapted from Matt Pocock's `domain-modeling` skill (MIT),
+<https://github.com/mattpocock/skills>.
+
+## File structure
+
+Most repos have a single context:
+
+```
+/
+├── CONTEXT.md
+├── docs/
+│   └── adr/
+│       ├── 0001-derive-migrations-from-models.md
+│       └── 0002-sqlite-for-local-development.md
+└── app/
+```
+
+If a `CONTEXT-MAP.md` exists at the root, the repo has several contexts and the
+map points at where each one lives. Create both lazily: only when you have
+something to write. If no `CONTEXT.md` exists, create it when the first term is
+resolved. If no `docs/adr/` exists, create it when the first ADR is needed.
+
+Formats for both files: [FORMATS.md](FORMATS.md).
+
+## During the session
+
+### Challenge against the glossary
+
+When the user uses a term that conflicts with the existing language in
+`CONTEXT.md`, call it out immediately. "Your glossary defines cancellation as X,
+but you seem to mean Y. Which is it?"
+
+### Sharpen fuzzy language
+
+When a term is vague or overloaded, propose a precise canonical one. "You are
+saying account. Do you mean the Customer or the User? Those are different
+things, and this project already has a `User` model."
+
+### Discuss concrete scenarios
+
+When domain relationships are on the table, stress-test them with specific
+scenarios. Invent cases that probe the edges and force precision about where one
+concept ends and the next begins.
+
+### Cross-reference with the code
+
+The code is a second source of truth for the domain, and in a Stacks project it
+is an unusually legible one. When the user states how something works, check
+whether the models agree:
+
+- `app/Models/` and `storage/framework/defaults/app/Models/` for the nouns.
+- The `belongsTo` / `hasMany` / `belongsToMany` declarations for the
+  relationships.
+- Model events (`observe: true` emits `<model>:created`, `:updated`, `:deleted`)
+  for the verbs.
+- `routes/` for the URIs the outside world sees.
+
+If you find a contradiction, surface it. "Your code cancels whole Orders, but you
+just said partial cancellation is possible. Which is right?"
+
+A term that lands in `CONTEXT.md` and disagrees with a model name is a bug in one
+of the two. Say which one you think should move.
+
+### Update CONTEXT.md inline
+
+When a term is resolved, update `CONTEXT.md` right there. Do not batch these up.
+
+`CONTEXT.md` is a glossary and nothing else. Keep it free of implementation
+detail: no file paths, no schemas, no config. Those go stale, and the whole value
+of the file is that it does not.
+
+### Offer ADRs sparingly
+
+Only offer to record a decision when all three are true:
+
+1. **Hard to reverse.** The cost of changing your mind later is meaningful.
+2. **Surprising without context.** A future reader will wonder why it was done
+   this way.
+3. **The result of a real trade-off.** There were genuine alternatives and you
+   picked one for specific reasons.
+
+If any of the three is missing, skip it.
+
+## Downstream
+
+> Reach for `stacks-codebase-design` when the argument is about a module's
+> shape rather than its name, and `stacks-grilling` when the term will not
+> settle without an interview.

package/ai/skills/stacks-enums/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: stacks-enums
-description: Use when working with framework constants in a Stacks application — NpmScript commands, Action identifiers, or any enumerated constants used across the build system, CLI, and actions. Covers @stacksjs/enums.
+description: Use when working with framework constants in a Stacks application - NpmScript commands, Action identifiers, or any enumerated constants used across the build system, CLI, and actions. Covers @stacksjs/enums.
 license: MIT
 compatibility: Bun >= 1.3.0, TypeScript
 allowed-tools: Read Edit Write Bash Grep Glob

package/ai/skills/stacks-error-handling/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: stacks-error-handling
-description: Use when implementing error handling in Stacks — the Result type (Ok/Err), handleError function, error page rendering (development with stack traces, production with friendly messages), ErrorHandler class, ModelNotFoundException, HTTP error mapping, log file writing, or error configuration. Covers @stacksjs/error-handling and config/errors.ts.
+description: Use when implementing error handling in Stacks - the Result type (Ok/Err), handleError function, error page rendering (development with stack traces, production with friendly messages), ErrorHandler class, ModelNotFoundException, HTTP error mapping, log file writing, or error configuration. Covers @stacksjs/error-handling and config/errors.ts.
 license: MIT
 compatibility: Bun >= 1.3.0, TypeScript
 allowed-tools: Read Edit Write Bash Grep Glob

package/ai/skills/stacks-events/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: stacks-events
-description: Use when working with the event system in a Stacks application — dispatching events, listening for events, model events, wildcard listeners, the event emitter, or event-driven architecture. Covers @stacksjs/events, app/Events.ts, app/Listener.ts, and app/Listeners/.
+description: Use when working with the event system in a Stacks application - dispatching events, listening for events, model events, wildcard listeners, the event emitter, or event-driven architecture. Covers @stacksjs/events, app/Events.ts, app/Listener.ts, and app/Listeners/.
 license: MIT
 compatibility: Bun >= 1.3.0, TypeScript
 allowed-tools: Read Edit Write Bash Grep Glob

package/ai/skills/stacks-faker/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: stacks-faker
-description: Use when working with fake data generation in a Stacks application — seeding databases, generating test data, model factories, or using faker utilities. Covers @stacksjs/faker (wrapper around ts-mocker) and its integration with the database seeder.
+description: Use when working with fake data generation in a Stacks application - seeding databases, generating test data, model factories, or using faker utilities. Covers @stacksjs/faker (wrapper around ts-mocker) and its integration with the database seeder.
 license: MIT
 compatibility: Bun >= 1.3.0, TypeScript
 allowed-tools: Read Edit Write Bash Grep Glob

package/ai/skills/stacks-flow/PHASE-BOUNDARIES.md

@@ -0,0 +1,91 @@
+# Phase boundaries
+
+A **phase** is a chunk of work inside a session: the grilling, the
+implementation, the QA. The definition is fuzzy on purpose, because a phase ends
+when you think "ok, we are done with that".
+
+The **phase boundary** is the gap between two phases, and it is the only place
+this decision belongs. Mid-phase there is no decision to make: continue, or split
+what is left into subagents. Compacting mid-phase makes the agent lose the
+thread.
+
+Credit: adapted from Matt Pocock's `ask-matt` skill (MIT),
+<https://github.com/mattpocock/skills>.
+
+## The five options
+
+| Option | What it does |
+|---|---|
+| **Continue** | Stay in the session. No context switch at all. |
+| **Clear** | Empty the context window and start from nothing. |
+| **Handoff** | Write a portable markdown file and seed a session anywhere with it. |
+| **Subagent** | Send the task to its own context window and get a report back. |
+| **Compact** | Compress this context and seed a fresh session with the summary. |
+
+## The tree
+
+Work top to bottom at the boundary. The first yes wins.
+
+**1. Can you continue in this session?** Two things make the answer yes: the next
+phase needs this one as a **primary source**, or you have enough window left for
+the next phase to fit. Design to implementation is the standard yes, because the
+implementation wants the reasoning verbatim, not a summary of it. Continue costs
+nothing and loses nothing, so rule it out before anything else.
+
+**2. Is the context irrelevant to what comes next?** If everything here (the
+exploration, the decisions, the dead ends) is disposable, **clear**. It is the
+cheapest move on the board: no time, and the whole window handed back. The cost
+of getting it wrong is one-way, though. Clear a *relevant* context and you lose
+the why behind what you built, and no amount of reading the diff back returns it.
+
+**3. Do you need to hand off?** `/stacks-handoff` is narrow. You need it only
+when you are swapping to a different harness, moving to a different directory or
+repo, sending the work to a colleague, or forking a side task you found
+mid-phase. That list is the whole clause. What a handoff buys is **portability**.
+If nothing is travelling, you do not need it.
+
+**4. Can the task be done with you away from the keyboard?** Scoped tightly
+enough to run with no steering? Send it to a **subagent** and leave this session
+untouched. Automated review is the standard case: the agent reads the diff and
+reports, and you are not needed while it does.
+
+**5. Otherwise, compact.** Relevant context, same harness, same directory, and
+you need to stay in the loop. This is where the tree lands, and it lands here
+often. Pass an instruction with it so the summary keeps what the next phase
+needs.
+
+Compact is the **default, not the first reach**. It sits at the bottom because
+the four questions above it are all cheaper or more precise. The failure mode
+when people start here is a fresh session that is confidently wrong about a
+decision the summary flattened.
+
+## Primary and secondary sources
+
+Every move except Continue turns a **primary source** into a **secondary**
+source: the session as it happened, replaced by a summary of it. The trade is
+always the same shape.
+
+| Source | Information | Noise | Room to move |
+|---|---|---|---|
+| Primary (continue) | Full | Lots | Little |
+| Secondary (compact, handoff) | Lossy | Less | Lots |
+
+This is why question 1 comes first. You only pay the lossiness when staying costs
+more than it saves.
+
+## In a Stacks session specifically
+
+Two boundaries recur, and both usually answer the same way:
+
+- **Migration generation to review.** `buddy generate:migrations` writes SQL you
+  then have to read. Continue: the model change you just made is the primary
+  source for judging the SQL.
+- **Implementation to review.** `/stacks-review` reads a diff and needs no
+  exploration, so it is the textbook subagent. Sending it out keeps the
+  implementation context intact for the fixes that follow.
+
+## These are judgement calls
+
+The questions are not objective. Each has taste in it, and the same boundary can
+go two ways on two days. The value is in asking them in order, at the boundary
+rather than in the middle of the work.

package/ai/skills/stacks-flow/SKILL.md

@@ -0,0 +1,117 @@
+---
+name: stacks-flow
+description: Ask which Stacks skill or flow fits the situation. A router over the bundled skills.
+disable-model-invocation: true
+license: MIT
+compatibility: Bun >= 1.3.0, TypeScript
+allowed-tools: Read Edit Write Bash Grep Glob
+---
+
+# Stacks flow
+
+Stacks ships more than a hundred skills. You do not remember them all, so ask.
+
+Two kinds live in that set, and they are reached differently:
+
+- **Subsystem reference**: `stacks-orm`, `stacks-router`, `stacks-queue`,
+  `stacks-cms`, one per part of the framework. These are model-invoked, so the
+  agent finds them on its own from the task. You rarely need to name one, and the
+  full index is the feature-to-skill table in `AGENTS.md`.
+- **Craft skills**: the ones below. These shape *how* the work happens, and this
+  is the map of them.
+
+Credit: the flow model here is adapted from Matt Pocock's `ask-matt` skill
+(MIT), <https://github.com/mattpocock/skills>.
+
+## The main flow: idea to shipped
+
+The route most work travels.
+
+1. **`/stacks-office-hours`** turns an idea into a design document. It runs the
+   `stacks-grilling` interview underneath, so vague answers get pushed on. Start
+   here when the question is still "should we build this, and what exactly".
+2. **Branch: can every question be settled in conversation?** If one needs a
+   runnable answer (a state model, a UI direction), detour through
+   **`/stacks-prototype`**, then come back with the verdict.
+3. **`/stacks-plan-review`** turns the design into scope, data flow,
+   architecture, a test matrix and an implementation plan. This is where
+   `stacks-codebase-design` gets used, because the plan is where seams are chosen.
+4. **`/stacks-new-feature`** slices the plan into **tracer bullets** and builds
+   them in the model to migration to action to route to test order, one vertical
+   slice at a time. It drives **`/stacks-tdd`** inside each slice.
+5. **`/stacks-review`** reviews the diff on two axes, standards and spec, before
+   anything merges.
+6. **`/stacks-browse`** QAs the result in a real browser when the slice has a UI.
+7. **`/stacks-retro`** looks back at the session and improves the environment the
+   next one runs in.
+
+### Context hygiene
+
+Keep steps 1 to 4 in one unbroken context window where you can, so the grilling,
+the plan and the slicing all build on the same thinking. Each slice in step 4 can
+then start fresh from its own ticket. When a session is running long, make the
+cut at a phase boundary rather than mid-phase: [PHASE-BOUNDARIES.md](PHASE-BOUNDARIES.md)
+has the ordered tree.
+
+## On-ramps
+
+A starting situation that generates work, then merges onto the main flow.
+
+- **Something is broken** goes to **`/stacks-investigate`**. It refuses to
+  theorise until it has a **tight** feedback loop, one command that already goes
+  red on *this* bug, then fixes with a regression test. When the real finding is
+  that there is no good seam to lock the bug down, it hands off to
+  `stacks-codebase-design`.
+- **A visual surface needs to be built or lifted** goes to
+  **`/stacks-design-taste`**, or `/stacks-redesign` when the UI already exists
+  and needs auditing first. Those two carry their own flow, including the
+  aesthetic presets and the image-first pipeline.
+- **Something needs a human's hands** goes to **`/stacks-wizard`**, which turns
+  the manual procedure into a script the human runs once.
+
+## Codebase health
+
+Not feature work, upkeep.
+
+- **`/stacks-codebase-design`** is the bench you design a module's shape on:
+  module, interface, depth, seam, adapter, leverage, locality. Reach for it when
+  the argument is about where a seam goes or how much a trait should hide.
+- **`/stacks-security-audit`** for OWASP, STRIDE and attack-surface work.
+- **`/stacks-registry`** and the other subsystem skills for the auditing patterns
+  specific to one part of the framework.
+
+## Vocabulary underneath
+
+Two model-invoked references that run *beneath* the other skills, each the single
+source of truth for its vocabulary. Reach for them directly when the **words**,
+not the process, are the problem.
+
+- **`/stacks-domain-modeling`** sharpens the project's *domain* language:
+  challenge a fuzzy term, resolve an overloaded one, record a hard-to-reverse
+  decision as an ADR. In a Stacks app that language becomes model names, table
+  names, route URIs and event names, so it is load-bearing.
+- **`/stacks-codebase-design`** is the deep-module vocabulary for a module's
+  *shape*. `stacks-tdd` and `stacks-plan-review` both speak it.
+
+## Standalone
+
+- **`/stacks-grilling`** is the interview primitive: rounds, the frontier, facts
+  are the agent's job and decisions are yours. Reach for it directly when you
+  want the interview with no wrapper.
+- **`/stacks-guard`** is the safety layer: destructive-command detection, freeze
+  mode, and the Claude Code hook that blocks the worst of it before it runs.
+- **`/stacks-handoff`** compacts the conversation into a portable document.
+  Narrow: only when something is actually travelling to a new harness, a new
+  directory, or a colleague.
+- **`/stacks-prototype`** answers one design question with throwaway code and
+  keeps the artifact on a `prototype/<name>` branch.
+- **`/stacks-writing-for-agents`** is the reference for writing any document an
+  agent reads, including the skills themselves. Read it before adding anything to
+  `app/Skills/`.
+- `/stacks-repl`, `/stacks-shell` and `/stacks-buddy` drive the toolchain
+  itself.
+
+## Precondition
+
+Nothing to run first. `buddy setup:ai <agent>` links these into your agent's
+directory, and `app/Skills/<name>/SKILL.md` shadows any of them per project.

package/ai/skills/stacks-git/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: stacks-git
-description: Use when working with git in a Stacks application — commit conventions, git hooks, changelog generation, commit scopes/types, or GitHub API types. Covers @stacksjs/git, config/git.ts, config/commit.ts, and the git hooks system.
+description: Use when working with git in a Stacks application - commit conventions, git hooks, changelog generation, commit scopes and types, GitHub API types, or resolving an in-progress merge or rebase conflict. Covers @stacksjs/git, config/git.ts, config/commit.ts, and the git hooks system.
 license: MIT
 compatibility: Bun >= 1.3.0, TypeScript
 allowed-tools: Read Edit Write Bash Grep Glob
@@ -147,12 +147,40 @@ interface WorkflowRun {
 }
 ```
 
+## Resolving a merge or rebase conflict
+
+Resolve by **intent**, traced back to each side's primary source, never by
+picking lines that look plausible.
+
+1. **See the current state.** `git status`, `git log --oneline --graph -20`, and
+   the conflicting files. Know which operation you are in the middle of, a merge
+   or a rebase, before touching anything.
+2. **Find the primary source for each side.** Read the commit messages, the PR,
+   the issue. Understand deeply why each change was made and what it was for. A
+   conflict is two intents colliding, and you cannot resolve it while you only
+   know one.
+3. **Resolve each hunk.** Preserve both intents where possible. Where they are
+   genuinely incompatible, pick the one matching the merge's stated goal and note
+   the trade-off. Do not invent new behaviour to bridge them. Always resolve,
+   never `--abort`.
+4. **Run the checks.** `./buddy lint`, `./buddy typecheck`, `./buddy test`. In
+   this framework two conflict classes survive a clean textual merge and only
+   show up here: a model changed on both sides, where the generated migrations
+   diverged and one has to be regenerated, and a registry file
+   (`app/Routes.ts`, `app/Events.ts`, `app/Middleware.ts`) where a dropped entry
+   fails silently rather than failing to compile.
+5. **Finish the operation.** Stage everything and commit, or continue the rebase
+   until every commit is replayed.
+
+Credit: adapted from Matt Pocock's `resolving-merge-conflicts` skill (MIT),
+<https://github.com/mattpocock/skills>.
+
 ## Gotchas
-- **`@stacksjs/git` is mostly re-exports** — actual functionality in `@stacksjs/gitlint`, `@stacksjs/gitit`, `bun-git-hooks`
-- **Pre-commit runs lint-staged** — the only default hook
-- **Emoji disabled by default** — `useEmoji: false` but emoji mappings exist for each type
-- **`buddy commit` runs `npm run commit`** — delegates to commitizen/cz-git flow
-- **Scopes dynamically extended** — component and function names merged into scopes at runtime
-- **Breaking changes only for feat/fix** — `allowBreakingChanges: ['feat', 'fix']`
-- **No max header length** — `maxHeaderLength: Infinity`
-- **Git hooks config re-exports** — `git-hooks.config.ts` just re-exports from `config/git.ts`
+- **`@stacksjs/git` is mostly re-exports** - actual functionality in `@stacksjs/gitlint`, `@stacksjs/gitit`, `bun-git-hooks`
+- **Pre-commit runs lint-staged** - the only default hook
+- **Emoji disabled by default** - `useEmoji: false` but emoji mappings exist for each type
+- **`buddy commit` runs `npm run commit`** - delegates to commitizen/cz-git flow
+- **Scopes dynamically extended** - component and function names merged into scopes at runtime
+- **Breaking changes only for feat/fix** - `allowBreakingChanges: ['feat', 'fix']`
+- **No max header length** - `maxHeaderLength: Infinity`
+- **Git hooks config re-exports** - `git-hooks.config.ts` just re-exports from `config/git.ts`

package/ai/skills/stacks-grilling/SKILL.md

@@ -0,0 +1,85 @@
+---
+name: stacks-grilling
+description: Use when a plan, design or decision needs stress-testing before any code is written, when the user asks to be grilled or to have their thinking challenged, or when another skill needs the round-and-frontier interview primitive. Produces a shared understanding, never code.
+license: MIT
+compatibility: Bun >= 1.3.0, TypeScript
+allowed-tools: Read Edit Write Bash Grep Glob
+---
+
+# Grilling
+
+Interview the user relentlessly until you reach a shared understanding. Map the
+work as a **design tree**: every decision branches into the decisions that hang
+off it.
+
+This is the interview primitive. `stacks-office-hours` runs it to shape a
+product idea, `stacks-plan-review` runs it to settle an architecture, and
+`stacks-redesign` runs it to pin down an aesthetic direction. Reach for it
+directly when you want the interview with no wrapper around it.
+
+Credit: adapted from Matt Pocock's `grilling` skill (MIT),
+<https://github.com/mattpocock/skills>.
+
+## Rounds and the frontier
+
+Work the tree in **rounds**. The **frontier** is every decision whose
+prerequisites are already settled: the questions you can ask *now* without
+guessing at answers you have not heard yet.
+
+Ask the whole frontier in one round. Number each question and give your
+recommended answer. Then wait for the user's answers before the next round.
+
+```
+❓ **Q1** - **<question title>**: <question body, possibly several paragraphs,
+including the options you see>
+
+➡️ <your recommended answer>
+
+---
+
+❓ **Q2** - **<question title>**: <question body>
+
+➡️ <your recommended answer>
+```
+
+Each round of answers reshapes the tree. Settled decisions push the frontier
+outward and unblock questions that depended on them. Recompute the frontier and
+ask the next round. A question whose answer depends on another question still
+open in this round belongs to a *later* round, not this one.
+
+## Facts are your job, decisions are the user's
+
+Finding *facts* is never the user's job. When a frontier question needs a fact
+from the environment, go get it. In a Stacks project that means reading rather
+than asking:
+
+- `config/*.ts` for what is already configured, and which driver is selected.
+- `app/Models/` and `storage/framework/defaults/app/Models/` for what the domain
+  already models.
+- `routes/` for the surface that already exists.
+- `buddy list` and `buddy <command> --help` for what the CLI already does.
+- `CONTEXT.md` for the terms already settled.
+- The relevant `stacks-*` skill for how a subsystem actually behaves.
+
+Do not block on the lookup. A running exploration is an unsettled prerequisite,
+so only the questions downstream of it wait. Ask the rest of the frontier now.
+
+The *decisions* are the user's. Put each to them and wait.
+
+## Done
+
+The session is done when the frontier is empty: every branch of the design tree
+visited, nothing left silently assumed. Do not act on it until the user confirms
+you have reached a shared understanding.
+
+## Do not build
+
+No code during a grilling session. If the user reaches for an implementation
+mid-interview, note the decision it implies, add it to the tree, and carry on.
+Where a question genuinely cannot be settled in conversation because it needs a
+runnable answer, reach for `stacks-prototype` and bring the result back.
+
+## Downstream
+
+> Frontier empty? `/stacks-plan-review` turns the understanding into an
+> implementation plan, or `/stacks-new-feature` slices it into tracer bullets.