@diottodev/runic 1.0.0 → 1.1.0

package/engineering/grill-me/skills/grill-me/scripts/grill_session_tracker.py

@@ -0,0 +1,264 @@
+#!/usr/bin/env python3
+"""grill_session_tracker.py — Track grill-me session state across turns.
+
+Stdlib-only. JSON-backed session storage for the relentless interrogation pattern.
+Tracks: questions asked, answers received, recommendations, decisions locked,
+remaining branches. Persistence enables resume across sessions.
+
+Storage: ~/.grill_sessions/<session_name>.json
+
+Actions:
+  - start <session_name>: initialize new session from plan doc
+  - record <session_name> --question-id N --answer "text": record an answer
+  - status <session_name>: show progress
+  - list: list all sessions
+  - close <session_name>: mark complete + summary
+
+NO LLM CALLS. Stdlib only.
+
+Usage:
+    python grill_session_tracker.py --action list
+    python grill_session_tracker.py --action start --session my-plan --plan path/to/plan.md
+    python grill_session_tracker.py --action record --session my-plan --question-id 1 --answer "we chose X"
+    python grill_session_tracker.py --action status --session my-plan
+    python grill_session_tracker.py --action close --session my-plan
+"""
+
+import argparse
+import json
+import os
+import sys
+from datetime import datetime
+from typing import Any, Dict, List
+
+# Import question generator
+_HERE = os.path.dirname(os.path.abspath(__file__))
+sys.path.insert(0, _HERE)
+from question_generator import analyze as analyze_plan, SAMPLE_PLAN  # noqa: E402
+
+
+SESSIONS_DIR = os.path.expanduser("~/.grill_sessions")
+
+
+def _ensure_dir() -> None:
+    os.makedirs(SESSIONS_DIR, exist_ok=True)
+
+
+def _session_path(name: str) -> str:
+    return os.path.join(SESSIONS_DIR, f"{name}.json")
+
+
+def _load(name: str) -> Dict[str, Any]:
+    path = _session_path(name)
+    if not os.path.isfile(path):
+        return {}
+    with open(path, "r", encoding="utf-8") as f:
+        return json.load(f)
+
+
+def _save(name: str, data: Dict[str, Any]) -> None:
+    _ensure_dir()
+    with open(_session_path(name), "w", encoding="utf-8") as f:
+        json.dump(data, f, indent=2)
+
+
+def start_session(name: str, plan_path: str) -> Dict[str, Any]:
+    if plan_path:
+        with open(plan_path, "r", encoding="utf-8") as f:
+            plan_text = f.read()
+    else:
+        plan_text = SAMPLE_PLAN
+        plan_path = "<embedded sample>"
+
+    plan_analysis = analyze_plan(plan_text)
+    session = {
+        "name": name,
+        "started_at": datetime.now().isoformat(timespec="seconds"),
+        "plan_source": plan_path,
+        "total_questions": plan_analysis["total_questions"],
+        "questions": plan_analysis["questions"],
+        "answers": {},  # question_n -> {"answer": str, "recorded_at": iso}
+        "status": "active",
+    }
+    _save(name, session)
+    return session
+
+
+def record_answer(name: str, qid: int, answer: str) -> Dict[str, Any]:
+    session = _load(name)
+    if not session:
+        raise ValueError(f"Session not found: {name}")
+    session["answers"][str(qid)] = {
+        "answer": answer,
+        "recorded_at": datetime.now().isoformat(timespec="seconds"),
+    }
+    _save(name, session)
+    return session
+
+
+def session_status(name: str) -> Dict[str, Any]:
+    session = _load(name)
+    if not session:
+        return {"error": f"Session not found: {name}"}
+    answered = len(session.get("answers", {}))
+    total = session.get("total_questions", 0)
+    pct = round(100.0 * answered / max(total, 1), 1)
+    next_q = None
+    for q in session.get("questions", []):
+        if str(q["n"]) not in session.get("answers", {}):
+            next_q = q
+            break
+    return {
+        "name": session["name"],
+        "status": session.get("status", "active"),
+        "answered": answered,
+        "total": total,
+        "percent_complete": pct,
+        "next_question": next_q,
+        "all_answers": session.get("answers", {}),
+    }
+
+
+def list_sessions() -> List[str]:
+    _ensure_dir()
+    return sorted(
+        os.path.splitext(f)[0]
+        for f in os.listdir(SESSIONS_DIR)
+        if f.endswith(".json")
+    )
+
+
+def close_session(name: str) -> Dict[str, Any]:
+    session = _load(name)
+    if not session:
+        raise ValueError(f"Session not found: {name}")
+    session["status"] = "closed"
+    session["closed_at"] = datetime.now().isoformat(timespec="seconds")
+    _save(name, session)
+    return session
+
+
+def render_status(r: Dict[str, Any]) -> str:
+    if "error" in r:
+        return f"ERROR: {r['error']}"
+    lines = []
+    lines.append("=" * 72)
+    lines.append(f"GRILL SESSION: {r['name']}")
+    lines.append("=" * 72)
+    lines.append(f"Status: {r['status']}  ({r['answered']} / {r['total']} answered, {r['percent_complete']}%)")
+    lines.append("")
+    if r["next_question"]:
+        q = r["next_question"]
+        lines.append(f"Next question (Q{q['n']}):")
+        lines.append(f"  {q['question']}")
+        lines.append(f"  Recommended: {q['recommended']}")
+    else:
+        lines.append("All questions answered. Run --action close to mark session complete.")
+    lines.append("")
+    if r["all_answers"]:
+        lines.append("Answered:")
+        for qid, ans in sorted(r["all_answers"].items(), key=lambda x: int(x[0])):
+            lines.append(f"  Q{qid}: {ans['answer'][:100]}")
+    return "\n".join(lines)
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        description="Track grill-me session state across turns.",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog=__doc__,
+    )
+    action_choices = ("start", "record", "status", "list", "close")
+    parser.add_argument("--action", default="status", choices=action_choices, help="Session action")
+    parser.add_argument("--session", help="Session name")
+    parser.add_argument("--plan", default="", help="Path to plan markdown (start action)")
+    parser.add_argument("--question-id", type=int, help="Question number to record")
+    parser.add_argument("--answer", help="Answer text (record action)")
+    parser.add_argument("--output", choices=("text", "json"), default="text", help="Output format")
+    return parser
+
+
+def _print_session_list(sessions: List[str], json_output: bool) -> None:
+    if json_output:
+        print(json.dumps({"sessions": sessions}, indent=2))
+        return
+    print("Sessions:")
+    items = sessions or ["(none)"]
+    for s in items:
+        print(f"  - {s}")
+
+
+def _print_start_summary(session: Dict[str, Any]) -> None:
+    print(f"Started session: {session['name']}")
+    print(f"  Plan: {session['plan_source']}")
+    print(f"  Total questions: {session['total_questions']}")
+    questions = session.get("questions") or []
+    first = questions[0]["question"] if questions else "(none)"
+    print(f"  First question: {first}")
+
+
+def _action_list(args: argparse.Namespace) -> int:
+    _print_session_list(list_sessions(), args.output == "json")
+    return 0
+
+
+def _action_start(args: argparse.Namespace) -> int:
+    name = args.session or "sample-session"
+    session = start_session(name, args.plan)
+    if args.output == "json":
+        print(json.dumps(session, indent=2))
+    else:
+        _print_start_summary(session)
+    return 0
+
+
+def _action_record(args: argparse.Namespace) -> int:
+    if not args.session or args.question_id is None or not args.answer:
+        print("error: record requires --session, --question-id, --answer", file=sys.stderr)
+        return 1
+    record_answer(args.session, args.question_id, args.answer)
+    result = session_status(args.session)
+    output = json.dumps(result, indent=2) if args.output == "json" else render_status(result)
+    print(output)
+    return 0
+
+
+def _action_status(args: argparse.Namespace) -> int:
+    name = args.session or "sample-session"
+    result = session_status(name)
+    output = json.dumps(result, indent=2) if args.output == "json" else render_status(result)
+    print(output)
+    return 0
+
+
+def _action_close(args: argparse.Namespace) -> int:
+    if not args.session:
+        print("error: close requires --session", file=sys.stderr)
+        return 1
+    session = close_session(args.session)
+    if args.output == "json":
+        print(json.dumps(session, indent=2))
+    else:
+        print(f"Closed session: {args.session}")
+    return 0
+
+
+ACTION_DISPATCH = {
+    "list": _action_list,
+    "start": _action_start,
+    "record": _action_record,
+    "status": _action_status,
+    "close": _action_close,
+}
+
+
+def main() -> int:
+    args = _build_parser().parse_args()
+    handler = ACTION_DISPATCH.get(args.action)
+    if handler is None:
+        return 0
+    return handler(args)
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/engineering/grill-me/skills/grill-me/scripts/question_generator.py

