The Definitive Starting Point
for Claude Code Projects

What's Included

Everything you need to start a Claude Code project the right way — security, automation, documentation, and testing all pre-configured.

MDD Workflow STANDALONE

Manual-First Development — the built-in methodology that turns Claude Code from a code generator into a development partner. Every feature starts with documentation. Every fix starts with an audit.

What is MDD?

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.

The Workflow

Usage

One command, fifteen modes:

# Build a new feature (Analyze → Document → Test skeletons → Plan → Implement → Verify)
/mdd 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 — includes lightweight drift summary
/mdd status

# Detect doc drift: source files changed outside MDD since last sync
/mdd scan

# Update an existing feature doc after code changed
/mdd update 04

# Generate docs from code, or regenerate + compare an existing doc
/mdd reverse-engineer src/handlers/payments.ts
/mdd reverse-engineer 07

# Show ASCII dependency graph with broken/risky dep warnings
/mdd graph

# Archive a deprecated feature cleanly
/mdd deprecate 03

# Fix all UNTRACKED docs in one pass (missing last_synced/status/phase)
/mdd upgrade

# ── Initiative / Wave Planning (NEW) ──────────────────────────────────────────

# Create an initiative (groups related waves into one roadmap item)
/mdd plan-initiative "auth system"             # guided mode
/mdd plan-initiative "auth system" --template  # write raw markdown yourself

# Add a wave (a phase of work with a concrete demo state)
/mdd plan-wave auth-system "Auth Foundation"

# Execute a wave — turns planned features into MDD docs
/mdd plan-execute auth-system-wave-1

# Re-stamp waves after editing the parent initiative
/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 planned work
/mdd plan-cancel-initiative auth-system

# Show a reference table of every /mdd mode and what it does
/mdd commands

Build Mode — New Features

When you run /mdd <feature description>, Claude follows a structured 7-phase process:

1. Phase 1 — Understand — Reads your architecture, existing docs, asks all questions upfront
2. Phase 2 — Analyze — Data Flow & Impact Analysis (mandatory gate): reads the existing code the feature will touch, traces every data value end-to-end (backend → API → frontend → UI transformation), checks for parallel computations of the same concept, greps for all usages of modified endpoints, and presents findings before documentation begins. Skipped automatically on greenfield projects (<5 source files, no existing MDD docs).
3. Phase 3 — Document — Creates a numbered MDD doc in .mdd/docs/ with full YAML frontmatter including a data_flow: field pointing to the Phase 2 analysis
4. Phase 4 — Test Skeletons + Red Gate — Generates failing tests from the documentation (Doc → Test → Code). Unit and E2E skeletons generated in parallel when both are needed. Red Gate then runs the new test files to confirm every skeleton actually fails — any skeleton that passes vacuously (no real assertion) or is already satisfied by pre-existing code is fixed before implementation begins.
5. Phase 5 — Plan — Presents the build plan as commit-worthy blocks: each block has a runnable end-state, a conventional commit scope, a verification command, and a handoff contract. Independent blocks are annotated for parallel execution after a file-overlap and type-dependency gate. Simple features (<3 files, no API, no DB) keep the flat step format.
6. Phase 6 — Implement + Green Gate — Executes blocks in dependency-layer order. Parallel blocks launch 2 agents simultaneously with self-contained prompts; a typecheck runs after each parallel batch before the next layer starts. Each block runs a Green Gate: a 5-iteration diagnosis-first loop. Every iteration requires stating the exact root cause and one targeted fix before applying it. At iteration 5, the loop stops and reports to the user — no blind retrying. Regression check runs after each block goes green.
7. Phase 7 — Verify + Integration Gate — Phase 7a: full test suite + typecheck. Phase 7b: Integration Gate verifies real behavior (real HTTP calls, real DB writes, real browser rendering — feature-type-aware checklist). Default stance on any anomaly: “my code is wrong until proven otherwise” — read logs, run a minimal probe, form a specific hypothesis before accepting an external blocker. Phase 7c: reports ✅ MDD Complete if verified, or ⏸ MDD Blocked with a concrete next step if an external condition prevented verification.

Tests are generated before code. They define the finish line. If a test fails, the implementation gets fixed — not the test. The Red Gate ensures the finish line is actually a finish line.

