@tea-agent/loop-agent 0.10.0 → 0.12.0

package/skills/frontend-design-review/SKILL.md

@@ -0,0 +1,59 @@
+---
+name: frontend-design-review
+description: Use for the frontend plan design gate before any writer runs.
+references:
+  - path: references/review-checklist.md
+    required: true
+---
+
+# Frontend Design Review
+
+Use for `frontend-design-gate-pi`. Read the required checklist first. Review the
+contract, scout report, plan, task source/constraints, `task.json` boundaries, and
+traceable component/design evidence. The connector format is TODO; never fabricate
+a result. When knowledge-base access is absent, failed, or unmatched, require evidence
+that `<repoRoot>/openSpec/**` was searched before accepting other repo conventions.
+
+## Verdict Contract
+
+The first non-empty line must be exactly:
+
+- `VERDICT: pass`
+- `VERDICT: request-revision`
+
+Use request-revision for any blocker. The shell gate reads this line exactly.
+
+## Blocking Conditions
+
+- An acceptance criterion lacks implementation or verification coverage.
+- Applicable UI states are missing without a reason.
+- A dependency is not explicitly permitted.
+- Confirmed project primitives/rules are ignored, or a claim has neither knowledge-base nor required `openSpec/` fallback evidence.
+- Planned paths exceed allowed/write scope or touch forbidden/generated paths.
+- Required static or behavior commands are missing or non-deterministic.
+- Interaction, responsive, accessibility, data, or failure behavior is ambiguous enough to require guessing.
+
+Knowledge-base unavailability alone is advisory when relevant `openSpec/` rules were
+searched and applied. Block when that fallback was skipped, sources conflict without
+resolution, or no source resolves a required user-visible decision.
+
+## Method And Output
+
+Map each criterion to steps, files, states, and checks; audit paths; verify evidence;
+then classify findings as Blocking or Advisory. Do not edit files.
+
+```markdown
+VERDICT: pass
+
+## Findings
+- None blocking.
+
+## Required Plan Corrections
+- None.
+
+## Checked Items
+- ...
+```
+
+For revisions, every correction names the criterion/section, missing evidence or
+decision, and exact plan change required.

package/skills/frontend-design-review/references/review-checklist.md

@@ -0,0 +1,37 @@
+# Frontend Design Review Checklist
+
+## Requirement And State Coverage
+
+- Target route/page/component and non-goals are clear.
+- Every acceptance criterion maps to steps, files, UI behavior, and verification.
+- Assumptions and unresolved ambiguity are explicit.
+- Success, error/validation, loading, empty, disabled, permission, retry, repeated-action, stale-response, and boundary states are handled or marked not applicable.
+
+## Project And Knowledge Fit
+
+- Existing components, hooks, API helpers, mocks, schemas, router patterns, templates, tokens, and theme rules were considered.
+- Component/design choices cite a knowledge-base result or relevant `openSpec/` rule.
+- If knowledge-base setup/query failed or returned no match, `<repoRoot>/openSpec/**` was recursively searched before other repo evidence.
+- Source is `knowledge-base`, `openSpec fallback`, `repository fallback`, or `unavailable`; evidence includes query/search terms, matched paths/headings, and conflicts.
+- Dependencies are authorized; paths fit allowed/write scope and avoid forbidden/generated files.
+
+## Interaction And Quality
+
+- Actions, feedback, validation timing, navigation, persistence, and recovery are unambiguous.
+- Responsive and overflow behavior covers target environments.
+- Keyboard, focus, semantics, contrast, reduced motion, data lifecycle, cancellation, and error recovery are addressed when applicable.
+
+## Verification
+
+- Static and behavior commands are exact, discoverable, and deterministic.
+- Tests prove changed state logic and flows at repository-supported levels.
+- Browser/visual checks are required only by task intent or existing gates.
+- Every missing verification path is a blocker or disclosed risk.
+
+## Verdict Matrix
+
+- Coverage gap, unsafe scope, unauthorized dependency, unresolved required interaction, or missing required verification: request revision.
+- Missing knowledge-base evidence and skipped `openSpec/` fallback: request revision.
+- No relevant knowledge-base or `openSpec/` rule for a required decision: request revision.
+- Knowledge-base unavailable but relevant `openSpec/` rules were applied: advisory connection gap, not a specification gap.
+- Optional cleanup that cannot affect acceptance: advisory.

