@claude-code-mastery/starter-kit 1.0.0

package/.claude/commands/diagram.md

@@ -0,0 +1,301 @@
+---
+description: Generate or update project diagrams by scanning actual code — architecture, API, database, infrastructure
+scope: project
+argument-hint: <type> [--update]
+allowed-tools: Read, Write, Edit, Grep, Glob, Bash
+---
+
+# Generate Diagram
+
+Scan the actual project and generate/update diagrams based on what exists in code.
+
+**Type:** $ARGUMENTS
+
+Available types:
+- `architecture` — System overview: services, connections, data flow → updates `project-docs/ARCHITECTURE.md`
+- `api` — API routes map: all endpoints grouped by resource → updates `project-docs/ARCHITECTURE.md`
+- `database` — Database schema: collections, indexes, relationships → updates `project-docs/ARCHITECTURE.md`
+- `infrastructure` — Deployment topology: servers, containers, regions → updates `project-docs/INFRASTRUCTURE.md`
+- `all` — Generate all diagram types
+
+If `--update` is passed, replace existing diagrams in-place. Otherwise, show the diagram and ask before writing.
+
+## Diagram Format
+
+**ALL diagrams use ASCII box-drawing characters.** No Mermaid, no SVG, no external tools. ASCII works in every terminal, every markdown renderer, every code review.
+
+```
+Box characters: ┌ ┐ └ ┘ │ ─ ├ ┤ ┬ ┴ ┼
+Arrows: → ← ↑ ↓ ──> <── ───>
+```
+
+---
+
+## Type: `architecture`
+
+Scan the project and generate a system overview diagram.
+
+### What to scan:
+
+1. **`src/` directory structure** — identify services, handlers, adapters
+   ```bash
+   find src/ -name "*.ts" -o -name "*.tsx" 2>/dev/null | head -50
+   ```
+
+2. **Entry points** — find all server/app files
+   ```bash
+   grep -rl "app.listen\|createServer\|express()\|fastify()\|Hono()" src/ 2>/dev/null
+   ```
+
+3. **Route definitions** — find where endpoints are defined
+   ```bash
+   grep -rn "app\.\(get\|post\|put\|delete\|patch\)\|router\.\(get\|post\|put\|delete\|patch\)" src/ 2>/dev/null
+   ```
+
+4. **Database usage** — find which services access the database
+   ```bash
+   grep -rl "queryOne\|queryMany\|insertOne\|updateOne\|bulkOps\|batch\|StrictDB\|MongoClient\|PrismaClient" src/ 2>/dev/null
+   ```
+
+5. **External service calls** — find adapters and API calls
+   ```bash
+   grep -rl "fetch(\|axios\|got(" src/ 2>/dev/null
+   ```
+
+6. **Package.json** — check for framework indicators
+   - `next` → Next.js app
+   - `express` → Express API
+   - `fastify` → Fastify API
+   - `hono` → Hono API
+
+### Generate the diagram:
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                        YOUR SYSTEM                           │
+│                                                              │
+│   ┌───────────┐    HTTP     ┌───────────┐                  │
+│   │  Client   │────────────>│ Website   │                  │
+│   │  Browser  │             │  :3000    │                  │
+│   └───────────┘             └───────────┘                  │
+│         │                                                    │
+│         │  API calls        ┌───────────┐                  │
+│         └──────────────────>│   API     │                  │
+│                             │  :3001    │                  │
+│                             └─────┬─────┘                  │
+│                                   │                         │
+│                          read/write│                         │
+│                                   ▼                         │
+│                            ┌───────────┐                   │
+│                            │ MongoDB   │                   │
+│                            │ (StrictDB)│                   │
+│                            └───────────┘                   │
+│                                                              │
+│   ┌───────────┐   reads    ┌───────────┐                  │
+│   │ Dashboard │────────────>│   API     │                  │
+│   │  :3002    │             │  :3001    │                  │
+│   └───────────┘             └───────────┘                  │
+│                                                              │
+└─────────────────────────────────────────────────────────────┘
+```
+
+**Adapt this to what ACTUALLY exists.** Don't include services that don't exist. Don't guess — only diagram what you found in code.
+
+### Where to write:
+
+Replace the `## System Overview` diagram section in `project-docs/ARCHITECTURE.md`.
+Also update `## Service Responsibilities` table and `## Data Flow` section based on findings.
+
+---
+
+## Type: `api`
+
+Scan all route definitions and generate an API routes map.
+
+### What to scan:
+
+```bash
+# Express/Fastify routes
+grep -rn "app\.\(get\|post\|put\|delete\|patch\)\|router\.\(get\|post\|put\|delete\|patch\)" src/ 2>/dev/null
+
+# Next.js API routes (file-based)
+find src/app/api -name "route.ts" -o -name "route.tsx" 2>/dev/null
+find src/pages/api -name "*.ts" -o -name "*.tsx" 2>/dev/null
+```
+
+### Generate the diagram:
+
+```
+API Routes Map
+==============
+
+  /api/v1/
+  ├── auth/
+  │   ├── POST   /login          → handlers/auth.ts:handleLogin
+  │   ├── POST   /signup         → handlers/auth.ts:handleSignup
+  │   └── POST   /logout         → handlers/auth.ts:handleLogout
+  ├── users/
+  │   ├── GET    /               → handlers/users.ts:listUsers
+  │   ├── GET    /:id            → handlers/users.ts:getUser
+  │   ├── PUT    /:id            → handlers/users.ts:updateUser
+  │   └── DELETE /:id            → handlers/users.ts:deleteUser
+  └── health/
+      └── GET    /               → server.ts (inline)
+```
+
+### Where to write:
+
+Add/update an `## API Routes` section in `project-docs/ARCHITECTURE.md`.
+
+---
+
+## Type: `database`
+
+Scan database queries, models, and index registrations to map the schema.
+
+### What to scan:
+
+```bash
+# Collections used in queries
+grep -rn "queryOne\|queryMany\|insertOne\|updateOne\|bulkOps\|deleteOne\|count(" src/ 2>/dev/null
+
+# Index registrations
+grep -rn "registerIndex\|createIndex\|ensureIndex" src/ scripts/ 2>/dev/null
+
+# Type definitions that map to collections
+grep -rn "interface.*{" src/types/ 2>/dev/null
+```
+
+### Generate the diagram:
+
+```
+Database Schema
+===============
+
+  ┌─────────────────────────┐      ┌─────────────────────────┐
+  │ users                   │      │ sessions                │
+  ├─────────────────────────┤      ├─────────────────────────┤
+  │ _id         ObjectId    │──┐   │ _id         ObjectId    │
+  │ email       string  [U] │  │   │ userId      ObjectId    │──┐
+  │ name        string      │  │   │ token       string  [U] │  │
+  │ apiKey      string [U,S]│  │   │ expiresAt   Date   [TTL]│  │
+  │ createdAt   Date        │  │   │ createdAt   Date        │  │
+  └─────────────────────────┘  │   └─────────────────────────┘  │
+                               │                                 │
+                               └─── userId references users._id ─┘
+
+  Indexes:
+    users.email       — unique
+    users.apiKey      — unique, sparse
+    sessions.userId   — compound (userId, startedAt DESC)
+    sessions.expiresAt — TTL (auto-delete)
+
+  [U] = unique  [S] = sparse  [TTL] = auto-expiring
+```
+
+### Where to write:
+
+Add/update a `## Database Schema` section in `project-docs/ARCHITECTURE.md`.
+
+---
+
+## Type: `infrastructure`
+
+Scan deployment config to generate infrastructure topology.
+
+### What to scan:
+
+1. **`.env` / `.env.example`** — region variables, ports, hosts
+2. **`Dockerfile`** — what's containerized
+3. **`docker-compose.yml`** — service orchestration
+4. **`claude-mastery-project.conf`** — multi-region config
+5. **`package.json`** — deployment scripts
+
+```bash
+# Check for multi-region
+grep -n "_US\|_EU\|REGION" .env.example .env 2>/dev/null
+
+# Check for Docker
+ls Dockerfile docker-compose.yml 2>/dev/null
+
+# Check for deployment config
+grep -n "DOKPLOY\|HOSTINGER\|VERCEL\|VPS" .env.example .env 2>/dev/null
+```
+
+### Generate the diagram:
+
+**Single region:**
+```
+Infrastructure
+==============
+
+  ┌──────────────── Production ────────────────┐
+  │                                             │
+  │   ┌─────────────┐     ┌─────────────┐     │
+  │   │   Docker     │     │  MongoDB    │     │
+  │   │   :3001      │────>│  Atlas      │     │
+  │   │   (API)      │     │             │     │
+  │   └─────────────┘     └─────────────┘     │
+  │         │                                   │
+  │   Dokploy on Hostinger VPS                  │
+  │   IP: (from .env)                           │
+  │                                             │
+  └─────────────────────────────────────────────┘
+```
+
+**Multi-region:**
+```
+Infrastructure — Multi-Region
+==============================
+
+  ┌────────── US Region ──────────┐    ┌────────── EU Region ──────────┐
+  │                                │    │                                │
+  │  ┌──────────┐  ┌──────────┐  │    │  ┌──────────┐  ┌──────────┐  │
+  │  │ Docker   │  │ MongoDB  │  │    │  │ Docker   │  │ MongoDB  │  │
+  │  │ :latest  │─>│ Atlas US │  │    │  │ :eu      │─>│ Atlas EU │  │
+  │  └──────────┘  └──────────┘  │    │  └──────────┘  └──────────┘  │
+  │                                │    │                                │
+  │  VPS: (US IP)                  │    │  VPS: (EU IP)                  │
+  │  Dokploy US                    │    │  Dokploy EU                    │
+  │                                │    │                                │
+  └────────────────────────────────┘    └────────────────────────────────┘
+
+  US containers → US database ONLY
+  EU containers → EU database ONLY
+  NEVER cross-connect regions
+```
+
+### Where to write:
+
+Replace the `## Environment Overview` diagram in `project-docs/INFRASTRUCTURE.md`.
+
+---
+
+## Type: `all`
+
+Run all four types in sequence: architecture → api → database → infrastructure.
+
+---
+
+## After Generating
+
+1. Show the generated diagram(s) to the user
+2. If `--update` was passed: write directly to the docs
+3. If not: ask "Write this to project-docs/ARCHITECTURE.md?" before writing
+4. Add a changelog entry with today's date:
+   ```
+   | (today) | Updated [type] diagram from code scan |
+   ```
+5. Report what was generated:
+   ```
+   Diagrams Generated
+   ==================
+   ✓ Architecture — 3 services found (Website, API, Dashboard)
+   ✓ API Routes — 12 endpoints across 4 resources
+   ✓ Database — 5 collections, 8 indexes
+   ✓ Infrastructure — multi-region (US + EU)
+
+   Written to:
+     project-docs/ARCHITECTURE.md (architecture, api, database)
+     project-docs/INFRASTRUCTURE.md (infrastructure)
+   ```

