Skip to content

lozit/groundrules

BranchesTags

Repository files navigation

groundrules

groundrules lays the documentation backbone of a software project — and keeps it alive. A Claude Code plugin that interviews you, captures the project's intent, and generates a tailored, opinionated doc structure (vision, decisions, learnings, architecture…), then gives you the skills to maintain it as the project evolves.

Interview → tailored project structure → git init → first commit → optional remote.

Why

Coding agents rarely fail for lack of information — they fail for lack of the right information, structured and at hand. Two forces make that hard, and groundrules is built to answer both:

  • More context isn't better — it's measured. Research on context rot (Chroma, 2025) found every frontier model tested — Claude included — degrades as the input grows; the classic lost in the middle effect drops accuracy 30%+ for anything buried mid-window. Anthropic's own guidance agrees: keep CLAUDE.md under 200 lines, because "larger files produce lower adherence." Stuffing everything into context actively hurts.
  • Knowledge evaporates. Decisions, conventions, and hard-won lessons end up in chat logs and an agent's volatile memory — gone by the next session, invisible to the next contributor.

groundrules' answer is a method, not just a folder of templates: write everything down on disk, load almost none of it. It generates a small always-loaded index (CLAUDE.md) that points to exhaustive docs read on demand, an ADR trail for the why, a rule-format learnings journal, and the discipline that the repo is the only memory. Exhaustive storage, minimal loading — the agent gets precisely what each task needs and nothing it doesn't.

What it buys you:

  • Sharper agents — a small, current index plus on-demand reads keeps attention undiluted and adherence high, instead of a bloated always-on file.
  • Knowledge that survives — decisions, conventions and lessons live in the repo, available to the next session, the next contributor, and any agent — not trapped in one chat.
  • Lower token cost — exhaustive on disk, minimal in context: you don't pay to carry the whole project every turn.
  • No lock-in — it's plain markdown; the structure stays readable and useful even without the plugin.
  • Docs that don't rot — living-docs discipline, checkpoint capture, and /groundrules:slim keep the backbone current and under budget over time.

The full reasoning and token economics: docs/CONTEXT-ECONOMY.md (ADR 0021).

Built for the age of loops

The way people drive coding agents is shifting from prompts to loops: instead of typing each prompt, you run a loop that restarts the agent from a fresh context every iteration and lets the repo — not the model — carry the memory. Claude Code's creator puts it plainly: "I don't prompt Claude anymore… my job is to write loops." The technique's slogan is blunter still: the model forgets, the repo remembers.

That is groundrules' thesis, arrived at independently — and the same context-rot research underwrites both: a short, fresh context each turn isn't a compromise, it's the goal. A loop only survives its amnesiac restarts on durable, on-disk state — a vision of what to build, a plan checked off run after run, lessons so it stops repeating mistakes, decisions for the why, and git for what's done. That state is exactly what groundrules generates. It makes a repo loop-ready: the structure a loop re-reads at the start of every iteration.

And it answers the paradigm's sharpest risk. Loops ship code fast, but they accrue comprehension debt — code that exists and works, yet no human ever read. groundrules' ADR trail, learnings journal, and the why it preserves are the antidote: loops write the code fast; groundrules keeps the understanding of the code.

Today groundrules is the memory + reflection layer a loop runs on — and ships opt-in loop scaffolding (loop/: a maker/verifier split with an independent, report-distrusting verifier, a capped runner, and a loop-safe backlog; off by default, offered by bootstrap/adopt), plus /groundrules:realize (turn an approved plan into a partitioned backlog, gated on a pre-written red acceptance test). Learn it by building Conway's Game of Life — test/loop/TUTORIAL.md (a deterministic oracle and a real trap, so you watch the loop engage); or see the terser reference run + deterministic checks in test/loop/WALKTHROUGH.md. Decisions: ADR 0027, ADR 0030; the roadmap.

How it works

