Project Health

Project Health

One skill for everything about your project's Claude Code configuration. Run it at the start, middle, or end of a project — it figures out what's needed.

Goal: Zero permission prompts, well-organised context files, no cruft.

When to Use

Architecture: Sub-Agents

Heavy analysis runs in sub-agents to keep the main conversation clean. The main agent orchestrates; sub-agents do the scanning and return summaries.

Agent 1: Permission Auditor

Launched with Task(subagent_type: "general-purpose"). Prompt:

Read .claude/settings.local.json.

**Discover connected MCP servers**: Use ToolSearch (search "mcp") and extract unique
server prefixes from tool names (e.g. mcp__vault__secret_list → vault).

**Discover installed skills**: Use the Skill tool or ToolSearch to list available skills.
For each skill that has scripts/ in its directory, note what Bash patterns it needs
(python3, env var prefixes like GEMINI_API_KEY=*, etc.). Check the SKILL.md for any
MCP tools the skill references (e.g. mcp__vault__secret_get).

Report:
1. MCP servers connected but NOT in settings (missing)
2. MCP servers in settings but NOT connected (stale)
3. Skill permissions: Bash patterns and MCP tools that installed skills need but aren't approved
4. File access: check for Read/Edit/Write patterns for .claude/** and //tmp/**
   in project settings, and ~/Documents/**/~/.claude/** in global settings
5. Leaked secrets: entries containing API keys, tokens, bearer strings, hex >20 chars, base64 >20 chars
6. Legacy colon syntax: entries like Bash(git:*) instead of Bash(git *)
7. Junk entries: shell fragments (Bash(do), Bash(fi), Bash(then), Bash(else), Bash(done)),
   __NEW_LINE_* artefacts, loop body fragments (Bash(break), Bash(continue), Bash(echo *))
8. Duplicates: entries covered by a broader pattern (e.g. Bash(git add *) redundant if Bash(git *) exists)
9. Missing presets: based on files present, suggest presets from [permission-presets.md]

Prefer Read/Glob/Grep tools over Bash. If you need to scan multiple files or
run 3+ commands for one analysis, write a Python script to .jez/scripts/
and run it once (mkdir -p .jez/scripts first).

Return a structured summary, not raw data.

Agent 2: Context Auditor

Launched with Task(subagent_type: "general-purpose"). Prompt:

Audit the project context landscape at [repo-path]:

1. Find all CLAUDE.md files. For each:
   - Count lines (target: root 50-150, subdirs 15-50)
   - Score quality on 6 criteria (see quality-criteria.md)
   - Check for stale file/path references
   - Flag oversized files

2. Find .claude/rules/ topic files. Check sizes (target: 20-80 lines).

3. Detect project type from files present (see project-types.md).
   Check expected docs exist (ARCHITECTURE.md, DATABASE_SCHEMA.md, etc.)

4. Find public markdown (README.md, LICENSE, CONTRIBUTING.md).
   Check for overlap with CLAUDE.md content.

5. Check auto-memory at ~/.claude/projects/*/memory/MEMORY.md

6. If Cloudflare project: find all wrangler.jsonc/wrangler.toml files.
   Check each has "observability": { "enabled": true }. Flag any missing it.

Prefer Read/Glob/Grep tools over Bash. If you need to scan many files or
aggregate data across the repo, write a Python script to .jez/scripts/
and run it once rather than running many individual bash commands
(mkdir -p .jez/scripts first).

Return: project type, quality scores, missing docs, stale refs, overlaps,
size violations, observability gaps, and total markdown footprint.

Parallel Execution

For a full health check, launch both agents in parallel:

Task(subagent_type: "general-purpose", name: "permission-audit", prompt: "...")
Task(subagent_type: "general-purpose", name: "context-audit", prompt: "...")

Both return summaries. The main agent combines them into one report and proposes fixes.

Mode 1: Full Health Check

The default. Run this anytime.

Steps

1. Launch Permission Auditor and Context Auditor agents in parallel 2. Combine findings into a single report:

   ## Project Health Report

   **Project type**: [detected type]
   **CLAUDE.md quality**: [score]/100 ([grade])

   ### Permissions
   - Missing MCP servers: [list]
   - Leaked secrets: [count] found
   - Legacy syntax: [count] entries
   - Missing presets: [list]

   ### Context
   - Oversized files: [list]
   - Stale references: [list]
   - Missing docs: [list]
   - Overlaps: [list]

   ### Recommended Fixes
   1. [fix 1]
   2. [fix 2]
   ...

3. Apply fixes after single yes/no confirmation

Mode 2: New Project Setup

When: No .claude/settings.local.json exists, or user says "setup" / "kickoff".

Steps

1. Detect project type from files present:

Types stack (e.g. cloudflare-worker + javascript-typescript).

2. Generate `.claude/settings.local.json`:

