MDD turns Claude Code into a structured development partner: every feature starts with documentation, every fix starts with an audit. 21 modes covering build, audit, planning, ops runbooks, and more — all via
/mddin any Claude Code session.Install:
npm install -g @thedecipherist/mdd && mdd install
Install once and all 27 commands, 10 hooks, and 25 skills are globally available in every Claude Code session. No need to clone this repo or always have the mastery project open.
npx @claude-code-mastery/starter-kit initCommands like
/new-project,/review,/commit, and/mddwork everywhere, not just inside this repo.
The GitHub Pages site has the complete documentation with syntax highlighting, navigation, and visual examples.
The definitive starting point for Claude Code projects. Based on Claude Code Mastery Guides V1-V5 by TheDecipherist.
This is a scaffold template, not a runnable application. It provides the infrastructure (commands, hooks, skills, documentation templates) that makes Claude Code dramatically more effective. You use it to create projects, not run it directly.
A. Install globally via npm (recommended):
npx @claude-code-mastery/starter-kit initAll 27 commands, hooks, and skills land in ~/.claude/ and work in every Claude Code session from that point on. No cloning, no staying in a specific directory. Run /new-project my-app from anywhere.
B. Scaffold a new project from a clone:
/new-project my-app clean # or: /new-project my-app default
cd ~/projects/my-app
/setupIf you cloned this repo, use it to scaffold projects. All the tooling gets copied into the new project's .claude/ directory.
C. Convert an existing project:
/convert-project-to-starter-kit ~/projects/my-existing-appNon-destructive merge - brings all starter kit infrastructure (commands, hooks, skills, CLAUDE.md rules) into your existing project while preserving everything you already have. Creates a safety commit first so you can git revert HEAD to undo.
D. Customize the template:
Clone this repo, modify the commands, hooks, skills, and rules to match your team's standards, then publish your own npm package or use the clone directly as the source for /new-project.
What NOT to do: Don't clone this repo and run
pnpm devexpecting a working app. This is the template that creates apps — it's not an app itself.
Progress through these phases at your own pace. Each builds on the previous one.
The starter kit supports two development workflows:
- Classic —
/review,/commit,/create-api,/create-e2e(individual commands, you drive) - MDD —
/mdd(structured Analyze → Document → Test → Code workflow, Claude drives with your approval)
Both use the same hooks, rules, and quality gates. MDD adds structured documentation and audit capabilities on top.
Phase 1 Phase 2 Phase 3 Phase 4 Phase 5
INITIAL SETUP BUILD FEATURES QUALITY & TESTING DEPLOYMENT ADVANCED
(5 minutes)
/install-global --> /mdd <feature> --> /mdd audit --> /optimize-docker --> /refactor
/new-project /review /mdd status /security-check /what-is-my-ai-doing
cd my-app /commit /create-e2e deploy /worktree
/setup /create-api /test-plan custom rules
Via npm (no clone needed):
npx @claude-code-mastery/starter-kit init # One-time global install
/new-project my-app clean # Scaffold a project from anywhere
cd ~/projects/my-app
/setup # Configure .env interactively
pnpm install && pnpm devVia clone (if you want to customize the templates):
/install-global # One-time: installs global Claude config + MDD
/new-project my-app clean # Scaffold a project
cd ~/projects/my-app
/setup
pnpm install && pnpm dev/mdd add user authentication # Claude interviews you, writes docs, generates
# test skeletons, presents a plan, then buildsUse /help to see all 27 commands at any time.
 |
 |
/help — All 27 commands |
/review — Catching violations with severity ratings |
 |
 |
| Auto-Branching — Hook blocks commits to main | Lint-on-Save — TypeScript errors caught instantly |
 |
 |
/diagram architecture — Generated from actual code |
/setup — Interactive .env configuration |
 |
 |
