grounding-rules

Grounding Rules

A Claude Code skill that distills a system or subsystem into a short, human-readable set of grounding rules — the minimal load-bearing invariants and design decisions that let a reader gain confidence in a system in minutes and settle future design questions, instead of reading a full spec for hours.

It follows the Agent Skills SKILL.md format, so it works in any skills-compatible agent (Claude Code, Codex CLI, …).

What it does

/grounding-rules produces a tight rules doc — the constitution of a module:

• a one-line mental model and a tl;dr of foundation rules,
• the one diagram (the entity skeleton),
• 8–15 numbered, load-bearing rules — each a one-line claim + why + a light file:symbol anchor,
• "Using these rules" — worked design questions each settled by citing a rule.

Three actions:

Command	What it does
/grounding-rules	A fresh grounding pass over the system you point it at.
/grounding-rules update <facts>	Re-ground an existing doc when the system changed — not append; it re-runs the whole doc.
/grounding-rules ask <question>	Answer a question from the real code, in the grounding voice.

The guiding bar: a rule is for a human acting in good faith — its plain reading should make the right choice obvious. Optimize for fast confidence, not completeness; the moment you add clauses to fence edge cases, you're writing a spec, not a rule.

Install (Claude Code)

/plugin marketplace add initialneil/grounding-rules
/plugin install grounding-rules@grounding-rules

Then type /grounding-rules in any project.

Update to the latest version

/plugin update grounding-rules

Manual install

Copy skills/grounding-rules/ into ~/.claude/skills/ (global) or your project's .claude/skills/.

Optional: Obsidian

When you point the skill at a path inside an Obsidian vault, it invokes the obsidian-markdown skill (if installed) to format with frontmatter + callouts. It's a soft dependency — plain Markdown is used everywhere else, and nothing breaks if it isn't installed.

Publishing a new version (maintainer)

Edit skills/grounding-rules/SKILL.md, then in this repo run:

/release [patch|minor|major | X.Y.Z] ["what changed"]

The /release skill (.claude/skills/release/, maintainer-only — not shipped to consumers) runs the whole pipeline: it publishes (bumps both manifests, prepends CHANGELOG.md, commits, tags v<version>, pushes — via scripts/publish.sh) and refreshes your local install (claude plugin marketplace update grounding-rules). Everyone else picks up the new version with /plugin update grounding-rules.

Prefer the raw script? scripts/publish.sh patch "what changed" does the publish half (no local refresh).

License

MIT — see LICENSE.