REFERENCE

Rules & hooks

Two quiet layers shape how your team behaves. Rules are always-on guidance every agent follows. Hooks are small scripts the harness runs automatically on certain events — a new session, a git push. Together they're the kit's house style and its reflexes.

You rarely touch either directly. This page is the map of what's there.

Rules

A profile scaffolds a set of rules into .claude/rules/. They're guidance, not code — read by the team on every task.

Rule	What it shapes
communication-style	How the team talks to you — tone, brevity, when to ask vs. proceed.
task-management	The issue → branch → PR → merge → close workflow through GitHub.
plan-output-format	How plans are written and where they live (markdown, mdx, or off).
design-routing	Sends any visual / UX call to the designer instead of being decided ad hoc.
mempalace	When to save and recall memory; writes a curated summary on close. (memory profiles)
skill-gaps	Ask about a missing capability once, only when non-obvious, then remember.
react-annotate	The annotate → locate → fix → resolve loop for UI feedback. (when annotate is wired)

Which rules you get depends on your profile and the options you turned on. See Profiles & configuration.

Hooks

Hooks fire on events, not on request. The kit installs a small, opt-in-friendly set.

Hook	Fires on	What it does
Update check	SessionStart	Quietly notes "update available" if the project trails the installed plugin. A no-op otherwise.
Memory recall	SessionStart	Recalls the project's memory wing at the start of a session. (memory on)
Memory save	Stop	Records decisions and writes the close summary. (memory on)
Memory preserve	PreCompact	Saves context before a long conversation is compacted. (memory on)
Pre-push gate	PreToolUse(Bash)	Runs your command before git push, blocking the push if it fails. (opt-in)

Hooks tied to options you didn't enable simply aren't installed — nothing fires for a feature you're not using.

Stack-gated skills

Build conventions aren't forced rules — they're skills that switch themselves on only when their technology is present in your package.json:

Skill	Activates when	Covers
feature-build-refine	@refinedev/* present	Next.js + Supabase + RefineDev feature/form/page architecture
supabase-patterns	@supabase/supabase-js present	Three-client model, server-action auth guard, RLS-first access

If the tech isn't in your stack, the skill simply doesn't apply. Add more the same way — one self-gating skill per technology. And karpathy-guidelines (guardrails against common LLM coding pitfalls) rides along in every profile.

The pre-push gate (opt-in)

Enable with --prepush "<command>" at init — e.g. --prepush "pnpm -w build". It installs a PreToolUse(Bash) hook that runs <command> before every git push and blocks the push if the command fails. It's self-passing: it only acts on git push, and projects that didn't opt in (or have an empty command) are never blocked. Adjust later via .prePush in kit.config.json.

Spec-Driven Development (opt-in)

Enable with --speckit on (or at the /kit-init prompt). The speckit skill installs or identifies Spec Kit, runs a Stack Interview, and drives the specify → clarify → plan → tasks → analyze → implement lifecycle with review gates. Any matching stack skill becomes the Spec Kit feature-module.md override automatically.

How it works under the hood

• Resolution at init. init.sh resolves conditional blocks in the templates — IF:MEMORY, IF:PROJECTS_V2, IF:PLANS, IF:DESIGN — so only the rules and hooks matching your choices are written.
• The update-check hook. templates/hooks/kit_version_check.sh.tmpl becomes a SessionStart hook that calls scripts/kit-version-check.sh, comparing the project's recorded kitVersion against the installed plugin via a semver-aware sort -V. It prints the notice only when the project is strictly behind.
• Memory hooks. The IF:MEMORY path wires SessionStart / Stop / PreCompact to the MemPalace MCP. Until the runtime is present, they're safe no-ops.
• Pre-push. The gate is a PreToolUse(Bash) matcher that inspects the command, acts only on git push, runs .prePush, and returns a blocking non-zero only on failure.

Where to go next

• Profiles & configuration — which rules each profile brings.
• Commands & scripts — the scripts the hooks call.
• Memory — the memory rule and hooks in plain language.