claude/README.md

claude-config

One repo that turns Claude Code into a reproducible engineering system — skills, agents, hooks, plugins, and per-project memory, versioned and symlinked into ~/.claude/. Clone it on any machine, run one command, and every project gets the same assistant with the same rules.

What it is

Not a collection of prompts — an operating layer on top of Claude Code:

• Skills (/feat, /bugfix, /ship-feature, /seo, /tour…) are the entry points: each one encodes a complete workflow, from quick fix to full feature pipeline with validation gates.
• Agents are the execution units skills dispatch to — each pinned to the cheapest model that can do the job (haiku collects, sonnet executes, opus judges, the session model only reflects).
• Hooks and permissions are deterministic guardrails: gitflow enforced by a pre-commit hook, every commit pushed by post-commit and post-merge hooks, main/develop undeletable by a reference-transaction hook, deny-first permission rules, secrets kept in ~/.claude/.env and never in config files.
• Templates and memory seed every project with persistent registries (decisions, learnings, blockers) — what a session learns, the next session knows.

How it works

git clone --recurse-submodules https://github.com/bchanot/claude
cd claude
make install     # CLI + auth + symlinks + plugins (pinned in plugins.lock.json)
make doctor      # verify everything

link.sh symlinks the repo into ~/.claude/, so editing here updates the live config — and git log is the audit trail of your entire setup. Day to day:

/onboard            # bring an existing repo into the framework
/ship-feature "…"   # brainstorm → plan → adversarial challenge → TDD → review → merge
/feat "…"           # same idea, 1-5 files, no ceremony
/close              # flush decisions and learnings to memory before quitting
make update         # keep CLI, plugins, and submodules current

Why it's good

• Reproducible. One clone rebuilds the whole environment; versions are locked, make doctor proves it works.
• Cost-shaped. Model tiering routes reflection to the big model and execution to cheap ones — the expensive context does only what it must.
• Safe by default. Protected branches, ask-before-run on risky tools, parameterized secrets: the guardrails are code, not good intentions.
• It compounds. Memory registries, audit skills, and doc-sync keep every project's knowledge growing across sessions instead of evaporating.

---

Everything below is the reference manual — model routing, components, commands, settings, secrets, maintenance.

---

Agent model routing (model-tiering v2)

Doctrine: the session model (Fable) does main-loop reflection ONLY — brainstorm, plan, contract, audit judgment, gates, loop decisions — enforced by a blocking gate (lib/model-gate.md + lib/model-check.sh) at the entry of the 13 reflection orchestrators. Nothing dispatched inherits silently: typed agents carry a frontmatter pin, built-ins get an explicit model= at every call site.

Agent	Model	Tier
feater, hotfixer, bugfixer	sonnet (pinned)	executors — code from a closed plan (feat), fix from a closed diagnosis (bugfix), fix-bundle appliers
verifier, security-auditor	sonnet (pinned)	fresh gates (≤3×/loop)
commit-changer, release-executor, code-cleaner	sonnet (pinned)	dispatched execution — grouping+commit / release spans / approved cleanup (audit + approval gates stay in the dispatcher)
onboarder, scaffolder, refactorer, validator-analyzer, plugin-probe	sonnet (pinned)	workers — config generation, scaffold, refactor, deterministic W3C/WCAG runner, mechanical plugin probe
status-reporter	haiku (pinned)	mechanical collector
analyzer, plan-challenger, plugin-advisor	opus (pinned)	dispatched judgment — pre-plan analysis, 3-lens adversarial plan challenge (/ship-feature STEP 2b), plugin-fit reasoning
seo-analyzer, geo-analyzer	opus pin (judge mode); collect/template spans dispatched model="sonnet"	3-mode audit pipelines — judgment fail-closed on opus, mechanical collect + templating on sonnet
doc-syncer	sonnet pin; audit mode dispatched model="opus"	two-mode: audit (drift judgment, opus) / patch (mechanical apply, sonnet)
handover-doc-writer	sonnet pin; synthesize mode dispatched model="opus"	two-mode: synthesize (opus) / render (sonnet) — client deliverable
interviewer, client-handover-writer	unpinned (inline-load = session model)	they ARE the main loop — a frontmatter pin would be inert
Explore (built-in)	inherit session (Fable/Opus)	search feeds reflection — kept on the big model, not pinned down

