claude-project-kit

A governance starter kit for AI-agent-driven projects.

The four-file governance chain (PRODUCT, DESIGN, AGENTS, GLOSSARY) plus the hooks works for any project type and any design register. The root templates ship one example combo (a brand landing page in the cinema register); browse registers/ and project-types/ for other combos and adapt.

This kit is not a generator. It is what disciplines a project that uses Claude Code (or Codex, or Cursor, or Copilot CLI) to build, redesign, or maintain a real surface.

---

Why this exists

Three months of building real surfaces with AI agents surfaced one consistent failure: the project passes every individual rule in the spec and still feels generic. A landing page collapses back to gradient hero and three-card feature row. A web app collapses back to shadcn defaults with no brand discipline. A CLI collapses back to the framework's auto-generated --help output. A design system collapses back to unstyled-Radix-with-no-tokens.

The cause: rules without enforcement. The fix: a chain of governance files that work together, each carrying a specific job, plus a literal yes/no checklist the agent runs at the end of every pass.

The chain answers four questions an agent needs to ground its work:

File	The question it answers
PRODUCT.md	Who is this for, and what must it not look or sound like?
DESIGN.md	What are the visual tokens, motion patterns, and self-review gate?
AGENTS.md	How do I run, build, deploy, and what are my boundaries?
GLOSSARY.md	What are the canonical names for products, formats, audiences, and CTAs?

Plus two Claude Code hooks that fire context-budget reminders so the session-summary workflow does not run out of room.

The kit assembles the chain. Each individual file pattern exists somewhere on GitHub. The integration around governing AI-agent-driven projects across multiple project types and registers does not.

---

Two flexibility axes

The kit ships defaults for one example combo at the root. Real projects pick a different combo by browsing two sets of profiles.

Design register (the visual language)

registers/ ships five opinionated profiles. Each describes voice, color strategy, typography, motion register, surface treatment, anti-references, and a "when to choose" guide.

Register	Aesthetic
cinema.md (root default)	Golden amber on dark canvas, oversize display serif italic, 3D heroes, Lenis-smoothed scroll, GSAP scrub
editorial.md	Magazine-grade typography, ruled separators, mono microlabels, restrained color, plenty of white space
brutalist.md	High-contrast geometric blocks, mono-driven typography, raw HTML feel, deliberate ugliness, hard edges
minimal.md	Linear/Notion-style restraint, flat surfaces, generous spacing, single accent, body-font-led
terminal.md	Terminal-native dark, monospace dominance, ASCII art, command-line aesthetic

See docs/choosing-a-register.md for the decision guide.

Project type (the project shape)

project-types/ ships four opinionated profiles. Each describes the typical shape, stack defaults, core surfaces, AGENTS.md variant specifics, and self-review gate adjustments.

Project type	Shape
landing-page.md (root default)	Single brand surface, marketing routes, no auth, Vercel auto-deploy
web-app.md	Multi-page SaaS / dashboard with auth + database, more aggressive boundaries
cli-tool.md	Terminal-distributed package, semver discipline, cross-platform CI
design-system.md	Component library or design tokens, accessibility, visual regression, Changesets

See docs/choosing-a-project-type.md for the decision guide.

The two axes are independent. A web-app can ship in any of the five registers; a CLI tool usually ships in terminal but can ship in minimal if the buyer is non-technical. Pick the project type first (it sets the boundaries and verification chain), then pick the register (it sets the visual language).

---

What you get

claude-project-kit/
├── README.md                      this file
├── template-README.md             the post-fork README to install at your project root
├── LICENSE                        MIT
│
├── CLAUDE.md                      one-liner @AGENTS.md (the doorbell pattern)
├── AGENTS.md                      build, structure, style, testing, git, boundaries, definition of done
│                                  (the landing-page variant; see project-types/ for others)
├── PRODUCT.md                     register, users, brand personality, anti-references, design principles
│                                  (project-type-agnostic schema; example values)
├── DESIGN.md                      OKLCH tokens, typography, motion canon, components, self-review gate
│                                  (the cinema register; see registers/ for others)
├── GLOSSARY.md                    domain vocabulary lock for product, formats, audiences, CTAs, voice
│
├── registers/                     five design register profiles
│   ├── cinema.md
│   ├── editorial.md
│   ├── brutalist.md
│   ├── minimal.md
│   └── terminal.md
│
├── project-types/                 four project-type profiles
│   ├── landing-page.md
│   ├── web-app.md
│   ├── cli-tool.md
│   └── design-system.md
│
├── .claude/
│   └── settings.json.example     autoCompactWindow=850000 + hooks wiring (copy to ~/.claude/)
│
├── hooks/
│   ├── graphify-precompact.sh    macOS notification before context compacts
│   └── graphify-stop.sh          in-terminal reminder on session end
│
└── docs/
    ├── self-review-gate.md       the 10-item checklist explained per item
    ├── anti-references-pattern.md why naming bad brands steers generation
    ├── context-budget-tuning.md  the math behind autoCompactWindow=850000
    ├── choosing-a-register.md    decision guide across the five registers
    └── choosing-a-project-type.md decision guide across the four project types

Every governance file in the kit ships as a populated template, anchored to a fictional brand called Lumen Studio. Customize the placeholders for your brand before using.

---

How to use it

1. Fork or copy the kit into your project root

gh repo clone ndreddy007-sudo/claude-project-kit your-project
cd your-project

Or copy the files into an existing project:

cp /path/to/claude-project-kit/{CLAUDE,AGENTS,PRODUCT,DESIGN,GLOSSARY}.md ./
cp -r /path/to/claude-project-kit/{docs,hooks,.claude,registers,project-types} ./
mv template-README.md README.md

2. Pick your project type and register