package/skills/frontend-implementation/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: frontend-implementation
+description: >-
+  Use for frontend contract, scout, plan, and implementation DAG nodes.
+references:
+  - path: references/node-contracts.md
+    required: true
+    maxChars: 3000
+  - path: references/design-spec.md
+    required: true
+    maxChars: 3000
+  - path: references/code-standards.md
+    required: true
+    maxChars: 3000
+---
+
+# Frontend Implementation
+
+Use for `frontend-contract-pi`, `frontend-scout-pi`, `frontend-plan-pi`, and
+`frontend-implement-pi`. Read every required reference before acting.
+
+## Source And Evidence Rules
+
+Use task source and references first, then constraints and `task.json`. Resolve
+component/design rules by the required sequence in `design-spec.md`: connect/query
+the knowledge base first; when it is not configured, connection/query fails, or no
+relevant result exists, search `<repoRoot>/openSpec/**` and treat matching rules as
+the current project's specification. Use other repository evidence only afterward.
+
+- Cite repository findings with paths and symbols or tight line ranges.
+- Label assumptions, unresolved questions, and unavailable evidence.
+- Never invent conventions, component APIs, tokens, commands, or knowledge-base results.
+- Record the selected source as `knowledge-base`, `openSpec fallback`, `repository fallback`, or `unavailable`, with evidence and conflicts.
+
+## Implementation Discipline
+
+- Treat explicit project specs and repo-local skills as authoritative within their stated scope.
+- Reuse confirmed components, tokens, helpers, APIs, mocks, schemas, and test patterns.
+- Do not add dependencies unless the task allows them and the approved plan justifies them.
+- Cover applicable success, error, loading, empty, disabled, permission, and boundary states; mark non-applicable states with reasons.
+- Keep state and validation logic testable where project conventions support it.
+- Writer nodes stay inside `writeSet`, preserve unrelated behavior, and update tests with behavior.
+- Never relax lint/type/test/build configuration or write unauthorized generated output.
+
+## Output And Failure Rules
+
+- Follow the node-specific headings in `node-contracts.md` exactly.
+- Read-only nodes return Markdown and never edit repository files.
+- Missing input blocks a node when proceeding would guess behavior, design compliance, write boundaries, or verification.
+- Keep protocol tokens, commands, paths, identifiers, and configured output language unchanged.
+- Implementation may report attempted checks, but completion requires fresh downstream shell evidence.

package/skills/frontend-implementation/references/code-standards.md

@@ -0,0 +1,34 @@
+# Frontend Code Standards
+
+Discover project rules from task constraints, the component/design source sequence
+in `design-spec.md`, configuration, source, tests, manifests, and generated types.
+When knowledge-base access is unavailable, relevant `<repoRoot>/openSpec/**` rules
+are normative for the current project. Generic style preferences are not rules, and
+documentation never overrides an installed API without an explicit compatibility decision.
+
+## Discover And Cite
+
+- Routing, server/client boundaries, state, forms, data fetching, cache/invalidation, and error boundaries.
+- API, mock, page, component, hook, utility, schema, template, and test directories.
+- Component, hook, route, mock, utility, and test naming.
+- Unit, component, integration, browser/e2e, fixture, and mock expectations.
+- Approved/forbidden dependencies and human-approval rules.
+
+Cite a representative file or configuration for every convention. When neighboring
+code conflicts, describe the alternatives rather than silently choosing one.
+
+## Plan And Implement
+
+- Map each acceptance criterion to code and verification.
+- Determine component placement, state ownership, request lifecycle, validation, error handling, API/schema compatibility, mocks, and fixtures.
+- Prefer existing helpers and public APIs; preserve behavior outside the contract.
+- Keep rendering, transitions, validation, and side effects separable where the project pattern supports it.
+- Handle cancellation, stale responses, repeated actions, and boundary inputs when applicable.
+- Update tests at repository-supported levels; update relevant existing tests before adding duplicates.
+- Keep writes inside `writeSet`; generated output requires explicit authorization.
+
+## Prohibited
+
+- Do not relax lint/type/test configuration.
+- Do not add dependencies, a parallel component library, styling system, or state framework without permission.
+- Do not describe an unexecuted command or unavailable browser/knowledge-base flow as verified.