package/.claude/commands/help.md

@@ -0,0 +1,120 @@
+---
+description: List all available commands and skills
+scope: project
+allowed-tools: Read, Glob
+---
+
+# Help — All Available Commands
+
+Display the complete list of commands and skills available in this project.
+
+## Step 1 — Detect Context
+
+Determine if we're running inside the starter kit or a scaffolded project:
+
+1. Check if BOTH `claude-mastery-project.conf` AND `.claude/commands/new-project.md` exist in the project root
+   - **Yes** → This is the **starter kit**. Show ALL commands (both `scope: project` and `scope: starter-kit`), grouped with a "KIT MANAGEMENT" section.
+   - **No** → This is a **scaffolded project**. Show only the commands present in `.claude/commands/`.
+
+## Step 2 — Enumerate Commands
+
+1. Glob `.claude/commands/*.md` to find all command files
+2. For each file, read the YAML frontmatter to extract:
+   - `description` — the command description
+   - `scope` — `project` or `starter-kit` (if present)
+3. Build the command list dynamically from what's actually installed
+
+## Step 3 — Display
+
+Format the output as a grouped reference. Use the categories below for organization.
+
+### If Starter Kit (show all commands with KIT MANAGEMENT section):
+
+```
+=== Claude Code Starter Kit — Command Reference ({N} commands) ===
+
+GETTING STARTED
+  /help              List all commands and skills (this screen)
+  /quickstart        Interactive first-run walkthrough for new users
+  /install-global    Install/merge global Claude config into ~/.claude/
+  /setup             Interactive .env configuration — GitHub, database, Docker, analytics
+  /setup --reset     Re-configure everything from scratch
+  /show-user-guide   Open the comprehensive User Guide in your browser
+
+KIT MANAGEMENT (starter kit only — not copied to projects)
+  /new-project       Scaffold a new project from a profile (clean, default, api, go, vue, python-api, etc.)
+  /set-project-profile-default  Set the default profile for /new-project (any profile name)
+  /add-project-setup  Interactive wizard to create a named profile in claude-mastery-project.conf
+  /projects-created  List all projects created by the starter kit with creation dates
+  /remove-project    Remove a project from the registry and optionally delete it from disk
+  /convert-project-to-starter-kit  Merge starter kit into an existing project (non-destructive)
+  /update-project    Update a starter-kit project with the latest commands, hooks, and rules
+  /update-project --clean  Remove starter-kit-scoped commands from a project
+
+CODE QUALITY
+  /review            Systematic code review against 7-point checklist
+  /refactor <file>   Audit + refactor a file against all CLAUDE.md rules
+  /security-check    Scan project for secrets, vulnerabilities, and .gitignore gaps
+  /commit            Smart commit with conventional commit format
+
+DEVELOPMENT
+  /create-api <res>  Scaffold a full API endpoint — route, handler, types, tests
+  /create-e2e <feat> Generate Playwright E2E test with explicit success criteria
+  /test-plan         Generate a structured test plan for a feature
+  /progress          Check project status — files, tests, git activity, next actions
+
+INFRASTRUCTURE
+  /diagram <type>    Generate diagrams from code: architecture, api, database, infrastructure, all
+  /architecture      Display system architecture and data flow
+  /optimize-docker   Audit Dockerfile against 12 production best practices
+  /worktree <name>   Create isolated branch + worktree for a task
+
+MONITORING
+  /what-is-my-ai-doing   Live monitor of AI activity — tokens, cost, violations
+```
+
+### If Scaffolded Project (show only installed commands):
+
+```
+=== Command Reference ({N} commands) ===
+```
+
+Group installed commands into the same categories (GETTING STARTED, CODE QUALITY, DEVELOPMENT, INFRASTRUCTURE, MONITORING). Skip any category that has no installed commands. Use the descriptions from the frontmatter.
+
+### Always append (both contexts):
+
+```
+=== Skills ===
+
+Auto-activate when Claude detects the work — no command needed:
+
+  API Conventions    Triggers: writing routes, handlers, or adapters
+                     Service structure — routing, layering, where code lives
+  MongoDB Rules      Triggers: queries, aggregations, indexes, connections, schema
+                     Driver, StrictDB, and data-modeling rules for MongoDB
+  Code Review        Triggers: "review", "audit", "check code", "security review"
+                     Systematic review with severity-rated, cited findings (read-only)
+  Debugger           Triggers: "crash", "stack trace", "fails in prod", "root cause"
+                     Diagnoses failures by root cause, not symptom (read-only)
+  Design Review      Triggers: "review UI", "layout", "accessibility", "does this look right"
+                     Critiques UI/UX for usability, accessibility, distinctiveness (read-only)
+  Test Writer        Triggers: "write tests", "add a test", "cover this"
+                     Writes tests that catch bugs, with explicit assertions
+  Dependency Vetting Triggers: "is this package safe", "should I add", "can I trust"
+                     Vets a package for supply-chain risk before you install it (read-only)
+
+Invoke explicitly (they write files):
+
+  Create Service     Triggers: "create service", "new service", "scaffold service"
+                     Scaffolds a microservice with server/handlers/adapters pattern
+  MCP Builder        Triggers: "MCP server", "expose as tools", "wrap this API"
+                     Builds an MCP server with well-designed tools and evals
+
+=== Tips ===
+
+  For detailed help on any command: ask "How do I use /command-name?"
+  First time here? Run /quickstart for a guided walkthrough.
+  Use /help anytime to see this list again.
+```
+
+**Note:** Only show the Skills section if `.claude/skills/` exists and contains files.