The pure-execution skills /doc, /status, /commit-change, /release-candidate dispatch their agent (instead of inline-loading it) so the pin takes effect and the work leaves the big session model; /hotfix was split like /feat (reflection inline + gate, hotfixer executor) and so joins the gated group (13th); /client-handover's nested skill-runner children are dispatched model:"fable" (they carry reflection).

---

Install notes

All scripts use their own location to find the repo — run them from anywhere. The plugins step logs to install-YYYYMMDD-HHMMSS.log.

Optional — Context7 (fast doc lookup for React / Next.js / Prisma…): the plugins step installs the ctx7 CLI and wires it into Claude Code. The doc-fetch surface is the find-docs skill alone (the generated rules/context7.md is purged by design; if you run ctx7 setup manually, delete that rule or re-run make plugin). A once-per-session ctx7-reminder hook nudges toward it when the current project carries fast-moving libs (lib/fast-libs.sh) — a scoped second surface, a refinement of the single-surface rule, not a reversal.

ctx7 login                 # optional: OAuth / API key for higher rate limits

---

Installed components

Component	Type	Description	Docs
Superpowers	Plugin (required)	Brainstorming, planning, subagent-driven dev, code review, branch finishing. Required by /init-project and /ship-feature.	obra/superpowers-marketplace
GStack	Plugin (toggle)	Full-product workflow: UI + design + deploy + browser QA. Skip for backend/CLI projects.	garrytan/gstack
GSD v2	External CLI	Multi-session orchestration: crash recovery, cost tracking, parallel workers, context-fresh execution.	gsd-build/gsd-2
RTK	Plugin (always on)	Code rewrite hook. Zero passive cost.	rtk-ai/rtk
security-guidance	Plugin (always on)	Security hook. Zero passive cost.	anthropics/claude-code
ui-ux-pro-max	Plugin (toggle)	Design system, color/typography choices. Enable for design-heavy projects.	nextlevelbuilder/ui-ux-pro-max-skill
Context7	Plugin (toggle)	Fast-evolving libs doc lookup (Next.js, React, Prisma...). Works anonymously; optional ctx7 login raises rate limits.	context7.com
pr-review-toolkit	Plugin (toggle)	Multi-agent PR review.	anthropics/claude-code
Graphify	Python CLI	Codebase → knowledge graph → navigable wiki. Helps Claude map and search projects efficiently.	pypi: graphifyy

Versions are pinned in plugins.lock.json. To update: edit the file, then re-run install-plugins.sh.

Graphify installs via pipx/PyPI only, never npm/npx: a different publisher squats the same graphifyy name on npm (version-shadowing shim re-exporting a different package, ships its own conflicting graphify bin) — see plugins.lock.json's graphifyy note.

---

Slash commands

Command	Description
/init-project	Initialize a complete project from scratch (full orchestrator, 12+ steps)
/ship-feature	Ship a feature end-to-end with validation gates (full orchestrator)
/onboard	Onboard an existing project — generate CLAUDE.md, settings, .claudeignore
/feat	Small feature implementation (1-5 files, lightweight)
/bugfix	Structured bug fix with root cause investigation
/hotfix	Quick fix for superficial bugs (typos, CSS, config — max 2 files)
/analyze	Deep factual analysis of code before any modification
/refactor	Improve code quality without changing behavior
/code-clean	Dead code removal, style/norm enforcement
/doc	Documentation audit and sync — detect stale docs, patch
/seo	Full SEO/GEO audit — real Search Console + CrUX field data when a Google account is connected (make seo-connect)
/impeccable	Design verbs (audit, polish, bolder…) + deterministic anti-slop detector (npx impeccable detect)
/commit-change	Smart commit grouping from staged/unstaged changes
/gitflow	Gitflow branch operations — bootstrap main+develop, start a typed branch, directed merge
/release-candidate	Cut a versioned release — finalize version.txt + CHANGELOG, merge develop→main, tag, push
/deploy	Run a project's deploy from its committed runbook — instantiate the delta, resume cold
/graphify	Codebase knowledge graph — navigation for large-scope tasks
/plugin-check	Check active plugins vs project needs — recommend enable/disable
/health	Code quality dashboard (gstack) — setup diagnostic is make doctor
/status	Consolidated project snapshot — plugins, git, GSD milestone
/skills-perso	List personal (user-created) skills
/audit-delta	Recurring audit of changes since last run (norms, bugs, dead code, security)
/capitalize	Flush uncapitalized context + reconcile TODO before /clear or /compact (--ritual adds the end-of-session reflection)
/prune-memory	Curate and compress the .claude/memory/ registries
/reconcile	Confront declared status (TODO, registries) against real git/fs state — surface stale items
/pdf-translate	Translate a PDF to another language, output as HTML (via Vision)
/close	End-of-session ritual — alias for /capitalize --ritual (dedup + TODO reconcile + 3-question reflection)
/harden	Web hardening audit — HTTPS/TLS, HSTS, CSP, security headers
/web-validate	W3C HTML/CSS validity + WCAG 2.1 accessibility audit
/geo	GEO-only audit — AI-search visibility (ChatGPT, Perplexity, Claude, Gemini…)
/client-handover	Final project delivery — audits + branded deliverable (Markdown / HTML / PDF)
/profile	Activate a skill profile (web / seo / web-full / full / backend / design / dev / qa / audit / minimal)
/tour	Grouped all-axes sweep — cleanup + security + reconcile + doc, fix and loop until clean