package/skills/frontend-implementation/references/design-spec.md

@@ -0,0 +1,46 @@
+# Frontend Design And Component Specification
+
+## Required Source Sequence
+
+1. Attempt the configured component/design knowledge-base query first.
+2. If unavailable, failed, timed out, or unmatched, recursively search the project root's exact `openSpec/` directory.
+3. Treat relevant matches as the current project's specification for this run.
+4. Only then use component source, tokens, stories, tests, and pages as non-normative repository fallback.
+
+Never skip `openSpec/` directly to neighboring-code conventions. Report source
+conflicts instead of combining them. Explicit task requirements remain the contract;
+flag conflicts with knowledge-base or `openSpec/` rules.
+
+## Knowledge Base Connection — TODO
+
+Request format is undecided. TODO: define connector/owner, namespaces, secret-free
+auth, query fields, result identity/version/time, and failure behavior.
+
+Attempt only a connector actually available in the execution environment. Otherwise
+record `not-configured` and run the `openSpec/` fallback; never invent a connection.
+
+## `openSpec/` Fallback Procedure
+
+- Confirm whether `<repoRoot>/openSpec/` exists and enumerate its files recursively.
+- Read indexes first, then search names/content using task, route, component, interaction, theme, token, and state terms.
+- Read relevant matches in context; do not treat a filename-only hit as a rule.
+- Record search terms, inspected/matched paths, headings or tight line ranges, applied rules, and conflicts.
+- If the directory or relevant rules are absent, record that fact before using repository fallback.
+
+## Retrieval Evidence
+
+Record source as `knowledge-base`, `openSpec fallback`, `repository fallback`, or
+`unavailable`. Knowledge-base evidence includes query, source ID/version/time, rules,
+and conflicts. `openSpec fallback` includes terms, paths/headings/lines, rules, and conflicts.
+
+## Rules To Retrieve Or Discover
+
+- Components, variants, props, composition, accessibility, deprecations, placement, forms, overlays, navigation, and state patterns.
+- Tokens, typography, color, layout, breakpoints, motion, focus/keyboard/contrast, exceptions, design debt, and forbidden patterns.
+
+## Gate Expectations
+
+- Reuse confirmed primitives unless a new pattern is authorized.
+- Define applicable states and responsive behavior before implementation.
+- Cite knowledge-base or `openSpec/` evidence for component/token choices; label weaker repository fallback.
+- Make deviations and unresolved gaps explicit.

package/skills/frontend-implementation/references/node-contracts.md