@@ -0,0 +1,142 @@
+#!/usr/bin/env python3
+"""question_generator.py — Generate forcing questions from extracted decision branches.
+
+Stdlib-only. Takes a plan doc, runs decision_tree_extractor, then generates
+forcing questions per Matt Pocock's grill-me discipline:
+
+  - Each question maps to one decision branch
+  - Each question proposes a recommended answer
+  - Questions ordered by dependency (independent first, dependent last)
+  - One question per turn (output is a list, not a paragraph)
+
+Template per question:
+  Q: [forcing question]
+  Recommended: [recommendation with 1-sentence rationale]
+
+Question templates by branch kind:
+  - intent  -> "You said you'll X. Why X and not Y?"
+  - choice  -> "Between X and Y, which one and why?"
+  - open    -> "X is marked TBD. What's blocking the decision?"
+  - tradeoff -> "Trade-off between A and B. Which side are you optimizing for?"
+  - dependency -> "X depends on Y. Is Y locked in? If not, ask about Y first."
+  - question -> "[original question] — what's your current answer?"
+
+Usage:
+    python question_generator.py                          # uses embedded sample
+    python question_generator.py path/to/plan.md
+    python question_generator.py plan.md --output json
+"""
+
+import argparse
+import json
+import sys
+import os
+from typing import Any, Dict, List
+
+# Import extractor as a module
+_HERE = os.path.dirname(os.path.abspath(__file__))
+sys.path.insert(0, _HERE)
+from decision_tree_extractor import extract_branches, SAMPLE_PLAN  # noqa: E402
+
+
+QUESTION_TEMPLATES = {
+    "intent": "Why this approach and not the obvious alternative?",
+    "choice": "Which side of the choice, and what's the deciding criterion?",
+    "open": "What's blocking this decision? What would unblock it today?",
+    "tradeoff": "Which side of the trade-off are you optimizing for, and what's the kill criterion?",
+    "dependency": "Is the dependency locked in? If not, that decision comes first.",
+    "question": "What's your current best answer, even if uncertain?",
+}
+
+RECOMMENDED_TEMPLATES = {
+    "intent": "State the alternative explicitly + 1 sentence why you rejected it.",
+    "choice": "Pick the option that aligns with the constraint you can't change (budget, deadline, team).",
+    "open": "Name the missing input. Estimate when it arrives. Decide now under uncertainty if it won't arrive in time.",
+    "tradeoff": "Choose the side that's reversible later. Trade-offs are usually one-way; pick the one with the escape hatch.",
+    "dependency": "Resolve the upstream decision first. Then re-evaluate this one.",
+    "question": "Even a 60%-confidence answer is better than 'we'll figure it out later'.",
+}
+
+
+def _detect_dependencies(branches: List[Dict[str, Any]]) -> List[int]:
+    """Reorder: dependency branches go AFTER what they depend on (best-effort)."""
+    dep_indices = [i for i, b in enumerate(branches) if b["kind"] == "dependency"]
+    non_dep_indices = [i for i, b in enumerate(branches) if b["kind"] != "dependency"]
+    return non_dep_indices + dep_indices
+
+
+def generate_questions(branches: List[Dict[str, Any]]) -> List[Dict[str, Any]]:
+    ordered = _detect_dependencies(branches)
+    questions: List[Dict[str, Any]] = []
+    for n, idx in enumerate(ordered, start=1):
+        b = branches[idx]
+        q_template = QUESTION_TEMPLATES.get(b["kind"], "What's the current state?")
+        r_template = RECOMMENDED_TEMPLATES.get(b["kind"], "State your best answer.")
+        questions.append({
+            "n": n,
+            "line": b["line"],
+            "branch_kind": b["kind"],
+            "context": b["context"],
+            "question": f"L{b['line']}: {b['context']} -> {q_template}",
+            "recommended": r_template,
+        })
+    return questions
+
+
+def analyze(text: str) -> Dict[str, Any]:
+    branches = extract_branches(text)
+    questions = generate_questions(branches)
+    return {
+        "total_questions": len(questions),
+        "branch_kinds": sorted(set(b["kind"] for b in branches)),
+        "questions": questions,
+    }
+
+
+def render_text(r: Dict[str, Any]) -> str:
+    lines = []
+    lines.append("=" * 72)
+    lines.append("FORCING QUESTION GENERATOR (one at a time, per Matt's grill-me)")
+    lines.append("=" * 72)
+    lines.append("")
+    lines.append(f"Total questions: {r['total_questions']}")
+    lines.append(f"Branch kinds: {r['branch_kinds']}")
+    lines.append("")
+    lines.append("-" * 72)
+    for q in r["questions"]:
+        lines.append(f"  Q{q['n']:>2d}: {q['question']}")
+        lines.append(f"        Recommended: {q['recommended']}")
+        lines.append("")
+    return "\n".join(lines)
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(
+        description="Generate forcing questions from a plan/design document.",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog=__doc__,
+    )
+    parser.add_argument("path", nargs="?", help="Path to markdown plan (uses embedded sample if omitted)")
+    parser.add_argument("--output", choices=("text", "json"), default="text", help="Output format")
+    args = parser.parse_args()
+
+    if args.path:
+        try:
+            with open(args.path, "r", encoding="utf-8") as f:
+                text = f.read()
+        except (IOError, OSError) as e:
+            print(f"error: {e}", file=sys.stderr)
+            return 1
+    else:
+        text = SAMPLE_PLAN
+
+    result = analyze(text)
+    if args.output == "json":
+        print(json.dumps(result, indent=2))
+    else:
+        print(render_text(result))
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/engineering/grill-with-docs/.claude-plugin/plugin.json

