pattyeng 1.0.4 → 1.0.7

package/skills/codebook/SKILL.md

@@ -0,0 +1,184 @@
+---
+name: codebook
+description: Use when a feature needs to be captured as durable reference documentation for a reader who has never seen the codebase, or when existing feature documentation has drifted from current source code and needs reconciliation.
+---
+
+# Codebook
+
+## Overview
+
+A skill for producing a **codebook** — a small, structured set of markdown files that lets a reader who has never seen the codebase understand a specific feature cold. Two modes:
+
+- **Create** — no codebook exists yet → write one from scratch.
+- **Parity sweep** — codebook exists → reconcile it against current source, fix only drifted parts, never rewrite what's still correct.
+
+The output is **always** a folder of 2–4 markdown files inside the project repo, not a single doc and not 8 chapters and not anything in `/tmp`.
+
+## Folder structure (enforced)
+
+```
+docs/codebook/<feature-name>/
+  01-orientation.md        # shallow — readable cold
+  02-walkthrough.md        # medium — guided tour through the code
+  03-deep-dive.md          # deepest — mechanics, invariants, gotchas
+  04-extension-points.md   # practical/forward — how to modify/extend
+  CHANGELOG.md             # one line per create or sweep
+```
+
+**Hard rules:**
+- Folder MUST live at `docs/codebook/<feature-name>/` inside the project repo. Never `/tmp`, never `~/`, never the user's home. If `docs/` doesn't exist, create it.
+- File count MUST be 2–4 chapter files plus `CHANGELOG.md`. Collapse chapters for small features (e.g. trivial bug fix → just `01-orientation.md` + `03-deep-dive.md` + `CHANGELOG.md` = 2 chapters). Never 5+. Never 8.
+- Chapter file names are FIXED. Do not invent `02-code-map.md` or `04-cli-reference.md` or any other naming scheme.
+
+## The four-chapter template
+
+### `01-orientation.md` (shallow)
+
+**Purpose:** A reader who knows nothing can answer "what is this, why does it exist, where does it live?"
+
+**Required sections:**
+- One-paragraph "what is this" (the feature, not the implementation)
+- One-paragraph "why does it exist" (the problem it solves)
+- "Where it lives" — directory tree of the 3–8 most important files, with one-line purpose each
+- "What this is NOT" — 3–6 bullets explicitly bounding scope (e.g. "not a strategy generator", "not the full pipeline")
+- A glossary table for jargon introduced later
+- At least one cross-reference to any existing plan/spec doc (don't duplicate it — point at it)
+
+**Voice and tone:** Direct, second-person. Walk the reader in. No tables-only sections.
+
+### `02-walkthrough.md` (medium)
+
+**Purpose:** Trace a real execution from input to output. One concrete end-to-end path through the code.
+
+**Required sections:**
+- The actual command(s) to invoke the feature (copy-pasteable)
+- The exact data flow: input → which files get read → which functions get called in what order → output artifacts
+- A worked example using a real artifact path from the repo (e.g. an actual intake YAML, an actual config file), not a synthetic one
+- An explicit "where the orchestration lives vs where the library lives" callout — separate the entry point from the supporting modules
+
+**Voice and tone:** Narrative. "First the script does X, then it calls Y which…" Reference tables are allowed in service of the narrative, not in place of it.
+
+### `03-deep-dive.md` (deepest)
+
+**Purpose:** Explain the mechanics. The reader should be able to predict behavior in edge cases after this chapter.
+
+**Required sections:**
+- The actual algorithm/mechanics of every non-obvious operation (e.g. how Wilson LCB is computed, how the sort key works, what the feature-policy classification logic does step-by-step). Pseudocode or short code excerpts are fine.
+- Every invariant the feature enforces (e.g. "test split is never used for ranking"; "every candidate is filtered against floors on both splits")
+- Every gotcha — the things that will silently bite a reader who assumes naive behavior
+- Decisions that were *not* made and why (e.g. "no nested rules because of X"; "no hyperparameter search because of Y")
+
+**Voice and tone:** Detailed. Walk through the math or the logic step by step. Cite function names, constants, and line ranges from the actual source.
+
+### `04-extension-points.md` (practical/forward)
+
+**Purpose:** Reader can modify or extend the feature confidently.
+
+**Required sections:**
+- "How to add X" — concrete recipe for the most likely modification (new feature, new intake, new CLI flag, new sibling script)
+- The exact files you'd touch, in order
+- The tests you'd add or run
+- Common modification pitfalls — things that look easy but break invariants
+
+**Voice and tone:** Imperative. "Edit `intake.py` line N. Add the column name to `LABEL_COLUMNS` if it's a label. Run test Y."
+
+### `CHANGELOG.md`
+
+One line per create or sweep, append-only:
+
+```
+2026-06-24 create — codebook baseline walkthrough for discover_rules.py
+2026-06-25 sweep  — synced against commit abc1234; updated §2 (CLI flags), §3 (bundle layout); added note about new feature_policy.py:quarantine_timing
+```
+
+## Frontmatter (mandatory in every chapter)
+
+Every chapter file MUST begin with:
+
+```yaml
+---
+feature: <feature-name>
+chapter: 01-orientation | 02-walkthrough | 03-deep-dive | 04-extension-points
+last-verified: <commit-hash or ISO date>
+last-verified-by: <agent-name or human-name>
+parity-status: synced | partial | drifted
+---
+```
+
+This is what makes parity sweeps possible — the agent can grep the project for `^feature: <name>` to find all chapters, and `parity-status: drifted` is a maintenance flag.
+
+## Parity-sweep mode
+
+Triggered when `docs/codebook/<feature>/` already exists.
+
+**Workflow:**
+1. Read every chapter file. Extract concrete claims: file paths, function/class names, signatures, defaults, sort keys, constants.
+2. Probe the codebase to verify each claim: `ls`/`find` for paths, `grep`/`rg` for identifiers, reads for flow correctness.
+3. Classify each claim into one of four buckets:
+   - **stale** — was true, no longer true
+   - **missing-coverage** — code added since doc was written, not reflected anywhere
+   - **wrong-rationale** — code behavior matches but the *why* has drifted (a decision was reversed)
+   - **still-true** — leave alone
+4. **Edit surgically.** Only touch the drifted sections. Never rewrite a whole chapter during a sweep — that destroys the parts that are still correct.
+5. Update `last-verified` and `parity-status` in every touched chapter's frontmatter. Set `parity-status: synced` if all claims check out, `partial` if some are stale, `drifted` if the chapter's premise no longer holds.
+6. Append a one-line entry to `CHANGELOG.md` summarizing what was updated, what was added, what was removed.
+7. Report to the user: what was changed, what was deleted, what new code is not yet documented.
+
+## Voice and tone — non-negotiable across every chapter
+
+- **Second person**: "you", "we". Not "the user", not "one".
+- **Define jargon on first use**, then reuse the term freely.
+- **Narrative over tables** when introducing concepts. Tables are reference material — use them after the concept is walked through.
+- **Real file paths, real identifiers, real defaults**. No `path/to/file` placeholders. If the doc says "the default is 0.72", that number must come from the source.
+- **Show, then explain**. A code block, then a paragraph about what it does — never just a paragraph.
+- **"What this is NOT"** in chapter 01 — always. It bounds scope and pre-empts the wrong mental model.
+
+## Anti-patterns (rationalization table)
+
+| Excuse | Reality |
+|---|---|
+| "The feature is small, one file is enough" | Even small features have a why. Use 2 chapters minimum: orientation + deep-dive. |
+| "I'll add more chapters as I find things to write about" | Chapter names are fixed. Add extra material to the appropriate chapter; do not invent new files. |
+| "Let me write to `/tmp` first and copy to the repo later" | The repo IS the deliverable. Writing to /tmp means the doc never ships and never gets version-controlled. Write directly to `docs/codebook/`. |
+| "Frontmatter is overhead, I'll add it later" | Frontmatter is the parity sweep mechanism. Without it, the doc is unfindable and unverifiable. |
+| "The mechanics are obvious from the code" | Obvious to you ≠ obvious to a cold reader. Mechanics chapter is non-negotiable. |
+| "I'll just describe the API surface" | API surface is `02-walkthrough` at best. If that's all you've written, you haven't written a codebook. |
+| "Sweep means I should rewrite the whole chapter to match the new code" | Sweep is surgical. Edit only drifted sections. Preserve what's still correct. That is the whole point. |
+| "I'll skip the changelog, it's just overhead" | Changelog is how the next agent (or future-you) sees what changed without diffing the whole chapter. |
+
+## Red flags — STOP and start over
+
+- File count > 4 chapters (excluding CHANGELOG.md)
+- Any chapter file outside `docs/codebook/<feature>/`
+- Frontmatter missing from any chapter
+- No `CHANGELOG.md`
+- Any chapter that reads like an API reference (no narrative, no "you")
+- Sweep mode that rewrote chapters instead of editing surgically
+- `parity-status: drifted` left unchanged after a sweep that touched the chapter
+
+## Quick reference
+
+| Operation | Where it goes |
+|---|---|
+| "What is this feature?" | `01-orientation.md` §1 |
+| "What problem does it solve?" | `01-orientation.md` §2 |
+| "What files should I read first?" | `01-orientation.md` §3 + `02-walkthrough.md` §1 |
+| "How do I invoke it?" | `02-walkthrough.md` §1 |
+| "How does the data flow?" | `02-walkthrough.md` §2 |
+| "How does X actually compute Y?" | `03-deep-dive.md` §1 |
+| "What invariants does it enforce?" | `03-deep-dive.md` §2 |
+| "How do I add a new <thing>?" | `04-extension-points.md` §1 |
+| "What will break if I change X?" | `04-extension-points.md` §4 |
+| "When was this last verified?" | Frontmatter `last-verified` field, every chapter |
+| "What's been changed in this codebook?" | `CHANGELOG.md` |
+
+## Reference outcome
+
+An unconstrained agent given the same task typically produces one of these failure modes — these are the targets this skill exists to prevent:
+
+- **Single giant doc** — drops everything into one file, often in `/tmp` or `~/`, not in the project repo
+- **Chapter sprawl** — invents 6–10 chapters by topic (code-map, cli-ref, bundle-layout, sibling-scripts, …) instead of the fixed 4-by-depth template
+- **Reference prose** — describes APIs and flags without second-person narrative, no "you", no worked example
+- **No frontmatter** — no way to know when a chapter was last verified or whether the code still matches
+- **No mechanics chapter** — explains *that* a default is 0.72 but never *how* it is computed
+- **No extension chapter** — leaves the reader stuck when they need to modify the feature

package/skills/doc-review/SKILL.md

@@ -0,0 +1,147 @@
+---
+name: doc-review
+description: 'Use right after an agent creates a doc (README, ADR, handoff, worklog entry, design doc, spec, runbook, etc.) — re-reads the doc against the conversation and any related plan/spec/code to catch dropped decisions (gaps), fabricated content (things written that were never decided), drift, staleness, and self-contradiction. Surfaces a punch-list first, then revises the doc in place once the user confirms the findings. Trigger: /doc-review, "review this doc", "check the doc against what we said", "did you miss anything in the doc?".'
+---
+
+# Doc Review
+
+## Overview
+
+A doc you just wrote is a draft. It reflects what you *think* was decided — not what was *actually* decided. Writing it forward from memory guarantees drift. The fix is to check it backward against the source of truth: the conversation, plus any plan, spec, or code the doc should match.
+
+The failure modes are **bidirectional**, and both are silent:
+
+- **Gaps** — discussed and agreed, then quietly dropped from the doc.
+- **Fabrications** — written in the doc but never actually said. Hallucinated requirements, invented constraints, "helpful" additions nobody asked for.
+
+Both slip through a casual re-read because the doc *sounds* right. The check only works if you walk both directions deliberately.
+
+## The source of truth
+
+For a doc just written, the sources of truth are, in order:
+
+1. **The conversation** — primary. Every decision, requirement, constraint, number, name, and edge case lives here.
+2. **The plan / spec / PRD** (if one exists) — defines what "done" means and what the doc must cover.
+3. **The code** (if the doc describes code) — the code is the ground truth; if the doc says the function does X and the function does Y, the doc is wrong.
+4. **Related docs** — for consistency (does this contradict an existing ADR, runbook, or sibling doc?).
+
+If the doc disagrees with any of these, the doc is the thing that's wrong — not the source.
+
+## The bidirectional check
+
+This is the core mechanism. Run it both ways.
+
+### Direction 1: Conversation → Doc (find gaps)
+
+Walk the conversation and ask, for each meaningful decision/requirement/constraint:
+
+- Is it in the doc?
+- Is it in the doc *correctly* — same meaning, not paraphrased into something weaker?
+- Is it in the doc *completely* — including the why, the edge cases, the constraints, not just the headline?
+
+Anything discussed-and-agreed but missing or weakened is a **gap**. List them.
+
+### Direction 2: Doc → Conversation (find fabrications and drift)
+
+Walk the doc section by section and ask, for each claim/requirement/number/name:
+
+- Did we actually decide this? Where in the conversation?
+- Is this what we decided, or a slightly mutated version? (Drift: a number changed, a constraint softened, "must" became "should".)
+- Is this still current, or did a later decision supersede it?
+- Is this in scope? Did the user ask for this, or did I invent it?
+
+Anything in the doc that you cannot trace back to a decision in the conversation is a **fabrication or drift**. List them with the doc location.
+
+### Direction 3: Self-consistency pass
+
+Read the doc end-to-end and check:
+
+- Does section 2 contradict section 4?
+- Does the summary match the body?
+- Are terms used consistently (same word = same meaning throughout)?
+- Are numbers/names/paths consistent across sections?
+
+Internal contradictions are the easiest to miss and the most embarrassing to ship.
+
+## The protocol
+
+### 1. Identify the target doc
+- If the user named a path (`/doc-review path/to/x.md`), use that.
+- Otherwise: the most recently created or edited doc by you this session. State which file you're reviewing — don't review the wrong doc silently.
+
+### 2. Re-read everything (don't skim)
+- The full doc.
+- The full conversation — especially the parts where decisions were made.
+- Any plan/spec/code the doc should match.
+
+### 3. Run the bidirectional check + self-consistency pass
+Produce findings, each tagged:
+- **[GAP]** — discussed, missing or weakened in the doc. Cite where in the conversation it was decided.
+- **[FAB]** — in the doc, not traceable to any decision. Cite the doc location.
+- **[DRIFT]** — in the doc, but mutated from what was decided. Cite both the doc and the conversation.
+- **[STALE]** — in the doc, superseded by a later decision. Cite both.
+- **[CONFLICT]** — internal contradiction, or contradiction with a related doc/ADR/code. Cite both locations.
+- **[VAGUE]** — placeholder-y language where something specific was decided. Cite both.
+
+Each finding must be **specific**: file path, section/heading, line if useful, and the exact divergence. "Missing some details" is not a finding.
+
+### 4. Categorize each finding, then ACT (don't ask)
+Present the findings as a numbered list AND categorize each one:
+- **Correction** ([GAP] missing from conversation, [DRIFT] mutated, [STALE] superseded, [CONFLICT] internal contradiction) — apply directly. The doc catching up to what was decided is not a choice.
+- **Recommendation** ([VAGUE] with a sensible default, [FAB] with low-stakes implications) — apply with your pick, name the pick in the punch list. The user can override after the fact.
+- **Genuine fork** ([FAB] that would change user-visible behavior significantly, content the user might deliberately want kept, or affects a decision that depends on user context you don't have) — surface and wait. **This is rare**; most findings are corrections or recommendations.
+
+The user wants the doc fixed, not pre-approved. Don't ask "want me to apply these?" for the default case — apply them, mark them applied in the punch list, and end with a one-line diff summary. The user reviews the diff after the fact, not before each edit.
+
+**Process every finding — do not pick and choose.** Apply EVERY correction, apply EVERY recommendation (with your pick), surface EVERY genuine fork. The user wants all items fixed, not the agent's selection. If you found 5 [GAP]s and 2 [FAB]s, you produce 5+2 actions (or 5+2 surfacings), not "I'll just do the 3 obvious ones." Selective fixing is the violation.
+
+### 5. Revise in place
+Edit the doc directly — do not produce a parallel doc or a "here's what I'd change" writeup. Each edit traces directly to a finding (now applied). The user reviews the diff after the fact; they don't need to pre-approve each edit.
+
+### 6. Re-verify
+After editing, re-read the doc once more end-to-end. Did the edits introduce new contradictions? Did fixing a gap create drift elsewhere? A second pass catches second-order issues.
+
+## What this is NOT
+
+- **Not a copy-edit / grammar pass.** Tone, spelling, and formatting are out of scope unless they change meaning. (If the user asked for a specific format and the doc doesn't match, that's a finding; otherwise leave style alone.)
+- **Not a "make it longer" pass.** Brevity is fine. Don't pad the doc with things never discussed just to feel thorough.
+- **Not a rewrite.** Surgical edits that map to findings only. Resist "while I'm in here…" changes.
+- **Not a substitute for the user's judgment.** The punch-list goes to the user before any edit. You propose; they decide.
+
+## Critical behaviors
+
+- **Re-read the whole conversation, not the tail.** Decisions made early and never revisited are exactly what get dropped.
+- **Cite both sides of every divergence.** A finding without locations is a vibe.
+- **Default to the conversation as truth.** If doc and conversation disagree, the doc is wrong — unless the user says otherwise.
+- **Surface fabrications even if they "sound right."** A plausible-sounding requirement you invented is the most dangerous finding. Don't self-censor.
+- **Categorize, then act by default.** Corrections and recommendations get applied directly. Genuine forks get surfaced. Don't ask the user to pre-approve each finding.
+- **Don't add things you weren't asked to add.** Reviewing is not authoring. If you spot something genuinely missing that wasn't discussed, flag it as a question ("should this also cover X?"), don't write it in.
+
+## When to use
+
+Triggered by:
+- `/doc-review [path]`
+- "review this doc"
+- "check the doc against what we said"
+- "did you miss anything in the doc?"
+- "is the doc complete?"
+- any time an agent just produced a doc and the user wants it stress-tested before it ships
+
+Best run **immediately after the doc is written**, while the conversation context is fresh. The longer you wait, the more the conversation compacts and the harder it is to verify against.
+
+## Common failure modes
+
+- **The surface re-read.** "Looks good!" without walking both directions. Not a review.
+- **Confirming your own draft.** You wrote it, so of course it reads right to you. The bidirectional check exists because forward-reading your own work is unreliable.
+- **Skipping fabrications.** "That sounds like something we'd want" → keeping an invented requirement. No. If it wasn't decided, it's a finding.
+- **Asking for permission on every finding.** Treating the user as a pre-approval gate. The user wants the doc fixed, not pre-approved. Apply corrections and recommendations; only ask for genuine forks.
+- **Picking and choosing which findings to fix.** The user wants all items fixed, not the agent's selection. If you found 5 corrections and 2 recommendations, you act on 5+2, not "the 3 I'm most confident about." Selective fixing is the violation.
+- **Style-editing under the guise of review.** Tweaking phrasing because you prefer it. Out of scope.
+- **Padding the doc.** Adding sections to "be thorough" that were never discussed. That's a fabrication, not a fix.
+
+## Related
+
+- **`plan-review`** — the narrower sibling. Use `plan-review` when the doc is specifically a *plan* (defines "done", sequencing, scope). Use `doc-review` for any other doc type.
+- **`prove-it`** — governs single claims. `doc-review` applies the same evidence discipline across a whole document.
+- **`sitrep`** — a sitrep verifies *understanding*; `doc-review` verifies a *written artifact*. Same discipline, different target.
+- **`professional`** — the professional does not ship docs with fabricated content. `doc-review` is how you uphold that.

package/skills/feature-research/SKILL.md

@@ -0,0 +1,34 @@
+---
+name: feature-research
+description: Research existing architecture before implementing a complex feature.
+metadata:
+  author: morph
+  version: "0.1.0"
+  argument-hint: <feature>
+---
+
+# Feature Research
+
+Before implementing a complex feature, use codebase_search to avoid duplicating patterns and to match existing conventions.
+
+## When To Use
+
+- New feature spans multiple modules/services.
+- You need to find existing patterns for similar features.
+- You need to identify API boundaries, data models, and tests.
+
+## Steps
+
+1. Identify the likely "shape" of the feature (routes, state, DB, background jobs, UI).
+2. Run `codebase_search` with a natural language question or description that asks for similar features and relevant files.
+3. Extract:
+   - Existing patterns to reuse
+   - Integration points
+   - Config/feature-flag conventions
+   - Tests to mirror
+4. Propose an implementation plan that matches the repo.
+5. Implement.
+
+## Query Template
+
+"Find existing implementations similar to <feature>. Include endpoints, data models, background tasks, and tests."

package/skills/file-op/SKILL.md

@@ -0,0 +1,116 @@
+---
+name: file-op
+description: Execute FileOpsREQ protocol requests. Handles autoflow domain ops for .ccb/ state management.
+---
+
+# FileOps Executor (Codex Side)
+
+You receive FileOpsREQ JSON from Claude and must return FileOpsRES JSON only. No markdown, no prose.
+
+## Protocol Reference
+
+See `~/.claude/skills/docs/protocol.md` for full FileOpsREQ/FileOpsRES schema.
+
+## Execution Rules
+
+1. Parse the incoming FileOpsREQ JSON
+2. Validate against schema (proto, id, purpose, ops, done, report)
+3. Execute each op in order
+4. Return FileOpsRES JSON only
+
+## AutoFlow Domain Ops Implementation
+
+All state files live under `.ccb/` directory relative to repo root.
+
+### `autoflow_plan_init`
+
+Input: `plan` object with taskName, objective, context, constraints, steps[], finalDone[]
+
+Actions:
+1. Create `.ccb/` directory if not exists
+2. Build `state.json` from plan:
+   ```json
+   {
+     "taskName": plan.taskName,
+     "objective": plan.objective,
+     "context": plan.context,
+     "constraints": plan.constraints,
+     "current": { "type": "step", "stepIndex": 1, "subIndex": null },
+     "steps": [ { "index": i+1, "title": title, "status": "todo" (first="doing"), "attempts": 0, "substeps": [] } ],
+     "finalDone": plan.finalDone
+   }
+   ```
+3. Write `.ccb/state.json`
+4. Generate `.ccb/todo.md` from state (see formats.md)
+5. Generate `.ccb/plan_log.md` with initial plan entry
+
+### `autoflow_state_preflight`
+
+Input: `path` (default `.ccb/state.json`), `maxAttempts` (default 2)
+
+Actions:
+1. Read `.ccb/state.json`
+2. If file missing → return fail status with "No plan. Use /tp first."
+3. Validate `current` pointer
+4. If `current.type == "none"` → return ok with taskComplete flag
+5. Get current step/substep, check attempts < maxAttempts
+6. If attempts exceeded → return fail with "Max attempts exceeded"
+7. Increment attempts, write back `.ccb/state.json`
+8. Return ok with `data.state` (current pointer) and `data.stepContext` (step title, objective, relevant info)
+
+### `autoflow_state_apply_split`
+
+Input: `stepIndex`, `substeps` (array of 3-7 title strings)
+
+Actions:
+1. Read `.ccb/state.json`
+2. Find step by stepIndex
+3. Set step.substeps = substeps mapped to `{ index: i+1, title: t, status: "todo" }`, first one "doing"
+4. Set `current = { type: "substep", stepIndex: stepIndex, subIndex: 1 }`
+5. Write `.ccb/state.json`
+6. Regenerate `.ccb/todo.md`
+
+### `autoflow_state_finalize`
+
+Input: `verification` (string), `changedFiles` (optional array)
+
+Actions:
+1. Read `.ccb/state.json`
+2. Mark current step/substep status = "done"
+3. Advance `current` to next todo step/substep:
+   - If substeps remain in current step → next substep
+   - If no substeps remain → next step
+   - If no steps remain → set `current = { type: "none", stepIndex: null, subIndex: null }`
+4. If next item exists, set its status to "doing"
+5. Write `.ccb/state.json`
+6. Regenerate `.ccb/todo.md`
+7. Append completion entry to `.ccb/plan_log.md`
+
+### `autoflow_state_mark_blocked`
+
+Input: `reason` (string)
+
+Actions:
+1. Read `.ccb/state.json`
+2. Mark current step/substep status = "blocked"
+3. Write `.ccb/state.json`
+4. Regenerate `.ccb/todo.md`
+
+### `autoflow_state_append_steps`
+
+Input: `steps` (array of 1-2 title strings), `maxAllowed` (default 2)
+
+Precondition: `current.type == "none"` (task completed)
+
+Actions:
+1. Read `.ccb/state.json`
+2. If steps.length > maxAllowed → return fail
+3. Append new steps to steps array
+4. Set `current` to first new step, mark it "doing"
+5. Write `.ccb/state.json`
+6. Regenerate `.ccb/todo.md`
+7. Append to `.ccb/plan_log.md`
+
+## Output Format
+
+Always return pure JSON matching FileOpsRES schema. Never wrap in markdown code blocks.

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/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,60 @@
+# CONTEXT.md Format
+
+## Structure
+
+```md
+# {Context Name}
+
+{One or two sentence description of what this context is and why it exists.}
+
+## Language
+
+**Order**:
+{A one or two sentence 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
+```
+
+## Rules
+
+- **Be opinionated.** When multiple words exist for the same concept, pick the best one and list the others under `_Avoid_`.
+- **Keep definitions tight.** One or two sentences max. Define what it IS, not what it does.
+- **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.
+
+## 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.