It starts the moment you run /groundrules:bootstrap in a fresh folder.

groundrules interviews you — a handful of grouped questions about the project's name, type, stack, and intent. It captures that intent (you paste a brief, point to a file, or answer an interview), synthesizes it into a docs/VISION.md, and generates a documentation backbone tailored to your answers: a CLAUDE.md that fits the project, an ADR folder for decisions, a learnings journal, a plan, and only the specialized docs you actually need (data model, security, design system, release runbook…). Then it git inits, makes the first commit, and — if you asked — creates the remote.

From there, the project is alive. As you work, learn and add-adr capture knowledge where it belongs; apply-best-practices pulls fresh practices from the community and tailors them to your vision; verify-bootstrap checks coherence; and when the plugin itself improves, migrate brings your project up to date without ever overwriting your work. Already have a project? adopt brings it under management — and can consolidate an existing layout onto the canonical one.

The throughline: knowledge lives in the repo, structured and current — not in scattered notes or an agent's volatile memory.

Installation

In Claude Code:

/plugin marketplace add https://github.com/lozit/groundrules
/plugin install groundrules

From a local clone, or for fast iteration without installing:

/plugin marketplace add /path/to/groundrules
/plugin install groundrules@claude-code-groundrules
# or, dev mode:
claude --plugin-dir /path/to/groundrules

Working in a team / shared repo? Install at Project scope (choose Project, not User, during /plugin install). This commits the plugin reference to .claude/settings.json, so anyone who clones and trusts the repo is prompted to install it — the /groundrules:* commands then work for everyone. The plugin does not travel with a git clone otherwise; a user-scope install is per-machine. (The generated docs are plain markdown and remain readable without the plugin — only the slash-command ergonomics need it. See ADR 0023.)

groundrules is a Claude Code plugin today. Extending it to other harnesses is a planned direction — the repo is named groundrules (harness-neutral) for that reason.

The workflow