This table lists personal skills. Gstack skills (investigate, review, retro, office-hours, context-save, context-restore, cso…) and marketplace plugins add many more — run /skills-perso to list your hand-written skills, or browse skills/.

---

Three core workflows

From scratch — /init-project

/plugin-check "description"     # configure plugins (also runs as STEP 0)
/init-project "description"     # interview → scaffold → implement → review
/ship-feature "next feature"    # ship feature by feature

Existing project — /onboard

cd my-existing-project/
/onboard                        # generates CLAUDE.md + settings + .claudeignore
/plugin-check "project type"
/ship-feature "next feature"

New feature — /ship-feature

/ship-feature "feature description"
# → STEP 0: plugin check
# → STEP 1-2: brainstorm + plan (superpowers)
# → STEP 2b: adversarial plan-challenge (3 lenses, report-only)
# → STEP 3: validation gate — user approval required
# → STEP 4-7: implement (TDD) → review → capitalize (memory)
# → STEP 8: sync README (doc-sync)
# → STEP 9: finish (merge / PR)

For small features (1-5 files), use /feat instead — no orchestration overhead.

---

Settings and permissions

Settings follow a hierarchy (highest priority first):

managed-settings.json   → enterprise (cannot be overridden)
CLI flags               → session only
.claude/settings.local  → personal machine overrides (gitignored)
.claude/settings.json   → project rules (committed)
~/.claude/settings.json → global user rules (this repo)

DENY always wins over ALLOW at any level. .claudeignore applies independently.

Templates for per-project settings are in templates/settings/. Copy them with /onboard or manually:

CONF="$(dirname "$(readlink ~/.claude/CLAUDE.md)")"
cp "$CONF/templates/settings/settings.json" .claude/settings.json
cp "$CONF/templates/settings/.claudeignore" .claudeignore

See templates/settings/SETTINGS.md for the full rule syntax reference (rule types, patterns, defaultMode values).

---

Adding an MCP server that needs a secret

