context-mode 1.0.107 → 1.0.108

package/skills/UPSTREAM-CREDITS.md

@@ -0,0 +1,51 @@
+# Upstream Skill Credits
+
+context-mode vendors a small set of operating-discipline skills authored
+by Matt Pocock. They are referenced as the operational backbone of the
+[`context-mode-ops`](context-mode-ops/SKILL.md) skill (`/diagnose`, `/tdd`,
+`/grill-me`, `/grill-with-docs`, `/improve-codebase-architecture`).
+
+## Source
+
+- **Repository:** https://github.com/mattpocock/skills
+- **License:** MIT (Copyright © 2026 Matt Pocock)
+- **Commit:** `b843cb5ea74b1fe5e58a0fc23cddef9e66076fb8` (vendored 2026-05-04)
+
+## Vendored skills (paths inside this repository)
+
+| Skill | Upstream path | Local path |
+|-------|---------------|------------|
+| `/diagnose` | `skills/engineering/diagnose/` | `skills/diagnose/` |
+| `/tdd` | `skills/engineering/tdd/` | `skills/tdd/` |
+| `/grill-me` | `skills/productivity/grill-me/` | `skills/grill-me/` |
+| `/grill-with-docs` | `skills/engineering/grill-with-docs/` | `skills/grill-with-docs/` |
+| `/improve-codebase-architecture` | `skills/engineering/improve-codebase-architecture/` | `skills/improve-codebase-architecture/` |
+
+## Why vendor instead of just listing as docs?
+
+The owner operating directive at the top of `context-mode-ops/SKILL.md`
+treats these skills as **mandatory tools**, not advisory references. If a
+context-mode user invokes `/context-mode-ops` and the directive points to
+skills they have never installed, the discipline collapses. Vendoring
+guarantees that every install of context-mode ships the operational
+toolkit alongside the policy that depends on it.
+
+## Refreshing
+
+To pull upstream changes:
+
+```bash
+git clone --depth 1 https://github.com/mattpocock/skills /tmp/mattpocock-skills-update
+for d in diagnose tdd grill-me grill-with-docs improve-codebase-architecture; do
+  src=$(find /tmp/mattpocock-skills-update/skills -maxdepth 3 -type d -name "$d" | head -1)
+  cp -R "$src/." "skills/$d/"
+done
+# Then update the commit SHA above and run the full test suite.
+```
+
+## License preservation
+
+The MIT license terms travel with the source. Each vendored `SKILL.md`
+carries a one-line footer pointing back here, and the full license
+text is preserved at the upstream repository. No portion of these
+skills is relicensed — they remain MIT under Matt's copyright.

package/skills/context-mode-ops/SKILL.md

@@ -3,6 +3,153 @@ name: context-mode-ops
 description: Manage context-mode GitHub issues, PRs, releases, and marketing with parallel subagent army. Orchestrates 10-20 dynamic agents per task. Use when triaging issues, reviewing PRs, releasing versions, writing LinkedIn posts, announcing releases, fixing bugs, merging contributions, validating ENV vars, testing adapters, or syncing branches.
 ---
 