@@ -0,0 +1,32 @@
+# Frontend Node Contracts
+
+## `frontend-contract-pi`
+
+- Read task source, constraints, `task.json`, and explicit references; do not edit.
+- Define scope, non-goals, routes/components, runtime, user flows, acceptance criteria, states, risks, and verification expectations.
+- Preserve requirement IDs and language; never turn an implementation guess into a requirement.
+- For every standard UI state, specify behavior or mark it not applicable with a reason.
+- Output: `Scope`, `Non-goals`, `Acceptance Criteria`, `UI States`, `Target Runtime Environment`, `Risks`, `Verification Expectations`.
+
+## `frontend-scout-pi`
+
+- Inspect routes, pages, components, styles/tokens, state/data flow, API/mocks, scripts, tests, and reusable assets; do not edit.
+- Separate confirmed facts, inferred conventions, and missing information.
+- Attempt knowledge-base first. If absent, failed, or unmatched, recursively inspect `<repoRoot>/openSpec/**` before other repo conventions.
+- Record source as `knowledge-base`, `openSpec fallback`, `repository fallback`, or `unavailable`, with query/search terms and matched paths.
+- Output: `Frontend Stack`, `Routes`, `Components`, `Styling System`, `Existing Design Conventions`, `State / Data Flow`, `Test Entry Points`, `Reuse Opportunities`, `Risks`.
+
+## `frontend-plan-pi`
+
+- Map every acceptance criterion to ordered implementation and verification steps.
+- Name target files and reasons; keep them within allowed paths and expected `writeSet`.
+- Define states, component/styling reuse, interaction behavior, dependency policy, and exact static/behavior commands.
+- Knowledge-base failure is not approval: apply relevant `openSpec/` matches as current-project rules. Request clarification only when neither source resolves required compliance or they conflict materially.
+- Output: `Implementation Steps`, `Target Files`, `UI State Handling`, `Styling / Component Strategy`, `Interaction Notes`, `Dependency Policy`, `Verification Plan`, `Residual Risks`.
+
+## `frontend-implement-pi`
+
+- Run only after design gate pass and implement only the approved plan inside `writeSet`.
+- Re-read current files; stop instead of crossing forbidden paths or guessing a blocking decision.
+- Reuse confirmed project primitives and update tests. Do not claim knowledge-base or downstream verification without evidence.
+- Output: `Changed Files`, `Implemented Behavior`, `UI States Covered`, `Styling / Component Notes`, `Verification Attempted`, `Residual Risks`.

package/skills/frontend-review/SKILL.md

@@ -0,0 +1,53 @@
+---
+name: frontend-review
+description: Use to review completed frontend code and verification before closeout.
+references:
+  - path: references/review-findings.md
+    required: true
+---
+
+# Frontend Review
+
+Use for `frontend-review-pi`; read the findings guide first. Required inputs are
+original task/reference material, derived contract/constraints, approved plan and
+design verdict, implementation summary, actual diff, and shell evidence. Missing
+actual diff or required evidence forces revision; never infer it from a summary.
+
+## Verdict Contract
+
+The first non-empty line must be exactly `VERDICT: pass` or
+`VERDICT: request-revision`. Any Critical/Important finding, failed or missing
+required check, forbidden write, or unmet acceptance criterion forces revision.
+
+## Review Scope
+
+- Compare original intent, derived artifacts, approved plan, actual diff, and evidence; report lost or altered requirements.
+- Inspect every changed file against allowed, forbidden, and approved write scope.
+- Map criteria to behavior, applicable UI states, tests, and shell evidence.
+- Review state/data flow, validation, async/error behavior, components/design, responsive behavior, accessibility, dependencies, maintenance, and regression risk when applicable.
+- Component/design claims require traceable knowledge-base evidence or, after connection/query failure or no match, relevant `<repoRoot>/openSpec/**` evidence. The connector format is TODO; never claim a query or fallback search without evidence.
+- Treat shell exit status as authoritative. Do not edit files.
+
+## Evidence And Output
+
+Findings cite a tight file location, exact command/result, or named DAG artifact.
+Separate confirmed defects, missing evidence, and residual risks.
+
+```markdown
+VERDICT: request-revision
+
+## Findings
+- [Important] `path:line` — issue, impact, and required correction.
+
+## Verification Assessment
+- ...
+
+## UX Assessment
+- ...
+
+## Residual Risks
+- ...
+```
+
+A pass requires no Critical/Important findings and all required shell checks passed.
+Still report knowledge-source status and optional browser/manual gaps.