| AI Monitor — Free mode, no API key needed | E2E Tests — Good vs bad assertions |
Everything you need to start a Claude Code project the right way — security, automation, documentation, and testing all pre-configured.
- CLAUDE.md — Battle-tested project instructions with 11 numbered critical rules for security, TypeScript, database access, testing, and deployment
- Global CLAUDE.md — Security gatekeeper for all projects. Never publish secrets, never commit .env files, standardized scaffolding rules
- 27 Slash Commands (16 project + 11 kit management)
- Project (copied into every scaffolded project):
/help,/review,/commit,/progress,/test-plan,/architecture,/security-check,/optimize-docker,/create-e2e,/create-api,/worktree,/what-is-my-ai-doing,/refactor,/diagram,/setup,/show-user-guide - Kit management (starter kit only):
/new-project,/update-project,/convert-project-to-starter-kit,/install-global,/install-mdd,/quickstart,/projects-created,/remove-project,/set-project-profile-default,/add-project-setup,/add-feature - MDD workflow — separate package:
npm install -g @thedecipherist/mdd && mdd install→ adds/mddglobally (21 modes)
- Project (copied into every scaffolded project):
- 10 Hooks — Deterministic enforcement that always runs. Block dangerous bash commands, enforce file-length limits, lint on save, verify no committed credentials, branch protection, port conflicts, Rybbit pre-deploy gate, E2E test gate, env sync warnings, and RuleCatch monitoring (optional — skips silently if not installed)
- 25 Skills — Context-aware expertise covering code review, debugging, testing, API conventions, MongoDB rules, Docker, Node.js, accessibility, web performance, responsive CSS, web architecture, NGINX, WAF, MDD workflow, and more
- Documentation Templates — Pre-structured ARCHITECTURE.md, INFRASTRUCTURE.md, and DECISIONS.md templates
- Testing Templates — Master test checklist, issue tracking log, and StrictDB integration that prevents connection pool explosion
- Live AI Monitor — See every tool call, token, cost, and violation in real-time with
/what-is-my-ai-doing. Free monitor mode works instantly — no API key, no account. Runpnpm ai:monitorin a separate terminal. Zero token overhead
MDD has been separated into its own standalone npm package. It is no longer bundled with this starter kit — you install it independently and use it in any project, with or without the starter kit.
We used MDD to audit this starter kit. Result: 20 findings discovered, 17 fixed, and 125 tests written from zero — all in 48 minutes. The methodology the starter kit teaches was used to audit the starter kit itself.
npm install -g @thedecipherist/mdd # install the MDD package
mdd install # deploy /mdd command to ~/.claude/commands/MDD is the companion development methodology that turns Claude Code from a code generator into a structured development partner. Every feature starts with documentation. Every fix starts with an audit.
Most people prompt Claude Code like this: "fix the bug in my auth system." Claude reads 40 files, burns through context trying to understand your architecture, and produces something that technically compiles but misses the bigger picture.
MDD flips this. You write structured documentation first, then Claude reads one doc instead of 40 files. It gets the full picture in 200 tokens instead of 20,000.
Every phase reads the output of the previous phase, compressing context further at each step:
| Phase | What Happens |
|---|---|
| 📋 Document | Write feature docs with YAML frontmatter in .mdd/docs/ |
| 🔍 Audit | Read source code, write incremental notes to disk (survives compaction) |
| 📊 Analyze | Read notes only → produce severity-rated findings report |
| 🔧 Fix | Execute pre-planned fixes with tests |
| ✅ Verify | Tests pass, types check, documentation updated |
# Build a new feature (Analyze → Document → Test skeletons → Plan → Implement → Verify)
/mdd add user authentication with JWT tokens
# Audit existing code (Scope → Read + Notes → Analyze → Present → Fix)
/mdd audit
/mdd audit database # audit a specific section
# Check MDD status and rebuild .mdd/.startup.md (includes drift summary)
/mdd status
# Detect code that changed outside MDD — catch doc drift before it silently spreads
/mdd scan
# Create a one-off task doc (follows full MDD workflow, but frozen — never shows as drifted)
/mdd task refactor db-query script
/mdd task investigate auth flow latency
# Update an existing feature doc after code has changed
/mdd update 04 # by number
/mdd update content-builder
# Generate docs from undocumented code, or regenerate an existing doc
/mdd reverse-engineer src/handlers/payments.ts
/mdd reverse-engineer 07 # regenerate doc 07 by comparing code vs existing doc
# Show cross-feature dependency graph with broken/risky dep warnings
/mdd graph
# Retire a feature cleanly — archive doc, flag dependents, optionally clean up files
/mdd deprecate 03
# Batch-patch missing frontmatter (last_synced, status, phase) across all docs
# Fixes the UNTRACKED state — use once when upgrading from an older MDD version
/mdd upgrade
# Append a note to .mdd/.startup.md (survives compaction)
/mdd note "just switched to PostgreSQL"
/mdd note list # view all notes
/mdd note clear # wipe notes section
# ── Initiative / Wave Planning (NEW) ────────────────────────────────────────────
# Create a new initiative (groups related waves and features into one roadmap item)
/mdd plan-initiative "auth system" # guided mode
/mdd plan-initiative "auth system" --template # write raw markdown yourself
# Add a wave to an initiative (a phase of work with a concrete demo state)
/mdd plan-wave auth-system "Auth Foundation"
/mdd plan-wave auth-system "Auth Foundation" --template
# Execute a wave — turns planned features into MDD docs and starts implementation
/mdd plan-execute auth-system-wave-1
# Sync wave docs after the parent initiative changes (version bump)
/mdd plan-sync auth-system
# Remove a feature from a wave (before it has a doc)
/mdd plan-remove-feature auth-system-wave-1 auth-signup
# Cancel an initiative and all its planned work
/mdd plan-cancel-initiative auth-system
# Show a reference table of every /mdd mode and what it does
/mdd commandsBuild mode (/mdd <description>) — 7 phases, 3 mandatory gates:
- Pipeline: Understand → Analyze → Document → Test Skeletons + Red Gate → Plan → Implement + Green Gate → Verify + Integration Gate
- Phase 1 gathers context using 3 parallel Explore agents (rules, existing features, codebase structure)
- Phase 2 is a mandatory Data Flow & Impact Analysis gate — traces every data value end-to-end before writing a line of docs; skipped automatically on greenfield projects
- Questions are context-adaptive — tooling tasks skip the database and API questions entirely
- Red Gate runs every test skeleton to confirm it actually fails before implementation begins
- Build plan uses commit-worthy blocks with runnable end-states, verification commands, and handoff contracts; independent blocks are annotated for parallel execution
- Green Gate implements each block with a 5-iteration diagnosis-first loop — states root cause before each fix; stops at 5 and reports to the user rather than continuing blindly
- Integration Gate verifies real behavior (real HTTP calls, real DB, real browser) before marking complete; blocked features get
⏸️ MDD Blockedwith a concrete next step
Audit mode (/mdd audit) — complete security and quality audit, 5 phases:
- A1 Scope — reads
.mdd/docs/to build the feature map; auto-generates docs if none exist - A2 Read + Notes — features batched across up to 3 parallel Explore agents; notes written to disk so findings survive context compaction
- A3 Analyze — reads notes file only to produce a severity-rated findings report
- A4 Present — shows top findings with effort estimates and asks what to fix
- A5 Fix — applies fixes, writes tests, updates documentation
- Auto-branches to
fix/mdd-audit-<date>before making any changes
Scan mode (/mdd scan) — detects documentation drift (features whose source files changed since last session):
- A single Explore agent runs all
git log --after="<last_synced>"checks in one pass - Returns a classification table: ✅ in sync /
⚠️ drifted / ❌ broken reference / ❓ untracked - Task docs (
type: task) appear in a separate frozen section — never flagged as drifted - Saves a full drift report to
.mdd/audits/scan-<date>.md
Update mode (/mdd update <feature-id>) — re-syncs a feature doc after code changes:
- Reads current source files, diffs them against the doc, presents "what changed"
- Rewrites only the affected sections; never touches unchanged content
- Appends new test skeletons for newly documented behaviors without modifying existing tests
- Updates
last_syncedin frontmatter
Reverse-engineer mode (/mdd reverse-engineer [path|feature-id]) — generates MDD docs from existing code:
- Works on undocumented files (new doc) or existing docs (regenerate + compare)
- ≤3 files read directly in the main conversation; 4+ files batched across up to 3 parallel Explore agents
- Always shows a diff in regenerate mode so you can merge rather than blindly overwrite
- Discloses limitations — business intent and implicit constraints must be manually reviewed
Graph mode (/mdd graph) — renders an ASCII dependency map from depends_on fields:
- Flags broken dependencies (deprecated features still depended on)
- Flags risky dependencies (complete features depending on in-progress ones)
- Identifies orphans (no connections either way)
- When
.mdd/initiatives/exists: appends an initiative → wave → feature hierarchy tree showing progress and broken doc links
Deprecate mode (/mdd deprecate <feature-id>) — retires a feature cleanly:
- Sets
status: deprecatedand moves the doc to.mdd/docs/archive/ - Adds known-issue warnings to all dependent docs
- Asks separately whether to delete source files and test files — never auto-deletes
Upgrade mode (/mdd upgrade) — batch-patches missing frontmatter fields across all docs:
- Adds
last_synced,status, andphaseto any doc missing them - Non-destructive — existing fields are never overwritten
last_syncedinferred fromgit logon each doc file (not today's date) so drift stays accurate- Shows a plan and asks for confirmation before writing anything
- Run once when upgrading from an older MDD version; fixes the UNTRACKED (❓) state
Plan-initiative mode (/mdd plan-initiative <title>) — creates a new initiative file in .mdd/initiatives/:
- Interviews you about goals, target audience, and open product questions (guided mode), or writes the raw template for you to fill in (--template)
- Generates a slug and a v1 hash; collision-checks against existing initiatives
- If an initiative with the same slug already exists and has active wave docs, blocks with an error — active code must be deprecated before overwriting
Plan-wave mode (/mdd plan-wave <initiative-id> <wave-title>) — adds a wave to an existing initiative:
- Asks about demo state, feature list, and dependencies between features in the same wave
- Writes a wave file in
.mdd/waves/stamped with the initiative's current version - Validates that the parent initiative exists and is not cancelled
Plan-execute mode (/mdd plan-execute <wave-id>) — turns a planned wave into real work:
- Reads the wave file; for each planned feature without a doc, runs
/mdd <feature-slug>build mode - Supports automated (run all) or interactive (confirm each feature) execution
- Updates each feature's
docPathandwaveStatusin the wave file as docs are created
Plan-sync mode (/mdd plan-sync <initiative-id>) — re-stamps all wave files after a version bump:
- Run after editing an initiative (overview, questions) — updates
initiativeVersionin all child waves - Surfaces stale waves flagged by
/mdd scan
Plan-remove-feature mode (/mdd plan-remove-feature <wave-id> <feature-slug>) — removes a feature from a wave before it has been executed:
- Hard-stops if the feature already has a
docPath— use/mdd deprecatefor that instead - Confirms with the user before removing
Plan-cancel-initiative mode (/mdd plan-cancel-initiative <initiative-id>) — cancels an initiative and all its planned work:
- Sets initiative
status: cancelledand all child wave statuses tocancelled - If any wave has executed features (docs with
docPath), warns and asks how to handle them - Cancelled initiatives are still visible in the TUI dashboard (shown in gray)
MDD versioning — every file created or updated by MDD is stamped with mdd_version: N in its frontmatter, where N matches the version declared in the @thedecipherist/mdd package. /mdd status shows a breakdown of which docs are on which version. Update MDD with npm install -g @thedecipherist/mdd && mdd install (or /install-global mdd). Files without mdd_version (created before versioning was introduced) are treated as version 0 and flagged as outdated.
All MDD artifacts live in a single dotfile directory, gitignored by default:
.mdd/
├── docs/ # Feature documentation (one per feature)
│ ├── 01-<feature-name>.md # auto-numbered, YAML frontmatter + last_synced/status/phase
│ ├── 02-<feature-name>.md
│ └── archive/ # Deprecated feature docs (set by /mdd deprecate)
├── initiatives/ # Initiative files (created by /mdd plan-initiative)
│ └── <initiative-slug>.md # YAML frontmatter: id, title, status, version, hash
├── waves/ # Wave files (created by /mdd plan-wave)
│ └── <initiative-slug>-wave-N.md # YAML frontmatter + feature table; links back to docs
├── audits/ # Audit artifacts (all gitignored)
│ ├── flow-<feature>-<date>.md # Data flow analysis written during Phase 2
│ ├── notes-<date>.md # Raw reading notes (Phase A2, written every 2 features)
│ ├── report-<date>.md # Severity-rated findings report (Phase A3)
│ ├── results-<date>.md # Before/after fix summary (Phase A5)
│ ├── scan-<date>.md # Drift report from /mdd scan
│ └── graph-<date>.md # Dependency graph from /mdd graph
└── .startup.md # Auto-generated session context (injected at startup)
| Audit Step | Time | Output |
|---|---|---|
| Create Docs (pre-audit) | ~25 min | 9 feature docs (795 lines) in .mdd/docs/ |
| A2: Read + Notes | 9 min 51s | 57+ files read, 837 lines of notes |
| A3: Analyze | 2 min 39s | 298-line report, 20 findings |
| A5: Fix All | 10 min 53s | 17/20 fixed, 125 tests written |
| Total | ~48 min | 20 findings, 125 tests from zero |
| Metric | Before MDD | After MDD |
|---|---|---|
| Unit tests | 0 | 94 |
| Test files | 0 | 5 |
| Documentation files | 3 | 14 |
| Known issues documented | 0 | 84 |
| Findings found & fixed | 0 | 17/20 |
| Quality gate violations | 1 (651-line file) | 0 (split into 5 modules) |
| Config validation | None (raw JSON.parse) | Zod schema with fail-fast |
| Secret detection patterns | 4 basic | 10+ (GitHub, Slack, Stripe, PEM, JWT) |
The most important technical detail: when Claude reads files during an audit, context will compact. If your findings are only in memory, they're gone. Instead, Claude writes notes to disk every 2 features. If context compacts, it reads the tail of the notes file and picks up where it left off. Zero data loss across 6 complete audit cycles.
Every time a Claude Code session starts (including after /clear and compaction),
the starter kit injects a compact project snapshot into Claude's context automatically.
This replaces the expensive habit of Claude reading 40 files to get oriented -- it reads
one file instead.
The snapshot is stored in .mdd/.startup.md and has two zones:
Auto-generated zone (above the --- divider) -- rewritten by /mdd commands:
- Current git branch
- Stack summary (framework, database, hosting)
- Features documented in
.mdd/docs/ - Last audit results (findings found, fixed, still open)
- Rules quick-reference
Notes zone (below the --- divider) -- append-only, never overwritten:
- Your own timestamped annotations added with
/mdd note
The file is gitignored -- it is machine state, not source code. It regenerates automatically as you use MDD.
Commands:
/mdd status -- regenerate .startup.md from current project state
/mdd note "your note" -- append a timestamped note
/mdd note list -- print only the Notes section
/mdd note clear -- wipe the Notes section
Why this works:
The SessionStart hook runs on startup, /clear, and compaction. Its only job is:
cat .mdd/.startup.md
One file. ~100-200 tokens. Claude is fully oriented before your first prompt.
The mdd package is a companion terminal dashboard for MDD workspaces. Run it inside any project that has a .mdd/ folder to get a real-time, interactive view of your workspace health — without leaving VS Code.
npm install -g @thedecipherist/mdd-tuiThen inside any project with a .mdd/ folder:
mdd # opens the interactive TUI
mdd dashboard # same
mdd status # same — all three open the dashboardWhat it shows:
| Panel | Contents |
|---|---|
| Left | INITIATIVES (collapsible tree, shown when .mdd/initiatives/ exists) · feature docs · audit reports · dep graph |
| Right | Initiative overview, wave detail, or full doc/audit content with drift info, frontmatter chips, and markdown |
| Top bar | Counts: docs · in-sync · drifted · broken · untracked · issues · audits · initiatives · active waves |
Left panel sections (top to bottom):
- INITIATIVES — collapsible tree of initiatives and their waves.
▸collapsed,▾expanded. Wave rows show●active /✓complete /○planned with a feature progress count (e.g.2/3). - FEATURE DOCS — all docs with drift icons:
✅in sync ·⚠️drifted ·❌broken ·❓untracked - AUDIT REPORTS — audit files from
.mdd/audits/ - DEP GRAPH — ASCII dependency map
Keyboard shortcuts:
| Key | Action |
|---|---|
↑ / k · ↓ / j |
Navigate left panel / scroll right panel |
→ / l / Enter |
Focus right panel (or expand initiative) |
← / h / Esc |
Focus left panel |
i |
Jump to first initiative |
Page Up / Page Down |
Scroll right panel one page |
Home / End |
Jump to top / bottom of right panel |
r |
Refresh and re-scan workspace |
q / Ctrl+C |
Quit |
The dashboard auto-detects drift by running git log against each doc's last_synced frontmatter field. Docs whose source_files have changed since last sync are marked
npm: mdd-tui · GitHub: TheDecipherist/mdd-tui
Recommended: install MDD globally. Run
/install-globalonce and answer "yes" to the MDD prompt —/mddis then available in every project on your machine with no per-project setup. Update the starter kit once and every project picks up the new version automatically on the next session. When you run/mddfor the first time in a fresh project, it auto-creates the.mdd/structure (docs, audits, ops,.startup.md) — no separate/install-mddstep needed.
The flaw MDD had: Deployment and infrastructure tasks had no documentation home. Running
/mdd dokploy-deploydefaulted to Build Mode and skipped the documentation phases — because deploying services isn't a feature to build. Ops Mode fixes this.
MDD now treats deployments as first-class citizens. Every deployment target gets a structured runbook — either project-local or global. Write it once — then runop executes it every time, with live health checks, verified steps, and canary-gated multi-region rollout.
| Command | What it does |
|---|---|
/mdd ops <description> |
Create a runbook — first question is always: global or project? |
/mdd ops list |
List all runbooks — global and project — with last-run health status |
/mdd runop <slug> |
Execute a runbook — checks project-local first, then global |
/mdd update-op <slug> |
Edit an existing runbook — same lookup order |
The first thing /mdd ops asks is where the runbook should live:
| Scope | Location | Use for |
|---|---|---|
| Project | .mdd/ops/<slug>.md |
This project only (e.g., deploy this specific app to Dokploy) |
| Global | ~/.claude/ops/<slug>.md |
Reusable across all projects (e.g., update Cloudflare DNS, renew SSL certs, Docker Hub login) |
Global ops cannot access project-local
.envvariables or project paths. They use~/.envglobals only — which is exactly right for infrastructure procedures that don't belong to any one project.
Global is the authoritative namespace. If a global runbook named cloudflare-dns exists, no project can create a local runbook with the same name. This prevents any ambiguity about which runbook runop will execute — you always know exactly what runs.
# First time — creates the runbook
/mdd ops "deploy rulecatch services to dokploy US and EU"
# Every deployment after — reads the runbook, no questions asked
/mdd runop rulecatch-dokployrunop reads .mdd/ops/rulecatch-dokploy.md and executes the full deployment: pre-flight checks, step-by-step procedure with verification at each step, and post-flight confirmation. No tribal knowledge. No forgotten steps. The doc IS the deployment.
Deploy to your canary region first. Gate on full health verification. Only then touch primary. If canary fails — primary is never touched, still running the last good version.
Pre-flight Health Check — rulecatch-dokploy
──────────────────────────────────────────────────────────
eu-west (canary) us-east (primary)
api ✓ healthy ✓ healthy
dashboard ✗ failing ✓ healthy
worker ✓ healthy ✓ healthy
dashboard is failing in eu-west.
(a) Redeploy (b) Skip (c) Abort
── eu-west (canary) — gate check ───────────────────────
api ✓ healthy (rulecatch-api-eu:latest)
dashboard ✓ healthy (rulecatch-dashboard-eu:latest)
worker ✓ healthy
Gate: PASSED ✓ — advancing to us-east (primary)
runop complete — rulecatch-dokploy
eu-west (canary) us-east (primary)
api ✓ healthy ✓ healthy
dashboard ✓ healthy ✓ healthy
worker ✓ healthy ✓ healthy
Canary gate: PASSED ✓
Regions deployed: 2/2
Steps executed: 14/14 ✓
Different image names for different regions? Fully supported. Each service has a default image plus per-region overrides:
services:
- slug: api
image: theDecipherist/rulecatch-api:latest # default
regions:
eu-west:
image: theDecipherist/rulecatch-api-eu:latest # different name for EU
status: healthy
last_checked: 2026-04-18T10:00:00Z
us-east:
image: theDecipherist/rulecatch-api:latest # same as default
status: healthy
last_checked: 2026-04-18T10:05:00ZAll keys are always fully populated — no implicit inheritance that breaks when you add a second region.
deployment_strategy:
order: sequential # sequential | parallel
gate: health_check # health_check | manual | none
on_gate_failure: stop # stop | skip_region | rollback
rollback_on_failure: false # auto-run rollback steps on failureon_gate_failure: stop — canary fails, primary untouched. Investigate, fix, re-run.
on_gate_failure: rollback — canary fails, auto-rollback EU, primary untouched.
on_gate_failure: skip_region — skip the failed region and continue to primary (useful when EU is lower priority).
/mdd ops list📦 Ops Runbooks
Global (~/.claude/ops/)
cloudflare-dns DNS record updates via Cloudflare API last run: 2026-04-10
ssl-renewal Let's Encrypt cert renewal (Certbot) last run: never
Project (.mdd/ops/)
rulecatch-dokploy 10 services → eu-west (canary) + us-east last run: 2026-04-18 ✓ all healthy
swarmk-dokploy 7 services → eu-west (canary) + us-east last run: 2026-04-17 ⚠ api degraded
Run /mdd runop <slug> to execute any runbook.
~/.claude/ops/ ← global runbooks (all projects)
cloudflare-dns.md
ssl-renewal.md
.mdd/
├── docs/ ← feature docs (type: feature | task)
└── ops/ ← project runbooks (this project only)
├── rulecatch-dokploy.md
├── swarmk-dokploy.md
└── archive/
All existing modes are ops-aware: /mdd status shows ops runbook count, /mdd scan checks runbook drift, /mdd graph includes a runbook health summary, /mdd audit flags missing sections and credential security violations.
Five open-source npm packages by TheDecipherist — the same developer behind this starter kit — are integrated into the default build. All are MIT-licensed.
Full disclosure: These packages are developed by the same person who maintains this starter kit. They are completely open source (MIT license), and the starter kit works fully without them. ClassMCP and Classpresso are auto-included in CSS-enabled profiles because they directly complement the AI-assisted CSS workflow this kit teaches. StrictDB-MCP is auto-included in database-enabled profiles. TerseJSON is documented but not auto-included.
MCP server that provides semantic CSS class patterns to Claude, reducing token usage when generating or editing styles. Auto-added to the mcp field in CSS-enabled profiles.
claude mcp add classmcp -- npx -y classmcp@latestGives AI agents direct database access through 14 MCP tools with full guardrails, sanitization, and error handling. Auto-included in database-enabled profiles (mcp field in claude-mastery-project.conf).
claude mcp add strictdb -- npx -y strictdb-mcp@latestnpm: strictdb-mcp
Consolidates CSS classes after build for 50% faster style recalculation with zero runtime overhead. Auto-added as a devDependency in CSS-enabled profiles. Runs automatically after pnpm build.
pnpm add -D classpressonpm: classpresso · Website
Proxy-based lazy JSON expansion achieving ~70% memory reduction for large payloads. Not auto-included — install only if your project handles large JSON datasets.
pnpm add tersejsonThis starter kit works with any language, framework, or database. Use /new-project my-app clean for zero opinions, or pick a profile that matches your stack.
| Category | Technologies | Notes |
|---|---|---|
| Languages | Node.js/TypeScript, Go, Python | Full scaffolding support for all three |
| Frontend | React, Vue 3, Svelte, SvelteKit, Angular, Next.js, Nuxt, Astro | CLI scaffold + CLAUDE.md rules per framework |
| Backend (Node.js) | Fastify, Express, Hono | API scaffolding with /create-api |
| Backend (Go) | Gin, Chi, Echo, Fiber, stdlib | Standard layout with cmd/internal/ |
| Backend (Python) | FastAPI, Django, Flask | Async support, Pydantic, pytest |
| Database | MongoDB, PostgreSQL, MySQL, MSSQL, SQLite, Elasticsearch | StrictDB for all backends |
| Hosting | Dokploy, Vercel, Static (GitHub Pages, Netlify) | Deployment scripts + Docker |
| Testing | Vitest, Playwright, pytest, Go test | Framework-appropriate test setup |
| CSS | Tailwind CSS + ClassMCP + Classpresso | ClassMCP (MCP) + Classpresso (post-build) auto-included in CSS profiles |
| Use Case | Stack | Profile |
|---|---|---|
| SPA Dashboard | Vite + React + Fastify + MongoDB | default |
| REST API (Node.js) | Fastify + PostgreSQL | api with postgres |
| Go Microservice | Gin + PostgreSQL | go with postgres |
| Python API | FastAPI + PostgreSQL | python-api |
| Vue SPA | Vue 3 + Vite + Tailwind | vue |
| Nuxt Full-Stack | Nuxt + MongoDB + Docker | nuxt |
| Svelte SPA | Svelte + Vite + Tailwind | svelte |
| SvelteKit Full-Stack | SvelteKit + MongoDB + Docker | sveltekit |
| Angular App | Angular + Tailwind | angular |
| Django Web App | Django + PostgreSQL + Docker | django |
| Content Site | Astro or SvelteKit | static-site or sveltekit |
| AI goodies only | Any — you choose everything | clean |
# Clone the starter kit
git clone https://github.com/TheDecipherist/claude-code-mastery-project-starter-kit my-project
cd my-project
# Remove git history and start fresh
rm -rf .git
git init
# Copy your .env
cp .env.example .env# Run the install command — smart merges into existing config
/install-globalThis installs global CLAUDE.md rules, settings.json hooks, and enforcement scripts (verify-no-secrets.sh, check-rulecatch.sh) into ~/.claude/. If you already have a global config, it merges without overwriting.
Manual setup (if you prefer)
cp global-claude-md/CLAUDE.md ~/.claude/CLAUDE.md
cp global-claude-md/settings.json ~/.claude/settings.json
mkdir -p ~/.claude/hooks
cp .claude/hooks/verify-no-secrets.sh ~/.claude/hooks/
cp .claude/hooks/check-rulecatch.sh ~/.claude/hooks/- Run
/setup— Interactive .env configuration (database, GitHub, Docker, analytics) - Edit
CLAUDE.md— Update port assignments, add your specific rules - Run
/diagram all— Auto-generate architecture, API, database, and infrastructure diagrams - Edit
CLAUDE.local.md— Add your personal preferences
StrictDB works out of the box — just set STRICTDB_URI in your .env and it connects to your database automatically. Built-in sanitization and guardrails run on all inputs: standard query operators pass through safely while dangerous operators are stripped. See the Database — StrictDB section for details.
claudeThat's it. Claude Code now has battle-tested rules, deterministic hooks, slash commands, and documentation templates all ready to go.
- Verify
.claude/settings.jsonis valid JSON:python3 -m json.tool .claude/settings.json - Check that hook file paths are correct and executable:
ls -la .claude/hooks/ - Restart your Claude Code session — hooks are loaded at session start
This is a scaffold template, not a runnable app. Use /new-project my-app to create a project first, then run pnpm dev inside that project.
- Run
/setupto configure your.envwith a valid connection string - Check that
STRICTDB_URIis set in.env - Verify your IP is whitelisted in your database provider's network access settings
This is normal. The command uses smart merge — it keeps your existing sections and only adds what's missing. If sections overlap, it preserves yours. Check the report output for details on what was added vs skipped.
# Find what's using the port
lsof -i :3000
# Kill it
kill -9 <PID>
# Or kill all test ports at once
pnpm test:kill-ports- Kill stale processes on test ports:
pnpm test:kill-ports - Run headed to see what's happening:
pnpm test:e2e:headed - Check that
playwright.config.tshas correctwebServercommands and ports
Free monitor mode requires no setup. Run
pnpm ai:monitorin a separate terminal — it works instantly with no API key.
- Free monitor:
pnpm ai:monitor(ornpx @rulecatch/ai-pooler monitor --no-api-key) — live view of tool calls, tokens, cost - Full experience: Sign up at rulecatch.ai for dashboards, violation tracking, and alerts, then run
npx @rulecatch/ai-pooler init --api-key=YOUR_KEY --region=us
project/
├── CLAUDE.md # Project instructions (customize this!)
├── CLAUDE.local.md # Personal overrides (gitignored)
├── .claude/
│ ├── settings.json # Hooks configuration
│ ├── commands/
│ │ │ # /mdd — installed globally via: npm install -g @thedecipherist/mdd && mdd install
│ │ ├── help.md # /help — list all commands and skills
│ │ ├── quickstart.md # /quickstart — interactive first-run walkthrough
│ │ ├── review.md # /review — code review
│ │ ├── commit.md # /commit — smart commit
│ │ ├── progress.md # /progress — project status
│ │ ├── test-plan.md # /test-plan — generate test plan
│ │ ├── architecture.md # /architecture — show system design
│ │ ├── new-project.md # /new-project — scaffold new project
│ │ ├── security-check.md # /security-check — scan for secrets
│ │ ├── optimize-docker.md # /optimize-docker — Docker best practices
│ │ ├── create-e2e.md # /create-e2e — generate E2E tests
│ │ ├── create-api.md # /create-api — scaffold API endpoints
│ │ ├── worktree.md # /worktree — isolated task branches
│ │ ├── what-is-my-ai-doing.md # /what-is-my-ai-doing — live AI monitor
│ │ ├── setup.md # /setup — interactive .env configuration
│ │ ├── refactor.md # /refactor — audit + refactor against all rules
│ │ ├── install-global.md # /install-global — merge global config into ~/.claude/
│ │ ├── install-mdd.md # /install-mdd — install MDD workflow into any project
│ │ ├── diagram.md # /diagram — generate diagrams from actual code
│ │ ├── set-project-profile-default.md # /set-project-profile-default — set default profile
│ │ ├── add-project-setup.md # /add-project-setup — create a named profile
│ │ ├── projects-created.md # /projects-created — list all created projects
│ │ ├── remove-project.md # /remove-project — remove a project from registry
│ │ ├── convert-project-to-starter-kit.md # /convert-project-to-starter-kit — merge into existing project
│ │ ├── update-project.md # /update-project — update a project with latest starter kit
│ │ ├── add-feature.md # /add-feature — add capabilities post-scaffolding
│ │ └── show-user-guide.md # /show-user-guide — open the User Guide in browser
│ ├── skills/
│ │ ├── api-conventions/SKILL.md # Service structure conventions
│ │ ├── code-review/SKILL.md # Triggered code review checklist
│ │ ├── create-service/SKILL.md # Service scaffolding template
│ │ ├── debugger/SKILL.md # Root-cause failure diagnosis
│ │ ├── dependency-vetting/SKILL.md # Supply-chain check before install
│ │ ├── design-review/SKILL.md # UI/UX + accessibility critique
│ │ ├── mcp-builder/SKILL.md # Build MCP servers with evals
│ │ ├── mongodb-rules/SKILL.md # Driver/StrictDB + data-modeling rules
│ │ └── test-writer/SKILL.md # Tests with explicit assertions
│ └── hooks/
│ ├── check-rybbit.sh # PreToolUse: block deploy without Rybbit
│ ├── check-branch.sh # PreToolUse: block commits on main
│ ├── check-ports.sh # PreToolUse: block if port in use
│ ├── check-e2e.sh # PreToolUse: block push without E2E tests
│ ├── block-dangerous-bash.py # PreToolUse: block destructive shell commands
│ ├── lint-on-save.sh # PostToolUse: lint after writes
│ ├── check-file-length.py # PostToolUse: enforce 300-line file limit
│ ├── verify-no-secrets.sh # Stop: scan staged files for secrets
│ ├── check-rulecatch.sh # Stop: report RuleCatch violations
│ └── check-env-sync.sh # Stop: warn on .env/.env.example drift
├── .mdd/ # MDD workflow directory (gitignored)
│ ├── docs/ # Feature documentation
│ └── audits/ # Audit notes, reports, results
├── project-docs/
│ ├── ARCHITECTURE.md # System overview (authoritative)
│ ├── INFRASTRUCTURE.md # Deployment details
│ └── DECISIONS.md # Architectural decision records
├── docs/ # GitHub Pages site
│ └── user-guide.html # Interactive User Guide (HTML)
├── src/
│ ├── handlers/ # Business logic
│ ├── adapters/ # External service adapters
│ └── types/ # Shared TypeScript types
├── scripts/
│ ├── db-query.ts # Test Query Master — dev/test query index
│ ├── queries/ # Individual dev/test query files
│ ├── build-content.ts # Markdown → HTML article builder
│ └── content.config.json # Article registry (SEO metadata)
├── content/ # Markdown source files for articles
├── tests/
│ ├── CHECKLIST.md # Master test tracker
│ ├── ISSUES_FOUND.md # User-guided testing log
│ ├── e2e/ # Playwright E2E tests
│ ├── unit/ # Vitest unit tests
│ └── integration/ # Integration tests
├── global-claude-md/ # Copy to ~/.claude/ (one-time setup)
│ ├── CLAUDE.md # Global security gatekeeper
│ └── settings.json # Global hooks config
├── USER_GUIDE.md # Comprehensive User Guide (Markdown)
├── .env.example
├── .gitignore
├── .dockerignore
├── package.json # All npm scripts (dev, test, db:query, etc.)
├── claude-mastery-project.conf # /new-project profiles + global root_dir
├── playwright.config.ts # E2E test config (test ports, webServer)
├── vitest.config.ts # Unit/integration test config
├── tsconfig.json
└── README.md
Three layers of protection working together:
- CLAUDE.md rules — Behavioral suggestions (weakest)
- Hooks — Guaranteed to run, stronger than rules, but not bulletproof
- Git safety — .gitignore as last line of defense (strongest)
Research shows 39% performance degradation when mixing topics, and a 2% misalignment early can cause 40% failure by end of conversation. Use /clear between unrelated tasks.
No file > 300 lines. No function > 50 lines. All tests pass. TypeScript compiles clean. These prevent the most common code quality issues in AI-assisted development.
With 10+ MCP servers, tool descriptions consume 50-70% of context. Tool Search lazy-loads on demand, saving 85% of context.
For non-trivial tasks, always start in plan mode. Don't let Claude write code until you've agreed on the plan. Bad plan = bad code.
Every step MUST have a unique name: Step 3 (Auth System). When you change a step, Claude must replace it — not append. Claude forgets this. If the plan contradicts itself, tell Claude: "Rewrite the full plan."
Every time Claude makes a mistake, add a rule to prevent it from happening again. Tell Claude: "Update CLAUDE.md so this doesn't happen again." Mistake rates actually drop over time. The file is checked into git — the whole team benefits from every lesson.
Auto-branch is on by default. Every command that modifies code automatically creates a feature branch when it detects you're on main. Zero friction — you never accidentally break main. Delete the branch if Claude screws up. Use /worktree for parallel sessions in separate directories. Set auto_branch = false in claude-mastery-project.conf to disable.
Every slash command and skill has two built-in enforcement steps: Auto-Branch (automatically creates a feature branch when on main — no manual step) and RuleCatch Report (checks for violations after completion). The rules aren't just documented — they're enforced at every touchpoint.
Types are specs that tell Claude what functions accept and return. Without types, Claude guesses — and guesses become runtime errors.
Most Windows developers don't know VS Code can run its entire backend inside WSL 2. HMR becomes 5-10x faster, Playwright tests run significantly faster, and file watching actually works. Your project must live on the WSL filesystem (~/projects/), NOT /mnt/c/. Run /setup to auto-detect.
The CLAUDE.md file is where you define the rules Claude Code must follow. These aren't suggestions — they're the operating manual for every session. Here are the critical rules included in this starter kit:
- NEVER commit passwords, API keys, tokens, or secrets to git/npm/docker
- NEVER commit
.envfiles — ALWAYS verify.envis in.gitignore - Before ANY commit: verify no secrets are included
- ALWAYS use TypeScript for new files (strict mode)
- NEVER use
anyunless absolutely necessary and documented why - When editing JavaScript files, convert to TypeScript first
- Types are specs — they tell you what functions accept and return
CORRECT: /api/v1/users
WRONG: /api/users
Every API endpoint MUST use /api/v1/ prefix. No exceptions.
- NEVER create direct database connections — ALWAYS use StrictDB
- NEVER import raw database drivers (
mongodb,pg,mysql2) in business logic - Built-in sanitization and guardrails: safe operators (
$gte,$in,$regex) pass through, dangerous operators ($where,$function) are stripped - Use
{ trusted: true }only for non-standard operators not in the allowlist (rare) - One connection pool. One place to change. One place to mock.
// CORRECT — explicit success criteria
await expect(page).toHaveURL('/dashboard');
await expect(page.locator('h1')).toContainText('Welcome');
// WRONG — passes even if broken
await page.goto('/dashboard');
// no assertion!ALWAYS use environment variables. NEVER put API keys, passwords, or tokens directly in code. NEVER hardcode connection strings — use STRICTDB_URI from .env.
NEVER auto-deploy, even if the fix seems simple. NEVER assume approval — wait for explicit confirmation.
- No file > 300 lines (split if larger)
- No function > 50 lines (extract helper functions)
- All tests must pass before committing
- TypeScript must compile with no errors (
tsc --noEmit)
When multiple await calls are independent, ALWAYS use Promise.all. Before writing sequential awaits, evaluate: does the second call need the first call's result?
// CORRECT — independent operations run in parallel
const [users, products, orders] = await Promise.all([
getUsers(),
getProducts(),
getOrders(),
]);
// WRONG — sequential when they don't depend on each other
const users = await getUsers();
const products = await getProducts(); // waits unnecessarily
const orders = await getOrders(); // waits unnecessarily- Auto-branch is ON by default — commands auto-create feature branches when on main
- Branch names match the command:
refactor/<file>,test/<feature>,feat/<scope> - Use
/worktreefor parallel sessions in separate directories - Review the full diff (
git diff main...HEAD) before merging - If Claude screws up on a branch — delete it. Main was never touched.
- Disable with
auto_branch = falseinclaude-mastery-project.conf
Disabled by default. When enabled, NO docker push is allowed until the image passes local verification:
- Build the image
- Run the container locally
- Verify it doesn't crash (still running after 5s)
- Health endpoint returns 200
- No fatal errors in logs
- Clean up, then push
Enable with docker_test_before_push = true in claude-mastery-project.conf. Applies to all commands that push Docker images.
The CLAUDE.md also includes a "Check Before Assuming" pattern:
- Missing UI element? → Check feature gates BEFORE assuming bug
- Empty data? → Check if services are running BEFORE assuming broken
- 404 error? → Check service separation BEFORE adding endpoint
- Auth failing? → Check which auth system BEFORE debugging
- Test failing? → Read the error message fully BEFORE changing code
| Service | Dev Port | Test Port |
|---|---|---|
| Website | 3000 | 4000 |
| API | 3001 | 4010 |
| Dashboard | 3002 | 4020 |
CLAUDE.md rules are suggestions. Hooks are stronger — they're guaranteed to run as shell/python scripts at specific lifecycle points. But hooks are not bulletproof: Claude may still work around their output. They're a significant upgrade over CLAUDE.md rules alone, but not an absolute guarantee.
Runs before any Bash command. Blocks destructive operations before they execute — recursive deletes of home/root, pipe-to-shell installs, force-pushes to main, world-writable permissions, database drops, and staging a .env secrets file.
# Command patterns that should never run
DANGEROUS = [
r'rm\s+-rf\s+[~/]', # recursive delete of home/root
r'curl[^|]*\|\s*(sudo\s+)?sh', # pipe-to-shell install
r'git\s+push\s+.*--force.*\b(main|master)\b', # force-push protected branch
r'chmod\s+777', # world-writable
r'git\s+add\s+(\.|.*\.env)\b', # staging a secrets file
]
# Exit code 2 = block operation and tell Claude why
if matches_any(command, DANGEROUS):
print(f"BLOCKED: refusing to run '{command}'.", file=sys.stderr)
sys.exit(2)Note: this is a publish-time guard, not a read guard. Reading
.envis how the app legitimately gets its config; the risk is committing or exfiltrating secrets, whichverify-no-secrets.sh(on Stop) and thegit add .envrule above cover.
Runs after Claude writes or edits a file. Flags source files over 300 lines — the point where a file is usually doing too much and should be split — so the codebase stays modular as Claude builds.
Runs before any deployment command (docker push, vercel deploy, dokploy). If the project has analytics = rybbit in claude-mastery-project.conf, verifies that NEXT_PUBLIC_RYBBIT_SITE_ID is set in .env with a real value. Blocks with a link to https://app.rybbit.io if missing. Skips projects that don't use Rybbit.
Runs before any git commit. If auto-branch is enabled (default: true) and you're on main/master, blocks the commit and tells Claude to create a feature branch first. Respects the auto_branch setting in claude-mastery-project.conf.
Runs before dev server commands. Detects the target port from -p, --port, PORT=, or known script names (dev:website→3000, dev:api→3001, etc.). If the port is already in use, blocks and shows the PID + kill command.
Runs before git push to main/master. Checks for real .spec.ts or .test.ts files in tests/e2e/ (excluding the example template). Blocks push if no E2E tests exist.
Runs after Claude writes or edits a file. Automatically checks TypeScript compilation, ESLint, or Python linting depending on file extension.
case "$EXTENSION" in
ts|tsx)
npx tsc --noEmit --pretty "$FILE_PATH" 2>&1 | head -20
;;
js|jsx)
npx eslint "$FILE_PATH" 2>&1 | head -20
;;
py)
ruff check "$FILE_PATH" 2>&1 | head -20
;;
esacRuns when Claude finishes a turn. Scans all staged git files for accidentally committed secrets using regex patterns for API keys, AWS credentials, and credential URLs.
# Check staged file contents for common secret patterns
if grep -qEi '(api[_-]?key|secret[_-]?key|password|token)\s*[:=]\s*["\x27][A-Za-z0-9+/=_-]{16,}' "$file"; then
VIOLATIONS="${VIOLATIONS}\n - POSSIBLE SECRET in $file"
fi
# Check for AWS keys
if grep -qE 'AKIA[0-9A-Z]{16}' "$file"; then
VIOLATIONS="${VIOLATIONS}\n - AWS ACCESS KEY in $file"
fiRuns when Claude finishes a turn. Checks RuleCatch for any rule violations detected during the session. Skips silently if RuleCatch isn't installed — zero overhead for users who haven't set it up yet.
Runs when Claude finishes a turn. Compares key names (never values) between .env and .env.example. If .env has keys that .env.example doesn't document, prints a warning so other developers know those variables exist. Informational only — never blocks.
Hooks are wired up in .claude/settings.json:
{
"hooks": {
"PreToolUse": [
{
"matcher": "Bash",
"hooks": [
{ "type": "command", "command": "bash .claude/hooks/check-rybbit.sh" },
{ "type": "command", "command": "bash .claude/hooks/check-branch.sh" },
{ "type": "command", "command": "bash .claude/hooks/check-ports.sh" },
{ "type": "command", "command": "bash .claude/hooks/check-e2e.sh" },
{ "type": "command", "command": "python3 .claude/hooks/block-dangerous-bash.py" }
]
}
],
"PostToolUse": [{
"matcher": "Write|Edit",
"hooks": [
{ "type": "command", "command": "bash .claude/hooks/lint-on-save.sh" },
{ "type": "command", "command": "python3 .claude/hooks/check-file-length.py" }
]
}],
"Stop": [{
"hooks": [
{ "type": "command", "command": "bash .claude/hooks/verify-no-secrets.sh" },
{ "type": "command", "command": "bash .claude/hooks/check-rulecatch.sh" },
{ "type": "command", "command": "bash .claude/hooks/check-env-sync.sh" }
]
}]
}
}Invoke these with /command in any Claude Code session. Each command is a markdown file in .claude/commands/ that gives Claude specific instructions and tool permissions.
The core MDD workflow command. Ten modes in one:
/mdd <feature description>— Build mode. Context-adaptive interview → documentation → test skeletons → named build plan → implementation → verification. Tests are generated before code. Claude presents a plan with time estimates and waits for approval./mdd task <description>— Task mode. Identical to Build mode, but stamps the doc withtype: task— frozen after completion, never appears as drifted in/mdd scan. Use for one-off investigations, refactors, or any work that is done-and-finished by definition./mdd audit [section]— Audit mode. Reads all source files, writes incremental notes (survives compaction), produces a severity-rated findings report, and fixes everything. Works on the whole project or a specific section./mdd status— Quick overview of feature docs, last audit date, test coverage, open findings, quality gate violations, and a lightweight drift summary./mdd scan— Drift detection. Usesgit logto find source files that changed since each feature doc'slast_synceddate. Flags drifted, broken, and untracked features./mdd update <feature-id>— Re-sync an existing feature doc after code changes. Diffs code vs doc, rewrites affected sections, appends new test skeletons, updateslast_synced./mdd reverse-engineer [path|id]— Generate MDD docs from existing code, or regenerate + compare against an existing doc. Always shows diff in regenerate mode./mdd graph— ASCII dependency map fromdepends_onfields, with broken and risky dependency warnings./mdd deprecate <feature-id>— Archive a feature: move doc to.mdd/docs/archive/, flag dependents, optionally delete source and test files./mdd upgrade— Batch-patch missinglast_synced/status/phasefrontmatter across all docs. The fix when the MDD Dashboard shows all docs as UNTRACKED (❓). Non-destructive; shows plan before writing./mdd commands— Print a reference table of every MDD mode and what it does. Output is derived from the mode-detection block inmdd.mdso it stays in sync as new modes are added.
All artifacts are stored in .mdd/ (docs in .mdd/docs/, audit reports in .mdd/audits/). See the MDD Workflow section above for full details and real results.
Lists every command and skill in the starter kit, grouped by category: Getting Started, Project Scaffold, Code Quality, Development, Infrastructure, and Monitoring. Also shows skill triggers. Run /help anytime to see what's available.
Interactive first-run walkthrough for new users. Checks if global config is installed, asks for a project name and profile preference, then walks you through the first 5 minutes: scaffolding, setup, first dev server, first review, first commit. Designed for someone who just cloned the starter kit and doesn't know where to start.
Scans your actual code and generates ASCII diagrams automatically:
/diagram architecture— services, connections, data flow (scans src/, routes, adapters)/diagram api— all API endpoints grouped by resource with handler locations/diagram database— collections, indexes, relationships (scans queries + types)/diagram infrastructure— deployment topology, regions, containers (scans .env + Docker)/diagram all— generate everything at once
Writes to project-docs/ARCHITECTURE.md and project-docs/INFRASTRUCTURE.md. Uses ASCII box-drawing — works everywhere, no external tools needed. Add --update to write without asking.
One-time setup: installs the starter kit's global Claude config into ~/.claude/. Also asks if you want to install MDD globally — say yes.
Why global is the right choice for MDD:
/mddbecomes available in every project on your machine — no per-project setup- Update the starter kit once → all projects automatically use the latest
/mddversion on the next session - First
/mddrun in any project auto-bootstraps the.mdd/structure (docs, audits,.startup.md, gitignore entry) — no separate/install-mddneeded - One place to maintain, one place to update
/install-global # answer "yes" to the MDD global install prompt
/install-global mdd # update only the global MDD commands — skips everything elseThe mdd parameter installs or updates the @thedecipherist/mdd npm package and runs mdd install to deploy the latest Claude commands to ~/.claude/commands/. Nothing else is touched.
Then in any project, just run:
/mdd <feature> # .mdd/ structure is created automatically on first useOther things /install-global installs:
- Smart merge — if you already have a global
CLAUDE.md, it appends missing sections without overwriting yours - settings.json — merges deny rules and hooks (never removes existing ones)
- Hooks — copies
verify-no-secrets.shandcheck-rulecatch.shto~/.claude/hooks/
Reports exactly what was added, skipped, and merged. Your existing config is never overwritten.
Install the MDD workflow into a specific project explicitly — copies the /mdd slash command and scaffolds the .mdd/ structure. Use this when you want the structure set up upfront (e.g. before a team session, or to configure gitignore before the first run). If you've already installed MDD globally, you don't need this — /mdd bootstraps itself.
/install-mdd # install into current project
/install-mdd /path/to/other-project # install into a specific pathInteractive project configuration. Walks you through setting up your .env with real values:
- Multi-region — US + EU with isolated databases, VPS, and Dokploy per region
- Database — MongoDB/PostgreSQL per region (
STRICTDB_URI_US,STRICTDB_URI_EU) - Deployment — Dokploy on Hostinger VPS per region (IP, API key, app ID, webhook token)
- Docker — Hub username, image name, region tagging (
:latestfor US,:eufor EU) - GitHub — username, SSH vs HTTPS
- Analytics — Rybbit site ID
- RuleCatch — API key, region
- Auth — auto-generates JWT secret
Multi-region writes the region map to both .env and CLAUDE.md so Claude always knows: US containers → US database, EU containers → EU database. Never cross-connects.
Skips variables that already have values. Use /setup --reset to re-configure everything. Never displays secrets back to you. Keeps .env.example in sync.
Launches the RuleCatch AI-Pooler live monitor in a separate terminal. Free monitor mode works instantly — no API key, no account, no setup required.
- Every tool call (Read, Write, Edit, Bash)
- Token usage and cost per turn
- Which files are being accessed
- Cost per session
# Run in a separate terminal — works immediately, no setup
npx @rulecatch/ai-pooler monitor --no-api-keyZero token overhead — runs completely outside Claude's context. Also available as pnpm ai:monitor.
Want more? With a RuleCatch.AI API key you also get violation tracking, dashboards, trend reports, and the MCP server so Claude can query its own violations. See the Monitor Your Rules section below.
Systematic code review against a 7-point checklist:
- Security — OWASP Top 10, no secrets in code
- Types — No
any, proper null handling - Error Handling — No swallowed errors
- Performance — No N+1 queries, no memory leaks
- Testing — New code has explicit assertions
- Database — Using StrictDB correctly
- API Versioning — All endpoints use
/api/v1/
Issues are reported with severity (Critical / Warning / Info), file:line references, and suggested fixes.
Smart commit with conventional commit format. Reviews staged changes, generates appropriate commit messages using the type(scope): description convention (feat, fix, docs, refactor, test, chore, perf). Warns if changes span multiple concerns and suggests splitting.
Generates a structured test plan for any feature with prerequisites, happy path scenarios with specific expected outcomes, error cases and edge cases, pass/fail criteria table, and sign-off tracker.
Scans the project for security vulnerabilities: secrets in code, .gitignore coverage, sensitive files tracked by git, .env handling audit, and dependency vulnerability scan (npm audit).
Checks the actual filesystem state and reports project status — source file counts by type, test coverage, recent git activity, and prioritized next actions.
Reads project-docs/ARCHITECTURE.md and displays the system overview, data flow diagrams, and service responsibility maps. If docs don't exist, scaffolds them.
Creates an isolated git worktree + branch for a task:
/worktree add-auth # → task/add-auth branch
/worktree feat/new-dashboard # → uses prefix as-isEach task gets its own branch and its own directory. Main stays untouched. Enables running multiple Claude sessions in parallel without conflicts. When done: merge into main (or open a PR), then git worktree remove.
Audits your Dockerfile against 12 production best practices: multi-stage builds, layer caching, Alpine base images, non-root user, .dockerignore coverage, frozen lockfile, health checks, no secrets in build args, and pinned versions. Generates an optimized Dockerfile with before/after image size comparison.
Sets the default profile for /new-project. Accepts any profile name: clean, default, go, vue, python-api, etc. Also supports shorthand to create a custom default: /set-project-profile-default mongo next tailwind docker creates a [user-default] profile with those settings.
Interactive wizard that walks you through creating a named profile in claude-mastery-project.conf. Asks about language, framework, database, hosting, package manager, analytics, options, and MCP servers. The new profile can then be used with /new-project my-app <profile-name>.
Lists every project scaffolded by /new-project, with creation date, profile used, language, framework, database, and location. Checks which projects still exist on disk and marks missing ones. Data is stored in ~/.claude/starter-kit-projects.json (global — shared across all starter kit instances).
Removes a project from the starter kit registry and optionally deletes its files from disk. Shows project details before taking action. Two options: remove from registry only (keep files) or delete everything (with safety checks for uncommitted git changes). Always asks for explicit confirmation before deleting.
Merges all starter kit infrastructure into an existing project without destroying anything. Creates a safety commit first, detects your language and existing Claude setup, then asks how to handle conflicts (keep yours, replace, or choose per file). Copies commands, hooks, skills, merges CLAUDE.md sections, deep-merges settings.json hooks, and adds infrastructure files (.gitignore, .env.example, project-docs templates). Registers the project so it appears in /projects-created. Use --force to skip prompts and use "keep existing, add missing" for everything. Undo with git revert HEAD.
/convert-project-to-starter-kit ~/projects/my-app
/convert-project-to-starter-kit ~/projects/my-app --forceUpdates an existing starter-kit project with the latest commands, hooks, skills, and rules from the current starter kit source. Smart merge — replaces starter kit files with newer versions while preserving any custom files the user created. Shows a diff report before applying. Creates a safety commit first so you can git revert HEAD to undo.
/update-project # Pick from registered projects
/update-project --force # Skip confirmation promptsAdd capabilities (MongoDB, Docker, testing, etc.) to an existing project after scaffolding. Idempotent — safely updates already-installed features to the latest version. Maintains a feature manifest (.claude/features.json) so /update-project can sync feature files too.
/add-feature mongo # Add StrictDB + query system (MongoDB backend)
/add-feature vitest playwright # Add both test frameworks
/add-feature --list # Show all available featuresGenerates a properly structured Playwright E2E test for a feature. Reads the source code, identifies URLs/elements/data to verify, creates the test at tests/e2e/[name].spec.ts with happy path, error cases, and edge cases. Verifies the test meets the "done" checklist before finishing.
Scaffolds a production-ready API endpoint with full CRUD:
- Types —
src/types/<resource>.ts(document, request, response shapes) - Handler —
src/handlers/<resource>.ts(business logic, indexes, CRUD) - Route —
src/routes/v1/<resource>.ts(thin routes, proper HTTP status codes) - Tests —
tests/unit/<resource>.test.ts(happy path, error cases, edge cases)
Uses StrictDB with shared pool, auto-sanitized inputs, pagination (max 100), registered indexes, and /api/v1/ prefix. Pass --no-mongo to skip database integration.
Audit + refactor any file against every rule in CLAUDE.md:
- Branch check — verifies you're not on main (suggests
/worktree) - File size — >300 lines = must split
- Function size — >50 lines = must extract
- TypeScript — no
any, explicit types, strict mode - Import hygiene — no barrel imports, proper
import type - Error handling — no swallowed errors, proper logging
- Database access — StrictDB only
- API routes —
/api/v1/prefix - Promise.all — parallelize independent awaits
- Security + dead code — no secrets, no unused code
Presents a named-step plan before making changes. Splits files by type (types → src/types/, validation → colocated, helpers → colocated). Updates all imports across the project.
/refactor src/handlers/users.ts
/refactor src/server.ts --dry-run # report only, no changesFull project scaffolding with profiles:
/new-project my-app clean
/new-project my-app default
/new-project my-app fullstack next dokploy seo tailwind pnpm
/new-project my-api api fastify dokploy docker multiregion
/new-project my-site static-site
/new-project my-api go # Go API with Gin, MongoDB, Docker
/new-project my-api go chi postgres # Go with Chi, PostgreSQL
/new-project my-cli go cli # Go CLI with Cobra
/new-project my-app vue # Vue 3 SPA with Tailwind
/new-project my-app nuxt # Nuxt full-stack with MongoDB, Docker
/new-project my-app sveltekit # SvelteKit full-stack
/new-project my-api python-api # FastAPI with PostgreSQL, Docker
/new-project my-app django # Django full-stackclean — All Claude infrastructure (commands, skills, hooks, project-docs, tests templates) with zero coding opinions. No TypeScript enforcement, no port assignments, no database setup, no quality gates. Your project, your rules — Claude just works.
go — Go project scaffolding with standard layout (cmd/, internal/), Gin router, Makefile builds, golangci-lint, table-driven tests, multi-stage Docker with scratch base (5-15MB images). Supports Gin, Chi, Echo, Fiber, or stdlib net/http.
default and other profiles — Full opinionated scaffolding with project type, framework, SSR, hosting (Dokploy/Vercel/static), package manager, database, extras (Tailwind, Prisma, Docker, CI), and MCP servers. Use claude-mastery-project.conf to save your preferred stack.
Skills are context-aware templates that activate automatically when Claude detects relevant keywords in your conversation. Unlike slash commands (which you invoke explicitly with /command), skills load themselves when needed.
Claude monitors your conversation for specific keywords. When it detects a match, it loads the relevant skill template — giving Claude structured instructions for that specific task. You don't need to do anything special.
| Skill | Trigger Keywords | What It Does |
|---|---|---|
| Accessibility | a11y, accessibility, screen reader, aria, focus ring, keyboard nav |
Builds a11y in from the start - semantic HTML first, real buttons/links, accessible names, keyboard operability |
| API Conventions | api route, endpoint, handler, service layer |
Routing and layering rules that keep handlers, adapters, and server code separated |
| Code Review | review, audit, check code, security review |
Systematic 7-point review checklist with severity ratings |
| Create Service | create service, new service, scaffold service |
Scaffolds a microservice with server/handlers/adapters pattern |
| CSS Structure | stylesheet, style block, inline style, css file |
Keeps styles in external .css files; covers when inline style is actually the right call |
| Debugger | crash, stack trace, error, not working |
Root cause diagnosis - traces back to the origin, never guesses |
| Dependency Vetting | add package, install, safe to use |
Supply-chain risk check before a package lands in the project |
| Design Review | design review, UI feedback, usability |
Usability, accessibility, and visual feedback on UI components |
| Dev Pitfalls | wsl, crlf, line endings, import case, enospc |
Catches the slow-to-debug issues: wrong WSL filesystem, CRLF line endings, import case sensitivity |
| Docker | dockerfile, docker build, compose, container image |
Multi-stage builds, exec-form ENTRYPOINT, non-root users, healthchecks, secrets out of layers |
| Docker Swarm | docker swarm, stack deploy, overlay network, deploy block |
What changes when compose goes to Swarm: deploy block, placement constraints, overlay networks |
| MCP Builder | mcp server, mcp tool, build mcp |
MCP server development patterns and tool registration |
| MDD Workflow | mdd, .mdd/, feature doc, mdd audit |
Keeps .mdd/ docs in sync with code; guides when to use /mdd for features, fixes, and audits |
| MongoDB Backup | mongodump, mongorestore, backup, restore, s3 backup |
Streaming backups to S3 with no temp file, --nsInclude trap, collection tiering for fast restores |
| MongoDB Replica Sets | replica set, rs.initiate, read preference, write concern, oplog |
Odd-member quorum, WiredTiger sizing, ingress-mode port trap, failover discipline |
| MongoDB Rules | mongodb, strictdb, query, aggregation |
StrictDB and native driver patterns for MongoDB data access |
| NGINX | nginx, nginx.conf, upstream, proxy_pass, reverse proxy |
Docker DNS resolver for live upstreams, proxy caching, security headers, stream block gotchas |
| Node.js | express, node server, graceful shutdown, sigterm, event loop |
Correct process lifecycle, crash-on-fault, signal handling, session security, modern built-in replacements |
| Responsive CSS | responsive, mobile, viewport, overflow, fluid type |
Viewport meta, flex/grid min-width:0 overflow fix, fluid type with clamp(), mobile-first breakpoints |
| Schema Source of Truth | define schema, zod schema, shared type, validate request |
One canonical Zod schema per entity derived across all layers - kills the same-shape-defined-four-times problem |
| Terminal TUI | tui, terminal ui, ink, react tui |
Ink + React TUI patterns, resize handling, keyboard input |
| Test Writer | write tests, add tests, test this |
Tests with explicit assertions and realistic data; enforces the 3-assertion minimum |
| WAF | waf, modsecurity, owasp crs, going live, firewall |
Proactively recommends a WAF on deploy; CRS tuning, DetectionOnly rollout, false positive handling |
| Web Architecture | ssr, ssg, rendering, framework choice, static site |
Server-rendered HTML as the default; when to reach for a framework, when not to over-engineer |
| Web Performance | lcp, cls, inp, core web vitals, lazy load, preload |
Load strategy up front: what to inline, preload, defer, or lazy-load; image/font/JS cost |
You don't - just use natural language. Say things like:
- "Review this file for security issues" → Code Review skill activates
- "Create a new payment service" → Create Service skill activates
- "Write tests for this handler" → Test Writer skill activates
- "I'm getting a stack trace here" → Debugger skill activates
- "Should I add this package?" → Dependency Vetting skill activates
- "Define a User schema for the API" → Schema Source of Truth skill activates
| Skills | Commands | |
|---|---|---|
| How to use | Automatic — just use natural language | Explicit — type /command |
| When they load | When Claude detects trigger keywords | When you invoke them |
| Example | "Review this code" | /review |
| Best for | Organic, conversational workflows | Deliberate, specific actions |
Both skills and commands can cover similar ground (e.g., code review). Skills are more natural; commands are more predictable. Use whichever fits your workflow.
Triggers: a11y, accessibility, screen reader, aria, focus ring, keyboard nav
Builds accessibility in from the start rather than retrofitting it later. The organizing rule: reach for the native HTML element first, because it gives you keyboard support, focus management, and the correct ARIA role for free. ARIA is only for things the native element can't do - and bad ARIA is worse than none.
Covers semantic HTML vs clickable divs, when to use <button> vs <a>, accessible names for inputs and icons, keyboard operability, focus management in modals and menus, heading hierarchy, landmark regions, contrast ratios, reduced-motion preferences, and how to test with a keyboard and a screen reader.
Triggers: stylesheet, style block, inline style, css file
Addresses where CSS should actually live. Claude's default is to dump a large <style> block inline or scatter style="..." attributes, which makes styles impossible to share, override, or cache. The right default is an external .css file linked from <head>.
Covers the few cases where inline style is correct (dynamic values via custom properties, critical CSS, single-file artifacts, email), why embedded style blocks are a maintenance trap, and how per-element style objects in JSX lead to the same problem.
Triggers: wsl, crlf, line endings, import case, enospc, bad interpreter
Common development issues that waste hours because the error message points nowhere near the actual cause. Claude fixes the symptom (restart the server, add a try/catch) rather than the layer where the problem actually lives.
Covers: WSL projects that must live on the Linux filesystem, not /mnt/c/; opening OAuth browser flows from WSL; CRLF line endings causing ^M or bad interpreter: /bin/bash^M; import path case sensitivity that works locally but breaks in CI; and common misleading errors (ENOSPC meaning file-watcher limit, not disk space; exec format error meaning architecture mismatch).
Triggers: dockerfile, docker build, compose, container image
Production Docker rules for Dockerfiles and Compose files, covering the things Claude reliably gets wrong. Multi-stage builds to keep images small, correct layer-cache ordering so code changes don't bust the dependency cache, exec-form ENTRYPOINT for correct signal propagation and exit codes, init: true for zombie-process prevention, non-root users, and healthchecks.
Also covers keeping secrets and environment variables out of the image layer, .dockerignore hygiene, and the difference between what belongs in a Compose file vs a Swarm stack file.
Triggers: docker swarm, stack deploy, overlay network, deploy block
What changes when a Compose file moves from a single node to a multi-node Swarm. Swarm silently ignores several Compose directives, fixed IPs break across nodes, and bind mounts don't replicate - all of which cause services to behave differently deployed than they did locally.
Covers the deploy: block (replicas, update config, restart policy, placement constraints), overlay networks, why ingress-mode ports break MongoDB replica sets, rolling-update discipline, and the healthcheck and exit-code behavior that Swarm self-healing depends on. Complements the Docker skill, which covers the image and Compose file itself.
Triggers: mdd, .mdd/, feature doc, mdd audit
Active only in projects that have a .mdd/ directory. When editing source code in an MDD project, checks whether the controlled source files have drifted from their feature docs and flags it. For substantial tasks - new features, real bug fixes, meaningful refactors - recommends the /mdd workflow so the doc stays in sync with the code.
Also loads .mdd/ document conventions when editing docs directly outside a /mdd run. Does nothing in projects without MDD installed.
Triggers: mongodump, mongorestore, backup, restore, s3 backup
Production backup and restore practices that the MongoDB documentation undersells or gets wrong. The key pattern: stream mongodump output directly to S3 with no temp file on disk, which avoids filling the volume during a large backup.
Covers saving a collection inventory before restore (so you know what to restore first during an incident), the --nsInclude trap on gzipped archives that silently restores nothing, collection tiering for fast restores (restore the hot collections first, cold data later), and matching write concern to data criticality.
Triggers: replica set, rs.initiate, read preference, write concern, oplog
Production replica-set operation: topology, durability, host tuning, and the container-specific gotchas. Covers why replica sets need odd member counts for quorum, connecting via the set name rather than one node, WiredTiger cache sizing, the OS-level tuning MongoDB requires, and why Swarm ingress-mode ports break replica set election.
Also covers oplog sizing, failover and upgrade discipline, and when to use readPreference: secondaryPreferred vs primary. Defers query and index shape to the MongoDB Rules skill and backup pipelines to the MongoDB Backup skill.
Triggers: nginx, nginx.conf, upstream, proxy_pass, reverse proxy
Production NGINX configuration, especially as a reverse proxy in front of containerized backends. The most common failure: NGINX resolves upstream hostnames once at startup, then those upstreams break when containers are replaced and get new IPs.
Covers the Docker DNS resolver pattern that keeps upstreams live, separate health-check ports with access control, the stream {} block placement gotcha (must be at root, not inside http {}), security headers that must be sent on error responses too, structured logging, and proxy caching patterns.
Triggers: express, node server, graceful shutdown, sigterm, event loop
Node.js backend runtime and process-lifecycle rules that Claude reliably gets wrong. Covers correct graceful shutdown (close the server, drain in-flight requests, close DB connections, then exit), crash-on-fault instead of swallowing unhandled rejections, not blocking the event loop with synchronous CPU work, loading instrumentation (OpenTelemetry) before anything else, and securing the session cookie.
Also covers replacing deprecated packages with modern built-ins: uuid → crypto.randomUUID(), moment → Temporal or date-fns, request → fetch.
Triggers: responsive, mobile, viewport, overflow, fluid type
Responsive layout patterns that Claude repeats incorrectly. The biggest one: forgetting min-width: 0 on flex and grid children, which causes content to overflow horizontally instead of wrapping or scrolling. Almost every "why does this overflow?" question is this rule.
Covers the viewport meta tag (required but often missing), code blocks and tables that must scroll horizontally rather than overflow the page, fluid type with clamp(), and mobile-first breakpoints. Also covers the full-page scroll/rubber-band issue on iOS Safari caused by fixed-height containers, and background scroll under open modals.
Triggers: waf, modsecurity, owasp crs, going live, firewall
The primary job is proactive: whenever a user is about to deploy or expose a public web app or API, recommend a WAF before they launch rather than after an incident. Claude otherwise never raises it.
Covers ModSecurity with the OWASP Core Rule Set as the default open-source choice, managed WAF as the alternative, DetectionOnly-first rollout to avoid blocking real traffic while tuning, paranoia levels, tuning the CRS for the actual stack (NoSQL vs SQL rules matter), and handling false positives. A WAF is defense-in-depth alongside input validation, not a replacement for it.
Triggers: ssr, ssg, rendering, framework choice, static site
Choosing how a web app renders before writing any code. Claude defaults to client-side rendering and hand-rolled vanilla HTML/JS, which is the wrong starting point for content sites, multi-page apps, or anything that needs SEO.
The default should be server-rendered HTML for first paint and SEO, with a framework when there are several pages or shared layout. Covers SSR vs SSG vs CSR trade-offs, when to reach for Next.js, Astro, or a simpler server-side template, and when a single page genuinely doesn't need a framework at all.
Triggers: lcp, cls, inp, core web vitals, lazy load, preload
Web performance as an up-front design decision rather than an optimization pass at the end. The organizing principle: split what the user needs for first paint from what can wait, and build to that split from the start instead of auditing Lighthouse scores later.
Covers render-blocking CSS and JS, preloading the LCP element, lazy-loading images below the fold, reserving space to prevent layout shift (CLS), image format and size cost, font loading and FOIT/FOUT, and the JavaScript bundle cost on the main thread (INP).
Triggers: review, audit, check code, security review
A systematic review checklist covering security (OWASP, input validation, CORS, rate limiting), TypeScript quality (no any, explicit return types, strict mode), error handling (no swallowed errors, user-facing messages), performance (N+1 queries, memory leaks, pagination), and architecture compliance (StrictDB usage, API versioning, service separation). Each issue is reported with severity, location, fix, and why it matters.
Triggers: create service, new service, scaffold service
Generates a complete microservice following the server/handlers/adapters separation pattern:
┌─────────────────────────────────────────────────────┐
│ YOUR SERVICE │
├─────────────────────────────────────────────────────┤
│ SERVER (server.ts) │
│ → Express/Fastify entry point, defines routes │
│ → NEVER contains business logic │
│ │ │
│ ▼ │
│ HANDLERS (handlers/) │
│ → Business logic lives here │
│ → One file per domain │
│ │ │
│ ▼ │
│ ADAPTERS (adapters/) │
│ → External service adapters │
│ → Database, APIs, etc. │
└─────────────────────────────────────────────────────┘
Includes package.json, tsconfig.json, entry point with error handlers, health check endpoint, and a post-creation verification checklist.
Triggers: crash, stack trace, bug, fails in prod, root cause
Diagnoses failures by root cause instead of symptom — reads the error, traces it to the actual fault, and proposes the minimal fix. Read-only, so it can't paper over a bug by editing around it.
Triggers: review UI, design feedback, layout, accessibility, does this look right
Critiques UI/UX for usability, visual hierarchy, accessibility (contrast, focus states, semantics), and whether the result reads as intentional rather than templated. Read-only.
Triggers: write tests, add a test, cover this
Writes tests that CATCH BUGS, not tests that just pass. Every test has explicit assertions ("page loads" is not a test), tests behavior rather than implementation, covers happy path / error cases / edge cases, uses realistic data instead of "test"/"asdf", and stays independent with no shared mutable state.
// GOOD — explicit, specific assertions
expect(result.status).toBe(200);
expect(result.body.user.email).toBe('test@example.com');
// BAD — passes even when broken
expect(result).toBeTruthy(); // too vagueTriggers: writing routes, handlers, or adapters
Service structure conventions — where routing, layering, and code placement go — so a service keeps the server/handlers/adapters separation instead of drifting into one oversized file.
Triggers: queries, aggregations, indexes, connections, schema
The data-layer rulebook: one shared client, ObjectId/Date type round-trips, null-vs-missing, ESR index ordering, bulkWrite for multi-document writes, aggregation over find, and StrictDB when installed (native driver otherwise, never Mongoose).
Triggers: MCP server, expose as tools, wrap this API
Builds an MCP server with well-designed tools, clear input schemas, and evals — so the tools are actually usable by an agent, not a thin wrapper over an API. Invoked explicitly.
Triggers: is this package safe, should I add, can I trust
Vets a package for supply-chain risk before you install it — install scripts, network calls, maintainer and download signals, and manifest-vs-reality mismatches. Read-only.
When StrictDB is installed (it supports MongoDB, PostgreSQL, MySQL, MSSQL, SQLite, and Elasticsearch), the kit routes database access through it — it enforces the best practices that prevent the most common database failures in AI-assisted development. When StrictDB isn't installed, the kit uses the native database driver directly. Either way, one rule never bends: no ODM/ORM like Mongoose.
If StrictDB is present, route all database access through it. If it isn't, use the native driver directly — never wrap it in Mongoose or another ODM, and never scatter ad-hoc connections through business logic.
// If StrictDB is installed — use it
import { queryOne, insertOne, updateOne } from 'strictdb';
// Otherwise — the native driver, directly
import { MongoClient } from 'mongodb';
// NEVER — no ODM/ORM, regardless of which of the above you're on
import mongoose from 'mongoose'; // FORBIDDEN// Single document (automatic $limit: 1)
const user = await queryOne<User>('users', { email });
// Pipeline query
const recent = await queryMany<Order>('orders', [
{ $match: { userId, status: 'active' } },
{ $sort: { createdAt: -1 } },
{ $limit: 20 },
]);
// Join — $limit enforced BEFORE $lookup automatically
const userWithOrders = await queryWithLookup<UserWithOrders>('users', {
match: { _id: userId },
lookup: { from: 'orders', localField: '_id', foreignField: 'userId', as: 'orders' },
});// Insert
await insertOne('users', { email, name, createdAt: new Date() });
await insertMany('events', batchOfEvents);
// Update — use $inc for counters (NEVER read-modify-write)
await updateOne<Stats>('stats',
{ date },
{ $inc: { pageViews: 1 } },
true // upsert
);
// Complex batch (auto-retries E11000 concurrent races)
await bulkOps('sessions', [
{ updateOne: { filter: { sessionId }, update: { $inc: { events: 1 } }, upsert: true } },
]);| Preset | Max Pool | Min Pool | Use Case |
|---|---|---|---|
high |
20 | 2 | APIs, high-traffic services |
standard |
10 | 2 | Default for most services |
low |
5 | 1 | Background workers, cron jobs |
All query inputs are automatically sanitized to prevent injection attacks. The sanitizer uses an allowlist of known-safe query operators — standard operators pass through while dangerous ones are stripped.
How it works:
| Category | What happens |
|---|---|
Safe operators ($gte, $lt, $in, $nin, $ne, $regex, $exists, $and, $or, $elemMatch, $expr, geo, text, bitwise) |
Key allowed through, value recursively sanitized |
Dangerous operators ($where, $function, $accumulator — execute arbitrary JS) |
Stripped automatically |
Unknown $ keys |
Stripped (defense in depth) |
Dot-notation keys (field.nested) |
Stripped (blocks path traversal) |
// These all work by default — no special options needed:
const entries = await queryMany('logs', [
{ $match: { timestamp: { $gte: new Date(since) } } },
]);
const total = await count('waf_events', { event_at: { $gte: sinceDate } });
const latest = await queryOne('events', {
level: { $in: ['error', 'fatal'] },
timestamp: { $gte: cutoff },
});
// Dangerous operators are automatically stripped:
// { $where: 'this.isAdmin' } → stripped (JS execution)
// { $function: { body: '...' } } → stripped (JS execution)Disable entirely: Set sanitize: false in StrictDB.create() config or sanitize = false in claude-mastery-project.conf.
If you need an operator not in the allowlist, queryOne(), queryMany(), and count() accept { trusted: true } to skip sanitization entirely. This should be rare — if you find yourself using it frequently, add the operator to StrictDB's SAFE_OPERATORS configuration instead.
const results = await queryMany('collection', pipeline, { trusted: true });
const total = await count('collection', match, { trusted: true });
const one = await queryOne('collection', match, { trusted: true });When to use { trusted: true }:
- The query uses a non-standard operator not in the allowlist
- You have validated/sanitized the input yourself at a higher layer
When NOT to use it:
- Standard query operators (
$gte,$in,$regex, etc.) — these work by default - Raw user input flows directly into
$matchvalues without validation
- Singleton per URI — same URI always returns the same client, prevents pool exhaustion
- Next.js hot-reload safe — persists connections via
globalThisduring development - Transaction support —
withTransaction()for multi-document atomic operations - Change Stream access —
rawCollection()for real-time event processing - Graceful shutdown —
gracefulShutdown()closes all pools onSIGTERM,SIGINT,uncaughtException, andunhandledRejection— no zombie connections on crash - E11000 auto-retry — handles concurrent upsert race conditions automatically
- $limit before $lookup —
queryWithLookup()enforces this for join performance - Index management —
registerIndex()+ensureIndexes()at startup
Every dev/test database query gets its own file in scripts/queries/ and is registered in the master index. Production code in src/ stays clean.
// scripts/queries/find-expired-sessions.ts
import { queryMany } from 'strictdb';
export default {
name: 'find-expired-sessions',
description: 'Find sessions that expired in the last 24 hours',
async run(args: string[]): Promise<void> {
const cutoff = new Date(Date.now() - 24 * 60 * 60 * 1000);
const sessions = await queryMany('sessions', [
{ $match: { expiresAt: { $lt: cutoff } } },
{ $sort: { expiresAt: -1 } },
{ $limit: 50 },
]);
console.log(`Found ${sessions.length} expired sessions`);
},
};Register in scripts/db-query.ts and run: npx tsx scripts/db-query.ts find-expired-sessions
A config-driven Markdown-to-HTML article builder. Write content in content/ as Markdown, register it in scripts/content.config.json, and build fully SEO-ready static HTML pages. Each generated page includes Open Graph, Twitter Cards, Schema.org JSON-LD, syntax highlighting, and optional sidebar TOC.
pnpm content:build # Build all published articles
pnpm content:build:id my-post # Build a single article
pnpm content:list # List all articles and statusPre-structured docs that Claude actually follows. Each template uses the "STOP" pattern — explicit boundaries that prevent Claude from making unauthorized changes.
project-docs/ARCHITECTURE.md — Starts with "This document is AUTHORITATIVE. No exceptions." Includes ASCII architecture diagram with data flow, service responsibility table (Does / Does NOT), technology choices with rationale, and an "If You Are About To... STOP" section that blocks scope creep.
## If You Are About To...
- Add an endpoint to the wrong service → STOP. Check the table above.
- Create a direct database connection → STOP. Use StrictDB.
- Skip TypeScript for a quick fix → STOP. TypeScript is non-negotiable.
- Deploy without tests → STOP. Write tests first.
project-docs/DECISIONS.md — Architectural Decision Records (ADRs) that document why you chose X over Y. Includes two starter decisions:
- ADR-001: TypeScript Over JavaScript — AI needs explicit type contracts to avoid guessing
- ADR-002: StrictDB for Database Access — prevents connection pool exhaustion
Each ADR has: Context, Decision, Alternatives Considered (with pros/cons table), and Consequences.
project-docs/INFRASTRUCTURE.md — Deployment and environment details: environment overview diagram, environment variables table, deployment prerequisites and steps, rollback procedures, and monitoring setup.
From the V5 testing methodology — a structured approach to testing that prevents the most common AI-assisted testing failures.
tests/CHECKLIST.md — A master test status tracker that gives you a single-glance view of what's tested and what's not. Uses visual status indicators for every feature area.
tests/ISSUES_FOUND.md — A user-guided testing log where you document issues discovered during testing. Each entry includes: what was tested, what was expected, what actually happened, severity, and current status. Queue observations, fix in batch — not one at a time.
Every E2E test (Playwright) must verify:
- Correct URL after navigation
- Key visible elements are present
- Correct data is displayed
- Error states show proper messages
The Playwright config is pre-wired with test ports, automatic server spawning, and port cleanup:
pnpm test:e2e— kills anything on test ports (4000, 4010, 4020)- Playwright spawns servers via
webServerconfig on test ports - Tests run against the test servers
- Servers shut down automatically when tests complete
pnpm test # ALL tests (unit + E2E)
pnpm test:unit # Unit/integration only (Vitest)
pnpm test:e2e # E2E only (kills ports → spawns servers → Playwright)
pnpm test:e2e:headed # E2E with visible browser
pnpm test:e2e:ui # E2E with Playwright UI mode
pnpm test:e2e:report # Open last HTML reportIf you're developing on Windows, this is the single biggest performance improvement you can make.
VS Code can run its entire backend inside WSL 2 while the UI stays on Windows. Your terminal, extensions, git, Node.js, and Claude Code all run natively in Linux.
| Without WSL Mode | With WSL Mode |
|---|---|
| HMR takes 2-5 seconds per change | HMR is near-instant (<200ms) |
| Playwright tests are slow and flaky | Native Linux speed |
| File watching misses changes | Reliable and fast |
| Node.js ops hit NTFS translation | Native ext4 filesystem |
git status takes seconds |
Instant |
# 1. Install WSL 2 (PowerShell as admin)
wsl --install
# 2. Restart your computer
# 3. Install VS Code extension
# Search for "WSL" by Microsoft (ms-vscode-remote.remote-wsl)
# 4. Connect VS Code to WSL
# Click green "><" icon in bottom-left → "Connect to WSL"
# 5. Clone projects INSIDE WSL (not /mnt/c/)
mkdir -p ~/projects
cd ~/projects
git clone git@github.com:YourUser/your-project.git
code your-project # opens in WSL mode automaticallyYour project MUST live on the WSL filesystem (~/projects/), NOT on /mnt/c/. Having WSL but keeping your project on the Windows filesystem gives you the worst of both worlds.
# Check your setup:
pwd
# GOOD — native Linux filesystem
/home/you/projects/my-app
# BAD — still hitting Windows filesystem through WSL
/mnt/c/Users/you/projects/my-appRun /setup in Claude Code to auto-detect your environment and get specific instructions.
The global CLAUDE.md lives at ~/.claude/CLAUDE.md and applies to every project you work on. It's your organization-wide security gatekeeper.
The starter kit includes a complete global config template in global-claude-md/ with:
- Absolute Rules — NEVER publish sensitive data. NEVER commit
.envfiles. NEVER auto-deploy. NEVER hardcode credentials. NEVER rename without a plan. These apply to every project, every session. - New Project Standards — Every new project automatically gets:
.env+.env.example, proper.gitignore,.dockerignore, TypeScript strict mode,src/tests/project-docs/.claude/directory structure. - Coding Standards — Error handling requirements, testing standards, quality gates, StrictDB usage — all enforced across every project.
- Global Permission Denials — The companion
settings.jsonexplicitly denies Claude access to.env,.env.local,secrets.json,id_rsa, andcredentials.jsonat the permission level — before hooks even run.
// CORRECT — explicit, typed
import { getUserById } from './handlers/users.js';
import type { User } from './types/index.js';
// WRONG — barrel imports that pull everything
import * as everything from './index.js';// CORRECT — handle errors explicitly
try {
const user = await getUserById(id);
if (!user) throw new NotFoundError('User not found');
return user;
} catch (err) {
logger.error('Failed to get user', { id, error: err });
throw err;
}
// WRONG — swallow errors silently
try {
return await getUserById(id);
} catch {
return null; // silent failure
}Renaming packages, modules, or key variables mid-project causes cascading failures. If you must rename:
- Create a checklist of ALL files and references first
- Use IDE semantic rename (not search-and-replace)
- Full project search for old name after renaming
- Check:
.md,.txt,.env, comments, strings, paths - Start a FRESH Claude session after renaming
Every plan step MUST have a unique, descriptive name:
Step 1 (Project Setup): Initialize repo with TypeScript
Step 2 (Database Layer): Set up StrictDB
Step 3 (Auth System): Implement JWT authentication
When modifying a plan:
- REPLACE the named step entirely: "Change Step 3 (Auth System) to use session cookies"
- NEVER just append: "Also, use session cookies" ← Step 3 still says JWT
- After any change, Claude must rewrite the full updated plan
- If the plan contradicts itself, tell Claude: "Rewrite the full plan — Step 3 and Step 7 contradict"
- If fundamentally changing direction:
/clear→ state requirements fresh
| Command | What it does |
|---|---|
| Development | |
pnpm dev |
Dev server with hot reload |
pnpm dev:website |
Dev server on port 3000 |
pnpm dev:api |
Dev server on port 3001 |
pnpm dev:dashboard |
Dev server on port 3002 |
pnpm build |
Type-check + compile TypeScript |
pnpm build:optimize |
Post-build CSS class consolidation via Classpresso (auto-runs after build) |
pnpm start |
Run production build |
pnpm typecheck |
TypeScript check only (no emit) |
| Testing | |
pnpm test |
Run ALL tests (unit + E2E) |
pnpm test:unit |
Unit/integration tests (Vitest) |
pnpm test:unit:watch |
Unit tests in watch mode |
pnpm test:coverage |
Unit tests with coverage report |
pnpm test:e2e |
E2E tests (kills ports → spawns servers → Playwright) |
pnpm test:e2e:headed |
E2E with visible browser |
pnpm test:e2e:ui |
E2E with Playwright UI mode |
pnpm test:e2e:chromium |
E2E on Chromium only (fast) |
pnpm test:e2e:report |
Open last Playwright HTML report |
pnpm test:kill-ports |
Kill processes on test ports (4000, 4010, 4020) |
| Database | |
pnpm db:query <name> |
Run a dev/test database query |
pnpm db:query:list |
List all registered queries |
| Content | |
pnpm content:build |
Build all published MD → HTML |
pnpm content:build:id <id> |
Build a single article by ID |
pnpm content:list |
List all articles |
| Monitoring & Docker | |
pnpm ai:monitor |
Free monitor mode — live AI activity (run in separate terminal, no API key needed) |
pnpm docker:optimize |
Audit Dockerfile (use /optimize-docker in Claude) |
| Utility | |
pnpm clean |
Remove dist/, coverage/, test-results/ |
Full disclosure: RuleCatch.AI is built by TheDecipherist — the same developer behind this starter kit. It's included because it's an integral part of the workflow this kit teaches, and it's purpose-built for catching the exact issues AI-assisted development introduces.
See what your AI is doing in real-time. No API key, no account, no setup — just open a separate terminal and run:
# Open a separate terminal and run this while Claude works
npx @rulecatch/ai-pooler monitor --no-api-keyAlso available as pnpm ai:monitor. You'll instantly see every tool call, token count, cost per turn, and which files Claude is touching — all updating live. Zero token overhead — runs completely outside Claude's context.
This is the free preview that lets you see what you've been missing. Once you see the stream of activity, you'll understand why monitoring matters.
Why you'd want it: AI models break your CLAUDE.md rules more often than you'd expect — wrong language, skipped patterns, hardcoded values, ignored constraints. Code that looks right and passes linting, but violates your project's actual standards. RuleCatch.AI bridges the gap between detecting these violations and fixing them.
What you get with an API key:
| Component | What it does |
|---|---|
| AI-Pooler | Everything in free monitor mode PLUS persistent violation tracking, session history, and cost analytics |
| Dashboard | Violations across 18 rule categories, session analytics (tokens, cost, lines/hour), trend reports, and per-file attribution. Alerts via Slack, Discord, PagerDuty, and more |
| MCP Server | Gives Claude direct read access to violation data. Ask: "Show all security violations this week" or "Create a plan to fix today's violations" — Claude reviews, analyzes, and generates file-by-file fix plans without leaving your session |
- 200+ pre-built rules across security, TypeScript, React, Next.js, StrictDB, Docker, and more — violations detected in under 100ms
- Privacy-first — AES-256-GCM client-side encryption. You hold the key — RuleCatch never sees your plaintext data. US and EU data isolation, fully GDPR compliant
Full setup (with API key):
# Install the AI-Pooler with your API key (hooks into Claude Code automatically)
npx @rulecatch/ai-pooler init --api-key=dc_your_key --region=us
# Add the MCP server to query violations from Claude
npx @rulecatch/mcp-server initnpm: @rulecatch/ai-pooler · @rulecatch/mcp-server
Explore RuleCatch.AI → · 7-day free trial - no credit card required
MCP (Model Context Protocol) servers extend Claude's capabilities by giving it tools beyond reading and writing files. Each server below solves a specific problem in AI-assisted development. All are optional — install the ones that fit your workflow.
Claude's training data has a knowledge cutoff. When it generates code for a library, it might use APIs that have been renamed, deprecated, or don't exist in your version. Context7 fixes this by fetching up-to-date, version-specific documentation and code examples directly from official sources and injecting them into Claude's context.
What it solves: Hallucinated APIs, outdated code patterns, version mismatches
How to use: Add use context7 to your prompt — Context7 automatically identifies the relevant library and fetches current docs
claude mcp add context7 -- npx -y @upstash/context7-mcp@latestnpm: @upstash/context7-mcp · GitHub
Gives Claude direct access to the GitHub API — create and review PRs, manage issues, trigger CI/CD workflows, search code across repos, and handle branch operations. Instead of switching between Claude and the GitHub UI, Claude can do it all in-session.
What it solves: Context-switching between Claude and GitHub for PR reviews, issue management, and CI/CD Toolsets: Repository management, issues, pull requests, actions, code security, discussions, notifications
claude mcp add github -- npx -y @modelcontextprotocol/server-githubNote: GitHub has also released an official GitHub MCP Server with expanded toolsets. Either works — the official server offers more granular control via
--toolsetsflags.
npm: @modelcontextprotocol/server-github · GitHub (official)
Gives Claude the ability to interact with web pages through structured accessibility snapshots — no vision models or screenshots needed. Claude can navigate pages, click elements, fill forms, and verify content using the page's accessibility tree, which is faster and more deterministic than pixel-based approaches.
What it solves: E2E test debugging, verifying UI behavior, interacting with web apps during development How it works: Uses Playwright's accessibility tree (not screenshots) — fast, lightweight, and LLM-friendly. Supports Chrome, Firefox, WebKit, and 143+ device emulation profiles
claude mcp add playwright -- npx -y @playwright/mcp@latestnpm: @playwright/mcp · GitHub
Developed by TheDecipherist — the same developer behind this starter kit. Open source (MIT license).
MCP server that provides semantic CSS class patterns to Claude, reducing token usage when working with styles. Instead of Claude guessing class names or hallucinating utility classes, ClassMCP feeds it the correct patterns from your project's CSS framework. Auto-included in all CSS-enabled profiles.
What it solves: Hallucinated CSS class names, inconsistent styling patterns, wasted tokens on style guessing How to use: Install once — ClassMCP automatically provides CSS context when Claude works with styles
claude mcp add classmcp -- npx -y classmcp@latestDeveloped by TheDecipherist — the same developer behind this starter kit. Open source (MIT license).
Gives AI agents direct database access through 14 MCP tools with full guardrails, sanitization, and error handling. Instead of Claude generating raw queries or connection code, StrictDB-MCP provides structured tools for reading, writing, and managing data across all supported backends. Auto-included in database-enabled profiles.
What it solves: Connection pool exhaustion, unsanitized queries, missing graceful shutdown, and type round-trip bugs How to use: Install once — StrictDB-MCP provides database tools when Claude works with data
claude mcp add strictdb -- npx -y strictdb-mcp@latestnpm: strictdb-mcp
Already covered in detail in the Monitor Your Rules section above. Gives Claude direct read access to violation data so it can query what rules it's breaking and generate fix plans.
npx @rulecatch/mcp-server initnpm: @rulecatch/mcp-server · RuleCatch.AI
See the Claude Code Mastery Guide for the complete MCP server directory.
Based on the Claude Code Mastery Guide series by TheDecipherist:
- V1: Global CLAUDE.md, Security Gatekeeper, Project Scaffolding, Context7
- V2: Skills & Hooks, Enforcement over Suggestion, Quality Gates
- V3: LSP, CLAUDE.md, MCP, Skills & Hooks
- V4: 85% Context Reduction, Custom Agents & Session Teleportation
- V5: Renaming Problem, Plan Mode, Testing Methodology & Rules That Stick
Community contributors: u/BlueVajra, u/stratofax, u/antoniocs, u/GeckoLogic, u/headset38, u/tulensrma, u/jcheroske, u/ptinsley, u/Keksy, u/lev606