• Read references/permission-presets.md
• Always include Universal Base (includes file access for .claude/**, //tmp/**)
• Add detected language + deployment presets
• Check if global ~/.claude/settings.local.json has home-relative file access

patterns (~/Documents/**, ~/.claude/**). If not, suggest adding them there (NOT in the project file — home paths belong in global settings only)

• Launch Permission Auditor agent to discover MCP servers and add per-server wildcards
• Always include WebSearch, WebFetch
• Always include explicit gh subcommands (workaround for Bash(gh *) bug)
• Write with // comment groups

3. Generate `CLAUDE.md`:

• Read references/templates.md
• Use project-type-appropriate template

4. Generate `.gitignore`:

• Read references/templates.md
• Always include .claude/settings.local.json, .claude/plans/, .jez/screenshots/, .jez/artifacts/
• Do NOT gitignore .jez/scripts/ — generated scripts are worth keeping

5. Optionally (ask first): git init + gh repo create

6. Warn: "Project settings.local.json SHADOWS global settings (does not merge). Session restart needed."

Mode 3: Tidy Permissions

When: User says "tidy permissions" or health check found permission issues.

Launch the Permission Auditor agent, then apply its recommended fixes.

Mode 4: Capture Learnings

When: End of session, "capture learnings", "save what we learned".

This runs in the main context (not a sub-agent) because it needs access to the conversation history.

1. Review conversation for discoveries worth preserving 2. Decide placement:

   Applies to all projects?
   ├── YES → ~/.claude/rules/<topic>.md
   └── NO  → Specific to a subdirectory?
       ├── YES → <dir>/CLAUDE.md
       └── NO  → Reference or operational?
           ├── Reference → docs/ or ARCHITECTURE.md
           └── Operational → ./CLAUDE.md (root)

3. Draft all changes as diffs in a single batch 4. Apply after single yes/no confirmation

Keep it concise: one line per concept.

Mode 5: Add Preset

When: "add python permissions", "add docker", "add MCP servers".

1. Read the preset from references/permission-presets.md 2. Read existing .claude/settings.local.json 3. Merge without duplicating 4. Remind: session restart required

Mode 6: Restructure Context

When: Root CLAUDE.md over 200 lines, "restructure memory".

1. Launch Context Auditor agent first 2. Based on findings:

• Split oversized CLAUDE.md into .claude/rules/<topic>.md
• Extract directory-specific content to sub-directory CLAUDE.md
• Move reference material to docs/
• Resolve overlaps
• Create missing docs for project type

3. Present plan, apply after approval

Size Targets

Permission Syntax Quick Reference

What Does NOT Work

Important Behaviours

• Not hot-reloaded: settings.local.json edits need session restart
• "Don't ask again" injects at runtime (no restart) using colon format — normal
• Shadows, not merges: Project settings completely replace global
• `gh` bug: Bash(gh *) sometimes misses subcommands — include explicit Bash(gh issue *) etc.

Autonomy

• Just do it: Detect project type, launch audit agents, discover MCP servers
• Brief confirmation: Write/update files (single batch yes/no)
• Ask first: git init, GitHub repo, delete existing content, major restructures

Reference Files

Recommended Hook: Context Capture on Commit

Automatically remind Claude to capture learnings after every git commit. This pairs with Mode 1 (Session Capture) — the hook triggers the prompt, the skill handles the capture.

Setup

Create this file at ~/.claude/hookify.context-capture-reminder.local.md for global coverage, or project/.claude/hookify.context-capture-reminder.local.md for a single project:

---
name: context-capture-reminder
enabled: true
event: bash
pattern: git\s+commit
action: warn
---

Context check: Were any patterns, gotchas, or commands discovered during this work that should be captured to CLAUDE.md or .claude/rules/? If yes, update them now before moving on. If nothing new was learned, carry on.

How It Works

1. You finish work and commit 2. The hook fires after the git commit Bash call 3. Claude pauses to consider whether anything learned during this work should be persisted 4. If yes, Claude updates CLAUDE.md or creates/updates a .claude/rules/ file 5. If nothing new, Claude continues

Why Commit Time?

• Context is fresh — you just finished the work
• You're creating a permanent record anyway
• Natural checkpoint before moving to the next task
• Pairs with git log for tracing when a pattern was discovered

Requires

This hook uses the hookify plugin for Claude Code. If you don't have hookify, you can add the same reminder as a line in your CLAUDE.md:

## Workflow
- Before committing: check if any discoveries should be captured to CLAUDE.md or .claude/rules/

Permission Presets

Curated permission presets for settings.local.json. Each preset is a JSON array of permission strings grouped with // comments. Compose presets by stacking: Universal Base + language preset + deployment preset + extras.

Syntax Reference

Format Notes

• Deprecated: Bash(git:*) colon syntax still works but prefer space syntax Bash(git *)
• "Don't ask again" prompt uses legacy colon format (e.g. node:*) — it's equivalent but looks different
• Comments: "// --- Section ---" strings in the allow array are ignored and useful for organisation
• Not hot-reloaded: Changes to settings.local.json require a session restart. "Don't ask again" bypasses this because it injects into the running session directly.

Critical: Project settings.local.json SHADOWS global settings (does not merge). If a project has its own allow list, the global allow list is ignored entirely for that project.

Shell operators (&&, ||, ;) are handled safely — Bash(git *) won't match git add && rm -rf /.

---

Universal Base

Every project gets these. Version control, file operations, and basic tools needed for all development.

"// --- Version Control ---",
"Bash(git *)",
"Bash(gh *)",
"Bash(gh repo *)",
"Bash(gh issue *)",
"Bash(gh pr *)",
"Bash(gh api *)",
"Bash(gh search *)",
"Bash(gh run *)",
"Bash(gh release *)",

"// --- File Operations ---",
"Bash(cd *)",
"Bash(ls *)",
"Bash(pwd *)",
"Bash(cat *)",
"Bash(head *)",
"Bash(tail *)",
"Bash(less *)",
"Bash(more *)",
"Bash(wc *)",
"Bash(sort *)",
"Bash(mkdir *)",
"Bash(mktemp *)",
"Bash(rm *)",
"Bash(rmdir *)",
"Bash(cp *)",
"Bash(mv *)",
"Bash(ln *)",
"Bash(touch *)",
"Bash(chmod *)",
"Bash(chown *)",
"Bash(find *)",
"Bash(tree *)",
"Bash(du *)",
"Bash(df *)",
"Bash(readlink *)",
"Bash(realpath *)",
"Bash(stat *)",
"Bash(file *)",

"// --- Archives ---",
"Bash(tar *)",
"Bash(zip *)",
"Bash(unzip *)",
"Bash(gzip *)",
"Bash(gunzip *)",

"// --- Text Processing ---",
"Bash(grep *)",
"Bash(rg *)",
"Bash(awk *)",
"Bash(sed *)",
"Bash(perl *)",
"Bash(diff *)",
"Bash(jq *)",
"Bash(yq *)",
"Bash(echo *)",
"Bash(printf *)",
"Bash(tee *)",
"Bash(cut *)",
"Bash(paste *)",
"Bash(tr *)",
"Bash(uniq *)",
"Bash(xargs *)",
"Bash(yes *)",
"Bash(basename *)",
"Bash(dirname *)",

"// --- System ---",
"Bash(which *)",
"Bash(whereis *)",
"Bash(type *)",
"Bash(ps *)",
"Bash(kill *)",
"Bash(env *)",
"Bash(export *)",
"Bash(unset *)",
"Bash(source *)",
"Bash(bash *)",
"Bash(sh *)",
"Bash(date *)",
"Bash(uname *)",
"Bash(make *)",
"Bash(cmake *)",
"Bash(id *)",
"Bash(whoami *)",
"Bash(hostname *)",
"Bash(uptime *)",

"// --- Process Management ---",
"Bash(pkill *)",
"Bash(killall *)",
"Bash(lsof *)",
"Bash(pgrep *)",
"Bash(timeout *)",
"Bash(sleep *)",
"Bash(wait *)",
"Bash(time *)",
"Bash(nohup *)",
"Bash(ss *)",
"Bash(top *)",
"Bash(htop *)",
"Bash(free *)",

"// --- Terminal Multiplexers ---",
"Bash(screen *)",
"Bash(tmux *)",

"// --- Security / Crypto ---",
"Bash(openssl *)",
"Bash(ssh-keygen *)",
"Bash(gitleaks *)",
"Bash(md5sum *)",
"Bash(md5 *)",
"Bash(shasum *)",

"// --- System Utilities ---",
"Bash(printenv *)",
"Bash(xxd *)",
"Bash(base64 *)",
"Bash(nslookup *)",
"Bash(seq *)",
"Bash(bc *)",
"Bash(column *)",
"Bash(iconv *)",
"Bash(strings *)",
"Bash(patch *)",
"Bash(cmp *)",

"// --- Network ---",
"Bash(curl *)",
"Bash(wget *)",
"Bash(ssh *)",
"Bash(scp *)",
"Bash(rsync *)",
"Bash(dig *)",
"Bash(ping *)",
"Bash(whois *)",
"Bash(sshpass *)",

"// --- Skill Scripts ---",
"Bash(python3 *)",

"// --- File Access ---",
"Read(.claude/**)",
"Edit(.claude/**)",
"Write(.claude/**)",
"Read(//tmp/**)",
"Edit(//tmp/**)",

"// --- Web ---",
"WebSearch",
"WebFetch"

File access patterns use gitignore-style syntax:

• .claude/** — project-relative (scripts, artifacts, screenshots)
• //tmp/** — absolute path (// prefix = filesystem root)
• ~/.claude/** — home-relative (global rules, memory)
• ~/Documents/** — home-relative (cross-project reads)
• * matches files in one directory, ** matches recursively

Add home-relative paths to global ~/.claude/settings.local.json only (not per-project):

"// --- Global File Access (add to ~/.claude/settings.local.json) ---",
"Read(~/.claude/**)",
"Edit(~/.claude/**)",
"Read(~/Documents/**)",
"Edit(~/Documents/**)",
"Read(~/Downloads/**)"

---

JavaScript / TypeScript

For any JS/TS project. Add to Universal Base.

"// --- Node.js ---",
"Bash(node *)",
"Bash(npm *)",
"Bash(npx *)",

"// --- Alternative Runtimes ---",
"Bash(bun *)",
"Bash(bunx *)",
"Bash(deno *)",

"// --- Package Managers ---",
"Bash(pnpm *)",
"Bash(yarn *)",

"// --- Node Version Managers ---",
"Bash(nvm *)",
"Bash(fnm *)",
"Bash(volta *)",

"// --- TypeScript ---",
"Bash(tsc *)",
"Bash(tsx *)",
"Bash(ts-node *)",

"// --- Bundlers ---",
"Bash(esbuild *)",
"Bash(vite *)",
"Bash(turbo *)",

"// --- Dev Servers ---",
"Bash(pm2 *)",

"// --- Testing ---",
"Bash(jest *)",
"Bash(vitest *)",
"Bash(playwright *)",
"Bash(playwright-cli *)",
"Bash(cypress *)",

"// --- Linting / Formatting ---",
"Bash(eslint *)",
"Bash(prettier *)",
"Bash(biome *)",

"// --- Build Tools ---",
"Bash(corepack *)",
"Bash(tsup *)",
"Bash(swc *)",
"Bash(rollup *)",
"Bash(webpack *)",

"// --- Monorepo ---",
"Bash(nx *)",
"Bash(lerna *)",
"Bash(changeset *)",

"// --- Component Dev ---",
"Bash(storybook *)",

"// --- npx Subcommands (workaround for broad wildcard bug) ---",
"Bash(npx tsc *)",
"Bash(npx tsx *)",
"Bash(npx ts-node *)",
"Bash(npx vite *)",
"Bash(npx vitest *)",
"Bash(npx esbuild *)",
"Bash(npx eslint *)",
"Bash(npx prettier *)",
"Bash(npx playwright *)",
"Bash(npx playwright-cli *)",
"Bash(npx tailwindcss *)",
"Bash(npx shadcn *)",
"Bash(npx shadcn@latest *)",
"Bash(npx @better-auth/cli *)",
"Bash(npx @better-auth/cli@latest *)",
"Bash(npx drizzle-kit *)",
"Bash(npx create-cloudflare *)",
"Bash(npx create-cloudflare@latest *)",
"Bash(npx create-next-app *)",
"Bash(npx create-next-app@latest *)",
"Bash(npx astro *)",
"Bash(npx storybook *)",
"Bash(npx lighthouse *)",
"Bash(npx repomix *)"

Note: Bash(npx *) is included in the base preset but may miss subcommands due to the same wildcard bug that affects gh. Include explicit npx <tool> entries for commonly used tools.

---

Python

For Python projects. Add to Universal Base.

"// --- Python Runtime ---",
"Bash(python *)",
"Bash(python3 *)",

"// --- Package Managers ---",
"Bash(pip *)",
"Bash(pip3 *)",
"Bash(uv *)",
"Bash(poetry *)",
"Bash(pipx *)",
"Bash(conda *)",

"// --- Testing / Quality ---",
"Bash(pytest *)",
"Bash(mypy *)",
"Bash(ruff *)",
"Bash(black *)",
"Bash(flake8 *)",
"Bash(isort *)",

"// --- Dev Servers ---",
"Bash(flask *)",
"Bash(uvicorn *)",
"Bash(gunicorn *)",
"Bash(django-admin *)",

"// --- Package Managers ---",
"Bash(pdm *)",
"Bash(hatch *)",

"// --- Git Hooks ---",
"Bash(pre-commit *)",

"// --- Notebooks ---",
"Bash(jupyter *)"

---

PHP

For PHP projects including WordPress and Laravel. Add to Universal Base.

"// --- PHP Runtime ---",
"Bash(php *)",
"Bash(composer *)",

"// --- WordPress ---",
"Bash(wp *)",

"// --- Testing / Quality ---",
"Bash(phpunit *)",
"Bash(phpstan *)",
"Bash(phpcs *)",
"Bash(phpcbf *)",
"Bash(pest *)",

"// --- Laravel ---",
"Bash(artisan *)",
"Bash(sail *)"

---

Go

For Go projects. Add to Universal Base.

"// --- Go ---",
"Bash(go *)",
"Bash(golangci-lint *)"

---

Rust

For Rust projects. Add to Universal Base.

"// --- Rust ---",
"Bash(cargo *)",
"Bash(rustc *)",
"Bash(rustup *)"

---

Ruby

For Ruby / Rails projects. Add to Universal Base.

"// --- Ruby ---",
"Bash(ruby *)",
"Bash(gem *)",
"Bash(bundle *)",
"Bash(bundler *)",
"Bash(rails *)",
"Bash(rake *)",
"Bash(rspec *)"

---

Cloudflare Worker

Deployment preset. Add to Universal Base + JavaScript/TypeScript.

"// --- Wrangler ---",
"Bash(wrangler *)",
"Bash(npx wrangler *)",
"Bash(npx wrangler@latest *)",
"Bash(npx create-cloudflare *)",
"Bash(npx create-cloudflare@latest *)",
"Bash(miniflare *)"

---

Vercel

Deployment preset. Add to Universal Base + JavaScript/TypeScript.

"// --- Vercel ---",
"Bash(vercel *)",
"Bash(npx vercel *)",

"// --- Prisma (common with Vercel) ---",
"Bash(prisma *)",
"Bash(npx prisma *)"

---

Docker / Containers

For containerised projects. Add to any stack.

"// --- Docker ---",
"Bash(docker *)",
"Bash(docker-compose *)",

"// --- Kubernetes ---",
"Bash(kubectl *)",
"Bash(helm *)",

"// --- IaC ---",
"Bash(terraform *)",
"Bash(pulumi *)"

---

Database

For projects that interact with databases directly. Add to any stack.

"// --- SQL ---",
"Bash(psql *)",
"Bash(mysql *)",
"Bash(sqlite3 *)",
"Bash(sqlite3 :memory:*)",

"// --- PostgreSQL Utilities ---",
"Bash(pg_dump *)",
"Bash(pg_restore *)",
"Bash(createdb *)",
"Bash(dropdb *)",

"// --- MySQL Utilities ---",
"Bash(mysqldump *)",

"// --- NoSQL ---",
"Bash(redis-cli *)",
"Bash(mongosh *)",

"// --- Managed Database CLIs ---",
"Bash(turso *)",
"Bash(pscale *)",

"// --- ORM CLIs (via npx) ---",
"Bash(npx drizzle-kit *)",
"Bash(npx prisma *)"

---

Cloud CLIs

For cloud-deployed projects. Add to any stack.

"// --- AWS ---",
"Bash(aws *)",

"// --- Google Cloud ---",
"Bash(gcloud *)",
"Bash(gsutil *)",

"// --- Azure ---",
"Bash(az *)"

---

AI / GPU

For AI/ML workloads. Add to any stack.

"// --- Local LLM ---",
"Bash(ollama *)",

"// --- GPU ---",
"Bash(nvidia-smi *)",
"Bash(nvidia-smi)",

"// --- API Key Passthrough ---",
"Bash(GEMINI_API_KEY=*)",
"Bash(OPENAI_API_KEY=*)",
"Bash(ANTHROPIC_API_KEY=*)"

Note: Bash(nvidia-smi) (no wildcard) matches the bare command with no arguments, which is the most common usage.

---

MCP Servers

MCP (Model Context Protocol) servers provide tool access to external services. Permission patterns use the format mcp__servername__toolname.

Per-Server Wildcards (Recommended)

Allow all tools on each MCP server you trust. You must list each server individually — mcp__* does NOT work as a blanket (the wildcard only matches within the last segment, not across the __ boundary).

"mcp__servername__*",
"mcp__playwright__*",
"mcp__another-server__*"

Individual Tools

For maximum control, allow specific tools only:

"mcp__servername__specific_tool",
"mcp__servername__another_tool"

---

macOS

macOS-specific commands. Add when developing on macOS.

"// --- macOS ---",
"Bash(brew *)",
"Bash(open *)",
"Bash(pbcopy *)",
"Bash(pbpaste *)",
"Bash(sips *)",
"Bash(screencapture *)",
"Bash(osascript *)",
"Bash(caffeinate *)",
"Bash(defaults *)",
"Bash(mdfind *)",
"Bash(mdls *)",
"Bash(ditto *)",
"Bash(say *)",
"Bash(plutil *)",
"Bash(softwareupdate *)",
"Bash(xcode-select *)",
"Bash(xattr *)"

---

Google Workspace CLI

Google Workspace CLI (gws) for Gmail, Drive, Calendar, Sheets, Docs, Chat, Tasks, and more. Add when using @googleworkspace/cli.

"// --- Google Workspace CLI ---",
"Bash(gws *)",
"Bash(gws auth *)",
"Bash(gws gmail *)",
"Bash(gws calendar *)",
"Bash(gws drive *)",
"Bash(gws sheets *)",
"Bash(gws docs *)",
"Bash(gws chat *)",
"Bash(gws tasks *)",
"Bash(gws slides *)",
"Bash(gws forms *)",
"Bash(gws people *)",
"Bash(gws admin *)",
"Bash(npx skills *)"

Note: Bash(gws *) should cover all subcommands, but explicit entries are included as workaround for the wildcard matching bug (same as gh and npx). npx skills is for installing/managing gws agent skills.

---

LLM CLIs

AI/LLM command-line tools. Add when using AI assistants or review tools.

"// --- LLM CLIs ---",
"Bash(claude *)",
"Bash(gemini *)",
"Bash(gemini-coach *)",
"Bash(elevenlabs *)",
"Bash(fastmcp *)",
"Bash(apify *)"

---

Firebase

Google Firebase CLI. Add alongside Cloud CLIs for Firebase projects.

"// --- Firebase ---",
"Bash(firebase *)"

---

Media Processing

Image and video processing tools. Add for projects that handle media assets.

"// --- Media Processing ---",
"Bash(convert *)",
"Bash(identify *)",
"Bash(exiftool *)",
"Bash(ffmpeg *)",
"Bash(ffprobe *)",
"Bash(ffplay *)",
"Bash(yt-dlp *)",
"Bash(mpv *)"

---

Linux System

Linux server administration. Add for projects deployed on Linux or managed via SSH.

"// --- Linux System ---",
"Bash(systemctl *)",
"Bash(journalctl *)",
"Bash(crontab *)",
"Bash(sudo *)",
"Bash(apt *)",
"Bash(apt-get *)",
"Bash(dpkg *)",
"Bash(yum *)",
"Bash(dnf *)",
"Bash(xdg-open *)",
"Bash(fuser *)"

---

Mobile Development

React Native, Expo, and mobile tooling. Add for mobile app projects.

"// --- React Native / Expo ---",
"Bash(eas *)",
"Bash(npx expo *)",
"Bash(adb *)",
"Bash(react-native *)",

"// --- Flutter ---",
"Bash(flutter *)",
"Bash(dart *)",

"// --- iOS ---",
"Bash(xcodebuild *)",
"Bash(pod *)",
"Bash(xcrun *)",

"// --- Cross-Platform ---",
"Bash(fastlane *)"

---

Java / JVM

For Java, Kotlin, Scala, and other JVM projects. Add to Universal Base.

"// --- Java ---",
"Bash(java *)",
"Bash(javac *)",
"Bash(jar *)",

"// --- Build Tools ---",
"Bash(mvn *)",
"Bash(gradle *)",
"Bash(gradlew *)",
"Bash(./gradlew *)",

"// --- Kotlin ---",
"Bash(kotlin *)",
"Bash(kotlinc *)",

"// --- Scala ---",
"Bash(sbt *)",
"Bash(scala *)"

---

.NET / C#

For .NET projects. Add to Universal Base.

"// --- .NET ---",
"Bash(dotnet *)",
"Bash(nuget *)"

---

Elixir

For Elixir / Phoenix projects. Add to Universal Base.

"// --- Elixir ---",
"Bash(elixir *)",
"Bash(mix *)",
"Bash(iex *)"

---

Swift

For Swift projects (macOS/iOS). Add to Universal Base + macOS.

"// --- Swift ---",
"Bash(swift *)",
"Bash(swiftc *)"

---

Static Site Generators

For static sites. Add to Universal Base + JavaScript/TypeScript (for most).

"// --- Static Site Generators ---",
"Bash(astro *)",
"Bash(hugo *)",
"Bash(gatsby *)",
"Bash(eleventy *)",
"Bash(jekyll *)"

---

Hosting Platforms

Deployment CLIs for various hosting providers. Add to any stack.

"// --- Hosting CLIs ---",
"Bash(railway *)",
"Bash(fly *)",
"Bash(flyctl *)",
"Bash(netlify *)",
"Bash(supabase *)",
"Bash(heroku *)",
"Bash(render *)",
"Bash(cpanel *)"

---

Tunneling / Local Dev

Expose local servers, generate local certs, etc. Add to any stack.

"// --- Tunneling ---",
"Bash(ngrok *)",
"Bash(cloudflared *)",

"// --- Local HTTPS ---",
"Bash(mkcert *)",
"Bash(certbot *)",

"// --- Cloud Storage Sync ---",
"Bash(rclone *)"

---

SaaS CLIs

CLI tools for common SaaS platforms. Add as needed.

"// --- Payment / Communication ---",
"Bash(stripe *)",
"Bash(twilio *)",

"// --- Auth ---",
"Bash(auth0 *)",

"// --- Monitoring ---",
"Bash(sentry-cli *)"

---

Document Processing

For projects that generate PDFs, convert documents, or process media.

"// --- Documents ---",
"Bash(pandoc *)",
"Bash(wkhtmltopdf *)",
"Bash(pdftotext *)",

"// --- ImageMagick v7 ---",
"Bash(magick *)"

Note: ImageMagick v6 uses convert (in Media Processing preset). v7 uses magick as the unified command.

---

CI / GitHub Actions

For running CI locally or managing workflows.

"// --- CI ---",
"Bash(act *)",

"// --- GitHub Actions ---",
"Bash(gh workflow *)",
"Bash(gh run *)"

---

Editors / IDE CLIs

For projects where Claude may interact with editor tooling.

"// --- Editor CLIs ---",
"Bash(code *)",
"Bash(cursor *)",
"Bash(zed *)",
"Bash(vim *)",
"Bash(nvim *)"

---

WebFetch Domains

Use blanket WebFetch (in Universal Base) to avoid per-domain prompts. If you prefer granular control, here is a comprehensive domain-scoped list organised by category to match the Bash presets above.

"// --- WebFetch (blanket — recommended) ---",
"WebFetch"

OR: Domain-Scoped (granular control)

Pick the categories that match your stack.

Core (every project)

"// --- GitHub ---",
"WebFetch(domain:github.com)",
"WebFetch(domain:raw.githubusercontent.com)",
"WebFetch(domain:api.github.com)",
"WebFetch(domain:docs.github.com)",
"WebFetch(domain:github.blog)",

"// --- General Dev Reference ---",
"WebFetch(domain:developer.mozilla.org)",
"WebFetch(domain:stackoverflow.com)",
"WebFetch(domain:dev.to)",
"WebFetch(domain:medium.com)",
"WebFetch(domain:deepwiki.com)",
"WebFetch(domain:bundlephobia.com)",

"// --- Package Registries ---",
"WebFetch(domain:www.npmjs.com)",
"WebFetch(domain:pypi.org)",
"WebFetch(domain:crates.io)",
"WebFetch(domain:pkg.go.dev)",
"WebFetch(domain:rubygems.org)",
"WebFetch(domain:nuget.org)"

AI / LLM

"// --- Anthropic ---",
"WebFetch(domain:docs.anthropic.com)",
"WebFetch(domain:www.anthropic.com)",
"WebFetch(domain:support.anthropic.com)",
"WebFetch(domain:platform.claude.com)",

"// --- Google AI ---",
"WebFetch(domain:ai.google.dev)",
"WebFetch(domain:cloud.google.com)",
"WebFetch(domain:developers.google.com)",

"// --- OpenAI ---",
"WebFetch(domain:platform.openai.com)",
"WebFetch(domain:developers.openai.com)",

"// --- AI SDKs ---",
"WebFetch(domain:ai-sdk.dev)",
"WebFetch(domain:openrouter.ai)",

"// --- ElevenLabs ---",
"WebFetch(domain:elevenlabs.io)",

"// --- MCP ---",
"WebFetch(domain:spec.modelcontextprotocol.io)",
"WebFetch(domain:gofastmcp.com)"

Cloudflare

"WebFetch(domain:developers.cloudflare.com)",
"WebFetch(domain:blog.cloudflare.com)",
"WebFetch(domain:community.cloudflare.com)"

JavaScript / TypeScript Ecosystem

"// --- Core ---",
"WebFetch(domain:nodejs.org)",
"WebFetch(domain:typescriptlang.org)",
"WebFetch(domain:tc39.es)",

"// --- React ---",
"WebFetch(domain:react.dev)",
"WebFetch(domain:reactnative.dev)",

"// --- Build Tools ---",
"WebFetch(domain:vitejs.dev)",
"WebFetch(domain:vite.dev)",
"WebFetch(domain:esbuild.github.io)",
"WebFetch(domain:turbo.build)",

"// --- UI Frameworks ---",
"WebFetch(domain:ui.shadcn.com)",
"WebFetch(domain:www.radix-ui.com)",
"WebFetch(domain:tailwindcss.com)",
"WebFetch(domain:lucide.dev)",

"// --- State / Data ---",
"WebFetch(domain:tanstack.com)",
"WebFetch(domain:swr.vercel.app)",
"WebFetch(domain:zustand.docs.pmnd.rs)",
"WebFetch(domain:zod.dev)",
"WebFetch(domain:react-hook-form.com)",

"// --- Auth ---",
"WebFetch(domain:better-auth.com)",
"WebFetch(domain:www.better-auth.com)",
"WebFetch(domain:clerk.com)",
"WebFetch(domain:authjs.dev)",

"// --- ORM / Database ---",
"WebFetch(domain:orm.drizzle.team)",
"WebFetch(domain:www.prisma.io)",

"// --- API Frameworks ---",
"WebFetch(domain:hono.dev)",
"WebFetch(domain:expressjs.com)",
"WebFetch(domain:fastify.dev)",
"WebFetch(domain:trpc.io)",

"// --- Testing ---",
"WebFetch(domain:playwright.dev)",
"WebFetch(domain:vitest.dev)",
"WebFetch(domain:jestjs.io)",
"WebFetch(domain:testing-library.com)",

"// --- Linting ---",
"WebFetch(domain:eslint.org)",
"WebFetch(domain:prettier.io)",
"WebFetch(domain:biomejs.dev)"

Python Ecosystem

"WebFetch(domain:python.org)",
"WebFetch(domain:docs.python.org)",
"WebFetch(domain:fastapi.tiangolo.com)",
"WebFetch(domain:docs.djangoproject.com)",
"WebFetch(domain:flask.palletsprojects.com)",
"WebFetch(domain:docs.pydantic.dev)",
"WebFetch(domain:docs.pytest.org)",
"WebFetch(domain:docs.astral.sh)"

Hosting / Deployment

"WebFetch(domain:vercel.com)",
"WebFetch(domain:docs.netlify.com)",
"WebFetch(domain:fly.io)",
"WebFetch(domain:docs.railway.com)",
"WebFetch(domain:supabase.com)",
"WebFetch(domain:render.com)",
"WebFetch(domain:firebase.google.com)"

Static Site Generators

"WebFetch(domain:astro.build)",
"WebFetch(domain:docs.astro.build)",
"WebFetch(domain:gohugo.io)",
"WebFetch(domain:www.gatsbyjs.com)",
"WebFetch(domain:www.11ty.dev)",
"WebFetch(domain:nextjs.org)"

Database

"WebFetch(domain:www.postgresql.org)",
"WebFetch(domain:dev.mysql.com)",
"WebFetch(domain:www.sqlite.org)",
"WebFetch(domain:redis.io)",
"WebFetch(domain:www.mongodb.com)",
"WebFetch(domain:docs.turso.tech)",
"WebFetch(domain:planetscale.com)",
"WebFetch(domain:neon.tech)"

PHP / WordPress

"WebFetch(domain:www.php.net)",
"WebFetch(domain:developer.wordpress.org)",
"WebFetch(domain:laravel.com)",
"WebFetch(domain:getcomposer.org)"

SaaS / API Services

"WebFetch(domain:docs.stripe.com)",
"WebFetch(domain:www.twilio.com)",
"WebFetch(domain:apidoc.smtp2go.com)",
"WebFetch(domain:support.smtp2go.com)",
"WebFetch(domain:docs.firecrawl.dev)",
"WebFetch(domain:apify.com)",
"WebFetch(domain:docs.sentry.io)",
"WebFetch(domain:docs.sendgrid.com)"

Go / Rust / Ruby / Java / .NET / Elixir

"WebFetch(domain:go.dev)",
"WebFetch(domain:doc.rust-lang.org)",
"WebFetch(domain:www.rust-lang.org)",
"WebFetch(domain:rubyonrails.org)",
"WebFetch(domain:ruby-doc.org)",
"WebFetch(domain:docs.oracle.com)",
"WebFetch(domain:spring.io)",
"WebFetch(domain:kotlinlang.org)",
"WebFetch(domain:learn.microsoft.com)",
"WebFetch(domain:hexdocs.pm)",
"WebFetch(domain:www.phoenixframework.org)"

Mobile

"WebFetch(domain:reactnative.dev)",
"WebFetch(domain:expo.dev)",
"WebFetch(domain:flutter.dev)",
"WebFetch(domain:dart.dev)",
"WebFetch(domain:developer.apple.com)",
"WebFetch(domain:developer.android.com)"

Docker / DevOps

"WebFetch(domain:docs.docker.com)",
"WebFetch(domain:kubernetes.io)",
"WebFetch(domain:helm.sh)",
"WebFetch(domain:www.terraform.io)",
"WebFetch(domain:docs.github.com)"

Security / Standards

"WebFetch(domain:owasp.org)",
"WebFetch(domain:cheatsheetseries.owasp.org)",
"WebFetch(domain:datatracker.ietf.org)",
"WebFetch(domain:www.ietf.org)",
"WebFetch(domain:caniuse.com)"

The blanket WebFetch is recommended for most users — domain-scoped is only needed if you want to restrict which sites Claude can fetch. Pick categories that match your stack if going granular.

---

Combining Presets

Presets stack. Examples:

When merging, deduplicate and keep the grouped // comment structure. The final settings.local.json should look like:

{
  "permissions": {
    "allow": [
      "// --- Version Control ---",
      "Bash(git *)",
      "Bash(gh *)",
      "// --- Node.js ---",
      "Bash(node *)",
      "..."
    ],
    "deny": []
  }
}

Project Types

Detect project type from file presence to determine which documentation files are expected. Only suggest docs that match — no enterprise bloat.

Detection Heuristics

Check indicators in priority order (first match wins for primary type, but types can stack):

Stacking: A Cloudflare Worker with D1 bindings is both cloudflare-worker and database-project. Union the expected docs.

Expected Documentation Per Type

All projects

cloudflare-worker

vite-react / nextjs

mcp-server

api-project

database-project

skills-repo

claude-ops

No additional docs beyond CLAUDE.md — operational repos are typically self-documenting through their agents and scripts.

Doc Templates

ARCHITECTURE.md outline

# Architecture

## Overview
[One paragraph: what this project does and how it's structured]

## Stack
[Tech stack with versions]

## Directory Structure
[Tree with purpose annotations]

## Key Flows
[1-3 main data/request flows through the system]

## Deployment
[How to deploy, what happens on deploy]

DATABASE_SCHEMA.md outline

# Database Schema

## Tables
[Table per section: name, columns, types, constraints]

## Relationships
[Foreign keys, join patterns]

## Migrations
[How to create/run migrations, local vs remote]

## Indexes
[Non-obvious indexes and why they exist]

API_ENDPOINTS.md outline

# API Endpoints

## Authentication
[Auth method, where tokens come from]

## Endpoints
[Per endpoint: method, path, params, response shape, auth required]

## Error Handling
[Standard error format, common error codes]

docs/ Directory

Projects with a docs/ folder get its contents scanned for staleness and overlap with CLAUDE.md. Common patterns:

The audit doesn't manage docs/ content — it flags staleness (broken file references) and overlap (sections duplicated with CLAUDE.md).

Rules

• Only suggest docs that match detected project type
• Simple projects (node-project, python-project) just need CLAUDE.md
• Don't create empty template docs — only suggest when there's content to fill
• Prefer one well-maintained doc over three sparse ones
• If CLAUDE.md duplicates ARCHITECTURE.md or docs/, move the content to docs/ and keep CLAUDE.md concise

Quality Criteria

Score CLAUDE.md files on a 100-point scale across 6 criteria. Use this when running a full audit (Mode 2) or restructure (Mode 3).

Scoring Rubric

Commands/Workflows (20 points)

Build, test, deploy, and dev commands documented with context.

Architecture Clarity (20 points)

Directory structure, module relationships, entry points, data flow.

Non-Obvious Patterns (15 points)

Gotchas, quirks, edge cases, workarounds, "why" for unusual decisions.

Conciseness (15 points)

Dense, valuable content. No filler, no redundancy, each line earns its place.

Currency (15 points)

Reflects the actual current codebase. Commands work, files exist, stack is correct.

Actionability (15 points)

Instructions are executable. Copy-paste ready commands, real paths, concrete steps.

Grading Scale

Red Flags

Flag these during audit — each indicates a quality problem:

• Commands that fail when run
• References to files/directories that don't exist
• Outdated technology versions or deprecated APIs
• Generic advice not specific to the project (e.g. "write clean code")
• Copy-paste templates that weren't customised
• "TODO" items that were never completed
• Duplicated content across multiple CLAUDE.md files
• Verbose explanations of things Claude already knows
• Changelogs or version history (belongs in git, not CLAUDE.md)

Templates

Templates for CLAUDE.md files, rules topic files, sub-directory context, and .gitignore. Use these when creating new files or restructuring existing ones.

---

Root CLAUDE.md (Minimal)

For simple projects with a single developer:

# [Project Name]

[One-line description]

## Stack

[Tech stack summary]

## Commands

| Command | Purpose |
|---------|---------|
| `npm run dev` | Start dev server |
| `npm run build` | Production build |
| `npm run deploy` | Deploy to [platform] |

## Gotchas

- [Non-obvious thing 1]
- [Non-obvious thing 2]

Target: 30-60 lines.

Root CLAUDE.md (Comprehensive)

For projects with external integrations, multiple contributors, or complex workflows:

# [Project Name]

**Repository**: [URL]
**Owner**: [Name]

[One-line description]

## Stack

[Tech stack with key decisions noted]

## Directory Structure

[Annotated tree of key directories]

## Commands

| Command | Purpose |
|---------|---------|
| `npm run dev` | Start dev server |
| `npm run build` | Production build |
| `npm run deploy` | Deploy to [platform] |
| `npm test` | Run test suite |

## Key Files

| File | Purpose |
|------|---------|
| `src/index.ts` | Entry point |
| `wrangler.jsonc` | Cloudflare config |

## Critical Rules

- [Never do X because Y]
- [Always do A before B]

## Gotchas

- [Non-obvious thing 1]
- [Non-obvious thing 2]

Target: 60-150 lines.

---

Project-Type Templates

Cloudflare Worker

# [Project Name]

**Repository**: https://github.com/[org]/[repo-name]
**Last Updated**: [date]

## Stack

- Cloudflare Workers + Static Assets
- Vite + React 19 + @cloudflare/vite-plugin
- Tailwind v4 + shadcn/ui (neutral palette)
- D1 (SQLite) + Drizzle ORM
- Hono (API routing)
- pnpm

## Commands

| Command | Purpose |
|---------|---------|
| `pnpm dev` | Local dev server (Vite + Miniflare) |
| `pnpm build` | Production build |
| `pnpm deploy` | Deploy to Cloudflare |
| `pnpm db:migrate:local` | Run D1 migrations locally |
| `pnpm db:migrate:remote` | Run D1 migrations on production |

## Cloudflare

- **Compatibility flags**: `nodejs_compat` (never use `node_compat`)
- Always use Workers + Static Assets (never Cloudflare Pages)

## Critical Rules

- Run migrations on BOTH local AND remote before testing
- Set `account_id` in wrangler.jsonc to avoid interactive prompts
- D1 bulk inserts: batch into chunks of ~10 rows (parameter limit)
- `wrangler secret put` does NOT auto-deploy — run `wrangler deploy` after

## Gotchas

[Add as discovered]

Vercel App

# [Project Name]

**Repository**: https://github.com/[org]/[repo-name]
**Last Updated**: [date]

## Stack

- Next.js / Vite + React 19
- Tailwind v4 + shadcn/ui (neutral palette)
- pnpm

## Commands

| Command | Purpose |
|---------|---------|
| `pnpm dev` | Local dev server |
| `pnpm build` | Production build |
| `vercel deploy` | Deploy to Vercel |
| `vercel deploy --prod` | Deploy to production |

## Gotchas

[Add as discovered]

Node Generic

# [Project Name]

**Repository**: https://github.com/[org]/[repo-name]
**Last Updated**: [date]

## Stack

- Node.js + TypeScript (ES modules)
- pnpm

## Commands

| Command | Purpose |
|---------|---------|
| `pnpm dev` | Local dev server |
| `pnpm build` | Production build |
| `pnpm test` | Run tests |

## Gotchas

[Add as discovered]

Python

# [Project Name]

**Repository**: https://github.com/[org]/[repo-name]
**Last Updated**: [date]

## Stack

- Python 3.12+
- uv (package management)

## Commands

| Command | Purpose |
|---------|---------|
| `uv run python main.py` | Run the application |
| `uv sync` | Install dependencies |
| `uv run pytest` | Run tests |

## Gotchas

[Add as discovered]

Ops / Admin (Claude Code Plugin)

# [Project Name]

**Repository**: https://github.com/[org]/[repo-name]
**Last Updated**: [date]

## Purpose

[What this operational project does]

## MCP Servers

| Server | Purpose |
|--------|---------|
| [server] | [what it does] |

## Gotchas

[Add as discovered]

---

Sub-Directory CLAUDE.md

For directories with external integrations, non-obvious config, or common gotchas:

# [Component Name]

## Key Integrations

- **[Service]**: [endpoint], [auth method], [secret location]

## Commands

[Directory-specific commands if different from root]

## Gotchas

- [Non-obvious thing specific to this directory]

Target: 15-50 lines.

Don't create when: parent CLAUDE.md covers it, directory is self-explanatory, content would be under 10 lines.

Rules Topic File (.claude/rules/*.md)

For correction rules, patterns, and technical facts:

# [Topic Name]

## [Pattern/Rule Category]

| If Claude suggests... | Use instead... |
|----------------------|----------------|
| [Wrong pattern] | [Correct pattern] |

[Code example if helpful]

**Last Updated**: [date]

Target: 20-80 lines per topic file.

---

Section Placement Guide

Anti-Patterns

• Verbose explanations of standard tools or frameworks
• Changelogs or version history (use git)
• Content Claude already knows from training
• Duplicating parent CLAUDE.md content in child files
• Generic best practices not specific to the project
• Empty template sections with placeholder text

---

.gitignore Templates

Cloudflare Worker / Node

node_modules/
.wrangler/
dist/
.dev.vars
*.log
.DS_Store
.env
.env.local
.claude/settings.local.json
.claude/plans/
.jez/screenshots/
.jez/artifacts/

Python

__pycache__/
*.pyc
.venv/
dist/
*.egg-info/
.env
.env.local
.DS_Store
.claude/settings.local.json
.claude/plans/
.jez/screenshots/
.jez/artifacts/

Ops / Admin

.DS_Store
.env
.env.local
.claude/settings.local.json
.claude/plans/
.jez/screenshots/
.jez/artifacts/

PHP / WordPress

vendor/
node_modules/
*.log
.DS_Store
.env
.env.local
.claude/settings.local.json
.claude/plans/
.jez/screenshots/
.jez/artifacts/

Go

bin/
*.exe
*.test
*.out
.DS_Store
.env
.claude/settings.local.json
.claude/plans/
.jez/screenshots/
.jez/artifacts/

Rust

target/
Cargo.lock
.DS_Store
.env
.claude/settings.local.json
.claude/plans/
.jez/screenshots/
.jez/artifacts/