# Claude Code Infrastructure Showcase

**A curated reference library of production-tested Claude Code infrastructure.**

Born from 6 months of real-world use managing a complex TypeScript microservices project, this showcase provides the patterns and systems that solved the "skills don't activate automatically" problem and scaled Claude Code for enterprise development.

> **This is NOT a working application** - it's a reference library. Copy what you need into your own projects.

**New to Claude Code infrastructure? Three terms cover 90% of this README:**
- **Skill** - a markdown guide (patterns, conventions, examples) that Claude loads when relevant
- **Hook** - a script Claude Code runs automatically at key moments (every prompt, before/after edits)
- **skill-rules.json** - the config that tells hooks which prompts/files should trigger which skills

Full explanations in [Key Concepts](#key-concepts).

---

## What's Inside

**Production-tested infrastructure for:**
- ✅ **Auto-activating skills** via hooks
- ✅ **Modular skill pattern** (500-line rule with progressive disclosure)
- ✅ **Specialized agents** for complex tasks
- ✅ **Dev docs system** that survives context resets
- ✅ **Comprehensive examples** using generic blog domain

**Time investment to build:** 6 months of iteration
**Time to integrate into your project:** 15-30 minutes

---

## Quick Start

### Requirements

- **Node.js 18+** (20+ recommended) and npm
- **macOS, Linux, or WSL2** - the hooks are bash scripts and won't run in plain cmd/PowerShell (Windows users: use WSL2)
- **jq** - only needed if you enable the optional Stop hooks

> Note: the first `npx tsx` run may ask to install tsx - say yes.

### Option A: Setup Wizard (Recommended)

The wizard copies everything, installs dependencies, and configures your mode:

```bash
# 1. Clone this repo
git clone https://github.com/diet103/claude-code-infrastructure-showcase.git

# 2. Run the setup wizard, pointing to YOUR project
cd claude-code-infrastructure-showcase
npx tsx setup.ts ~/my-project
```

The wizard will:
- Copy `.claude/` (hooks, skills, agents, commands) into your project
- Detect your tech stack (React, Express, Prisma, etc.)
- Ask: Classic (regex-only) or AI-Enhanced mode?
- If AI: which provider? Validates API key availability
- Install hook dependencies and make scripts executable
- **Verify its own work** - 8 health checks before it declares success

> Scripting it, or letting Claude Code run it? Add `--yes`:
> `npx tsx setup.ts ~/my-project --yes` (see `--help` for all flags)

### Option B: Manual (3 Commands)

```bash
# 1. Clone this repo
git clone https://github.com/diet103/claude-code-infrastructure-showcase.git

# 2. Copy .claude/ into YOUR project
cp -r claude-code-infrastructure-showcase/.claude ~/my-project/.claude

# 3. Install hook dependencies
cd ~/my-project/.claude/hooks && npm install && chmod +x *.sh
```

### Option C: Let Claude Code Do It (Easiest)

Don't want to touch the terminal? Open Claude Code in your project and paste this:

```text
Clone https://github.com/diet103/claude-code-infrastructure-showcase to a temp
directory and read its CLAUDE_INTEGRATION_GUIDE.md. Then install the
infrastructure into this project by running the setup wizard non-interactively
(npx tsx setup.ts <this project's absolute path> --yes). When it finishes, show
me the verification results and fix anything that failed.
```

Claude clones the repo, runs the wizard (which verifies its own work), and reports back.

### Verify It Works (30 Seconds)

Any time, from your project root:

```bash
bash .claude/scripts/verify-setup.sh
```

Eight checks - Node version, hook registration, executable bits, dependencies, config validity, even firing a test prompt through the real activation hook - each with an exact fix command if it fails. Or ask Claude to run `/verify-setup` and it fixes failures itself.

### Enable AI-Powered Classification (Optional)

**No API key needed by default.** The standard mode uses regex/keyword matching - free, offline, zero API calls. AI classification is an optional upgrade that matches your *intent* instead of your keywords.

To enable it (Gemini's free tier easily covers this use case):

```bash
# 1. Get a free Gemini API key: https://aistudio.google.com/apikey

# 2. Put it in the hooks .env file:
cp .claude/hooks/.env.example .claude/hooks/.env
# then open .claude/hooks/.env and uncomment: GEMINI_API_KEY=your-key-here
# (add .env to your project's .gitignore so you never commit it)

# 3. Enable AI mode - edit .claude/skills/skill-rules.json and change:
#   "skill_activation_mode": "disabled"  →  "skill_activation_mode": "fallback"
```

Prefer environment variables? `export GEMINI_API_KEY=your-key` in `~/.bashrc` works too - the hooks read both. (`fallback` mode always degrades gracefully: no key, dead network, slow provider - you get regex matching, never a broken prompt.)

### Upgrading an Existing Install

Re-running the wizard on a project that already has `.claude/` deliberately copies **no files** - it only re-chmods hooks, updates skill-rules.json settings, and reinstalls dependencies. It will never clobber your customized `skill-rules.json` or skills.

To pick up new files from a newer version of this repo:
- Copy specific pieces from a fresh clone (e.g. `cp -r showcase/.claude/scripts ~/my-project/.claude/`), or
- If your `.claude/` is committed to git: delete it, re-run the wizard, then `git diff` to port your customizations back.

### Editor Setup (Optional)

The repo includes a NeoVim configuration optimized for Claude Code's prompt editing mode (`Ctrl+G`):

- **Relative line numbers** for easy jumping (`5j` = down 5 lines)
- **Word-boundary wrapping** for long prompts
- **System clipboard integration** (yank = Cmd+C)
- **Space+w** to save and submit, **Space+q** to cancel

The setup wizard can install this automatically, or manually:

```bash
mkdir -p ~/.config/nvim
cp editor-config/init.lua ~/.config/nvim/init.lua
cp editor-config/vimrc ~/.vimrc
echo 'export EDITOR=nvim' >> ~/.bashrc && source ~/.bashrc
```

See [`editor-config/README.md`](editor-config/README.md) for full keybinding reference.

### What You'll See

After setup, when you type "create a React component" in Claude Code:

```
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
⛔ MANDATORY SKILL ACTIVATION REQUIRED
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

You MUST activate these skills BEFORE any action:
  → frontend-dev-guidelines

⚠️ EDITS WILL BE BLOCKED until mandatory skills are activated.
Your FIRST action must be: Skill tool calls.
[via regex]
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
```

Skills auto-activate based on your prompts. No more forgetting to load them.

---

## Pick Your Path

### 🤖 Using Claude Code to Integrate?

**Claude:** Read [`CLAUDE_INTEGRATION_GUIDE.md`](CLAUDE_INTEGRATION_GUIDE.md) for step-by-step integration instructions tailored for AI-assisted setup.

### 📚 Browse the Skills Catalog

**Available skills** ([full catalog](.claude/skills/)):
- **backend-dev-guidelines** - Node.js/Express/TypeScript patterns
- **frontend-dev-guidelines** - React/TypeScript/MUI v7 patterns
- **skill-developer** - Meta-skill for creating skills
- **error-tracking** - Sentry integration patterns

### 🤖 Specialized Agents

8 production-tested agents for complex tasks ([full list](.claude/agents/)):
- Code architecture review, refactoring, documentation, error debugging, and more

---

## What Makes This Different?

### The Auto-Activation Breakthrough

**Problem:** Claude Code skills just sit there. You have to remember to use them.

**Solution:** UserPromptSubmit hook that:
- Analyzes your prompts
- Checks file context
- Automatically suggests relevant skills
- Works via `skill-rules.json` configuration

**Result:** Skills activate when you need them, not when you remember them.

### AI-Powered Classification (NEW in v2.0)

Choose your activation mode:

| Mode | How It Works | Cost | Offline |
|------|-------------|------|---------|
| **`disabled`** (default) | Regex/keyword matching only | Free | Yes |
| **`fallback`** | AI first, regex on failure | Low | Graceful |
| **`ai-only`** | Pure AI classification | Low | No |

**Supported AI providers:**

| Provider | Model | API Key | Free Tier |
|----------|-------|---------|-----------|
| Gemini | gemini-3-flash-preview | `GEMINI_API_KEY` | Yes (generous) |
| OpenAI | gpt-4o-mini | `OPENAI_API_KEY` | No |
| Anthropic | claude-haiku-4-5 | `ANTHROPIC_API_KEY` | No |
| Ollama | llama3.2 (local) | None needed | Yes (local) |

Auto-detection tries providers in order: Gemini > OpenAI > Anthropic > Ollama. Override with `SKILL_AI_PROVIDER=gemini`.

**Conservativeness levels** control suggestion aggressiveness:
- **`strict`** - Minimize false positives. Only suggest when clear intent.
- **`balanced`** (default) - Standard behavior.
- **`aggressive`** - Catch everything. Suggest liberally.

### Production-Tested Patterns

These aren't theoretical examples - they're extracted from:
- ✅ 6 microservices in production
- ✅ 50,000+ lines of TypeScript
- ✅ React frontend with complex data grids
- ✅ Sophisticated workflow engine
- ✅ 6 months of daily Claude Code use

The patterns work because they solved real problems.

### Modular Skills (500-Line Rule)

Large skills hit context limits. The solution:

```
skill-name/
  SKILL.md                  # <500 lines, high-level guide
  resources/
    topic-1.md              # aim for <500 lines each
    topic-2.md
    topic-3.md
```

**Progressive disclosure:** Claude loads main skill first, loads resources only when needed.

---

## Repository Structure

```
.claude/
├── skills/                 # 4 production skills
│   ├── backend-dev-guidelines/  (11 resource files)
│   ├── frontend-dev-guidelines/ (10 resource files)
│   ├── skill-developer/         (6 resource files)
│   ├── error-tracking/
│   └── skill-rules.json    # Skill activation configuration
├── hooks/                  # 9 hooks for automation
│   ├── skill-activation-prompt.*  (ESSENTIAL)
│   ├── skill-verification-guard.* (ESSENTIAL, v2.0)
│   ├── skill-activation-tracker.* (ESSENTIAL, v2.0)
│   ├── post-tool-use-tracker.sh   (ESSENTIAL)
│   ├── session-doc-updater.*      (optional, installed by default)
│   ├── error-handling-reminder.*  (optional)
│   ├── stop-build-check-enhanced.sh (optional)
│   ├── tsc-check.sh        (optional, needs customization)
│   └── trigger-build-resolver.sh  (optional)
├── agents/                 # 8 specialized agents
│   ├── code-architecture-reviewer.md
│   ├── refactor-planner.md
│   ├── frontend-error-fixer.md
│   └── ... 5 more
├── commands/               # 4 slash commands
│   ├── dev-docs.md
│   ├── verify-setup.md
│   └── ...
└── scripts/
    └── verify-setup.sh     # One-command health check

dev/
└── active/                 # Dev docs pattern examples
    └── showcase-ai-upgrade/
```

---

## Component Catalog

### 🎨 Skills (4)

| Skill | Lines | Purpose | Best For |
|-------|-------|---------|----------|
| [**skill-developer**](.claude/skills/skill-developer/) | 426 | Creating and managing skills | Meta-development |
| [**backend-dev-guidelines**](.claude/skills/backend-dev-guidelines/) | 304 | Express/Prisma/Sentry patterns | Backend APIs |
| [**frontend-dev-guidelines**](.claude/skills/frontend-dev-guidelines/) | 398 | React/MUI v7/TypeScript | React frontends |
| [**error-tracking**](.claude/skills/error-tracking/) | ~250 | Sentry integration | Error monitoring |

**All skills follow the modular pattern** - main file + resource files for progressive disclosure.

**👉 [How to integrate skills →](.claude/skills/README.md)**

### 🪝 Hooks (9)

| Hook | Type | Essential? | Customization |
|------|------|-----------|---------------|
| skill-activation-prompt | UserPromptSubmit | ✅ YES | ✅ None needed |
| skill-verification-guard | PreToolUse | ✅ YES (v2.0) | ✅ None needed |
| skill-activation-tracker | PostToolUse (Skill) | ✅ YES (v2.0) | ✅ None needed |
| post-tool-use-tracker | PostToolUse (Edit) | ✅ YES | ✅ None needed |
| tsc-check | Stop | ⚠️ Optional | ⚠️ Heavy - monorepo only |
| trigger-build-resolver | Stop | ⚠️ Optional | ⚠️ Heavy - monorepo only |
| error-handling-reminder | Stop | ⚠️ Optional | ⚠️ Moderate |
| stop-build-check-enhanced | Stop | ⚠️ Optional | ⚠️ Moderate |
| session-doc-updater | Stop | ⚠️ Optional (installed by default) | ✅ None - no-ops until session indexing is configured ([CONFIG.md](.claude/hooks/CONFIG.md)) |

**Hook types:** UserPromptSubmit fires on every prompt you send; PreToolUse fires before each Edit/Write; PostToolUse fires after; Stop fires when Claude finishes responding.

**New in v2.0:**
- **skill-verification-guard** - PreToolUse hook that analyzes code being written and enforces mandatory skill activation (two-try blocking model)
- **skill-activation-tracker** - Clears skills from mandatory_pending after they're activated via the Skill tool

**Start with the essential hooks** - they enable skill auto-activation and work out of the box.

**👉 [Hook setup guide →](.claude/hooks/README.md)**

### 🤖 Agents (8)

**Standalone - just copy and use!**

| Agent | Purpose |
|-------|---------|
| code-architecture-reviewer | Review code for architectural consistency |
| code-refactor-master | Plan and execute refactoring |
| documentation-architect | Generate comprehensive documentation |
| frontend-error-fixer | Debug frontend errors |
| plan-reviewer | Review development plans |
| refactor-planner | Create refactoring strategies |
| web-research-specialist | Research technical issues online |
| auto-error-resolver | Auto-fix TypeScript errors |

**👉 [How agents work →](.claude/agents/README.md)**

### 💬 Slash Commands (4)

| Command | Purpose |
|---------|---------|
| /dev-docs | Create structured dev documentation |
| /dev-docs-update | Update docs before context reset |
| /verify-setup | Run the infrastructure health check and fix failures |
| /route-research-for-testing | Research route patterns for testing |

---

## Key Concepts

### Hooks + skill-rules.json = Auto-Activation

**The system:**
1. **skill-activation-prompt hook** runs on every user prompt
2. Checks **skill-rules.json** for trigger patterns
3. Suggests relevant skills automatically
4. Skills load only when needed

**This solves the #1 problem** with Claude Code skills: they don't activate on their own.

### Progressive Disclosure (500-Line Rule)

**Problem:** Large skills hit context limits

**Solution:** Modular structure
- Main SKILL.md <500 lines (overview + navigation)
- Resource files aim for <500 lines each (full disclosure: a few deep-dives currently run 500-871 lines - kept whole for coherence, splitting them is on the list)
- Claude loads incrementally as needed

**Example:** backend-dev-guidelines has 11 resource files covering routing, controllers, services, repositories, testing, etc.

### Dev Docs Pattern

**Problem:** Context resets lose project context

**Solution:** Three-file structure
- `[task]-plan.md` - Strategic plan
- `[task]-context.md` - Key decisions and files
- `[task]-tasks.md` - Checklist format

**Works with:** `/dev-docs` slash command to generate these automatically

---

## Works with Codex Too (Cross-Agent Support)

Codex CLI's hooks system uses the same events, stdin schema, and exit-code semantics as Claude Code, and skills follow the cross-agent [Agent Skills standard](https://agentskills.io). This repo ships both wired up — **one canonical codebase, zero forked scripts**:

- **`.agents/skills/`** — a synced mirror of `.claude/skills/` in the standard location Codex (and 30+ other tools) reads natively. Keep it fresh with `.claude/scripts/sync-agent-skills.sh`; `verify-setup` warns on drift.
- **`.codex/hooks.json`** — registers the same four lifecycle hooks for Codex.
- **`.codex/hooks/_codex-adapter.sh`** — a thin shim that closes the two real gaps: it sets `CLAUDE_PROJECT_DIR` (Codex runs hooks at the session cwd) and translates Codex's native `apply_patch` tool into per-file events the verification guard understands. Everything else passes through untouched to `.claude/hooks/`.

Setup:

1. Install Codex natively in your shell environment (`npm i -g @openai/codex`). If you're on WSL, don't use a Windows-side install through the interop layer — hooks would run as Windows processes with UNC paths.
2. Launch `codex` from the repo root. On first run Codex asks you to **trust this project's hooks** — accept (trust is hash-persisted in `~/.codex/config.toml`, and re-prompted if the hook config changes).
3. That's it. Prompt-time skill suggestions, edit blocking for `block`-enforced skills (two-try model included), file tracking, session-state, and the activation telemetry (`state/metrics.jsonl`) all run identically under both agents — same state directory, same metrics, one `skill-rules.json`.

Known parity gap: Codex has no `Skill` tool event, so the PostToolUse tracker that clears `mandatory_pending` early never fires there; the two-try model bounds the cost at one advisory block per skill per session. `.codex/agents/` is an experimental subagent port and not wired into any of this.

---

## ⚠️ Important: What Won't Work As-Is

### settings.json
The included `settings.json` works out of the box for the essential hooks (UserPromptSubmit, PreToolUse, PostToolUse). If you add optional Stop hooks (tsc-check, build-check), those need customization for your project structure. Note that the shipped `settings.json` contains hook registrations only - permissions are yours to manage (e.g. via `/permissions` in Claude Code).

### Blog Domain Examples
Skills use generic blog examples (Post/Comment/User):
- These are **teaching examples**, not requirements
- Patterns work for any domain (e-commerce, SaaS, etc.)
- Adapt the patterns to your business logic

### Hook Directory Structures
Some hooks expect specific structures:
- `tsc-check.sh` expects service directories
- Customize based on YOUR project layout

---

## Integration Workflow

**Recommended approach:**

### Option A: Setup Wizard (Fastest)

```bash
npx tsx setup.ts ~/my-project          # interactive
npx tsx setup.ts ~/my-project --yes    # non-interactive (what Claude Code uses)
```

The wizard handles everything: tech detection, mode selection, provider config, dependency install, and a self-verification pass at the end.

### Option B: Manual Setup

#### Phase 1: Skill Activation (15 min)
1. Copy all essential hooks (skill-activation-prompt, skill-verification-guard, skill-activation-tracker, post-tool-use-tracker)
2. Update settings.json with hook registrations
3. Install hook dependencies: `cd .claude/hooks && npm install`
4. Make shell scripts executable: `chmod +x .claude/hooks/*.sh`

#### Phase 2: Add First Skill (10 min)
1. Pick ONE relevant skill
2. Copy skill directory
3. Create/update skill-rules.json
4. Customize path patterns

#### Phase 3: Enable AI (Optional, 5 min)
1. Edit `.claude/skills/skill-rules.json`
2. Change `"skill_activation_mode"` to `"fallback"`
3. Set your API key: `export GEMINI_API_KEY=your-key` in `~/.bashrc`
4. Restart Claude Code

#### Phase 4: Test & Iterate (5 min)
1. Edit a file - skill should activate
2. Ask a question - skill should be suggested
3. Add more skills as needed

#### Phase 5: Optional Enhancements
- Add agents you find useful
- Add slash commands
- Customize Stop hooks (advanced)
- Tune conservativeness level

## Environment Variables

```bash
# AI Provider (optional - only for AI mode)
SKILL_AI_PROVIDER=gemini         # Force: gemini|openai|anthropic|ollama
GEMINI_API_KEY=                  # Auto-detect Gemini
OPENAI_API_KEY=                  # Auto-detect OpenAI
ANTHROPIC_API_KEY=               # Auto-detect Anthropic
OLLAMA_MODEL=llama3.2            # Default Ollama model
OLLAMA_BASE_URL=http://localhost:11434

# Behavior
SKILL_CONSERVATIVENESS=balanced  # strict|balanced|aggressive
DEBUG_SKILLS=0                   # 1 for debug output

# PreToolUse Guard
PRETOOLUSE_SOFT_BLOCK=false      # true for soft-blocking
SKIP_MANDATORY_SKILLS=false      # true to bypass enforcement
```

See [`.env.example`](.env.example) for full documentation.

---

## Getting Help

### Troubleshooting / Disabling

**Something not working?** Run the health check first - it tells you exactly what to fix:

```bash
bash .claude/scripts/verify-setup.sh
```

Or ask Claude to run `/verify-setup` and it fixes the failures itself.

**Need everything off fast?** Remove the `"hooks"` block from `.claude/settings.json` - all hooks stop running immediately.

**Per-feature kill switches** (set in your shell or before launching Claude Code):
- `SESSION_DOCS_ENABLED=false` - disable session doc updates
- `SKIP_MANDATORY_SKILLS=true` - bypass mandatory skill enforcement
- `DEBUG_SKILLS=1` - verbose logging for skill activation

**Where logs live:** `.claude/hooks/*.log` and `.claude/hooks/data/`

### For Users
**Issues with integration?**
1. Check [CLAUDE_INTEGRATION_GUIDE.md](CLAUDE_INTEGRATION_GUIDE.md)
2. Ask Claude: "Why isn't [skill] activating?"
3. Open an issue with your project structure

### For Claude Code
When helping users integrate:
1. **Read CLAUDE_INTEGRATION_GUIDE.md FIRST**
2. Ask about their project structure
3. Customize, don't blindly copy
4. Verify after integration

---

## What This Solves

### Before This Infrastructure

❌ Skills don't activate automatically
❌ Have to remember which skill to use
❌ Large skills hit context limits
❌ Context resets lose project knowledge
❌ No consistency across development
❌ Manual agent invocation every time

### After This Infrastructure

✅ Skills suggest themselves based on context
✅ Hooks trigger skills at the right time
✅ Modular skills stay under context limits
✅ Dev docs preserve knowledge across resets
✅ Consistent patterns via guardrails
✅ Agents streamline complex tasks

---

## Community

**Found this useful?**

- ⭐ Star this repo
- 🐛 Report issues or suggest improvements
- 💬 Share your own skills/hooks/agents
- 📝 Contribute examples from your domain

**Background:**
This infrastructure was detailed in a post I made to Reddit ["Claude Code is a Beast – Tips from 6 Months of Hardcore Use"](https://www.reddit.com/r/ClaudeAI/comments/1oivjvm/claude_code_is_a_beast_tips_from_6_months_of/). After hundreds of requests, this showcase was created to help the community implement these patterns.


---

## License

MIT License - Use freely in your projects, commercial or personal.

---

## Quick Links

- 📖 [Claude Integration Guide](CLAUDE_INTEGRATION_GUIDE.md) - For AI-assisted setup
- 🎨 [Skills Documentation](.claude/skills/README.md)
- 🪝 [Hooks Setup](.claude/hooks/README.md)
- 🤖 [Agents Guide](.claude/agents/README.md)
- 📝 [Dev Docs Pattern](dev/README.md)

**Start here:** Copy the two essential hooks, add one skill, and see the auto-activation magic happen.