package/skills/frontend-review/references/review-findings.md

@@ -0,0 +1,42 @@
+# Frontend Review Findings Guide
+
+## Severity
+
+- **Critical**: blocks primary flow, corrupts data, violates security/privacy, writes forbidden paths, or bypasses required verification.
+- **Important**: acceptance/state/validation gap, material convention drift, missing behavior tests, unauthorized dependency, or failed/missing required verification.
+- **Minor**: non-blocking maintainability, copy, layout, or cleanup issue.
+
+## Evidence
+
+- Cite tight file locations, exact commands/results, or named DAG artifacts.
+- Never invent evidence; name the missing check. An implementation summary is not the actual diff.
+- Failed required static/behavior verification is at least Important unless proven unrelated.
+- A knowledge-base claim records connector/query, source ID/version, and retrieval time. If absent, failed, or unmatched, review evidence must show `<repoRoot>/openSpec/**` search terms and matched paths/headings; label `openSpec fallback`, `repository fallback`, or `unavailable` accurately.
+
+## Review Sequence
+
+1. Establish changed-file inventory and write boundaries.
+2. Compare original requirement with derived contract/constraints.
+3. Map each criterion to code, states, tests, and evidence.
+4. Inspect interactions, state/data/API behavior, failure paths, and regression risk.
+5. Check component/design evidence, responsive/accessibility behavior, dependencies, and maintenance fit when applicable.
+6. Classify findings and derive the verdict mechanically.
+
+Skipping the required `openSpec/` search after knowledge-base failure is Important
+when component/design compliance affects acceptance or implementation choices.
+
+Use one issue per finding:
+
+```text
+- [Critical|Important|Minor] path:line — Problem; impact; required correction; evidence.
+```
+
+Avoid vague advice. When no source location exists, cite the command or artifact.
+
+## Pass Rules
+
+- No Critical or Important findings remain.
+- Required static and behavior nodes ran and passed.
+- Changed files are authorized.
+- Criteria and applicable states have implementation and evidence.
+- Optional unavailable knowledge-base, browser, visual, or manual checks remain explicit risks.

package/skills/frontend-verification/SKILL.md

@@ -0,0 +1,40 @@
+---
+name: frontend-verification
+description: Use to assess frontend evidence and produce closeout.
+references:
+  - path: references/verification-checklist.md
+    required: true
+---
+
+# Frontend Verification
+
+Use for `frontend-closeout-pi`. Shell nodes execute commands; this read-only skill
+assesses their evidence. Read the checklist first.
+
+Required inputs: criteria, implementation summary/change inventory, static and
+behavior shell commands/source/status/artifacts, review verdict/findings, and any
+required browser, visual, manual, or knowledge-base validation.
+
+## Evidence Rules
+
+- Static evidence covers type/lint/build/schema checks; behavior evidence covers tests or interaction checks that actually exercise the flow.
+- Shell exit status is authoritative. Classify checks as `passed`, `failed`, `not-run`, `blocked`, or `unavailable`; only passed satisfies a required check.
+- Never use static success as behavior proof, or tests as visual/browser proof they did not exercise.
+- Unavailable commands remain gaps, not weaker success claims.
+- Resolve component/design evidence as knowledge base first, then `<repoRoot>/openSpec/**` when setup/query fails or has no match. Mark `openSpec fallback` as the active project specification source; do not report it as missing merely because the connector format is TODO.
+
+## Method And Output
+
+Inventory required checks, map each to fresh evidence, classify gaps, confirm review
+pass, and state only proven user-visible changes.
+
+Return Markdown headings:
+
+- `Changes`: changed behavior and areas.
+- `Verification Evidence`: table of check, command/source, status, and artifact/result.
+- `Review Result`: exact review verdict and findings.
+- `Known Risks`: missing optional checks and environment caveats.
+- `Follow-up`: concrete work or `None`.
+
+Do not edit files. Do not claim complete when review is not pass or a required check
+is failed, not-run, blocked, unavailable, stale, or contradicted.

