aw-ecc 1.4.31 → 1.4.47

package/skills/aw-spec/SKILL.md

@@ -72,6 +72,19 @@ Capture at least:
 - ADR-needed decision when the change has durable architectural impact
 - rollout, migration, or environment constraints when relevant
 
+## Human HTML Companion
+
+Markdown `spec.md` remains canonical for agents.
+When this helper writes or materially updates `spec.md`, also create or refresh `.aw_docs/features/<feature_slug>/spec.html`. HTML sidecars are required stage outputs, not advisory metadata.
+
+Delegate to the `aw:echo` subagent with the `technical-spec` profile.
+Invoking `/aw:plan` or `aw-spec` in default `dual` mode is explicit authorization to spawn exactly one `aw:echo` subagent for HTML companion generation; do not skip HTML only because no direct command is available.
+Resolve output mode as: explicit user request for Markdown-only -> otherwise `dual`. `.aw_docs/config.json` and `AW_DOCS_OUTPUT_MODE` may request `dual` or `html`, but must not silently suppress required SDLC HTML sidecars.
+
+Pass the approved direction, `spec.md`, relevant source paths, risks, alternatives, interfaces, rollout constraints, and validation strategy as the source bundle.
+Record the colocated sidecar in `state.json` `html_companion_artifacts` with `source_path`, `html_path`, profile, status, `run_ref` when available, publish status, and any explicit Markdown-only skip or fallback reason.
+Spawn exactly one `aw:echo` subagent and wait for the colocated `.html` sidecar before the final handoff unless the user explicitly asks not to wait. If the harness still cannot spawn `aw:echo`, create a conservative self-contained fallback HTML sidecar in the same turn using the `aw:echo` safety and design contract, record `generated_fallback` plus the blocker, and keep Markdown canonical.
+
 ## Common Rationalizations
 
 | Rationalization | Reality |
@@ -101,6 +114,7 @@ Before handoff, run this inline review:
 6. alternatives and decision-rationale check
 7. testing and operations completeness check
 8. ambiguity check
+9. HTML companion file exists, or the user explicitly requested Markdown-only
 
 Fix issues inline instead of carrying them into task planning.
 
@@ -124,5 +138,6 @@ Always end with:
 - `Testing Strategy`
 - `Assumptions & Constraints`
 - `Acceptance Criteria`
+- `HTML Companion`
 - `Open Approval Needs`
 - `Recommended Next`

package/skills/aw-tasks/SKILL.md

@@ -127,6 +127,19 @@ Never write:
 
 If a worker would have to guess, the task is not ready.
 
+## Human HTML Companion
+
+Markdown `tasks.md` remains canonical for agents.
+When this helper writes or materially updates `tasks.md`, also create or refresh `.aw_docs/features/<feature_slug>/tasks.html`. HTML sidecars are required stage outputs, not advisory metadata.
+
+Delegate to the `aw:echo` subagent with the `implementation-plan` profile.
+Invoking `/aw:plan` or `aw-tasks` in default `dual` mode is explicit authorization to spawn exactly one `aw:echo` subagent for HTML companion generation; do not skip HTML only because no direct command is available.
+Resolve output mode as: explicit user request for Markdown-only -> otherwise `dual`. `.aw_docs/config.json` and `AW_DOCS_OUTPUT_MODE` may request `dual` or `html`, but must not silently suppress required SDLC HTML sidecars.
+
+Pass `spec.md`, `tasks.md`, phase order, file map, parallelization metadata, validation commands, save-point expectations, and handoff notes as the source bundle.
+Record the colocated sidecar in `state.json` `html_companion_artifacts` with `source_path`, `html_path`, profile, status, `run_ref` when available, publish status, and any explicit Markdown-only skip or fallback reason.
+Spawn exactly one `aw:echo` subagent and wait for the colocated `.html` sidecar before the final handoff unless the user explicitly asks not to wait. If the harness still cannot spawn `aw:echo`, create a conservative self-contained fallback HTML sidecar in the same turn using the `aw:echo` safety and design contract, record `generated_fallback` plus the blocker, and keep Markdown canonical.
+
 ## Verification
 
 Before handoff:
@@ -138,6 +151,7 @@ Before handoff:
 5. confirm behavior-changing slices use explicit `RED -> GREEN -> REFACTOR` wording or explicitly justify why test-first is not meaningful
 6. confirm the execution mode and review mode are clear when they can be known safely
 7. confirm execution can route straight to `/aw:build`
