grill-with-docs — Claude Code plugin: plan review and install
The grill-with-docs plugin interrogates a plan against project terminology, ADRs, and code, then records clarified language and architectural decisions in the project docs.
MIT ★ 30,251 updated 2026-10-23
/plugin marketplace add alirezarezvani/claude-skills
/plugin install grill-with-docs@claude-code-skillsWhat grill-with-docs does
grill-with-docs walks through a plan one decision at a time. It checks terms against CONTEXT.md, compares choices with docs/adr/, and explores the codebase when a question can be answered there. The session produces notes, inline context updates, and an ADR when a decision is hard to reverse, needs context to be understood, and reflects a genuine trade-off.
The package includes three Python checks: a CONTEXT.md linter, an ADR scanner, and a glossary-to-code consistency check. It also ships three reference documents, the cs-grill-with-docs agent, and the /cs-grill-with-docs command. Python is needed for the checks; change the src/ argument when the project code lives elsewhere.
What it helps with
- stress-test a plan against project terminology
- spot glossary terms that do not match the code
- scan ADR files for numbering and body integrity
- record architectural decisions during plan review
Example prompts for the agent
- Run
/cs-grill-with-docsagainst this plan and compare it withCONTEXT.md,docs/adr/, and the codebase. - Review the plan one question at a time, resolving terminology conflicts from the project files.
- Run the checks for
CONTEXT.md,docs/adr/, andsrc/before starting the grilling session.
How to install grill-with-docs
Plugin marketplace
/plugin marketplace add alirezarezvani/claude-skills/plugin install grill-with-docs@claude-code-skillsStep by step, with commands for each platform: Claude Code plugins: marketplaces, installing, and building your own
Questions about grill-with-docs
How do I install grill-with-docs in Claude Code?
Run /plugin marketplace add alirezarezvani/claude-skills, then run /plugin install grill-with-docs@claude-code-skills.
What does grill-with-docs do?
It reviews a plan against project language, recorded decisions, and code. The plugin updates CONTEXT.md and may create an ADR when the decision meets all three stated criteria.
How is grill-with-docs different from grill-me?
grill-me examines the plan and produces session notes. grill-with-docs also reads CONTEXT.md, docs/adr/, and the codebase, then can update the project documents.
Source text
grill-with-docs · MIT
# grill-with-docs Docs-anchored grilling session. Walks the decision tree of a plan one branch at a time, but does so against the project's existing **language** (`CONTEXT.md`) and recorded **decisions** (`docs/adr/`). Sharpens terminology + records architecturally-significant decisions inline as they crystallise. ## Attribution **Derived from [Matt Pocock's grill-with-docs](https://github.com/mattpocock/skills/tree/main/skills/engineering/grill-with-docs)** (MIT, © 2026 Matt Pocock). Matt's interview discipline + domain-awareness rules preserved verbatim per his MIT license — relentless one-question-at-a-time grilling, codebase-and-docs-first exploration, the three-criterion gate for offering an ADR (hard-to-reverse + surprising-without-context + real-trade-off). ## How this differs from `grill-me` | Aspect | `grill-me` | `grill-with-docs` | |---|---|---| | Grounding | Plan text only | Plan + `CONTEXT.md` + `docs/adr/` + codebase | | Output | Session notes | Session notes **plus** inline updates to CONTEXT.md and (when warranted) new ADRs | | Question source | Decision tree extracted from plan | Decision tree **plus** language conflicts, fuzzy terms, code-vs-glossary contradictions | | When to use | Stress-testing a fresh plan | Onboarding a plan into an established codebase with documented language | Both ship as separate plugins; pick whichever matches the situation. The `grill-me` skill is plan-only; `grill-with-docs` is plan + project memory. ## What this adds on top of Matt's original | Addition | Where | Why | |---|---|---| | **3 stdlib Python tools** | `skills/grill-with-docs/scripts/` | Lint CONTEXT.md format · Walk docs/adr/ for numbering + body integrity · Cross-reference bold terms in CONTEXT.md against codebase usage (dead glossary + code-only common nouns) | | **3 in-depth references** (7+ sources each) | `skills/grill-with-docs/references/` | Ubiquitous language canon · ADR practice canon · CONTEXT.md as living artifact | | **cs-grill-with-docs persona agent** | `agents/cs-grill-with-docs.md` | Docs-aware grill voice; pre-flights the linters before the first question | | **`/cs-grill-with-docs` slash command** | `commands/cs-grill-with-docs.md` | Activation + workflow handoff | ## Matt's original (preserved) > "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." > "Only offer to create an ADR when all three are true: hard to reverse, surprising without context, the result of a real trade-off. If any of the three is missing, skip the ADR." ## Quick start ```bash # 1. Lint existing CONTEXT.md (if present) python skills/grill-with-docs/scripts/context_md_linter.py CONTEXT.md # 2. Scan existing ADRs (if present) python skills/grill-with-docs/scripts/adr_scanner.py docs/adr/ # 3. Cross-reference glossary terms against codebase python skills/grill-with-docs/scripts/glossary_code_consistency.py \ --context CONTEXT.md --code src/ # 4. Use /cs-grill-with-docs to start the session ``` ## License MIT (matching Matt's upstream).
© Alireza Rezvani · MIT · alirezarezvani/claude-skills