claude mcp add <name> --env KEY=VALUE ... writes VALUE literally into ~/.claude.json (or the project's .mcp.json) — if you pass the real secret on that command line, it materializes as a second plaintext copy outside ~/.claude/.env, invisible to the repo's .gitignore/allowlist reach (this bit us once).

Claude Code expands ${VAR} and ${VAR:-default} in mcpServers config — in env, command, args, url, and headers — for both project (.mcp.json) and user (~/.claude.json) scope. Use that instead of a literal value:

# single-quoted so bash doesn't expand it; Claude Code expands it at
# launch, reading the var from its own process environment:
claude mcp add <name> --scope user --env 'API_KEY=${SOME_API_KEY}' -- <command>

The var still has to exist in the environment of the process that starts claude — sourcing ~/.claude/.env into your everyday interactive shell would defeat the point (every subprocess, every stray env/printenv, would then see it). Wrap the claude command instead: a claude() shell function that sources ~/.claude/.env into a subshell and execs the real binary, so the var reaches claude and its children only, never the ambient shell.

This config registers no MCP server today. The pattern stays documented for the next one that needs a secret.

There is no claude mcp add flag that writes the reference form for you — the ${VAR} syntax has to be typed by hand (or via a wrapper script), same as above.

SEO data layer (/seo FULL) — Google OAuth + CrUX keys

The same ~/.claude/.env also feeds lib/seo-data, which pulls real Google Search Console and Chrome UX Report data into /seo FULL audits. Add these three vars (template with the GCP console steps in .env.example):

# OAuth Desktop client — GCP console → APIs & Services → Credentials →
# OAuth client (Desktop). Consent scope: webmasters.readonly only.
GOOGLE_OAUTH_CLIENT_ID=<your-client-id.apps.googleusercontent.com>
GOOGLE_OAUTH_CLIENT_SECRET=<your-client-secret>
# CrUX + PageSpeed API key — GCP console → Credentials → API key,
# restricted to those two APIs. https://developer.chrome.com/docs/crux/api
CRUX_API_KEY=<your-crux-api-key>

Then run the one-time consent flow: make seo-connect (per-label token store, multi-site safe). Missing credentials never break an audit — /seo degrades gracefully to anonymous PageSpeed lab data.

21st.dev CLI

@21st-dev/cli (bin 21st) is the 21st.dev integration; it replaced the former Magic MCP server this config used to register. Same endpoint, one browser login, no API key, and nothing loaded into a session that isn't using it:

npm i -g @21st-dev/cli
21st login                  # browser flow, token saved in ~/.config/21st

make plugin does both (Step 8.7 installs the CLI, then offers the login in an interactive terminal) and installs the skill pack that drives it: 21st-ui-build, -ui-explore, -ui-review, -cli-use, -ai, plus the two publishing skills -registry and -design-sync. The pack is disabled by default. /profile design turns on the five design skills; bash lib/toggle-external.sh enable 21st turns on all seven.

The pack is machine-owned and gitignored. It cannot be installed the way upstream documents it (21st install-skill, i.e. 21st skills install --global): that writes into ~/.claude/skills/, and the installer refuses to follow a symlink anywhere on that path, while ~/.claude/skills is itself a symlink to this repo's skills/. So the install runs under a throwaway HOME and the result is moved into skills-external/21st-*, where toggle-external.sh and profile.sh symlink it in on demand.

The permission gate is now one autoMode.soft_deny entry covering the outward-facing verbs (21st publish*, submit, edit, delete, remove-from-catalog, profile set|upload), because publishing a component puts it on a public listing under your account. That tier rather than ask: under defaultMode: auto (this config's default) ask rules were observed auto-approving with no prompt raised (LRN-153), so an ask entry would have declared an intent without gating anything.

---

Diagnostic and maintenance

# Terminal
bash doctor.sh              # full diagnostic (symlinks, plugins, permissions, token budget)
bash update-all.sh          # update all components (CLI, plugins, submodules, symlinks)

# Claude Code
/health                     # gstack code-quality dashboard (doctor.sh -> make doctor)
/status                     # project snapshot (plugins, git, GSD milestone)
/plugin-check "description" # audit plugin config vs project needs

# Makefile (from repo directory)
make install                # bootstrap: CLI + auth + symlinks + plugins
make plugin                 # install plugins only
make link                   # create/update symlinks into ~/.claude/
make doctor                 # diagnostic
make update                 # update Claude Code, config, submodules, plugins, and verify
make test                   # run deterministic tests (lib/tests/*.test.sh + lib/seo-data/*.test.sh + lib/gitflow-test.sh + lib/tests/run-*.sh)
make onboard                # onboard an existing project (run from its dir)
make seo-connect            # connect a Google account for /seo FULL (OAuth consent)
make profile cmd="set X"    # activate a skill profile (web/seo/web-full/full/backend/design/dev/qa/audit/minimal)
make profile-list           # list skill profiles
make profile-current        # show the active profile
make profile-reset          # re-enable all gstack skills
make new-skill name=myskill # scaffold agent + skill files

doctor.sh checks: symlinks, GStack submodule, Playwright browser cache, prerequisites (git, Node, Cargo, Python, Claude Code), plugins, permissions, token budget, config consistency.

---

Going further

USAGE.md — workflows and skill decision tree · ARCHITECTURE.md — layout and principles · CHANGELOG.md — version history.