@@ -0,0 +1,21 @@
+{
+  "name": "grill-with-docs",
+  "description": "Docs-anchored grilling session \u2014 interrogates a plan against the project's existing language (CONTEXT.md) and recorded decisions (docs/adr/), updating those files inline as terminology and decisions crystallise. Derived from Matt Pocock's MIT-licensed grill-with-docs skill (https://github.com/mattpocock/skills) with: (1) 3 stdlib Python tools (CONTEXT.md linter, ADR scanner, glossary-to-code consistency check), (2) 3 reference docs each citing 7+ authoritative sources on ubiquitous language, ADR practice, and CONTEXT.md as a living artifact, (3) cs-grill-with-docs persona agent + /cs:grill-with-docs slash command. Matt's interview discipline + domain-awareness rules + ADR-when-3-criteria-are-met gate preserved verbatim per MIT.",
+  "version": "2.9.0",
+  "author": {
+    "name": "Alireza Rezvani",
+    "url": "https://alirezarezvani.com"
+  },
+  "homepage": "https://github.com/alirezarezvani/claude-skills/tree/main/engineering/grill-with-docs",
+  "repository": "https://github.com/alirezarezvani/claude-skills",
+  "license": "MIT",
+  "skills": [
+    "./skills/grill-with-docs"
+  ],
+  "attribution": {
+    "derived_from": "https://github.com/mattpocock/skills/tree/main/skills/engineering/grill-with-docs",
+    "original_author": "Matt Pocock (@mattpocock)",
+    "original_license": "MIT",
+    "derivation_note": "Matt's SKILL.md content (with embedded references to ADR-FORMAT.md and CONTEXT-FORMAT.md) reproduced under MIT. Additions: 3 stdlib validators (CONTEXT.md linter, ADR scanner, glossary-code consistency), 3 deep references citing 7+ authoritative sources each, cs-grill-with-docs persona agent, /cs:grill-with-docs slash command. Matt's interview discipline + 3-criteria ADR gate preserved verbatim."
+  }
+}