package/.claude/commands/install-global.md

@@ -0,0 +1,145 @@
+---
+description: Install global Claude config — merges into existing ~/.claude/ without overwriting
+scope: starter-kit
+allowed-tools: Read, Write, Edit, Bash, Grep, Glob, AskUserQuestion
+---
+
+# Install Global Config
+
+**$ARGUMENTS**
+
+Install the starter kit's global Claude configuration into `~/.claude/`. This is a one-time setup that gives you security rules, hooks, and settings across ALL projects.
+
+**Smart merge:** If you already have a global config, this merges new content — it never overwrites your existing rules.
+
+## Step 1 — Check What Exists
+
+```bash
+# Check if global claude directory exists
+ls -la ~/.claude/ 2>/dev/null || echo "NO_GLOBAL_DIR"
+
+# Check for existing files
+[ -f ~/.claude/CLAUDE.md ] && echo "EXISTING_CLAUDE_MD" || echo "NO_CLAUDE_MD"
+[ -f ~/.claude/settings.json ] && echo "EXISTING_SETTINGS" || echo "NO_SETTINGS"
+[ -d ~/.claude/hooks ] && echo "EXISTING_HOOKS" || echo "NO_HOOKS"
+```
+
+## Step 2 — Handle Each File
+
+### 2A. ~/.claude/CLAUDE.md
+
+**If NO existing file:**
+- Copy `global-claude-md/CLAUDE.md` directly to `~/.claude/CLAUDE.md`
+- Report: "Installed global CLAUDE.md (fresh install)"
+
+**If existing file found:**
+1. Read BOTH files:
+   - The existing `~/.claude/CLAUDE.md`
+   - The starter kit's `global-claude-md/CLAUDE.md`
+2. Compare section by section. The starter kit has these sections:
+   - `## Identity`
+   - `## NEVER EVER DO`
+   - `## New Project Setup`
+   - `## Coding Standards (All Projects)`
+   - `## Workflow`
+3. For each section:
+   - If the section header **already exists** in the user's file → **SKIP** (don't overwrite their version)
+   - If the section header **does NOT exist** → **APPEND** it to the end of the user's file
+4. Report exactly what was added and what was skipped:
+   ```
+   Global CLAUDE.md merge:
+     ✓ Identity — already exists, skipped
+     ✓ NEVER EVER DO — already exists, skipped
+     + New Project Setup — added
+     + Coding Standards — added
+     ✓ Workflow — already exists, skipped
+   ```
+
+**IMPORTANT:** NEVER delete or overwrite existing content. Only append missing sections.
+
+### 2B. ~/.claude/settings.json
+
+**If NO existing file:**
+- Copy `global-claude-md/settings.json` directly to `~/.claude/settings.json`
+- Report: "Installed global settings.json (fresh install)"
+
+**If existing file found:**
+1. Read both settings files as JSON
+2. Merge the `permissions.deny` array — add any entries from the starter kit that aren't already present
+3. Merge the `hooks` object:
+   - For `PreToolUse`: add hooks that aren't already present (match by `command` string)
+   - For `Stop`: add hooks that aren't already present (match by `command` string)
+4. Write the merged result back
+5. Report what was added:
+   ```
+   Global settings.json merge:
+     + Added deny rule: Read(.env.production)
+     ✓ Hook verify-no-secrets.sh — already present, skipped
+     + Added Stop hook: verify-no-secrets.sh
+   ```
+
+**IMPORTANT:** NEVER remove existing permissions or hooks. Only add missing ones.
+
+### 2C. ~/.claude/hooks/
+
+1. Create `~/.claude/hooks/` if it doesn't exist:
+   ```bash
+   mkdir -p ~/.claude/hooks
+   ```
+
+2. Check if the project has hooks to install:
+   ```bash
+   ls .claude/hooks/ 2>/dev/null
+   ```
+
+3. For each hook file in the project's `.claude/hooks/`:
+   - If the file **already exists** at `~/.claude/hooks/` → **SKIP** (don't overwrite)
+   - If the file **does NOT exist** → **COPY** it
+   - Make all hooks executable: `chmod +x ~/.claude/hooks/*`
+
+4. Report:
+   ```
+   Global hooks:
+     + verify-no-secrets.sh — installed
+     ✓ verify-no-secrets.sh — already exists, skipped
+     + lint-on-save.sh — installed
+   ```
+
+## Step 4 — Verify Installation
+
+After all merges, verify:
+
+```bash
+echo "=== Global CLAUDE.md ==="
+[ -f ~/.claude/CLAUDE.md ] && echo "✓ exists" || echo "✗ MISSING"
+
+echo "=== Global settings.json ==="
+[ -f ~/.claude/settings.json ] && echo "✓ exists" || echo "✗ MISSING"
+
+echo "=== Global hooks ==="
+ls ~/.claude/hooks/ 2>/dev/null || echo "✗ NO HOOKS"
+```
+
+## Step 5 — Report
+
+```
+Global Config Installation Complete
+====================================
+
+~/.claude/CLAUDE.md:
+  [fresh install / merged X new sections / already up to date]
+
+~/.claude/settings.json:
+  [fresh install / merged X new rules / already up to date]
+
+~/.claude/hooks/:
+  [X hooks installed / X already existed]
+
+Your existing rules were NOT overwritten.
+New sections were appended. Review ~/.claude/CLAUDE.md to customize.
+
+TIP: Update the Identity section with your GitHub username:
+  ~/.claude/CLAUDE.md → ## Identity
+
+Next: /new-project my-app clean   — scaffold your first project
+```