Advisory
CLAUDE.mdRead at session start. Can be ignored if context fills. Soft guidance — Claude will usually follow it, but there is no enforcement mechanism.
Features · Project Brain
Project Brain
The context layer Claude reads at the start of every session. Stops re-derivation. Keeps decisions stable across hundreds of tool calls.
What it is
A CLAUDE.md plus auxiliary context files.
Claude Code reads CLAUDE.md at the start of every session — and on every significant tool call. That file is the brain: a structured document telling Claude what stack it's in, what conventions to follow, which agents exist, and what decisions have already been made.
The kit installs an opinionated, pre-filled version of this file tuned for Next.js + Supabase, plus a set of rules files and a source-of-truth directory that extend and reinforce it.
What's inside
Four layers of context.
Project context
One paragraph orienting Claude in thirty seconds. Stack, deploy target, auth provider, database setup. Enough for Claude to start with the right assumptions rather than ask.
Stack-specific decisions
Structured entries in the source-of-truth directory: "we use App Router not Pages Router," "RLS is required on every user-data table," "migrations are reversible — no DROP without a corresponding CREATE." These are written once and stay stable.
Subagent registry
A map of which agents exist and what each one's scope is. Code-reviewer owns diffs. Planner owns plan state. Security-reviewer owns authentication surfaces. Claude knows who to delegate to.
Conventions list
File paths, naming patterns, where logs go, how secrets are handled, when to ask before writing. The conventions Claude would otherwise forget between sessions.
CLAUDE.md template
Eight sections. Under 100 lines.
The kit holds CLAUDE.md to under 100 lines because real benchmarks show degradation past that point — the file begins to compete with the task context rather than supplement it.
- Tech stackLanguage, framework, database, deploy target. One paragraph.
- File structureThe top-level directories and what goes where.
- Key filesThe five or ten files Claude should know by heart.
- CommandsHow to run tests, start the dev server, run migrations.
- ConventionsNaming patterns, where logs go, how secrets are handled.
- Subagent architectureWhich agents exist, what each one owns, how to invoke them.
- What NOT to includeExplicit list of things that should not live in CLAUDE.md — large schemas, full API references, deployment checklists. These belong in source-of-truth documents.
Three-tier instruction hierarchy
Advisory, scoped, deterministic.
Claude is a probabilistic actor. The kit places each guardrail at the strictness level that fits — advisory context for soft guidance, scoped rules for automatic enforcement, shell hooks for hard blocks Claude cannot override.
Scoped
.claude/rules/Auto-fire on file-pattern match. When Claude touches a file that matches the glob, the rule is injected automatically. Claude cannot skip rules the way it can ignore a long CLAUDE.md.
Deterministic
.claude/settings.jsonShell commands executed by Claude Code directly. Exit 2 blocks the action and surfaces stderr to Claude. No model in the loop — this is a hard block.
Context-window toolbox
Six commands for managing context pressure.
A long-running session accumulates context. These commands — plus two hook events the kit wires — let you manage it deliberately rather than hitting the wall.
/clearWipe the conversation, open a fresh window. Use when the session has drifted or accumulated noise.
/compactSummarise earlier turns and drop them. Keeps the active context; reduces token pressure.
/contextShow current context usage. How many tokens are loaded, how much headroom remains.
/rewindBack up N messages. Undo a chain of tool calls without starting over entirely.
PreCompact hookFires before context compresses. The kit uses this to save state — open issues, current task status — so the post-compact session knows where it was.
PostCompact hookFires after compression. Reloads the saved state. The session continues as if the compress did not happen.
Component architecture rules
Four structural rules for components that stay maintainable.
If a fix requires SSH, the architecture is wrong
Infra-as-code or it does not ship. docker/caddy/, docker/systemd/, and docker/firewall/ all live in repo and are applied by deploy.sh. No manual server state.
One test file per component
No shared test fixtures bleeding across components. A test that relies on fixture state set up by a different test is not a test — it is a coupling.
Single access path
Do not expose the same data through three routes. If a piece of data has three callers, two of them are future confusion.
Ontology before code
Each component type is defined before any code is written: what it is, why it exists, what it may do, what it must not do, its influence chain. The kit sequences ontology in Layer 11, before epic planning in Layer 08, so types stay coherent when scope expands.
Why it matters
Without this, Claude re-derives everything.
Claude has no persistent memory between sessions. Each new conversation starts blank. Without a project brain, it re-derives your stack from the file tree — which works, but costs tokens and drifts. Every session is a fresh guess.
With a project brain, Claude opens with the right assumptions already loaded. It knows App Router is the target, not Pages Router. It knows RLS is required. It knows which agent handles review. No re-derivation. No drift.
Files installed
What lands on disk.
CLAUDE.md __documentation/recovery-playbook.md .claude/rules/context-discipline.md
Everything is reconciled against your existing .claude/ — never clobbered. The manifest preview shows every conflict before anything is written.
Before / after
One concrete example.
Without project brain
Claude proposes Pages Router routing on a new page. You correct it. Same correction next session.
With project brain
Claude opens with App Router patterns automatically. Decision made once, held indefinitely.