Claude Code Setup

claude-code-setup

The quality layer for Claude Code. Not everything you need — what actually survived seven months of daily use.

Two layers, one selection rule:

Layer	What's in it	Why it holds
Enforcement — hooks	claim-guard (no "done" without a run) · scope-lock (no inventing files) · bash guard (no destructive commands, no cd that breaks other hooks)	Rules written in CLAUDE.md are followed about half the time. Hooks are followed always.
Workflow — skills	deep-research · systematic-debugging · pr-hero · rpi-methodology, plus a shelf of six more	Skills guide the parts hooks can't enforce — and a usage log decides which ones stay.

The selection rule: every component is telemetry-tracked, and the numbers are published below — including the components that scored zero. This is not a collection; it's what was kept.

The plugin wires exactly 6 hooks and nothing else. Everything beyond the core is opt-in — breadth you didn't opt into costs you nothing, and in an LLM tool breadth has a real price: it's paid in context, every turn.

This is also not a framework you live inside. Hooks are short Python files, skills are Markdown — all of it lands readable in your .claude/, yours to edit. Think component-copy, not runtime dependency.

---

Why the enforcement layer is not a documentation problem

Vercel ran a controlled eval in January 2026. A skill with a default description scored 53% — exactly the no-guidance baseline, zero gain; in 56% of runs the model never invoked it. Adding an explicit instruction in AGENTS.md got it to 79%. Scott Spence's 250-eval harness found the same shape, and found what closes the gap: a forced-eval hook reached 100% activation with zero false positives.

So writing the rule more emphatically does not work, and it is not your phrasing. A text instruction is a probability; a hook is a rule. Worse, the two interact badly: compliance decays with the length of the instruction list, so every rule you append in frustration weakens the ones already there.

Two ways in, depending on how much time you have:

• 📖 The pitch — ~10 minutes. The argument, the mechanisms, and the risks, in the order you'd present them to a team. Speaker notes included; the spoken narrative + Q&A is there too if you have to defend it.
• 🔬 docs/instruction-mechanics.md — the full picture with sources: the four layers rules live in, why text runs at ~50%, hook mechanics including what is architecturally impossible, the permissions-vs-hooks boundary, and a worked example of a "simple" task that produced five database tables nobody wanted.

Read one of them before installing. Hooks you cannot explain are hooks you should not run — see Trust.

---

Install

The repo is a plugin. Loading it as one means your settings.json is never touched — hooks ride inside the plugin, which sidesteps the entire class of installers that destroy user config.

git clone --branch v1.1.0 https://github.com/akuroglo/claude-code-setup \
  ~/.claude/skills/claude-code-setup

Restart Claude Code. A directory under ~/.claude/skills/ containing .claude-plugin/plugin.json loads as a plugin on the next session — no remote marketplace, no install step.

Alternatively, register the clone as a local marketplace — this is what .claude-plugin/marketplace.json is for — by adding to ~/.claude/settings.json:

{
  "extraKnownMarketplaces": {
    "akuroglo": {
      "source": { "source": "directory", "path": "/path/to/claude-code-setup" }
    }
  },
  "enabledPlugins": { "claude-code-setup@akuroglo": true }
}

This is how the origin setup runs it: one clone, enabled globally, hooks active in every project without touching any project's config.

Then verify it actually works before trusting it:

bash ~/.claude/skills/claude-code-setup/tests/run-all.sh

Pin the tag, don't track main — see Trust.

Let Claude install it

The deploy-setup skill reads your project, asks a few questions, shows a plan, and writes only after you approve:

install this setup in my project

It picks a profile, adapts what it writes to your stack, never overwrites an existing CLAUDE.md (it appends inside markers), and records a manifest so the install can be updated or reverted.

Manual wiring instead

If you would rather not run it as a plugin, templates/settings.json.example has the full wiring for all events. Merge it into .claude/settings.json yourself — paths use $CLAUDE_PROJECT_DIR.

Turning on scope-lock

scope-lock is inert until you give it an allowlist, so installing it changes nothing until you opt in:

// .claude/scope-lock.json
{
  "enabled": true,
  "contract": "CONTRACT.md",
  "allow": ["web/**", "server/main.py", "*.md"]
}