Why Phase 2 matters: In a maturing project, the most common class of bug isn’t in the new code — it’s in the assumption that existing data is correct and consistent. An AI sees projectedProgress: number on a type and assumes it’s ready to use, without tracing how that value was computed. Phase 2 forces that trace to happen before a single line of documentation is written, catching divergent parallel computations before they become UI bugs that take 3 sessions to debug.

Audit Mode — Existing Code

When you run /mdd audit, Claude runs a complete security and quality audit:

1. Scope — Reads all .mdd/docs/ files, builds the feature map
2. Read + Notes — Parallelized: features batched across up to 3 parallel Explore agents, each reading assigned source files and returning structured notes; main conversation is single writer. Single-feature audits stay sequential. Notes written to disk so findings survive context compaction.
3. Analyze — Reads only the notes (not source code again), produces findings report
4. Present — Shows top issues with severity, estimated fix time, asks what to fix
5. Fix — Applies fixes from the report, writes tests, updates documentation

More Modes — Drift Detection, Doc Lifecycle & Planning

• /mdd task <description> — Task mode. Identical to Build mode, but stamps the resulting doc with type: task — frozen after completion and permanently excluded from drift detection. Use for one-off work (investigations, refactors, tooling sessions) that is done-and-finished by definition. Task docs appear in a separate frozen section in /mdd scan and are counted separately in /mdd status.
• /mdd scan — Detects documentation drift. Parallelized: a single Explore agent runs all git log --after="<last_synced>" checks in one pass and returns a classification table, eliminating the sequential bottleneck on large feature sets. Reports ✅ in sync / ⚠️ drifted / ❌ broken / ❓ untracked. Task docs (type: task) are excluded from drift checks and shown in a separate frozen section. Also checks for stale waves (wave initiativeVersion out of sync with parent initiative). The fix for drift is /mdd update.
• /mdd update <feature-id> — Re-syncs an existing feature doc after code has changed. Diffs code vs doc, presents what changed, rewrites only the affected sections, appends new test skeletons for new behaviors, and updates last_synced in frontmatter.
• /mdd reverse-engineer [path|id] — Generates MDD docs from existing code. Works on undocumented files (new doc) or existing docs (regenerate + compare). Parallelized for multi-file scope: ≤3 files read in main conversation; 4+ files batched across up to 3 Explore agents returning structured inference output (purpose, models, routes, rules, edge cases), synthesized into the doc draft. In regenerate mode, shows old vs new side-by-side so you can merge rather than overwrite.
• /mdd graph — Renders an ASCII dependency map from depends_on fields. Flags broken dependencies (deprecated features still referenced), risky dependencies (complete features depending on draft/in-progress ones), and orphans. When .mdd/initiatives/ exists, also renders an initiative → wave → feature hierarchy tree with progress indicators and broken doc-path warnings.
• /mdd deprecate <feature-id> — Retires a feature: sets status: deprecated, moves doc to .mdd/docs/archive/, adds known-issue warnings to all dependents, and optionally deletes source and test files (asks separately for each).
• /mdd upgrade — Batch-patches missing last_synced, status, and phase frontmatter fields across all .mdd/docs/ files. Non-destructive — existing fields are never overwritten. last_synced is inferred from git log on each doc file (preserving actual history, not defaulting to today). Shows a full plan before writing. Run this once if the MDD Dashboard shows all docs as UNTRACKED (❓) — it converts them all to IN SYNC in a single pass.
• /mdd commands — Prints a reference table of every MDD mode and what it does. Output is derived from the mode-detection block in mdd.md at runtime, so it stays in sync automatically as new modes are added — nothing is hardcoded.
• MDD versioning — Every file created or updated by MDD is stamped with mdd_version: N in its frontmatter, matching the version declared in mdd.md. /mdd status shows a breakdown of files by version so you can see at a glance what’s out of sync. /install-mdd and /install-global mdd compare mdd_version between source and installed file before overwriting — no silent updates. Files without mdd_version (created before versioning) are treated as version 0 and flagged as outdated.

Initiative & Wave Planning NEW