package/skills/frontend-verification/references/verification-checklist.md

@@ -0,0 +1,56 @@
+# Frontend Verification Checklist
+
+## Static And Behavior Evidence
+
+- Type/compile, lint/format, build, and schema/client checks ran when required.
+- Generated output was authorized.
+- Unit/component/integration tests cover changed logic and flows; regressions pass.
+- Browser/e2e/manual evidence exists when explicitly required.
+- API/mock behavior and applicable loading, empty, error, success, disabled, permission, retry, and boundary states have evidence.
+
+## Design And Component Evidence
+
+- Claims cite traceable knowledge-base retrieval or relevant `<repoRoot>/openSpec/**` fallback evidence.
+- Retrieval includes connector/query, collection/document ID, version when available, and time.
+- When connector setup/query fails or has no match, evidence shows recursive `openSpec/` search terms, inspected paths, matched headings/lines, and applied rules.
+- Relevant `openSpec/` matches become the current-project specification and satisfy source availability; only the knowledge-base connection remains unavailable.
+- Missing both sources blocks explicit compliance or an unresolved required design decision.
+
+## Status
+
+- `passed`: fresh successful evidence matches current implementation.
+- `failed`: check ran and failed.
+- `not-run`: no fresh attempt exists.
+- `blocked`: a prerequisite prevented execution.
+- `unavailable`: tool, environment, connector, or source was absent.
+
+Only passed satisfies a required check. Other optional statuses remain disclosed risks.
+
+## Closeout Checks
+
+- List exact commands, source, exit status, and archived output/artifact when available.
+- Map every criterion to evidence or a named gap.
+- Record review verdict before completion.
+- Do not conflate static, behavior, browser/visual/manual, or knowledge-base proof.
+
+```markdown
+## Changes
+- ...
+
+## Verification Evidence
+| Check | Command or source | Status | Evidence |
+|---|---|---|---|
+| ... | ... | passed | ... |
+
+## Review Result
+- Verdict: `VERDICT: pass`
+
+## Known Risks
+- ...
+
+## Follow-up
+- None.
+```
+
+If review is not pass or a required check is not passed, describe the task as
+incomplete and list concrete follow-up.

package/skills/grill-me/SKILL.md

@@ -0,0 +1,10 @@
+---
+name: grill-me
+description: Interview the user relentlessly about a plan or design until reaching shared understanding, resolving each branch of the decision tree. Use when user wants to stress-test a plan, get grilled on their design, or mentions "grill me".
+---
+
+Interview me relentlessly about every aspect of this plan until we reach a shared understanding. Walk down each branch of the design tree, resolving dependencies between decisions one-by-one. For each question, provide your recommended answer.
+
+Ask the questions one at a time.
+
+If a question can be answered by exploring the codebase, explore the codebase instead.

package/skills/grill-with-docs/SKILL.md