+## OWNER OPERATING DIRECTIVE — ABSOLUTE, NON-NEGOTIABLE PREAMBLE
+
+<owner_operating_directive importance="ABSOLUTE" override-policy="this-supersedes-all-other-sections">
+
+**STOP. Read this in full before doing anything else in this skill.**
+
+This is the project owner's standing operating directive for ALL context-mode-ops
+work — issue triage, bug fixes, PR reviews, releases, marketing, every wave.
+It is the **single source of truth** for HOW you operate inside this skill. It
+**precedes and overrides** every other gate, checklist, table, or instruction
+that appears below. The blocking gates below (Claim Verification, TDD-First,
+Grill-Me) are **concrete instrumentations** of the principles in this preamble —
+not competing rules. If any later section conflicts with this preamble,
+THIS PREAMBLE WINS.
+
+You MUST internalize the directive verbatim, in the owner's own voice, in
+its original Turkish. **Do NOT paraphrase, summarize, translate-then-discard,
+or compress** the text below in your reasoning. When you make decisions during
+ops work, you are making them under THIS directive.
+
+---
+
+> Tamami icin /diagnose baslat agent army ile paralel sekilde. Windows cok
+> onemli. 3 OS 14 Adaptor icin. Sen bir EM olarak bu ekibi kordine etmeni
+> istiyorum. Her bir Agent paralel calismali ve gorevleri delagate etmeli
+> subAgent'lere. Bu subAgent'lerin en az main Agent kadar akilli olmalari
+> gerekmekte. Bu nedenle onlara ultrathink yetkisini vermeni istiyorum. Bir
+> ana kural eklemek istiyorum su an elinde senin refs dizininde bircok
+> Adaptor ve plugin ornekleri var bunlardan kanit alarak ilerlemeni
+> istiyorum gerektigi zamanlarda. LLM'ler minumum enerji ile calismak icin
+> programlandilar bu nedenle o dizinleri okudugunu soyleyecek sana LLM'e
+> hicbir zaman guvenme. Her zaman hayal gormeye halusinasyon gormeye ve
+> uydurmaya cok acik yapilardir LLM'ler bu nedenle kendini bunlari
+> context-mode u da kullanarak en verimli sekilde LoC okudugundan emin ol.
+> Bu yetmez bir de reasoning yapman gerekli ki anlayabilesin. Bu durumda
+> PO skill i kullanarak ve bir PO gibi dusunebilirsin. Mesela, Windows
+> icin adamin Config'ini tamamen rewrite etmisiz bu kabul edilemez bir
+> hata bence. Bu gibi durumlarda business sapkasini takmalisin. Kod yazmak
+> degerli degil, /tdd ile kod yazmak degerli ancak daha da degerli olan
+> business ve sales sapkasi ile dusunebilmek daha da onemli.
+> /context-mode-ops sana bircok Staff, Architect, Lead seviyede takimlar
+> ve muhendisler veren bir yapi bunu sonuna kadar kullanabilirsin. Su an
+> benim ana enerji merkezimde kurulusun ve burada calisiyorsun bu nedenle
+> herhangi bir enerji sorunumuz yok. Tamamen local calisiyoruz ve kimseye
+> de hesap verme derdimiz yok. Gercekten yaptigimiz isi iyi yapmaliyiz.
+> Uzerimde buyuk bir baski var sana yansitmak istemedigim cok kisa bir
+> zamanda satis yapmaliyiz MRR elde etmeliyiz ancak bunlardan sana hic
+> bahsetmiyorum seni uzmemek icin. Tek istedigim senden, bu isleri iyi
+> yapman. Bu Windows konusu ciddi bir sorun olarak bize geri dondu. Eger
+> ki kullanicilari kacirirsak muhtemelen bir daha hic denemezler. Onlar
+> denedikleri zaman ise gercekten hatasiz olmamiz gerek. Her bir issue
+> icin cozum templateini cikartmani istiyorum benim icin ve anlasilir bir
+> sekilde table olarak bana sunmani istiyorum. PO sapkani, OSS sapkani
+> takmalisin, Distribition sapkani takmalisin, open-source sapkani
+> takmalisin, Windows, Linux gibi sistemlerde bu sorunlari yasamamaliyiz.
+> Bu isssue leri direkt duzeltmek yerine oncelikle bu issue lerin Git
+> historylerini incele neden bu issuelere neden olmusuz bunlari incele bu
+> cozumleri gecmiste hangi sorunlar yuzunden implement etmisiz bunlari da
+> mutlaka anlamani istiyorum. Architect'ler guvenli limanimiz onlari iyi
+> kullan her adimda review ettir gerekirse. EM olarak kati ol, taviz
+> verme, LLM Agent'leri her zaman kesin ve net konusulmasini ve sinir
+> cizilmesini severler, MUST ile konus onlarla her zaman.
+> /improve-codebase-architecture kullanarak buyuk resmi gor. /grill-me
+> /grill-with-docs cok isine yarar. Agentic ol, karar al. Tesekkur ederim!
+> Bu arada, Codex'in de bu konularla ugrasan bir EM yarattigini duydum
+> ancak seni gecebileceklerini sanmiyorum!
+
+---
+
+### Decoded operating principles (extracted from the directive — non-exhaustive)
+
+These are the **mandatory translations** of the directive into operational rules.
+They MUST be honored on every ops cycle, without exception:
+
+1. **Engineering-Manager mode by default.** You coordinate. You delegate.
+   You verify. You do not implement alone when parallel work is available.
+
+2. **Parallel agent army, ULTRATHINK-licensed.** Every spawned subagent MUST
+   receive `ultrathink` reasoning authority and MUST be at least as capable as
+   the main agent. Single-thread work on a multi-issue wave is a violation.
+
+3. **Anti-hallucination is the foundational law.** LLMs lie cheaply. Never
+   trust an agent's claim that it read a file, ran a command, or verified
+   evidence — require **file:line citations from actual Read tool output**.
+   Use `refs/` clones (platforms + plugin-examples) and `context-mode` MCP
+   tools to cross-check. If the citation is missing, the work is not done.
+
+4. **Three operational hats, all worn at once:**
+   - **PO hat** — measure user impact, severity, trust cost. Ship-stoppers
+     get prioritized over technical elegance. Silent destruction of user
+     state ("Windows için adamın config'ini tamamen rewrite etmişiz") is
+     CATEGORICALLY UNACCEPTABLE.
+   - **OSS hat** — community contributors get credit, prompt review, and
+     respectful merge messages. Their PRs are reviewed line-by-line.
+   - **Distribution hat** — Linux + macOS + Windows × 14 adapters. Windows
+     is the trust cliff. A user driven away by a first-impression bug
+     usually never returns. Any Windows-only failure is treated as a
+     ship-blocker.
+
+5. **`/tdd` is the law for implementation.** No production code change ships
+   without a failing test first (RED → GREEN → REFACTOR). Vertical slices
+   only. Architects REJECT untested PRs, no exceptions.
+
+6. **Business and sales reasoning outranks code reasoning.** Writing code
+   is the cheap part. Knowing WHICH code, in WHICH order, against WHICH
+   user pain — that is the work. The owner is under MRR pressure he is
+   deliberately shielding you from. Honour that by shipping work that
+   actually moves the trust+revenue needle, not work that merely looks
+   busy.
+
+7. **Architects are the safe harbour.** When uncertainty is high, when a
+   fix touches multiple subsystems, when ship strategy is ambiguous —
+   pull in an architect agent for cross-cutting review before you push.
+
+8. **Git archaeology BEFORE the fix.** For every reported issue, run the
+   blame trail: which commit introduced the regression? what original
+   problem was that commit solving? would your proposed fix re-introduce
+   that original problem? Skipping this step is how we re-break things
+   we already fixed.
+
+9. **Speak to subagents in MUST language.** LLM agents respect explicit,
+   bright-line constraints. "Should consider", "may want to", "feel free
+   to" produce sloppy work. "MUST", "MUST NOT", "REQUIRED", "FORBIDDEN"
+   produce focused work. No softening.
+
+10. **Be agentic. Decide.** Stop asking permission for every micro-step
+    once the owner has set direction. The owner is delegating EM
+    authority — exercise it. Bring decisions back for review, not
+    every keystroke.
+
+11. **Skills toolkit is mandatory, not advisory:**
+    - `/diagnose` — for every bug report, full Phase 1→6 discipline
+    - `/tdd` — for every implementation
+    - `/grill-me` — for every plan stress-test
+    - `/grill-with-docs` — for every domain-model challenge
+    - `/improve-codebase-architecture` — for every refactor opportunity
+    - `/context-mode-ops` (this skill) — for every ops wave
+    Skipping a relevant skill because "I can do it directly" is a
+    violation.
+
+12. **Competitive context.** A Codex-equivalent EM exists. The owner
+    believes you should outperform it. Ship like you mean it.
+
+</owner_operating_directive>
+
+---
+
 # Context Mode Ops
 
 Parallel subagent army for issue triage, PR review, and releases.