Seven skills ordered by a project's lifecycle, plus six cross-cutting skills:

  1. bootstrap — new, empty folder. Interview + intent capture (paste / file / interview) + from-scratch generation of the whole structure, git init, optional remote.
  2. adopt — existing (brownfield) project. Scans, maps existing files to roles, generates only what's missing, backfills .groundrules.json. Never overwrites; supports --dry-run and a consolidate mode that migrates an existing layout onto the canonical paths.
  3. learn — after a correction or a discovery. Adds an actionable rule to docs/LEARNINGS.md (Why + When to apply).
  4. add-adr — a structural decision is made. Creates a numbered ADR and updates the index.
  5. apply-best-practices — want outside input. Fetches the up-to-date shanraisshan/claude-code-best-practice and proposes recommendations tailored to your docs/VISION.md. (The only skill that needs the network.)
  6. verify-bootstrap — sanity check. Validates signatures, leftover {{KEY}} placeholders, CLAUDE.md size, valid JSON, git. --fix for trivial corrections.
  7. migrate — the plugin has a new version. Per-file diff, never overwrites without confirmation, chains historical renames, --dry-run.
  8. checkpoint — any time, especially before a push. Runs the capture ritual (see below).
  9. slim — when CLAUDE.md approaches 200 lines. Proposes concrete optimizations to stay under budget — extract a bulky section to docs/, move file-type rules to .claude/rules/ (loaded on demand), compress, de-duplicate. Moves content, never deletes it. (verify-bootstrap points here when it flags the size.)
  10. prd — before a non-trivial feature. Writes a per-feature PRD (problem, success criteria, scope, constraints, build plan, risks) to docs/prd/<feature>.md, so the agent builds the right thing. Defers to superpowers if that plugin is in use (its per-feature spec altitude).
  11. vision — the project needs a strong vision. Builds or refreshes docs/VISION.md through a guided interview (goal, users, constraints, non-goals, acceptance criteria) — for an adopted project with no vision, or to deepen a thin one. Create-if-absent / refine-if-present, never overwrites. Complements bootstrap's intent capture.
  12. idea — a thought you don't want to lose. Parks a one-line idea in PLAN.md's "Ideas — to triage" inbox, fast. Prospective capture (forward ideas), the complement to checkpoint. Triage later → ADR / PRD / ROADMAP / drop.
  13. realize — you have an approved plan and want to loop part of it. The forward bridge: partitions the plan into [loop] (atomic, isolatable) vs [supervised] tasks and writes the loop-safe ones into loop/backlog.md. Gates [loop] on a pre-written, currently-red acceptance test authored separately from the maker (TDD-before-loop — the loop's back pressure, not a global rule); no such test → it stays [supervised]. Requires the loop scaffolding (opt-in); defers to superpowers when present.

Capturing knowledge as you go

Knowledge is worthless if it evaporates. groundrules captures it at the moments that matter, routed to where it belongs:

  • Decided something structural → an ADR (docs/decisions/)
  • Learned something, or blocked 30+ min → a rule in docs/LEARNINGS.md (Why + When to apply)
  • Caught the agent repeating a mistake, hallucinating, or drifting → docs/AGENT-EVALS.md (optional doc) + a guard in CLAUDE.md

This checkpoint-capture ritual fires two ways. The agent proposes it proactively at the boundaries it can perceive — before a git push, tag, or release (the most reliable moment, also wired into the RELEASE.md pre-release checklist) or at a completed PLAN.md milestone. And you can trigger it yourself any time with /groundrules:checkpoint. (There's no "end of session" trigger: an agent can't perceive a session ending — so capture is anchored to events it can see. See ADR 0022.)

What's generated

groundrules gives a project a clear geography.

Folder Role
intake/ Raw upstream inputs, captured as received: client specs, emails, scoping notes, spreadsheets, brand assets. Read-only (don't "fix" inputs — synthesize them into docs/), binaries welcome. The draft side.
docs/ The living, synthesized documentation: vision, architecture, learnings, specialized docs. Where stable knowledge lives and is kept in sync.
docs/decisions/ The ADRs: one file per structural decision — context, decision, alternatives, tradeoffs. The why, frozen at decision time.
docs/prd/ Per-feature PRDs (problem, success criteria, scope, constraints, build plan, risks): one file per feature, written before building. Created on demand by /groundrules:prd.
docs/media/ Visual assets supporting the docs: mockups, screenshots, diagrams (with their editable sources).
loop/ (opt-in) Autonomous loop scaffolding — a maker/verifier split, a capped runner, and the loop's own backlog. The loop owns this dir; you own PLAN.md. Off by default; offered by bootstrap/adopt.

The flow: intake/ (raw, untouched) → docs/ (synthesized, living) → docs/decisions/ (the why, frozen). Root files (README.md, CLAUDE.md, PLAN.md, CHANGELOG.md, RELEASE.md) are the operational surface.

File When created Content
README.md Always Public project presentation: title, description, install, usage, structure, doc links. Skeleton to flesh out per the stack.
CLAUDE.md Always Instructions for Claude Code. Mutable and iterative (target < 200 lines): session-start reading order, Setup/Build/Test commands, conventions, "repo is the only memory".
.gitignore Always Minimal, stack-agnostic list: OS (.DS_Store…), editors (.vscode/, .idea/…), logs, .env, and common build folders to adapt.
docs/decisions/README.md Always Explains the ADR format (after Michael Nygard): naming convention NNNN-kebab-title.md and when to create an ADR.
docs/decisions/0000-template.md Always ADR template to copy: Context, Decision, Alternatives considered, Consequences, Status.
docs/LEARNINGS.md Always Rules learned from corrections: one entry = an actionable rule with Why (the story + cost) and When to apply (triggers). Fed by /groundrules:learn, re-read at session start.
intake/README.md Always Explains the role of intake/ and its conventions (read-only, binaries welcome, explicit names).
docs/media/README.md Always Explains the role of docs/media/ with naming and format conventions.
.groundrules.json Always Plugin manifest (not meant for manual editing): version, chosen options, intent, generated/adopted/migrated files. Used by resume mode and migrate/verify-bootstrap.
PLAN.md On by default Active todo maintained by Claude during work: In progress / Up next / Waiting / Recently done, with the [~] in-review status vocabulary. Distinct from the long-term roadmap.
docs/VISION.md Intent not skipped Structured synthesis of the intent: Goal, Users/personas, Constraints, V1 non-goals, Acceptance criteria. Required by /groundrules:apply-best-practices.
intake/INTENT.md Intent captured (paste/file) Raw source of the project intent (paste, email, call transcript, PO doc…) before synthesis.
docs/ARCHITECTURE.md Code project Living snapshot of the architecture: overview, stack, components and responsibilities. The why goes in docs/decisions/.
docs/GLOSSARY.md Domain jargon Domain vocabulary, one entry per term, alphabetical — so a new dev (or Claude) understands the domain language.
CHANGELOG.md Versioned releases Change tracking in Keep a Changelog + SemVer format.
docs/DATA_MODEL.md The project has a database Entities/tables and their fields, relationships, row-level access rules (RLS), indexes, migrations.
docs/SECURITY.md Sensitive / personal data Authentication, authorization, personal data & GDPR compliance, secrets, attack surface, incident procedure.
docs/DESIGN_SYSTEM.md Project with a UI Principles, colors (tokens), typography, spacing/grid, components, accessibility, where tokens live in the code.
docs/ROADMAP.md Long-term trajectory Milestone breakdown (goal, scope, exit criteria, status). Distinct from PLAN.md (active todo).
docs/I18N.md Multilingual project Supported languages and fallback, translation organization, localized formats, translation process.
docs/PROCESS.md Phased way of working The working-method contract: phases, validation gates, interview style, where artifacts live. Claude follows it and never skips a phase.
RELEASE.md Project deploys somewhere Operational release runbook: TL;DR commands, environments table, pre-release checklist, secrets, rollback, known fragilities.
docs/AGENT-EVALS.md Long agent-driven project A log of the agent's own failure modes here (recurring mistakes, hallucinations, drifts) + the guard added for each. Distinct from LEARNINGS.md (project/domain). Fed by the checkpoint-capture ritual (before a push/release).
docs/ADOPTION-LOG.md adopt, opt-in A dated, frozen record of the adopt run — what was here, what groundrules did (and why) — with a Remarks section to annotate and share back to improve groundrules. A field → plugin feedback channel.
loop/ + ## Invariants in CLAUDE.md Opt-in (off by default) Loop scaffolding: maker.md/verifier.md (an independent verifier that distrusts the maker's report), LOOP.md, a capped run-loop.sh (hard iteration ceiling), and backlog.md (loop-safe tasks only). Adds an ## Invariants section the verifier enforces each iteration, and a triage convention for loop/blocked.md (the backward crossing: re-decompose / decide → ADR / fix interactively, with a Resolution: audit trail). Not offered when superpowers is detected (it defers the realization).

Every generated file carries a <!-- generated-by: groundrules --> signature, which enables resume mode: re-run a skill on a non-empty folder with no overwrite risk.

Already using superpowers?

superpowers and groundrules work at different altitudes — they don't overlap. superpowers owns the realization of a feature: it turns a conversation into a technical spec, a TDD implementation plan, and runs a maker/verifier loop to build it. It's excellent at how to build — and groundrules detects it and defers that whole pipeline to it.

What superpowers deliberately leaves out is exactly what groundrules adds, without duplicating a line of its design:

  • The durable why — ADRs, LEARNINGS, VISION. superpowers' specs and plans are per-feature and volatile; groundrules keeps the stable, hand-curated memory that survives across features and sessions. It's the antidote to the comprehension debt a fast build pipeline creates: superpowers builds the loop, groundrules keeps you the engineer.
  • The PRD altitude above the spec — problem framing, measurable success criteria, and risks. A superpowers spec covers context, design, and scope, but not these; a short docs/prd/<feature>.md sits above its spec (/groundrules:prd offers just that thin layer when superpowers is present).
  • The cross-cutting "now" — PLAN.md as the single backlog/in-progress view, pointing to the active superpowers plan instead of restating its tasks.

You keep the build pipeline superpowers is great at; you gain the memory and the high-altitude framing it doesn't provide.

Philosophy

  • Template over code — plain {{KEY}} text substitution, never a template engine or application logic (ADR 0002).
  • The repo is the only memory — project knowledge lives in the repo docs, never in an agent's machine-local memory or scattered notes (ADR 0020).
  • Living docs — every generated doc is kept in sync in the same change that makes it stale; maintenance is part of the task, not a follow-up.
  • Never overwrite without confirmation — resume mode detects what exists and offers skip / overwrite / save-as-.new; your edits are safe.
  • Offline-first — only apply-best-practices needs the network; the rest works offline (the update check fails silent).
  • Posture, not just process — the generated CLAUDE.md tells the agent to push back (challenge off-strategy/wrong plans, don't be sycophantic) and stay reversible (confirm before hard-to-undo actions).
  • A handoff, not gospel — a generated CLAUDE.md is a starting point you edit and enrich, not absolute truth.

The full reasoning behind every structural choice lives in docs/decisions/.

What the research says

groundrules' core choices aren't aesthetic — they follow published findings from three fields: how language models behave under load, software-engineering economics, and usability research. The receipts:

Choice What the research shows Recorded in
Keep CLAUDE.md small; store exhaustively on disk, load on demand Model accuracy degrades as input grows — measured across 18 frontier models, Claude included (context rot, Chroma 2025) — and the lost-in-the-middle effect drops accuracy ~30% for information buried mid-context (Liu et al., 2023). Anthropic's own guidance caps CLAUDE.md at < 200 lines ("larger files produce lower adherence"). ADR 0021, docs/CONTEXT-ECONOMY.md
Index + native read over a doc-search/RAG layer (for your own docs) The cost is in always-loaded tokens; reading a file natively is cheaper and lossless. A RAG/graph layer earns its keep only for large external corpora you can't fit. ADR 0021
Make the agent push back (don't be sycophantic) Sycophancy is a general, measured behavior of state-of-the-art assistants, driven by preference training that rewards agreement (Sharma et al., Anthropic, 2023). A default posture demanding pushback counteracts a documented bias. ADR 0026
Spec a non-trivial feature before building it (/groundrules:prd) Software-engineering economics has shown for decades that the cost of fixing a defect rises sharply the later it's caught: a misunderstanding corrected in the spec is a sentence; caught after the build it costs far more (Boehm, Software Engineering Economics, 1981 — the exact multiplier varies with project size). A PRD surfaces the ambiguity early. ADR 0026
Stay reversible — confirm before hard-to-undo actions, keep an escape hatch "User control and freedom" is one of Nielsen's foundational usability heuristics: people will act by mistake and need a clearly-marked exit and undo (NN/g). For an agent acting on your repo, that exit is git + /rewind + confirm-before-destructive. ADR 0026

One honest caveat — so this stays evidence, not marketing: the rest of the design — the repo is the only memory, living docs, never-overwrite — follows from a plain fact (agents are stateless across sessions, and their window degrades within one) plus engineering prudence, not a single paper. And some choices aren't lab findings at all but recognized standards — those have their own section below, kept separate on purpose.

The reasoning for every choice is recorded in docs/decisions/.

Established practices we adopt

Not everything here is a research result — and we won't pretend it is. Some choices are recognized engineering standards: proven in practice, widely understood, no lab paper needed. We adopt them because they're established, and label them as such.

Practice Why we adopt it Reference
ADRs — one short file per structural decision Captures the why of a decision in a durable, greppable form, so the reasoning outlives the people who made it. Michael Nygard's format is the de-facto standard. Nygard · docs/decisions/
Keep a Changelog — a curated, human-readable history git log is a transcript, not a summary; a hand-curated changelog tells a person what actually changed between versions. The [Unreleased] accumulator keeps it current without per-commit churn. keepachangelog.com · CHANGELOG.md
Conventional Commits — feat: / fix: / docs: … A predictable commit grammar makes history scannable for humans and parseable for tooling (automated changelog, version bumps). conventionalcommits.org
Semantic Versioning — MAJOR.MINOR.PATCH A version number that means something: consumers can tell at a glance whether an update is a fix, a feature, or a breaking change. semver.org
Test-Driven Development — a failing test before the code (loop regime only) When a task is handed to the autonomous loop (/groundrules:realize), a pre-written, currently-red acceptance test is the loop's back pressure: the maker makes it green, an independent verifier replays it. Red-first is Kent Beck's discipline; groundrules applies it as the loop precondition — not a global mandate (interactive work keeps the human as back pressure, handoff-not-gospel). Beck, TDD by Example · ADR 0027

These aren't dressed up as science — they're conventions we chose deliberately, and the choice itself is recorded where every other one is: docs/decisions/.

Updating the plugin

Updating is two steps — and skipping the second is the most common trap.

# 1. Refresh the marketplace catalog — this does NOT update your installed plugin
/plugin marketplace update claude-code-groundrules

# 2. Update the installed plugin itself — the step people miss
/plugin install groundrules@claude-code-groundrules     # re-installing pulls the new version
# (or: /plugin → select groundrules → Update)

Then restart Claude Code. A new skill ships in its own directory and only registers on a full restart — /reload-plugins alone surfaces edits to existing skills, not a brand-new command.

Why two steps? /plugin marketplace update only refreshes the catalog; your installed plugin stays on its old version until you explicitly reinstall/update it. If a new command (e.g. /groundrules:slim) doesn't appear even after a restart, you almost certainly did step 1 but not step 2. Check the version you actually have: ls ~/.claude/plugins/cache/claude-code-groundrules/groundrules/.

To avoid the trap entirely, turn on auto-update: /plugin → Marketplaces tab → select claude-code-groundrules → Enable auto-update.

bootstrap, adopt and migrate also run a best-effort update check when invoked (single git ls-remote, ~3s timeout, silent when offline) and print a notice if a newer version is published. To update an already-bootstrapped project after updating the plugin, run /groundrules:migrate in that project.

Requirements for the remote

If absent, the plugin shows the ready-to-paste commands for manual execution.

Plugin structure

groundrules/
├── .claude-plugin/plugin.json       # manifest
├── .claude-plugin/marketplace.json  # mono-plugin marketplace
└── skills/<name>/SKILL.md           # one slash command per skill
    bootstrap also has templates/    # Markdown templates

Contributing

Issues and pull requests are welcome. A few conventions:

  • Structural changes go through an ADR — propose one with /groundrules:add-adr (or describe the decision in the PR so it can become one).
  • The plugin dogfoods itself — this repo uses its own generated structure (docs/, intake/, ADRs, PLAN.md), so changes should keep the dogfood coherent.
  • Templates are plain text — {{KEY}} substitution only, no engine.

References

The findings behind the design choices above:

The complete per-decision history lives in docs/decisions/ and CHANGELOG.md.

License

MIT © 2026 Guillaume Ferrari.

About

Claude Code plugin to bootstrap new projects interactively — interview, docs scaffolding, ADRs, git init, optional remote.

Resources

Readme

License

MIT license
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases 23

v1.6.0 — M1 Loop-readiness Latest
Jun 14, 2026
+ 22 releases

Packages

 
 
 

Contributors

Languages