+8. confirm the HTML companion file exists, or that the user explicitly requested Markdown-only
 
 ## Final Output Shape
 
@@ -152,4 +166,5 @@ Always end with:
 - `Review Mode`
 - `Parallel Candidates`
 - `Review Result`
+- `HTML Companion`
 - `Recommended Next`

package/skills/aw-test/SKILL.md

@@ -92,9 +92,23 @@ Every testing handoff must make these things obvious:
 - evidence artifacts
 - failures
 - unavailable checks
+- `html_companion_artifacts`
 - blockers
 - recommended next commands
 
+## Human HTML Companion
+
+Markdown `verification.md` remains canonical for agents.
+When test writes or materially updates `verification.md`, also create or refresh `.aw_docs/features/<feature_slug>/verification.html`. HTML sidecars are required stage outputs, not advisory metadata.
+
+Delegate to the `aw:echo` subagent with the `verification-report` profile.
+Invoking `/aw:test` in default `dual` mode is explicit authorization to spawn exactly one `aw:echo` subagent for HTML companion generation; do not skip HTML only because no direct command is available.
+Resolve output mode as: explicit user request for Markdown-only -> otherwise `dual`. `.aw_docs/config.json` and `AW_DOCS_OUTPUT_MODE` may request `dual` or `html`, but must not silently suppress required SDLC HTML sidecars.
+
+Pass QA scope, checks run, pass/fail/unavailable lanes, runtime evidence, screenshots or links when safe, failures, confidence, and next command as the source bundle.
+Record the colocated sidecar in `state.json` `html_companion_artifacts` with `source_path`, `html_path`, profile, status, `run_ref` when available, publish status, and any explicit Markdown-only skip or fallback reason.
+Spawn exactly one `aw:echo` subagent and wait for the colocated `.html` sidecar before the final handoff unless the user explicitly asks not to wait. If the harness still cannot spawn `aw:echo`, create a conservative self-contained fallback HTML sidecar in the same turn using the `aw:echo` safety and design contract, record `generated_fallback` plus the blocker, and keep Markdown canonical.
+
 ## Verification
 
 Before leaving test, confirm:
@@ -104,6 +118,7 @@ Before leaving test, confirm:
 - [ ] unavailable checks are marked unavailable, not silently passed
 - [ ] fresh evidence is written to `verification.md`
 - [ ] `state.json` is updated with checks, failures, and next action
+- [ ] the HTML companion file exists, or the user explicitly requested Markdown-only
 
 ## Final Output Shape
 
@@ -115,4 +130,5 @@ Always end with:
 - `Evidence`
 - `Failures`
 - `Unavailable`
+- `HTML Companion`
 - `Next`

package/skills/aw-yolo/SKILL.md

@@ -53,6 +53,8 @@ If the user asked for one stage, stay in that stage.
 4. Preserve stage artifacts.
    Internal orchestration is not permission to skip `execution.md`, `verification.md`, `release.md`, or `state.json`.
    A stage is not done until its required artifacts are written.
+   HTML sidecars are required whenever the delegated stage writes a canonical Markdown artifact.
+   When a delegated stage writes a canonical Markdown artifact, preserve that stage's `aw:echo` obligation too: produce the colocated `.aw_docs/features/<feature_slug>/<artifact_basename>.html` companion before the stage handoff. Spawn exactly one `aw:echo` subagent in default `dual` mode; record `run_ref` when the harness exposes one. If the harness still cannot spawn `aw:echo`, create a conservative self-contained fallback HTML sidecar in the same turn, record `generated_fallback` plus the blocker, and keep Markdown canonical. Markdown-only is allowed only when the user explicitly requests it for the run.
 5. Respect stage boundaries.
    `aw-yolo` coordinates stages, but it does not collapse them together.
    Build still cannot self-certify.
@@ -80,6 +82,7 @@ Always end with:
 - `Current Stage`
 - `Completed Stages`
 - `Artifacts Written`
+- `HTML Companions`
 - `Blockers`
 - `Recommended Next`
 
@@ -107,5 +110,6 @@ Always end with:
 - [ ] the selected flow is the smallest correct end-to-end sequence
 - [ ] the chosen starting stage matches the current repo/artifact state
 - [ ] each stage still writes its required artifacts
+- [ ] each eligible stage generated or recorded its HTML companion status
 - [ ] failed stages stop the flow instead of being hand-waved away
 - [ ] blockers name the exact stage where the run stopped

