Skip to main content
plugin

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

Install into Claude Code · Plugin marketplace All methods and platforms ↓
/plugin marketplace add alirezarezvani/claude-skills
/plugin install grill-with-docs@claude-code-skills
Open on GitHub

What 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-docs against this plan and compare it with CONTEXT.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/, and src/ 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-skills

Step 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

Similar plugins

All plugins for Agent setup: memory, context, orchestration →

From the same set488

The whole set →
video-content-strategist video-content-strategist plans video content strategy, writes scripts, and optimizes YouTube channels. Suitable for setting up Reels, TikTok, and Shorts workflows or repurposing long-form content. ★ 30,251repo stars business-investment-advisor business-investment-advisor is a Claude Code plugin that compares equipment, property, hiring, and technology investments by ROI, IRR, NPV, and payback to help allocate a limited budget. ★ 30,251repo stars prompt-governance prompt-governance — a Claude plugin for prompts already running in production: versioning, A/B tests, a registry and regression prevention. ★ 30,251repo stars llm-cost-optimizer llm-cost-optimizer reduces LLM API spend using model routing and prompt caching. Useful when token bills climb or when launching AI features without cost controls. ★ 30,251repo stars power-user-coach power-user-coach — a coaching plugin for Claude. It hands you a ranked list of power-user tricks on first run, then stays quiet unless one tip would help. ★ 30,251repo stars behuman behuman adds an inner dialogue loop to Claude Code so responses sound natural rather than robotic. ★ 30,251repo stars snowflake-development The snowflake-development plugin for Claude Code covers Snowflake SQL, data pipelines, Snowpark Python, Cortex AI functions, and dbt. ★ 30,251repo stars compliance-os The compliance-os plugin for Claude Code selects applicable frameworks, maps control overlap, simulates audits and builds a shared evidence pool for teams running multiple compliance programs. ★ 30,251repo stars

Project sponsors

Companies that keep this analytics open