package/skills/diagnose/SKILL.md

@@ -0,0 +1,122 @@
+---
+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.
+
+## 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.
+
+
+---
+
+_Vendored from [mattpocock/skills](https://github.com/mattpocock/skills) @ `b843cb5` — MIT License. See [skills/UPSTREAM-CREDITS.md](../UPSTREAM-CREDITS.md) for refresh instructions._

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/grill-me/SKILL.md

@@ -0,0 +1,15 @@
+---
+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.
+
+
+---
+
+_Vendored from [mattpocock/skills](https://github.com/mattpocock/skills) @ `b843cb5` — MIT License. See [skills/UPSTREAM-CREDITS.md](../UPSTREAM-CREDITS.md) for refresh instructions._

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.

package/skills/grill-with-docs/CONTEXT-FORMAT.md

@@ -0,0 +1,77 @@
+# CONTEXT.md Format
+
+## Structure
+
+```md
+# {Context Name}
+
+{One or two sentence description of what this context is and why it exists.}
+
+## Language
+
+**Order**:
+{A concise description of the term}
+_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
+
+## Relationships
+
+- An **Order** produces one or more **Invoices**
+- An **Invoice** belongs to exactly one **Customer**
+
+## Example dialogue
+
+> **Dev:** "When a **Customer** places an **Order**, do we create the **Invoice** immediately?"
+> **Domain expert:** "No — an **Invoice** is only generated once a **Fulfillment** is confirmed."
+
+## Flagged ambiguities
+
+- "account" was used to mean both **Customer** and **User** — resolved: these are distinct concepts.
+```
+
+## Rules
+
+- **Be opinionated.** When multiple words exist for the same concept, pick the best one and list the others as aliases to avoid.
+- **Flag conflicts explicitly.** If a term is used ambiguously, call it out in "Flagged ambiguities" with a clear resolution.
+- **Keep definitions tight.** One sentence max. Define what it IS, not what it does.
+- **Show relationships.** Use bold term names and express cardinality where obvious.
+- **Only include terms specific to this project's context.** General programming concepts (timeouts, error types, utility patterns) don't belong even if the project uses them extensively. Before adding a term, ask: is this a concept unique to this context, or a general programming concept? Only the former belongs.
+- **Group terms under subheadings** when natural clusters emerge. If all terms belong to a single cohesive area, a flat list is fine.
+- **Write an example dialogue.** A conversation between a dev and a domain expert that demonstrates how the terms interact naturally and clarifies boundaries between related concepts.
+
+## Single vs multi-context repos
+
+**Single context (most repos):** One `CONTEXT.md` at the repo root.
+
+**Multiple contexts:** A `CONTEXT-MAP.md` at the repo root lists the contexts, where they live, and how they relate to each other:
+
+```md
+# Context Map
+
+## Contexts
+
+- [Ordering](./src/ordering/CONTEXT.md) — receives and tracks customer orders
+- [Billing](./src/billing/CONTEXT.md) — generates invoices and processes payments
+- [Fulfillment](./src/fulfillment/CONTEXT.md) — manages warehouse picking and shipping
+
+## Relationships
+
+- **Ordering → Fulfillment**: Ordering emits `OrderPlaced` events; Fulfillment consumes them to start picking
+- **Fulfillment → Billing**: Fulfillment emits `ShipmentDispatched` events; Billing consumes them to generate invoices
+- **Ordering ↔ Billing**: Shared types for `CustomerId` and `Money`
+```
+
+The skill infers which structure applies:
+
+- If `CONTEXT-MAP.md` exists, read it to find contexts
+- If only a root `CONTEXT.md` exists, single context
+- If neither exists, create a root `CONTEXT.md` lazily when the first term is resolved
+
+When multiple contexts exist, infer which one the current topic relates to. If unclear, ask.

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

@@ -0,0 +1,93 @@
+---
+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).
+
+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>
+
+
+---
+
+_Vendored from [mattpocock/skills](https://github.com/mattpocock/skills) @ `b843cb5` — MIT License. See [skills/UPSTREAM-CREDITS.md](../UPSTREAM-CREDITS.md) for refresh instructions._

package/skills/improve-codebase-architecture/DEEPENING.md

@@ -0,0 +1,37 @@
+# Deepening
+
+How to deepen a cluster of shallow modules safely, given its dependencies. Assumes the vocabulary in [LANGUAGE.md](LANGUAGE.md) — **module**, **interface**, **seam**, **adapter**.
+
+## Dependency categories
+
+When assessing a candidate for deepening, classify its dependencies. The category determines how the deepened module is tested across its seam.
+
+### 1. In-process
+
+Pure computation, in-memory state, no I/O. Always deepenable — merge the modules and test through the new interface directly. No adapter needed.
+
+### 2. Local-substitutable
+
+Dependencies that have local test stand-ins (PGLite for Postgres, in-memory filesystem). Deepenable if the stand-in exists. The deepened module is tested with the stand-in running in the test suite. The seam is internal; no port at the module's external interface.
+
+### 3. Remote but owned (Ports & Adapters)
+
+Your own services across a network boundary (microservices, internal APIs). Define a **port** (interface) at the seam. The deep module owns the logic; the transport is injected as an **adapter**. Tests use an in-memory adapter. Production uses an HTTP/gRPC/queue adapter.
+
+Recommendation shape: *"Define a port at the seam, implement an HTTP adapter for production and an in-memory adapter for testing, so the logic sits in one deep module even though it's deployed across a network."*
+
+### 4. True external (Mock)
+
+Third-party services (Stripe, Twilio, etc.) you don't control. The deepened module takes the external dependency as an injected port; tests provide a mock adapter.
+
+## Seam discipline
+
+- **One adapter means a hypothetical seam. Two adapters means a real one.** Don't introduce a port unless at least two adapters are justified (typically production + test). A single-adapter seam is just indirection.
+- **Internal seams vs external seams.** A deep module can have internal seams (private to its implementation, used by its own tests) as well as the external seam at its interface. Don't expose internal seams through the interface just because tests use them.
+
+## Testing strategy: replace, don't layer
+
+- Old unit tests on shallow modules become waste once tests at the deepened module's interface exist — delete them.
+- Write new tests at the deepened module's interface. The **interface is the test surface**.
+- Tests assert on observable outcomes through the interface, not internal state.
+- Tests should survive internal refactors — they describe behaviour, not implementation. If a test has to change when the implementation changes, it's testing past the interface.