MDD Waves adds a three-level planning hierarchy on top of feature docs: Initiatives → Waves → Feature docs. An initiative is a roadmap item (e.g., “Auth System”); a wave is a phase of that initiative with a concrete demo state; feature docs are the individual MDD docs built by /mdd plan-execute.

• /mdd plan-initiative <title> — Creates a new initiative in .mdd/initiatives/. Guided mode interviews you about goals, target audience, and open product questions. --template flag skips the interview and writes the raw markdown file for you to fill in. Collision-checks slugs against existing initiatives and blocks if active wave docs exist for that slug.
• /mdd plan-wave <initiative-id> <wave-title> — Adds a wave to an existing initiative. Captures the demo state (what a user can do when this wave ships), the feature list with inter-feature dependencies, and open research questions. Writes to .mdd/waves/ stamped with the initiative’s current version.
• /mdd plan-execute <wave-id> — Runs /mdd <feature> build mode for each planned feature in the wave that doesn’t have a doc yet. Supports automated (run all) or interactive (confirm each) modes. Updates docPath and waveStatus in the wave file as docs are created.
• /mdd plan-sync <initiative-id> — Re-stamps all child wave files with the initiative’s current version after the initiative is edited. Run this to clear stale-wave warnings from /mdd scan.
• /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 deprecate for that.
• /mdd plan-cancel-initiative <initiative-id> — Sets the initiative and all child waves to cancelled. Warns if any wave has executed features and asks how to handle them. Cancelled initiatives remain visible in the TUI dashboard (shown in gray) for historical reference.

The MDD Dashboard TUI gains a collapsible INITIATIVES section at the top of the left panel. Press Enter or → on an initiative to expand its waves; press i to jump directly to the first initiative. The status bar shows total initiative count and active wave progress.

The .mdd/ Directory

All MDD artifacts live in a single dotfile directory, gitignored by default:

.mdd/
├── docs/                        # Feature documentation (one per feature)
│   ├── 01-project-scaffolding.md  # YAML frontmatter: last_synced, status, phase
│   ├── 02-profile-system.md
│   └── archive/                 # Deprecated feature docs (/mdd deprecate)
├── initiatives/                 # Initiative files (/mdd plan-initiative)
│   └── auth-system.md           # id, title, status, version, hash, overview
├── waves/                       # Wave files (/mdd plan-wave)
│   └── auth-system-wave-1.md    # features table + docPath, waveStatus per feature
└── audits/                      # Audit artifacts
    ├── notes-2026-03-01.md      # Raw reading notes
    ├── report-2026-03-01.md     # Structured findings
    ├── results-2026-03-01.md    # Before/after summary
    ├── scan-2026-04-12.md       # Drift report (/mdd scan)
    └── graph-2026-04-12.md      # Dependency graph (/mdd graph)

Real Results: Self-Audit

We used MDD to audit this starter kit — the same methodology the kit teaches. Here's what happened:

Why It Works

The problem with Claude Code isn't intelligence — it's context. A 200K token window sounds huge until you're reading 40 files and burning 80% of context on comprehension before writing a single line of output.

MDD makes each phase a context compressor: documentation compresses 40 files into 1 doc, raw notes compress all source code into a single file, the audit report compresses notes into severity-rated findings. By the time Claude writes code, it's working from a 300-line report — not a 40,000-line codebase. It's not problem-solving. It's pattern-matching.

The Incremental Write Trick

The most important technical detail: when Claude reads files during an audit, context will compact. If your findings are only in Claude's 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. We've run this pattern across 6 complete audit cycles. Zero data loss.

After processing every 2 features, immediately append your notes to
.mdd/audits/notes.md. If context compacts, read the TAIL of the notes
file and continue from where you left off.

Startup Context

Every Claude Code session starts cold. Without context, Claude reads dozens of files to understand your project — burning thousands of tokens before writing a single line of output. The MDD Startup Context system eliminates this entirely.

.mdd/.startup.md is a compact project snapshot that the SessionStart hook injects automatically at the start of every session — including after /clear and after context compaction. Claude reads one file (~100–200 tokens) instead of your entire codebase. It is regenerated automatically by /mdd commands and gitignored — it is machine state, not source code.

Example file:

## Project Snapshot
Generated: 2026-03-04 | Branch: feat/webserver

## Stack
Framework: Next.js | DB: MongoDB (StrictDB) | Host: Dokploy

## Features Documented (4)
01-project-scaffolding -- complete
02-profile-system -- complete
03-auth -- complete
04-webserver -- IN PROGRESS

## Last Audit
Date: 2026-03-01 | Findings: 20 | Fixed: 17 | Open: 3
Open: ssl-redeploy-race, nginx-log-tab, e2e-coverage-gap

## Rules Summary
Read CLAUDE.md for full rules. Key rules:
- TypeScript always, strict mode, no any
- StrictDB only -- no raw drivers
- /api/v1/ prefix on all endpoints
- No file > 300 lines, no function > 50 lines
- Never commit .env

---

## Notes
- [2026-03-04] ssl issue is a docker swarm bug, not nginx
- [2026-03-04] waiting on Anthropic SessionStart fix for startup source

The hook that powers this is session-context.sh — wired to fire on startup, clear, and compact sources. The resume source is intentionally excluded: when resuming a session, Claude already has the transcript and injecting context again wastes tokens.

"SessionStart": [
  {
    "matcher": "startup|clear|compact",
    "hooks": [
      {
        "type": "command",
        "command": "bash .claude/hooks/session-context.sh"
      }
    ]
  }
]

Why not just use CLAUDE.md? CLAUDE.md is rules. .startup.md is state. Rules change rarely — you write them once and they compound over time. State changes constantly — current branch, active features, open findings. Mixing them means Claude re-reads your entire rulebook to find out what branch you are on. Separating them means each file stays small, focused, and cheap to load.

MDD Dashboard — Terminal TUI

The mdd package is a standalone terminal dashboard for MDD workspaces. Run it inside any project with a .mdd/ folder to get a real-time, interactive view of your workspace health — without leaving VS Code.

npm install -g mdd-tui

Then inside any project with a .mdd/ folder:

mdd              # opens the interactive TUI
mdd dashboard    # same
mdd status       # same — all three open the dashboard

npm: mdd-tui · GitHub

Ops Mode NEW

Document-first deployments — the same discipline MDD brings to features, now applied to ops tasks. Runbooks replace improvised deploys. Every region is gated. If canary fails, primary is never touched.

The Four Commands

Global vs Project Scope

/mdd ops asks scope as its very first question. The answer controls where the runbook is stored and how it is shared.

Listing All Runbooks

/mdd ops list shows all runbooks across both scopes in a unified view:

Ops Runbooks
────────────────────────────────────────────────────────────

Global (~/.claude/ops/)
  docker-hub-login       docker-hub    all projects    complete
  dns-cloudflare         manual        all projects    draft

Project (.mdd/ops/)
  rulecatch-dokploy      dokploy       staging, prod   in_progress
  api-rollback           manual        production      draft

4 runbooks total (2 global, 2 project)
Run /mdd runop <slug> to execute any runbook.

The Runbook Concept

A runbook is a structured ops document in .mdd/ops/ with YAML frontmatter declaring services, regions, deployment order, health check endpoints, and gate behaviour. It is the single source of truth for a deployment. /mdd runop reads it and executes it — you do not hand-craft the sequence each time.

Write once, runs every time. Once a runbook exists, every future deployment of that service runs through the same documented sequence, with the same pre-flight checks, the same canary gate, and the same post-flight verification. Nothing falls through the cracks because someone forgot a step.

Canary Deployment Pattern

Ops Mode enforces a canary-first deployment model. Regions are ordered by deploy_order in the runbook frontmatter. The canary region always deploys first — only if all its services pass the health gate does the primary region proceed.

If the canary gate fails — any service unhealthy after deploy — the primary region is never touched. It is still running the old version. You can redeploy to canary, skip that region, or abort entirely. The gate behaviour is configurable: stop (default), skip_region, or rollback.

Pre-flight Health Check

Before any deployment begins, /mdd runop checks the current health of all services across all regions. If a service is already failing before you deploy, you know upfront — not after the deploy makes it worse. The pre-flight table surfaces this clearly and prompts for a decision:

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. Redeploy, skip, or abort?

Canary Gate Output