package/skills/diagnose/SKILL.md

@@ -0,0 +1,121 @@
+---
+name: diagnose
+description: Disciplined diagnosis loop for hard bugs and performance regressions. Reproduce → minimise → hypothesise → instrument → fix → regression-test. Use when user says "diagnose this" / "debug this", reports a bug, says something is broken/throwing/failing, or describes a performance regression.
+---
+
+# Diagnose
+
+A discipline for hard bugs. Skip phases only when explicitly justified.
+
+When exploring the codebase, use the project's domain glossary to get a clear mental model of the relevant modules, and check ADRs in the area you're touching.
+
+## When To Use
+
+Use this for unclear bugs, regressions, performance problems, flaky behavior, repeated failed fixes, or any investigation where the next safe move is to build a trustworthy feedback loop before patching.
+
+## Phase 1 — Build a feedback loop
+
+**This is the skill.** Everything else is mechanical. If you have a fast, deterministic, agent-runnable pass/fail signal for the bug, you will find the cause — bisection, hypothesis-testing, and instrumentation all just consume that signal. If you don't have one, no amount of staring at code will save you.
+
+Spend disproportionate effort here. **Be aggressive. Be creative. Refuse to give up.**
+
+### Ways to construct one — try them in roughly this order
+
+1. **Failing test** at whatever seam reaches the bug — unit, integration, e2e.
+2. **Curl / HTTP script** against a running dev server.
+3. **CLI invocation** with a fixture input, diffing stdout against a known-good snapshot.
+4. **Headless browser script** (Playwright / Puppeteer) — drives the UI, asserts on DOM/console/network.
+5. **Replay a captured trace.** Save a real network request / payload / event log to disk; replay it through the code path in isolation.
+6. **Throwaway harness.** Spin up a minimal subset of the system (one service, mocked deps) that exercises the bug code path with a single function call.
+7. **Property / fuzz loop.** If the bug is "sometimes wrong output", run 1000 random inputs and look for the failure mode.
+8. **Bisection harness.** If the bug appeared between two known states (commit, dataset, version), automate "boot at state X, check, repeat" so you can `git bisect run` it.
+9. **Differential loop.** Run the same input through old-version vs new-version (or two configs) and diff outputs.
+10. **HITL bash script.** Last resort. If a human must click, drive _them_ with `scripts/hitl-loop.template.sh` so the loop is still structured. Captured output feeds back to you.
+
+Build the right feedback loop, and the bug is 90% fixed.
+
+### Iterate on the loop itself
+
+Treat the loop as a product. Once you have _a_ loop, ask:
+
+- Can I make it faster? (Cache setup, skip unrelated init, narrow the test scope.)
+- Can I make the signal sharper? (Assert on the specific symptom, not "didn't crash".)
+- Can I make it more deterministic? (Pin time, seed RNG, isolate filesystem, freeze network.)
+
+A 30-second flaky loop is barely better than no loop. A 2-second deterministic loop is a debugging superpower.
+
+### Non-deterministic bugs
+
+The goal is not a clean repro but a **higher reproduction rate**. Loop the trigger 100×, parallelise, add stress, narrow timing windows, inject sleeps. A 50%-flake bug is debuggable; 1% is not — keep raising the rate until it's debuggable.
+
+### When you genuinely cannot build a loop
+
+Stop and say so explicitly. List what you tried. Ask the user for: (a) access to whatever environment reproduces it, (b) a captured artifact (HAR file, log dump, core dump, screen recording with timestamps), or (c) permission to add temporary production instrumentation. Do **not** proceed to hypothesise without a loop.
+
+Do not proceed to Phase 2 until you have a loop you believe in.
+
+## Phase 2 — Reproduce
+
+Run the loop. Watch the bug appear.
+
+Confirm:
+
+- [ ] The loop produces the failure mode the **user** described — not a different failure that happens to be nearby. Wrong bug = wrong fix.
+- [ ] The failure is reproducible across multiple runs (or, for non-deterministic bugs, reproducible at a high enough rate to debug against).
+- [ ] You have captured the exact symptom (error message, wrong output, slow timing) so later phases can verify the fix actually addresses it.
+
+Do not proceed until you reproduce the bug.
+
+## Phase 3 — Hypothesise
+
+Generate **3–5 ranked hypotheses** before testing any of them. Single-hypothesis generation anchors on the first plausible idea.
+
+Each hypothesis must be **falsifiable**: state the prediction it makes.
+
+> Format: "If <X> is the cause, then <changing Y> will make the bug disappear / <changing Z> will make it worse."
+
+If you cannot state the prediction, the hypothesis is a vibe — discard or sharpen it.
+
+**Show the ranked list to the user before testing.** They often have domain knowledge that re-ranks instantly ("we just deployed a change to #3"), or know hypotheses they've already ruled out. Cheap checkpoint, big time saver. Don't block on it — proceed with your ranking if the user is AFK.
+
+## Phase 4 — Instrument
+
+Each probe must map to a specific prediction from Phase 3. **Change one variable at a time.**
+
+Tool preference:
+
+1. **Debugger / REPL inspection** if the env supports it. One breakpoint beats ten logs.
+2. **Targeted logs** at the boundaries that distinguish hypotheses.
+3. Never "log everything and grep".
+
+**Tag every debug log** with a unique prefix, e.g. `[DEBUG-a4f2]`. Cleanup at the end becomes a single grep. Untagged logs survive; tagged logs die.
+
+**Perf branch.** For performance regressions, logs are usually wrong. Instead: establish a baseline measurement (timing harness, `performance.now()`, profiler, query plan), then bisect. Measure first, fix second.
+
+## Phase 5 — Fix + regression test
+
+Write the regression test **before the fix** — but only if there is a **correct seam** for it.
+
+A correct seam is one where the test exercises the **real bug pattern** as it occurs at the call site. If the only available seam is too shallow (single-caller test when the bug needs multiple callers, unit test that can't replicate the chain that triggered the bug), a regression test there gives false confidence.
+
+**If no correct seam exists, that itself is the finding.** Note it. The codebase architecture is preventing the bug from being locked down. Flag this for the next phase.
+
+If a correct seam exists:
+
+1. Turn the minimised repro into a failing test at that seam.
+2. Watch it fail.
+3. Apply the fix.
+4. Watch it pass.
+5. Re-run the Phase 1 feedback loop against the original (un-minimised) scenario.
+
+## Phase 6 — Cleanup + post-mortem
+
+Required before declaring done:
+
+- [ ] Original repro no longer reproduces (re-run the Phase 1 loop)
+- [ ] Regression test passes (or absence of seam is documented)
+- [ ] All `[DEBUG-...]` instrumentation removed (`grep` the prefix)
+- [ ] Throwaway prototypes deleted (or moved to a clearly-marked debug location)
+- [ ] The hypothesis that turned out correct is stated in the commit / PR message — so the next debugger learns
+
+**Then ask: what would have prevented this bug?** If the answer involves architectural change (no good test seam, tangled callers, hidden coupling), hand off to the `improve-codebase-architecture` skill with the specifics. Make the recommendation **after** the fix is in, not before — you have more information now than when you started.

package/skills/diagnose/scripts/hitl-loop.template.sh

@@ -0,0 +1,41 @@
+#!/usr/bin/env bash
+# Human-in-the-loop reproduction loop.
+# Copy this file, edit the steps below, and run it.
+# The agent runs the script; the user follows prompts in their terminal.
+#
+# Usage:
+#   bash hitl-loop.template.sh
+#
+# Two helpers:
+#   step "<instruction>"          → show instruction, wait for Enter
+#   capture VAR "<question>"      → show question, read response into VAR
+#
+# At the end, captured values are printed as KEY=VALUE for the agent to parse.
+
+set -euo pipefail
+
+step() {
+  printf '\n>>> %s\n' "$1"
+  read -r -p "    [Enter when done] " _
+}
+
+capture() {
+  local var="$1" question="$2" answer
+  printf '\n>>> %s\n' "$question"
+  read -r -p "    > " answer
+  printf -v "$var" '%s' "$answer"
+}
+
+# --- edit below ---------------------------------------------------------
+
+step "Open the app at http://localhost:3000 and sign in."
+
+capture ERRORED "Click the 'Export' button. Did it throw an error? (y/n)"
+
+capture ERROR_MSG "Paste the error message (or 'none'):"
+
+# --- edit above ---------------------------------------------------------
+
+printf '\n--- Captured ---\n'
+printf 'ERRORED=%s\n' "$ERRORED"
+printf 'ERROR_MSG=%s\n' "$ERROR_MSG"

package/skills/finish-only-when-green/SKILL.md

@@ -0,0 +1,265 @@
+---
+name: finish-only-when-green
+description: Use when the user says continue until done, do not stop early, loop until all tests pass, or wants artifact-based completion for package, release, setup, or validation workflows. Enforces an explicit done contract, repeated fix-and-rerun loops, blocker-only pauses, and a final proof artifact before claiming completion.
+---
+
+# Finish Only When Green
+
+Use this skill when the user wants persistent execution until the work is actually complete, especially for:
+- release validation
+- package publishing
+- fresh environment setup
+- end-to-end CLI smoke testing
+- regression fixing loops
+- “don’t stop until it’s done” requests
+
+## Core Rule
+
+Do not stop at a status update if the explicit completion gates are not green.
+
+Do not silently downgrade or replace the top-level completion contract mid-run.
+If the final release gate is red, then the task is still red even if many sub-checks are green.
+
+Do not enter the fix-and-rerun loop until `green` is defined clearly enough to be testable.
+
+If the task has ambiguous success criteria, first tighten the goal, define the gates, and identify the proof artifact.
+
+Only pause when one of these is true:
+- a real external blocker exists
+- credentials, permissions, or network access are missing
+- the user must choose between materially different outcomes
+
+Otherwise, continue the loop yourself.
+
+## Required Workflow
+
+### 1. Define Green First
+
+Before substantial work, write down the exact completion contract in 3-6 bullets.
+
+Use concrete gates such as:
+- package published
+- fresh workspace created
+- init command succeeded
+- Cursor/Codex/Claude smoke passed
+- summary artifact written
+
+If there is no proof artifact, the task is not done.
+
+Prefer one final source-of-truth artifact whenever possible:
+- `summary.json`
+- `summary.txt`
+- release-gate report
+
+Do not substitute a collection of scattered green artifacts for the final gate unless the user explicitly changes the contract.
+
+The definition of green must be:
+- observable
+- specific
+- scoped
+- rerunnable
+- tied to one or more artifacts or commands
+
+Bad:
+- "works"
+- "looks good"
+- "mostly done"
+- "migration seems safe"
+
+Good:
+- `npm run test:e2e:staging -- --grep @CONVERSATIONS_V2` passes
+- visual diff report exists and is within threshold
+- summary JSON says `GREEN`
+
+### 2. Ask Sharp Questions Before Looping
+
+If the user has not defined green well enough, ask the smallest set of questions needed before entering the loop.
+
+Ask at most 1-3 short, high-value questions.
+
+Good question types:
+- Which environment is the source of truth: local, staging, or production-like?
+- What exact flows are in scope for green, and what is explicitly out of scope?
+- What proof artifact should exist at the end?
+- Should visual checks be exact pixel match, perceptual tolerance, or layout-contract based?
+- Are we blocking on all tests, only tagged tests, or only a specific suite?
+
+Do not ask broad or deferring questions like:
+- "What do you want me to do?"
+- "How should I proceed?"
+- "Anything else?"
+
+If you can make a safe default assumption, do so and state it before starting the loop.
+
+### 3. Write the Done Contract Down
+
+Before the loop starts, write down:
+- the goal
+- the exact green state
+- the commands or checks that prove it
+- the proof artifact path
+- what is still red at the start
+
+If this is missing, the loop has not started yet.
+
+### 4. Work in a Green Loop
+
+Run this loop until all gates pass:
+1. execute the next highest-value check
+2. inspect the failure precisely
+3. patch the smallest correct fix
+4. rerun the affected check
+5. rerun the full gate when needed
+
+Do not keep re-running the same broken step without changing anything.
+
+### 5. Prefer Narrow Reruns, Then Full Confirmation
+
+After a fix:
+- rerun the failing case first
+- once it passes, rerun the broader suite that proves the whole contract
+
+Do not stop after targeted reruns if the top-level suite has not been rerun successfully.
+
+### 6. Report Progress Without Pretending Done
+
+Intermediary updates should say:
+- what gate is green
+- what gate is still red
+- what you are doing next
+
+Do not frame “partially working” as complete.
+
+Every substantial status update should include one explicit overall state line:
+- `Overall state: GREEN`
+- `Overall state: RED`
+
+If any required gate is red, the overall state is red.
+
+### 7. End With Proof
+
+A task is complete only when you can point to the final proof artifact, for example:
+- `summary.json`
+- `summary.txt`
+- published package version
+- init log
+- smoke verdict files
+
+## Default Completion Template
+
+When the user has not given exact gates, use:
+- explicit goal statement written down
+- exact green state written down
+- implementation or config change applied
+- focused verification passed
+- broader workflow rerun passed
+- final artifact saved
+
+## Green State Template
+
+Use this template at the start of the task whenever green is not already explicit:
+
+- Goal:
+- Green means:
+- Required checks:
+- Proof artifact:
+- Initial red gates:
+
+## Pre-Loop Checklist
+
+Before entering the loop, confirm:
+- the success criteria are concrete
+- the scope is bounded
+- the proving command or commands are known
+- the proof artifact is known
+- any unclear tradeoff has been resolved or safely assumed
+
+If one of these is missing, clarify first.
+
+## Packaging / E2E Variant
+
+For package or release workflows, default gates are:
+- package version created or published
+- fresh isolated init succeeded
+- local init succeeded
+- real harness smoke passed for the required CLIs
+- final summary artifact exists and is green
+
+Preferred execution order:
+1. fix contract drift
+2. fix generated artifact drift
+3. fix narrow harness/case failures
+4. rerun aggregated release gate
+5. publish only after the aggregated release gate is green
+
+For migration or regression programs, default gates are:
+- scope inventory exists
+- machine-readable coverage or gate file exists
+- high-priority gaps are identified
+- targeted regression suite passes
+- differential or comparison checks pass if required
+- final summary artifact exists and is green
+
+## Ralph Loop Additions
+
+Borrow these behaviors from Ralph Loop when the work is release-critical, verification-heavy, or prone to false positives.
+
+### 1. One Red Gate Per Iteration
+
+At any given moment, choose one primary red gate.
+
+Examples:
+- `hook-contracts` is red
+- `cursor-generated-output` is red
+- `published-package-init` is red
+- `claude:review-security-risk` is red
+- `release-gate summary artifact` is red
+
+Use that gate to drive the next fix. Do not chase multiple unclear failures at once unless they are truly independent.
+
+### 2. Fresh-Context Iterations
+
+After each meaningful fix, restate the current state from fresh evidence:
+- what is green
+- what is still red
+- what exact artifact is missing or failing
+
+Do not let stale assumptions from earlier attempts drive the next step.
+
+### 3. Backpressure Through the Top-Level Gate
+
+Use narrow reruns for diagnosis, but keep pressure on the top-level gate that proves completion.
+
+If the final gate is still red, the workflow is still red.
+
+### 4. Artifact-Only Exit
+
+A loop iteration may look successful, but the workflow is not complete until the chosen final artifact says green.
+
+Examples:
+- release summary says all gates passed
+- final smoke summary includes all required harnesses and all required cases
+- package validation report is fully green
+
+### 5. Explicit Contract Changes Only
+
+If you discover a better proving method mid-run:
+- explicitly restate the updated contract
+- explain why the old one is insufficient
+- then continue
+
+Do not quietly switch from a strict gate to a weaker gate.
+
+## Anti-Patterns
+
+Do not:
+- enter an infinite loop without first defining what exits the loop
+- confuse activity with progress when green is vague
+- claim coverage is complete without a written scope inventory
+- stop after the first success if later gates remain red
+- stop after publishing if install/init/smoke is still unverified
+- stop after one harness passes if the release gate requires all harnesses
+- claim success from memory when the latest rerun is missing
+- replace the final release gate with a weaker ad hoc check set without explicitly updating the contract
+- say “mostly green” when the final summary artifact is missing or still red
+- leave a known red gate for later if you still have a clear next step and the user asked you to continue until done

package/skills/grill-me/SKILL.md

@@ -0,0 +1,24 @@
+---
+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".
+---
+
+# Grill Me
+
+## When To Use
+
+Use this when the user explicitly wants a plan, design, proposal, or decision to be challenged through questions before it becomes an artifact or implementation direction.
+
+## Workflow
+
+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.
+
+## Guardrails
+
+- Keep questions concrete and decision-oriented.
+- Do not ask questions that local repo exploration can answer cheaply.
+- Stop once the important decisions are clear enough for the next AW stage.

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

@@ -0,0 +1,92 @@
+---
+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.
+---
+
+## When To Use
+
+Use this inside planning when the problem is fuzzy, domain language is overloaded, acceptance criteria are under-specified, or existing docs/code may contradict the user's mental model.
+
+<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).
+
+Don't couple `CONTEXT.md` to implementation details. Only include terms that are meaningful to domain experts.
+
+### 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>