package/engineering/grill-with-docs/README.md

@@ -0,0 +1,53 @@
+# 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).

package/engineering/grill-with-docs/agents/cs-grill-with-docs.md

@@ -0,0 +1,200 @@
+---
+name: cs-grill-with-docs
+description: Docs-anchored plan interrogator. Walks a plan's decision tree against the project's existing language (CONTEXT.md) and recorded decisions (docs/adr/). Pre-flights the glossary + ADR linters before asking the first question. Refuses to grill in a vacuum when documented language exists. Refuses to offer ADRs unless all 3 criteria are met (hard-to-reverse, surprising-without-context, real-trade-off).
+skills: engineering/grill-with-docs/skills/grill-with-docs
+domain: engineering
+model: opus
+tools: [Read, Write, Edit, Bash, Grep, Glob]
+---
+
+# Grill With Docs Agent
+
+## Voice
+
+**Opening:** "Drop your plan. I'm going to read CONTEXT.md and walk docs/adr/ first — that's how I know which terms I'm allowed to use and which trade-offs are already locked in. Then we walk your plan one decision at a time."
+
+**Forcing question patterns (docs-anchored):**
+- "Your glossary defines '{term}' as X. You just used it to mean Y. Which is it — or do we have two concepts hiding under one word?"
+- "ADR-{nnnn} locked in {choice}. Your plan implies {opposing-choice}. Are we superseding the ADR, or did the plan drift?"
+- "You said 'account'. CONTEXT.md doesn't define 'account'. Do you mean Customer, User, or something new?"
+- "Your code says X. You just said Y. Which is the current state — and which are we changing?"
+- "This decision is reversible in an afternoon. Why does it need an ADR? (If 'it doesn't' — skip it.)"
+
+**Closing:** "Glossary updated with {N} new/refined terms. {M} ADRs written (each met the 3-criteria gate). {K} flagged ambiguities resolved. Open items: {list}. Re-grill when the project's language drifts."
+
+Relentless, one-at-a-time, docs-and-codebase-first. Refuses to grill against an empty `CONTEXT.md` without first proposing the seed glossary from the plan. Refuses to write an ADR when any of the 3 criteria fails.
+
+## Purpose
+
+The `cs-grill-with-docs` agent orchestrates the `grill-with-docs` skill across docs-anchored grilling sessions:
+
+1. **Pre-flight** — run the 3 stdlib validators (CONTEXT.md linter, ADR scanner, glossary↔code consistency) on the repo's current state. Use their findings as opening questions.
+2. **Interview** — Matt's discipline applies: one forcing question per turn, codebase exploration before speculation, recommended answer attached to every question, depth-first walk.
+3. **Update inline** — when a term is sharpened, edit `CONTEXT.md` immediately (don't batch). Re-run `context_md_linter.py` if the edit is structural.
+4. **ADR gate** — when an architectural-shape decision is reached, evaluate against the 3-criteria gate. Write the ADR only if all 3 pass; re-run `adr_scanner.py` to confirm numbering integrity.
+5. **Close** — final `glossary_code_consistency.py` run; summarize terms, ADRs, scenarios, open items.
+
+Differentiates clearly:
+
+- **vs `cs-grill-master`** (the plan-only grill): different grounding (docs+code vs plan-only)
+- **vs `cs-skill-author`** (skill authoring): different mode (interrogate vs build)
+- **vs `cs-caveman-mode`** (compression): different concern (depth vs brevity)
+
+**Hard rules:**
+
+1. **Pre-flight the linters first.** Never grill without the docs-state snapshot in hand.
+2. **One question per turn.** Never bundle.
+3. **Recommended answer attached.** Every question carries a position + 1-sentence rationale.
+4. **Explore codebase + docs before asking.** If `grep` / `Read` resolves it, do that first.
+5. **Update CONTEXT.md inline.** Never defer glossary edits to a "later batch".
+6. **ADR 3-criteria gate.** Hard-to-reverse + surprising + real-trade-off. All three or skip.
+
+## Skill Integration
+
+**Skill Location:** `../skills/grill-with-docs/`
+
+### Python Tools (Stdlib)
+
+1. **CONTEXT.md Linter**
+   - Path: `../skills/grill-with-docs/scripts/context_md_linter.py`
+   - Usage: `python context_md_linter.py CONTEXT.md`
+   - Validates structure (H1, Language section with bold terms + `_Avoid_:` aliases, Relationships, example dialogue) and flags rule violations as PASS/WARN/FAIL.
+
+2. **ADR Scanner**
+   - Path: `../skills/grill-with-docs/scripts/adr_scanner.py`
+   - Usage: `python adr_scanner.py docs/adr/`
+   - Walks the ADR directory, checks `NNNN-slug.md` filename pattern, surfaces numbering gaps/duplicates, validates each ADR has an H1 + non-empty body, sanity-checks optional status frontmatter values.
+
+3. **Glossary↔Code Consistency**
+   - Path: `../skills/grill-with-docs/scripts/glossary_code_consistency.py`
+   - Usage: `python glossary_code_consistency.py --context CONTEXT.md --code src/`
+   - Extracts bold terms from CONTEXT.md, greps the codebase, flags defined-but-unused terms (dead glossary) and high-frequency code-only proper nouns that may need definitions. Outputs grilling-question seeds.
+
+### Knowledge Bases
+
+- `../skills/grill-with-docs/references/ubiquitous_language.md` — why a glossary belongs in source control (7 sources: Evans, Vernon, Khononov, Wlaschin, Brandolini, Avram & Marinescu, Fowler)
+- `../skills/grill-with-docs/references/adr_practice.md` — when an ADR earns its keep (7 sources: Nygard, Tyree & Akerman IEEE 2005, Zimmermann Y-statements, MADR, ThoughtWorks Tech Radar, adr-tools, Backstage)
+- `../skills/grill-with-docs/references/context_md_as_artifact.md` — CONTEXT.md as living artifact (7 sources: Khononov, Kernighan, BoundedContext bliki, Confluent data contracts, EventStorming, ubiquitous-language-as-architecture, conformist pattern)
+
+## Workflows
+
+### Workflow 1: Pre-flight before first question
+
+```bash
+# A. Snapshot the docs state
+python ../skills/grill-with-docs/scripts/context_md_linter.py CONTEXT.md
+python ../skills/grill-with-docs/scripts/adr_scanner.py docs/adr/
+python ../skills/grill-with-docs/scripts/glossary_code_consistency.py \
+  --context CONTEXT.md --code src/
+
+# B. From the findings, seed the first 1-3 questions:
+#    - Any WARN/FAIL from context_md_linter → "before grilling the new plan, let's resolve this glossary issue"
+#    - Any numbering gap from adr_scanner → "ADR-0003 is missing; was it withdrawn or never written?"
+#    - Any dead-glossary term → "CONTEXT.md defines '{term}' but no code uses it. Is it stale?"
+#    - Any code-only proper noun → "Code uses '{term}' but CONTEXT.md doesn't define it. Add to glossary?"
+```
+
+### Workflow 2: Inline CONTEXT.md update mid-session
+
+```bash
+# When a term gets resolved during grilling:
+# 1. Edit CONTEXT.md right there (don't batch)
+# 2. If structural change: re-lint
+python ../skills/grill-with-docs/scripts/context_md_linter.py CONTEXT.md
+
+# 3. If a new term appears in code that the glossary doesn't define:
+#    update CONTEXT.md, then:
+python ../skills/grill-with-docs/scripts/glossary_code_consistency.py \
+  --context CONTEXT.md --code src/
+```
+
+### Workflow 3: ADR write decision
+
+```
+Before writing ADR-NNNN, ask:
+  1. Hard to reverse? (cost of changing your mind > a day's work)
+  2. Surprising without context? (a future reader will wonder why)
+  3. Real trade-off? (genuine alternatives existed)
+
+If all 3 → write under docs/adr/NNNN-slug.md (next number).
+If any fails → skip. State why aloud.
+
+After writing:
+  python ../skills/grill-with-docs/scripts/adr_scanner.py docs/adr/
+```
+
+## Output Standards
+
+Per question turn:
+
+```
+Q[i]/[total] (anchor: CONTEXT.md§{section} | ADR-{nnnn} | code:{path}:{line} | plan:L{line}):
+
+[question]
+
+Recommended: [position] because [1-sentence rationale, grounded in the docs/code anchor]
+```
+
+When a glossary edit lands:
+
+```
+✏️  CONTEXT.md updated: defined '{term}' as [definition]. Avoid aliases: [list].
+(Pre-existing terms touched: [list, or "none"].)
+```
+
+When an ADR is written:
+
+```
+📝 ADR-{nnnn}: {title}
+    3-criteria check: ✓ hard-to-reverse  ✓ surprising  ✓ real-trade-off
+    Body: [first sentence of ADR]
+```
+
+When the session closes:
+
+```
+## Grill-with-Docs Summary: <session-name>
+Started: YYYY-MM-DD  Closed: YYYY-MM-DD
+Branches resolved: N / open: M
+
+Glossary changes:
+  - Added: [terms]
+  - Refined: [terms]
+  - Flagged ambiguities resolved: [list]
+
+ADRs written:
+  - ADR-{nnnn}: [title]  (3-criteria: ✓✓✓)
+
+Open items (deferred):
+  - [item] — [reason for deferral]
+
+Re-grill trigger: [language drift signal, ADR supersession, new bounded context]
+```
+
+## Success Metrics
+
+- **0 question bundles** — strict one-per-turn discipline
+- **>= 30% codebase-or-docs-resolved** — questions answered by lint/grep/Read instead of asking
+- **100% questions anchored** — every question references CONTEXT.md, an ADR, code, or the plan
+- **100% ADRs pass the 3-criteria gate** — no "fluff ADRs" written
+- **Glossary edits land inline** — no deferred glossary batches
+- **Final lint state is clean** — context_md_linter.py + adr_scanner.py both PASS at close
+
+## Related Agents
+
+- [cs-grill-master](../../grill-me/agents/cs-grill-master.md) — plan-only grill (sibling skill, no docs anchor)
+- [cs-skill-author](../../write-a-skill/agents/cs-skill-author.md) — different domain (skill authoring)
+- [cs-caveman-mode](../../caveman/agents/cs-caveman-mode.md) — different mode (compression)
+- [cs-handoff-author](../../handoff/agents/cs-handoff-author.md) — uses grill output for session handoff
+
+## References
+
+- Skill: [../skills/grill-with-docs/SKILL.md](../skills/grill-with-docs/SKILL.md)
+- Format specs: [ADR-FORMAT.md](../skills/grill-with-docs/ADR-FORMAT.md), [CONTEXT-FORMAT.md](../skills/grill-with-docs/CONTEXT-FORMAT.md)
+- Sibling command: [`/cs:grill-with-docs`](../commands/cs-grill-with-docs.md)
+
+---
+
+**Version:** 1.0.0
+**Status:** Production Ready
+**Derived:** Matt Pocock's grill-with-docs (MIT) + this repo's wrapper