After the canary deploy completes, /mdd runop re-checks every service in the canary region. The gate output shows exactly which image each service is running and its health status:

── eu-west (canary) — gate check ──────────────
api         ✓ healthy  (rulecatch-api-eu:latest)
dashboard   ✓ healthy
worker      ✓ healthy
Gate: PASSED ✓ — advancing to us-east (primary)

Multi-Region, Multi-Image Support

Each service can have a different Docker image name per region. This supports regional image registries, blue-green strategies, or teams that maintain separate EU and US image builds. Per-region health status is tracked in the runbook frontmatter so the dashboard can show the last-known state of every region at a glance.

Directory Structure

Project runbooks live in .mdd/ops/. Global runbooks live in ~/.claude/ops/ alongside your other global Claude config:

# Project-scoped runbooks (this project only)
.mdd/
├── docs/                          # Feature documentation
├── ops/                           # Project deployment runbooks
│   ├── rulecatch-dokploy.md       # Multi-region Dokploy deploy runbook
│   └── api-rollback.md            # Emergency rollback runbook
├── initiatives/
├── waves/
└── audits/

# Global runbooks (available in every project)
~/.claude/
├── commands/                      # Global slash commands
├── skills/                        # Global skills
├── ops/                           # Global deployment runbooks ← NEW
│   ├── docker-hub-login.md        # Reusable Docker Hub auth runbook
│   └── dns-cloudflare.md          # DNS update runbook (any project)
└── CLAUDE.md

Project runbooks are gitignored by default alongside the rest of .mdd/ — they contain environment-specific configuration (region URLs, health endpoints, image names) that belongs in your local workspace, not version control. Global runbooks persist in your home directory and are never project-specific.

Featured Packages

Five open-source npm packages by TheDecipherist — the same developer behind this starter kit — are integrated into project profiles. All are MIT-licensed.

claude mcp add classmcp -- npx -y classmcp@latest

claude mcp add strictdb-mcp -- npx -y strictdb-mcp@latest

pnpm add -D classpresso

pnpm add tersejson

What Is This?

Three Ways to Use It

Learning Path

Progress through these phases at your own pace. Each builds on the previous one.

First 5 Minutes

/install-global                    # One-time: install global Claude config
/new-project my-app clean          # Scaffold a project (or: default for full stack)
cd ~/projects/my-app               # Enter your new project
/setup                             # Configure .env interactively
pnpm install && pnpm dev           # Start building

First Feature (MDD Workflow)

/mdd user authentication           # Claude analyzes existing code, interviews you,
                                    # writes docs, generates test skeletons, presents
                                    # a plan, then builds

Use /help to see all 27 commands at any time.

Quick Start

# 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-global

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/block-secrets.py ~/.claude/hooks/
cp .claude/hooks/verify-no-secrets.sh ~/.claude/hooks/
cp .claude/hooks/check-rulecatch.sh ~/.claude/hooks/

claude

Troubleshooting

Project Structure

project/
├── CLAUDE.md                    # Project instructions (customize this!)
├── CLAUDE.local.md              # Personal overrides (gitignored)
├── .claude/
│   ├── settings.json            # Hooks configuration
│   ├── commands/
│   │   ├── help.md              # /help — list all commands, skills, and agents
│   │   ├── 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/
│   │   ├── code-review/SKILL.md # Triggered code review checklist
│   │   └── create-service/SKILL.md # Service scaffolding template
│   ├── agents/
│   │   ├── code-reviewer.md     # Read-only review subagent
│   │   └── test-writer.md       # Test writing subagent
│   └── hooks/
│       ├── block-secrets.py     # PreToolUse: block sensitive files
│       ├── 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
│       ├── lint-on-save.sh      # PostToolUse: lint after writes
│       ├── verify-no-secrets.sh # Stop: check for secrets
│       ├── check-rulecatch.sh   # Stop: report RuleCatch violations
│       └── check-env-sync.sh    # Stop: warn on .env/.env.example drift
├── 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

Key Concepts

CLAUDE.md — The Rulebook

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:

CORRECT: /api/v1/users
WRONG:   /api/users

// 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!

// 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

When Something Seems Wrong