@@ -0,0 +1,88 @@
+---
+name: grill-with-docs
+description: Grilling session that challenges your plan against the existing domain model, sharpens terminology, and updates documentation (CONTEXT.md, ADRs) inline as decisions crystallise. Use when user wants to stress-test a plan against their project's language and documented decisions.
+---
+
+<what-to-do>
+
+Interview me relentlessly about every aspect of this plan until we reach a shared understanding. Walk down each branch of the design tree, resolving dependencies between decisions one-by-one. For each question, provide your recommended answer.
+
+Ask the questions one at a time, waiting for feedback on each question before continuing.
+
+If a question can be answered by exploring the codebase, explore the codebase instead.
+
+</what-to-do>
+
+<supporting-info>
+
+## Domain awareness
+
+During codebase exploration, also look for existing documentation:
+
+### File structure
+
+Most repos have a single context:
+
+```
+/
+├── CONTEXT.md
+├── docs/
+│   └── adr/
+│       ├── 0001-event-sourced-orders.md
+│       └── 0002-postgres-for-write-model.md
+└── src/
+```
+
+If a `CONTEXT-MAP.md` exists at the root, the repo has multiple contexts. The map points to where each one lives:
+
+```
+/
+├── CONTEXT-MAP.md
+├── docs/
+│   └── adr/                          ← system-wide decisions
+├── src/
+│   ├── ordering/
+│   │   ├── CONTEXT.md
+│   │   └── docs/adr/                 ← context-specific decisions
+│   └── billing/
+│       ├── CONTEXT.md
+│       └── docs/adr/
+```
+
+Create files lazily — only when you have something to write. If no `CONTEXT.md` exists, create one when the first term is resolved. If no `docs/adr/` exists, create it when the first ADR is needed.
+
+## 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 the user uses vague or overloaded terms, propose a precise canonical term. "You're saying 'account' — do you mean the Customer or the User? Those are different things."
+
+### Discuss concrete scenarios
+
+When domain relationships are being discussed, stress-test them with specific scenarios. Invent scenarios that probe edge cases and force the user to be precise about the boundaries between concepts.
+
+### Cross-reference with code
+
+When the user states how something works, check whether the code agrees. If you find a contradiction, surface it: "Your code cancels entire Orders, but you just said partial cancellation is possible — which is right?"
+
+### Update CONTEXT.md inline
+
+When a term is resolved, update `CONTEXT.md` right there. Don't batch these up — capture them as they happen. Use the format in [context-format.md](./context-format.md).
+
+`CONTEXT.md` should be totally devoid of implementation details. Do not treat `CONTEXT.md` as a spec, a scratch pad, or a repository for implementation decisions. It is a glossary and nothing else.
+
+### Offer ADRs sparingly
+
+Only offer to create an ADR 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 did they do it 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 the ADR. Use the format in [adr-format.md](./adr-format.md).
+
+</supporting-info>

package/skills/grill-with-docs/adr-format.md

@@ -0,0 +1,47 @@
+# ADR Format
+
+ADRs live in `docs/adr/` and use sequential numbering: `0001-slug.md`, `0002-slug.md`, etc.
+
+Create the `docs/adr/` directory lazily — only when the first ADR is needed.
+
+## Template
+
+```md
+# {Short title of the decision}
+
+{1-3 sentences: what's the context, what did we decide, and why.}
+```
+
+That's it. 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 include these when they add genuine value. Most ADRs won't need them.
+
+- **Status** frontmatter (`proposed | accepted | deprecated | superseded by ADR-NNNN`) — useful when decisions are revisited
+- **Considered Options** — only when the rejected alternatives are worth remembering
+- **Consequences** — only when non-obvious downstream effects need to be called out
+
+## Numbering
+
+Scan `docs/adr/` for the highest existing number and increment by one.
+
+## When to offer an ADR
+
+All three of these must be true:
+
+1. **Hard to reverse** — the cost of changing your mind later is meaningful
+2. **Surprising without context** — a future reader will look at the code and wonder "why on earth did they do it this way?"
+3. **The result of a real trade-off** — there were genuine alternatives and you picked one for specific reasons
+
+If a decision is easy to reverse, skip it — you'll just reverse it. If it's not surprising, nobody will wonder why. If there was no real alternative, there's nothing to record beyond "we did the obvious thing."
+
+### What qualifies
+
+- **Architectural shape.** "We're using a monorepo." "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 out.
+- **Boundary and scope decisions.** "Customer data is owned by the Customer context; other contexts reference it by ID only." The explicit no-s are as valuable as the yes-s.
+- **Deliberate deviations from the obvious path.** "We're using manual SQL instead of an ORM 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 can't use AWS because of compliance requirements." "Response times must be under 200ms because of the partner API contract."
+- **Rejected alternatives when the rejection is non-obvious.** If you considered GraphQL and picked REST for subtle reasons, record it — otherwise someone will suggest GraphQL again in six months.