Read docs/choosing-a-project-type.md and pick from landing-page, web-app, cli-tool, design-system. Then read docs/choosing-a-register.md and pick from cinema, editorial, brutalist, minimal, terminal.

The root templates ship the landing-page-plus-cinema combo. If your combo differs:

• Open the matching registers/<chosen>.md and adapt your DESIGN.md token block, typography, motion, and surface treatment to match.
• Open the matching project-types/<chosen>.md and adapt your AGENTS.md build commands, boundaries, testing, and definition of done to match.

3. Customize for your brand

Replace Lumen Studio and the example placeholders throughout PRODUCT.md, DESIGN.md, and GLOSSARY.md. The structure stays; the content is yours.

The order of customization matters:

1. PRODUCT.md first. Your register, users, brand personality, anti-references, design principles. Decide what the brand is and is not before deciding how it looks.
2. DESIGN.md second. Your tokens, typography, motion, components. Pull the values from the chosen registers/<chosen>.md. The self-review gate at the bottom stays as-is; that is the kit's enforcement layer.
3. GLOSSARY.md third. Your product name, format names, audience names, CTA verbs.
4. AGENTS.md last. Pull the section contents from the chosen project-types/<chosen>.md. Your build commands, project structure, boundaries.

4. Wire the hooks (optional but recommended)

If you run a vault-discipline workflow (an Obsidian vault, a session running-note in 00_inbox/, a periodic graphify or wiki-compile pass), the hooks fire reminders so the wrap workflow does not run out of context.

# Set your inbox path
export VAULT_INBOX="$HOME/path/to/your/vault/inbox"

# Copy the example settings, then edit absolute paths
cp .claude/settings.json.example ~/.claude/settings.json
$EDITOR ~/.claude/settings.json

Update the command paths in the hooks block to the absolute path where you cloned this kit. See docs/context-budget-tuning.md for the threshold math.

5. Use the chain in your workflow

When you start a pass:

1. Open PRODUCT.md and confirm the brief.
2. Open DESIGN.md and read the relevant sections.
3. Author the change.
4. Run the self-review gate in DESIGN.md (the 10-item checklist, adapted per project type).
5. Fix any "no" answers.
6. Rerun the gate.
7. Ship only when all 10 items pass.

The gate adds about 10 minutes per pass and prevents the AI failure modes per project type: gradient hero on a landing page, shadcn-default on a web-app dashboard, auto-generated --help on a CLI, unstyled-Radix-with-no-tokens on a design system. See docs/self-review-gate.md for each item explained.

---

What makes this kit different

Existing pattern	What this kit does instead
Single-file kits (only AGENTS.md or only DESIGN.md)	Four-file governance chain, each owning a specific job
General-purpose Claude Code starters	Multiple project types (landing, web-app, cli, design system), each with its own boundaries and verification chain
AI-generated templates with no register choice	Five opinionated registers (cinema, editorial, brutalist, minimal, terminal) with anti-references per register
Hook recipes scattered across blog posts	Hooks integrated with the chain, with documented autoCompactWindow=850000 rationale
.cursorrules plus copilot-instructions.md plus CLAUDE.md	One-line @AGENTS.md doorbell so every agent reads the same rules, no duplication
Rules without enforcement	A 10-item self-review gate the agent runs as a literal yes/no checklist before shipping

The integration is the value. Each piece is replaceable; the assembled chain is what stops a project from collapsing back to template.

---

Concepts the kit teaches

The docs/ folder explains the why, not just the how. Five explainers:

• docs/self-review-gate.md walks through every one of the 10 items: what it asks, what failure looks like, what passes look like, and how to verify it programmatically when possible.
• docs/anti-references-pattern.md explains why naming bad brands steers generation more than naming good ones, and how to write anti-references that actually constrain the agent's output.
• docs/context-budget-tuning.md shows the math behind the 850k threshold and how to tune for your own session profile.
• docs/choosing-a-register.md is the decision guide across the five registers, with an interview, a project-type-to-register table, and cross-cutting anti-references.
• docs/choosing-a-project-type.md is the decision guide across the four project types, with edge cases, the AGENTS.md diff table, and the boundaries that change per type.

---

What the kit is not

• Not a generator. It does not produce code from a prompt; it disciplines a project that does.
• Not a Next.js boilerplate. The landing-page variant assumes Next.js + Tailwind v4; the web-app, cli-tool, and design-system variants ship their own stack defaults. None of the variants ships the stack itself.
• Not opinionated on every choice. The kit ships a default combo at root (landing-page plus cinema); five registers and four project types are alternatives, each opinionated within itself, none mandatory.
• Not Cursor-specific or Codex-specific. The doorbell pattern (CLAUDE.md is @AGENTS.md) means every agent that reads AGENTS.md natively (Codex, Cursor, Copilot CLI, Claude Code) gets the same rules.

---

Acknowledgments and influences

The kit assembles patterns from several public sources:

• @anthropic/impeccable Claude Code skill (the canonical PRODUCT.md schema, design-register definitions, the four color strategies)
• @google/design.md open spec (the YAML front-matter token format)
• GitHub's 2,500-repo AGENTS.md analysis (the six-section structure)
• paperclipai/paperclip (the read-this-first pointer pattern)
• VoltAgent/awesome-design-md (canonical DESIGN.md examples and naming conventions)
• The cinema register vocabulary draws on Linear, Klim Type Foundry, Vercel as anti-template aesthetic anchors
• The terminal register vocabulary draws on Fly, Railway, Supabase developer pages
• The editorial register vocabulary draws on Klim, Are.na, Pentagram

If you ship something like this kit, please link back. If a pattern in this kit improves, please open a PR.

---

License

MIT. Use it, fork it, ship with it. Attribution is appreciated but not required.