The CLAUDE.md also includes a “Check Before Assuming” pattern that prevents Claude from jumping to conclusions:

Fixed Service Ports

Port conflicts are one of the most common problems in multi-service development. The CLAUDE.md locks them down:

Hooks — Stronger Than Rules

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 that behavior will be followed.

# Files that should NEVER be read or edited by Claude
SENSITIVE_FILENAMES = {
    '.env', '.env.local', '.env.production',
    'secrets.json', 'id_rsa', 'id_ed25519',
    '.npmrc', 'credentials.json',
    'service-account.json',
}

# Exit code 2 = block operation and tell Claude why
if path.name in SENSITIVE_FILENAMES:
    print(f"BLOCKED: Access to '{file_path}' denied.", file=sys.stderr)
    sys.exit(2)

case "$EXTENSION" in
    ts|tsx)
        # TypeScript — run type check
        npx tsc --noEmit --pretty "$FILE_PATH" 2>&1 | head -20
        ;;
    js|jsx)
        # JavaScript — run eslint
        npx eslint "$FILE_PATH" 2>&1 | head -20
        ;;
    py)
        # Python — run ruff or flake8
        ruff check "$FILE_PATH" 2>&1 | head -20
        ;;
esac

# 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"
fi

# Run RuleCatch violation check
RESULT=$(npx @rulecatch/ai-pooler@latest check --quiet --format summary 2>/dev/null)

if [ -n "$RESULT" ] && [ "$RESULT" != "0 violations" ]; then
    echo "📋 RuleCatch: $RESULT" >&2
    echo "   Run 'pnpm ai:monitor' for details." >&2
fi

Hook Configuration

Hooks are wired up in .claude/settings.json. Each hook type fires at a different point in Claude's lifecycle:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Read|Edit|Write",
        "hooks": [{ "type": "command", "command": "python3 .claude/hooks/block-secrets.py" }]
      },
      {
        "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" }
        ]
      }
    ],
    "PostToolUse": [{
      "matcher": "Write",
      "hooks": [{ "type": "command", "command": "bash .claude/hooks/lint-on-save.sh" }]
    }],
    "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" }
      ]
    }]
  }
}

Slash Commands — On-Demand Tools

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.

/install-global mdd    # updates @thedecipherist/mdd npm package only — skips everything else

# Open a separate terminal and run this while Claude works
npx @rulecatch/ai-pooler monitor --no-api-key

/worktree add-auth          # → task/add-auth branch
/worktree feat/new-dashboard # → uses prefix as-is

/refactor src/handlers/users.ts
/refactor src/server.ts --dry-run    # report only, no changes

/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, StrictDB, 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 StrictDB, 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-stack

/convert-project-to-starter-kit ~/projects/my-app
/convert-project-to-starter-kit ~/projects/my-app --force

/update-project              # Pick from registered projects
/update-project --force      # Skip confirmation prompts

/add-feature strictdb         # Add StrictDB + query system
/add-feature vitest playwright # Add both test frameworks
/add-feature --list           # Show all available features

Supported Technologies

This 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.

Languages & Frameworks

Recommended Stacks

Skills — Triggered Expertise

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.

What Triggers Skills?

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.

How to Activate Skills

You don't — just use natural language. Say things like:

• “Review this file for security issues” → Code Review skill activates
• “Audit the authentication module” → Code Review skill activates
• “Create a new payment service” → Create Service skill activates
• “Scaffold a notification service” → Create Service skill activates

Skills vs Commands

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.

┌─────────────────────────────────────────────────────┐
│                    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                         │
│  → Third-party APIs, etc.                            │
└─────────────────────────────────────────────────────┘

Custom Agents — Specialist Subagents

Agents are specialists that Claude delegates to automatically. They run with restricted tool access so they can't accidentally modify your code when they shouldn't.

// 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 vague

StrictDB — Unified Database Driver

The starter kit uses StrictDB — a production-grade unified database driver (npm package) supporting MongoDB, PostgreSQL, MySQL, MSSQL, SQLite, and Elasticsearch. It enforces every best practice that prevents the most common database failures in AI-assisted development.

The Absolute Rule

ALL database access goes through StrictDB. No exceptions. Never create direct database clients. Never import raw database drivers in business logic.

// CORRECT — import from StrictDB
import { queryOne, insertOne, updateOne } from 'strictdb';

// WRONG — NEVER do this
import { MongoClient } from 'mongodb';     // FORBIDDEN — use StrictDB
import { Pool } from 'pg';                 // FORBIDDEN — use StrictDB

Reading Data — Aggregation Only

// 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' },
});

Writing Data — BulkWrite Only

// 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 } },
]);

Connection Pool Presets

Built-in Sanitization and Guardrails

All query inputs are automatically sanitized. The sanitizer uses an allowlist of known-safe query operators — standard operators pass through while dangerous ones are stripped.

This means standard queries just work without any special options:

// All of these 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 sanitization entirely with sanitize: false in StrictDB.create() config or sanitize = false in claude-mastery-project.conf.

{ trusted: true } — Escape Hatch

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 use it frequently, add the operator to the SAFE_OPERATORS configuration in StrictDB instead.

// Only needed for operators NOT in the allowlist:
const results = await queryMany('collection', pipeline, { trusted: true });
const total = await count('collection', match, { trusted: true });
const one = await queryOne('collection', match, { trusted: true });

Additional Features

• Singleton per URI — same STRICTDB_URI always returns the same client, prevents pool exhaustion
• Next.js hot-reload safe — persists connections via globalThis during development
• Transaction support — withTransaction() for multi-document atomic operations
• Change Stream access — rawCollection() for real-time event processing
• Graceful shutdown — gracefulShutdown() closes all pools on SIGTERM, SIGINT, uncaughtException, and unhandledRejection — 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

Test Query Master — scripts/db-query.ts

One of the biggest problems with AI-assisted database development: Claude scatters random query scripts all over your project. The Test Query Master solves this completely.

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`);
  },
};

Then register in scripts/db-query.ts and run: npx tsx scripts/db-query.ts find-expired-sessions

Every query uses StrictDB — same connection pool, same patterns, same rules. When you're done exploring, just delete the file and its registry entry.

Content Builder — scripts/build-content.ts

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 with one command.

{
  "articles": [
    {
      "id": "getting-started",
      "published": true,
      "mdSource": "content/getting-started.md",
      "htmlOutput": "public/articles/getting-started/index.html",
      "title": "Getting Started Guide",
      "description": "Everything you need to know.",
      "url": "https://example.com/articles/getting-started/",
      "datePublished": "2026-01-15",
      "category": "Guides",
      "keywords": ["setup", "installation"]
    }
  ]
}

Each generated page includes: Open Graph, Twitter Cards, Schema.org JSON-LD, syntax highlighting, optional sidebar TOC, and parent/child article relationships.

pnpm content:build              # Build all published articles
pnpm content:build:id my-post   # Build a single article
pnpm content:list               # List all articles and status
pnpm content:dry-run            # Preview what would build

All Scripts — package.json

Everything is tied together through package.json scripts. No random npx commands to remember.

Documentation Templates

Pre-structured docs that Claude actually follows. Each template uses the “STOP” pattern — explicit boundaries that prevent Claude from making unauthorized changes.

## 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.

Testing Methodology

From the V5 testing methodology — a structured approach to testing that prevents the most common AI-assisted testing failures.

describe('[Feature]', () => {
  describe('[Scenario]', () => {
    it('should [expected behavior] when [condition]', async () => {
      // Arrange — set up test data
      // Act — perform the action
      // Assert — verify SPECIFIC outcomes
    });
  });
});

E2E Infrastructure — playwright.config.ts

The Playwright config is pre-wired with test ports, automatic server spawning, and port cleanup. You never have to manually start servers for E2E tests.

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 report

/create-e2e Slash Command

Use /create-e2e <feature-name> to generate a properly structured E2E test. Claude will:

1. Read the source code for the feature being tested
2. Identify all URLs, elements, and data to verify
3. Ask what specific success criteria you expect (if not obvious)
4. Create the test at tests/e2e/[name].spec.ts with happy path, error cases, and edge cases
5. Verify the test meets the “done” checklist before finishing

Windows Users — VS Code in WSL Mode

If you're developing on Windows, this is the single biggest performance improvement you can make — and most people don't even know it exists.

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. Everything just works — but 5-10x faster.

Setup (One Time)

# 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 automatically

The Critical Mistake

Your 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 — every file operation still crosses the slow Windows/Linux boundary.

# 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-app

Run /setup in Claude Code to auto-detect your environment and get specific instructions if something is misconfigured.

Global CLAUDE.md — Security Gatekeeper

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:

Coding Standards

Patterns and practices enforced across the project through CLAUDE.md rules, hooks, and code review.

Imports

// 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';

Error Handling

// 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
}

Naming Safety

Renaming packages, modules, or key variables mid-project causes cascading failures. If you must rename:

1. Create a checklist of ALL files and references first
2. Use IDE semantic rename (not search-and-replace)
3. Full project search for old name after renaming
4. Check: .md, .txt, .env, comments, strings, paths
5. Start a FRESH Claude session after renaming

Plan Mode — Named Steps + Replace, Don't Append

Every plan step MUST have a unique, descriptive name so you can reference it unambiguously:

Step 1 (Project Setup): Initialize repo with TypeScript
Step 2 (Database Layer): Configure StrictDB
Step 3 (Auth System): Implement JWT authentication

When modifying a plan, Claude tends to append instead of replacing — creating contradictions. The rules:

• 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

Monitor Your Rules

Full disclosure: RuleCatch.AI is built by TheDecipherist — the same developer behind this starter kit. It's purpose-built for catching the exact issues AI-assisted development introduces.

Try It Now — Free Monitor Mode

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-key

Also 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. This is the free preview that lets you see what you've been missing.

Unlock the Full Experience

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.

AI-Pooler (Free Monitor Mode)

Free monitor mode works instantly — no API key needed. See every tool call, token, cost, and file access in a live terminal view. With an API key: adds persistent violation tracking, session history, and cost analytics

Dashboard

Violations across 18 rule categories, session analytics (tokens, cost, lines/hour), trend reports, 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+ Rules & Privacy-First

Security, TypeScript, React, Next.js, MongoDB, Docker — violations in under 100ms. AES-256-GCM client-side encryption. You hold the key. US and EU data isolation, fully GDPR compliant

The RuleCatch dashboard — violation trends, category breakdown, per-file attribution, and top triggered rules at a glance. Configure alerts via Slack, Discord, PagerDuty, and more.

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 init

npm: @rulecatch/ai-pooler · @rulecatch/mcp-server

The AI-Pooler free monitor in action — tokens, cost, and tool usage updating in real time. Try it now: open a separate terminal and run npx @rulecatch/ai-pooler monitor --no-api-key

Explore RuleCatch.AI 7-day free trial - no credit card required

Recommended MCP Servers

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 mcp add context7 -- npx -y @upstash/context7-mcp@latest

claude mcp add github -- npx -y @modelcontextprotocol/server-github

claude mcp add playwright -- npx -y @playwright/mcp@latest

claude mcp add classmcp -- npx -y classmcp@latest

claude mcp add strictdb-mcp -- npx -y strictdb-mcp@latest

npx @rulecatch/mcp-server init

See the Claude Code Mastery Guide for the complete MCP server directory.

Screenshots

The starter kit in action — every screenshot is from real command output.

/help Command Output

All 27 commands organized by category — Setup, Kit Management, Code Quality, Development, Infrastructure, Monitoring

/review Catching Violations

Severity-rated findings with file:line references, fix suggestions, and CLAUDE.md rule citations

Auto-Branching on Commit

Hook blocks commits to main and suggests feature branches — zero-friction branch safety

Hooks Firing (lint-on-save)

TypeScript error caught immediately after file write — PostToolUse hook in action

/diagram architecture Output

ASCII box-drawing diagram generated from actual source files — Client, API, Handler, Adapter layers

/setup Interactive Flow

Category-by-category .env configuration — GitHub, Database, Docker, Analytics, RuleCatch

AI Monitor — Free Mode

Live view of tool calls, tokens, cost, and files accessed — npx @rulecatch/ai-pooler monitor --no-api-key

E2E Test Assertions: Good vs Bad

Side-by-side comparison — a test that passes when broken vs one with real assertions

Credits

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