@claude-code-mastery/starter-kit 1.0.0

package/.claude/commands/projects-created.md

@@ -0,0 +1,79 @@
+---
+description: List all projects created by the starter kit
+scope: starter-kit
+allowed-tools: Read, Bash(ls:*), Bash(date:*), Bash(stat:*), Bash(wc:*)
+---
+
+# Projects Created — Starter Kit Project Registry
+
+List every project that was scaffolded by `/new-project`, with creation date, profile used, and location.
+
+## Steps
+
+### 1. Read the registry
+
+Read `~/.claude/starter-kit-projects.json`. If the file does not exist, tell the user:
+
+> No projects have been created yet. Use `/new-project my-app` to scaffold your first project.
+
+And stop.
+
+### 2. Parse and validate
+
+The registry format is:
+
+```json
+{
+  "projects": [
+    {
+      "name": "my-app",
+      "path": "/home/user/projects/my-app",
+      "profile": "default",
+      "language": "node",
+      "framework": "next",
+      "database": "mongo",
+      "createdAt": "2025-01-15T10:30:00Z"
+    }
+  ]
+}
+```
+
+### 3. Check which projects still exist on disk
+
+For each project in the registry, check if the directory still exists:
+
+```bash
+ls -d /path/to/project 2>/dev/null
+```
+
+Mark projects whose directory no longer exists as `(missing)`.
+
+### 4. Display the table
+
+Print a formatted table sorted by creation date (newest first):
+
+```
+=== Projects Created by Starter Kit ===
+
+ #  Name              Profile       Language   Framework   Database   Created          Path
+ 1  my-app            default       node       next        mongo      2025-01-15       ~/projects/my-app
+ 2  my-api            python-api    python     fastapi     postgres   2025-01-14       ~/projects/my-api
+ 3  old-project       go            go         gin         mongo      2025-01-10       ~/projects/old-project (missing)
+
+Total: 3 projects (2 active, 1 missing)
+
+Tip: Use /remove-project <name> to remove a project and its registry entry.
+```
+
+### 5. Handle empty registry
+
+If the registry exists but has zero projects:
+
+> No projects in the registry. Use `/new-project my-app` to scaffold a project.
+
+### Notes
+
+- The registry is stored at `~/.claude/starter-kit-projects.json` (global — shared across all starter kit instances)
+- Projects are registered automatically by `/new-project` after successful scaffolding
+- Missing projects still appear in the list — use `/remove-project` to clean them up
+- The registry file is NEVER committed to git (it's in `~/.claude/`)

package/.claude/commands/quickstart.md

@@ -0,0 +1,105 @@
+---
+description: Interactive first-run walkthrough for new users
+scope: starter-kit
+allowed-tools: Bash(ls:*), Bash(cat:*), AskUserQuestion, Read
+---
+
+# Quickstart — First-Run Walkthrough
+
+Guide the user through their first experience with the Claude Code Starter Kit. This is an interactive walkthrough — ask questions, check state, and give personalized next steps.
+
+## Step 1 — Check Global Config
+
+```bash
+ls ~/.claude/CLAUDE.md 2>/dev/null && echo "GLOBAL_CONFIG=installed" || echo "GLOBAL_CONFIG=missing"
+```
+
+If `GLOBAL_CONFIG=missing`:
+
+Tell the user:
+
+```
+Your global Claude config isn't installed yet. This is a one-time setup that adds
+security rules and hooks across ALL your projects.
+
+Run: /install-global
+
+This smart-merges into your existing ~/.claude/ config — it never overwrites.
+Come back to /quickstart after it's done.
+```
+
+**Stop here if global config is missing.** Don't proceed until they install it.
+
+If `GLOBAL_CONFIG=installed`, continue to Step 2.
+
+## Step 2 — Ask Project Details
+
+Ask the user:
+
+**Question 1:** "What do you want to name your project?"
+
+Validate: lowercase letters, numbers, and hyphens only. No spaces, no uppercase. Show an example: `my-awesome-app`
+
+**Question 2:** "Which profile do you want to use?"
+
+Options:
+- **clean** — All Claude AI tools (commands, hooks, skills) with zero coding opinions. You pick your own language, framework, and structure. Best for: experienced developers who want Claude's tooling without opinionated scaffolding.
+- **default** — Full opinionated stack: Next.js, TypeScript, MongoDB, Tailwind, Docker, CI, Rybbit analytics, Playwright tests. Best for: new projects that want everything pre-configured.
+- **go** — Go project with standard layout (cmd/internal/), Gin router, golangci-lint, Makefile builds, and multi-stage Docker. Best for: developers who prefer Go over Node.js.
+- **vue** — Vue 3 SPA with Composition API, Tailwind, Vite. Best for: Vue developers building SPAs.
+- **nuxt** — Nuxt full-stack with auto-imports, SSR, MongoDB, Docker. Best for: Vue developers who need SSR.
+- **svelte** — Svelte SPA with Tailwind, Vite. Best for: developers who prefer compiled frameworks.
+- **sveltekit** — SvelteKit full-stack with SSR, MongoDB, Docker. Best for: Svelte developers who need SSR + API routes.
+- **angular** — Angular standalone components with Tailwind. Best for: enterprise Angular teams.
+- **python-api** — FastAPI with PostgreSQL, Docker. Best for: Python API developers.
+- **django** — Django full-stack with PostgreSQL, Docker. Best for: Python web developers.
+- **flask** — Flask API with PostgreSQL, Docker. Best for: lightweight Python APIs.
+
+## Step 3 — Tell Them to Scaffold
+
+Based on their answers, tell the user:
+
+```
+Great! Here's your next step:
+
+  /new-project $NAME $PROFILE
+
+This creates ~/projects/$NAME with everything wired up.
+```
+
+**Do NOT run `/new-project` for them.** Tell them to run it themselves — it's a separate command with its own interactive flow.
+
+## Step 4 — Show Next Steps
+
+After they understand the scaffolding command, show:
+
+```
+After scaffolding, here's your first 5 minutes:
+
+  1. cd ~/projects/$NAME
+  2. /setup                    Configure .env (database, GitHub, Docker, analytics)
+  3. pnpm install              Install dependencies
+  4. pnpm dev                  Start the dev server
+  5. Make a change             Edit any file
+  6. /review                   Run a code review on your changes
+  7. /commit                   Smart commit with conventional format
+
+Available commands (run /help for the full list):
+  /diagram all       Generate architecture diagrams from your actual code
+  /test-plan         Create a structured test plan for a feature
+  /create-api users  Scaffold a full API endpoint with types, handler, route, tests
+  /create-e2e login  Generate a Playwright E2E test with explicit assertions
+  /progress          Check project status and prioritized next actions
+```
+
+## Step 5 — Offer Docs
+
+Ask: "Want me to open the full documentation?"
+
+If yes, tell them:
+```
+Full interactive guide: https://thedecipherist.github.io/claude-code-mastery-project-starter-kit/
+Source guides: https://github.com/TheDecipherist/claude-code-mastery
+```
+
+If no, say: "You're all set! Run `/help` anytime to see all available commands."

package/.claude/commands/refactor.md

@@ -0,0 +1,267 @@
+---
+description: Refactor a file following all project best practices — split, type, extract, clean
+scope: project
+argument-hint: <file-path> [--dry-run]
+allowed-tools: Read, Write, Edit, Grep, Glob, Bash, AskUserQuestion
+---
+
+# Refactor — Best Practices Enforcement
+
+Refactor the target file following every rule in this project's CLAUDE.md.
+
+**Target:** $ARGUMENTS
+
+If `--dry-run` is passed, report what WOULD change without modifying any files.
+
+## Step 0 — Auto-Branch (if on main)
+
+Before making any changes, check the current branch:
+
+```bash
+git branch --show-current
+```
+
+**Default behavior** (`auto_branch = true` in `claude-mastery-project.conf`):
+- If on `main` or `master`: automatically create a feature branch and switch to it:
+  ```bash
+  git checkout -b refactor/<filename-without-extension>
+  ```
+  Report: "Created branch `refactor/<name>` — main stays untouched."
+- If already on a feature branch: proceed
+- If not a git repo: skip this check
+
+**To disable:** Set `auto_branch = false` in `claude-mastery-project.conf`. When disabled, warn and ask the user before proceeding on main.
+
+## Step 0.5 — Read Before Touching
+
+**NEVER refactor blind.** Read these files first:
+
+1. The target file (fully — every line)
+2. `CLAUDE.md` — to know the current project rules
+3. `project-docs/ARCHITECTURE.md` — to understand where things belong (if it exists)
+4. `tsconfig.json` — to check TypeScript strict mode settings (if it exists)
+
+Also check:
+```bash
+# What imports this file? (understand the blast radius)
+# Search for the filename in all source files
+```
+
+Report: "This file is imported by X other files. Changes here affect: [list]"
+
+## Step 1 — Audit the File
+
+Run through EVERY check below. For each violation found, note the line number, what's wrong, and what the fix is.
+
+### 1A. File Size (Rule 7: Quality Gates)
+
+- **> 300 lines = MUST split.** No exceptions.
+- Identify logical sections that can become their own files
+- Group by: types, constants, helpers/utilities, main logic, exports
+
+### 1B. Function Size (Rule 7: Quality Gates)
+
+- **> 50 lines = MUST extract.** No exceptions.
+- Identify functions that do multiple things — each "thing" becomes its own function
+- Name extracted functions by what they DO, not where they came from
+
+### 1C. TypeScript Compliance (Rule 1: TypeScript Always)
+
+- If the file is `.js` or `.jsx` → **convert to `.ts` / `.tsx`**
+- Find ALL `any` types → replace with proper types or `unknown`
+- Check for missing return types on exported functions
+- Check for missing parameter types
+- Check for implicit `any` (TypeScript should catch these in strict mode)
+- Check for `@ts-ignore` or `@ts-expect-error` — remove if possible, document if necessary
+
+### 1D. Import Hygiene (Coding Standards)
+
+- No barrel imports (`import * as everything from`)
+- No circular imports (A imports B, B imports A)
+- Types should use `import type { }` not `import { }`
+- Unused imports → remove
+- Sort: external packages first, then internal, then types
+
+### 1E. Error Handling (Coding Standards)
+
+- No swallowed errors (`catch { return null }`)
+- No empty catch blocks
+- Errors must be logged with context (what was being attempted, relevant IDs)
+- User-facing errors must have clear messages
+
+### 1F. Database Access (Rule 3)
+
+- No direct `MongoClient`, `pg`, `mysql2`, or other database driver imports — use StrictDB
+- All queries go through StrictDB (`queryOne`, `queryMany`, `insertOne`, etc.)
+- No `find()` or `findOne()` — use StrictDB's query API
+- Counters use `$inc` not read-modify-write
+
+### 1G. API Routes (Rule 2)
+
+- All endpoints use `/api/v1/` prefix
+- No business logic in route handlers — extract to `handlers/`
+
+### 1H. Independent Awaits (Rule 8)
+
+- Find sequential `await` calls that don't depend on each other
+- Wrap in `Promise.all`
+
+### 1I. Security (Rule 0 + Rule 5)
+
+- No hardcoded secrets, API keys, tokens, or connection strings
+- No SQL/NoSQL injection vulnerabilities
+- Input validation on external data
+
+### 1J. Dead Code
+
+- Unused functions → remove entirely (don't comment out)
+- Unused variables → remove
+- Unreachable code → remove
+- Commented-out code blocks → remove (that's what git history is for)
+
+## Step 2 — Plan the Refactor
+
+Before changing ANYTHING, present the plan to the user:
+
+```
+Refactor Plan for: src/handlers/users.ts (347 lines)
+=====================================================
+
+File size: 347 lines → SPLIT REQUIRED (max 300)
+
+Split into:
+  1. src/handlers/users.ts        — main handler (route logic, ~120 lines)
+  2. src/handlers/user-validation.ts — input validation helpers (~80 lines)
+  3. src/handlers/user-transforms.ts — data transformation functions (~60 lines)
+  4. src/types/user.ts             — User, CreateUserInput, UserResponse types (~40 lines)
+
+Function extraction:
+  - processUserSignup() (73 lines) → split into validateSignupInput() + createUserRecord() + sendWelcomeEmail()
+  - getUserDashboard() (62 lines) → split into fetchDashboardData() + formatDashboardResponse()
+
+TypeScript fixes:
+  - Line 45: `any` → `CreateUserInput`
+  - Line 89: missing return type → `Promise<UserResponse>`
+  - Line 134: `@ts-ignore` → proper null check
+
+Other fixes:
+  - Lines 23-25: sequential awaits → Promise.all (independent)
+  - Line 67: swallowed error → proper logging + rethrow
+  - Line 112: direct database driver import → use StrictDB
+  - Lines 200-215: dead code (commented out old auth) → remove
+
+Blast radius: imported by 3 files (server.ts, user-routes.ts, admin.ts)
+  - Imports will be updated to point to new file locations
+
+Proceed? (yes / no / modify plan)
+```
+
+**WAIT for user approval before making any changes.**
+
+Use named steps (Step 1, Step 2, etc.) so the user can say "skip Step 3" or "change Step 2 to keep validation inline."
+
+## Step 3 — Execute the Refactor
+
+After approval, make changes in this order:
+
+1. **Create new files first** (types, helpers, utilities)
+2. **Move code** from the original file to new files
+3. **Update imports** in the original file to reference new files
+4. **Update imports** in ALL files that imported from the original
+5. **Fix TypeScript** (types, return types, remove `any`)
+6. **Fix patterns** (Promise.all, error handling, dead code)
+7. **Verify TypeScript compiles:**
+   ```bash
+   npx tsc --noEmit 2>&1 | head -30
+   ```
+
+### Splitting Rules
+
+When splitting a file into multiple files:
+
+- **Types** → `src/types/<domain>.ts` (or colocated `<name>.types.ts`)
+- **Constants** → colocated `<name>.constants.ts` or `src/constants/`
+- **Helpers/Utilities** → colocated `<name>.utils.ts` or `src/utils/`
+- **Validation** → colocated `<name>.validation.ts`
+- **The original file** keeps the main logic and imports from the new files
+
+```typescript
+// BEFORE: one massive file
+// src/handlers/users.ts (347 lines — types, validation, helpers, handlers all mixed)
+
+// AFTER: clean separation
+// src/types/user.ts          — User, CreateUserInput, UserResponse
+// src/handlers/user-validation.ts — validateEmail(), validatePassword()
+// src/handlers/user-transforms.ts — formatUserResponse(), sanitizeInput()
+// src/handlers/users.ts      — handler functions only, imports from above
+```
+
+### Import Updates
+
+After splitting, update EVERY file that imported from the original:
+
+```typescript
+// BEFORE
+import { User, getUserById, validateEmail } from './handlers/users.js';
+
+// AFTER
+import type { User } from '../types/user.js';
+import { getUserById } from './handlers/users.js';
+import { validateEmail } from './handlers/user-validation.js';
+```
+
+## Step 4 — Verify
+
+After all changes:
+
+1. **TypeScript compiles clean:**
+   ```bash
+   npx tsc --noEmit
+   ```
+
+2. **No broken imports** — search for any import referencing moved/renamed exports:
+   ```bash
+   # Check for compilation errors
+   npx tsc --noEmit 2>&1 | grep "error TS"
+   ```
+
+3. **No file exceeds 300 lines**
+4. **No function exceeds 50 lines**
+5. **No remaining `any` types** (unless documented why)
+
+## Step 5 — RuleCatch Report
+
+After the refactor is complete, check RuleCatch:
+
+- If the RuleCatch MCP server is available: query for violations in the refactored files
+- Report any remaining violations
+- If no MCP: suggest checking the dashboard
+
+## Step 6 — Report
+
+```
+Refactor Complete: src/handlers/users.ts
+========================================
+Before: 1 file, 347 lines, 4 violations
+After:  4 files, ~300 lines total, 0 violations
+
+Files created:
+  ✓ src/types/user.ts (40 lines)
+  ✓ src/handlers/user-validation.ts (80 lines)
+  ✓ src/handlers/user-transforms.ts (60 lines)
+
+Files modified:
+  ✓ src/handlers/users.ts (120 lines — down from 347)
+  ✓ src/server.ts (imports updated)
+  ✓ src/routes/user-routes.ts (imports updated)
+
+Fixes applied:
+  ✓ 3 `any` types replaced with proper types
+  ✓ 2 functions extracted (were >50 lines)
+  ✓ 1 Promise.all optimization
+  ✓ 1 swallowed error fixed
+  ✓ 15 lines of dead code removed
+
+TypeScript: compiles clean ✓
+RuleCatch: no violations ✓
+```

package/.claude/commands/remove-project.md

@@ -0,0 +1,95 @@
+---
+description: Remove a project created by the starter kit
+scope: starter-kit
+argument-hint: <project-name>
+allowed-tools: Read, Edit, Bash(rm:*), Bash(ls:*), AskUserQuestion
+---
+
+# Remove Project — Unregister and Optionally Delete
+
+Remove a project from the starter kit registry and optionally delete its files from disk.
+
+**Arguments:** $ARGUMENTS
+
+## Steps
+
+### 1. Read the registry
+
+Read `~/.claude/starter-kit-projects.json`. If the file does not exist, tell the user:
+
+> No projects have been created yet. Nothing to remove.
+
+And stop.
+
+### 2. Find the project
+
+Search the registry for a project matching $ARGUMENTS (by name).
+
+**If no argument provided:**
+- List all projects by name
+- Ask via AskUserQuestion: "Which project do you want to remove?"
+- Options: list all project names from the registry
+
+**If the project name is not found:**
+- Tell the user: "Project `<name>` not found in the registry."
+- Show the list of registered projects
+- Stop
+
+### 3. Show project details
+
+Display the project details:
+
+```
+Project: my-app
+Path:    ~/projects/my-app
+Profile: default
+Language: node
+Framework: next
+Created: 2025-01-15
+Status:  exists on disk / directory not found
+```
+
+### 4. Ask what to do
+
+Ask via AskUserQuestion: "What do you want to do with this project?"
+
+- **Remove from registry only** — Keep the files, just remove the tracking entry
+- **Delete everything** — Delete the project directory AND remove from registry
+
+### 5a. If "Remove from registry only"
+
+- Read `~/.claude/starter-kit-projects.json`
+- Remove the matching project entry from the `projects` array
+- Write the updated registry back
+- Confirm: "Removed `<name>` from the project registry. Files at `<path>` are untouched."
+
+### 5b. If "Delete everything"
+
+**Safety check — ask for explicit confirmation:**
+
+Ask via AskUserQuestion: "Are you sure you want to permanently delete `<path>` and all its contents? This cannot be undone."
+
+- **Yes, delete it** — Proceed with deletion
+- **No, cancel** — Stop without deleting
+
+**If confirmed:**
+
+1. Check if the project directory exists on disk
+2. If it exists:
+   - Check for uncommitted git changes: `cd <path> && git status --porcelain 2>/dev/null`
+   - If there are uncommitted changes, WARN the user and ask again: "This project has uncommitted changes. Are you SURE you want to delete?"
+   - Delete the directory: `rm -rf <path>`
+3. Remove the entry from `~/.claude/starter-kit-projects.json`
+4. Confirm: "Deleted `<path>` and removed `<name>` from the registry."
+
+**If the directory doesn't exist:**
+- Just remove from registry
+- Confirm: "Directory `<path>` was already gone. Removed `<name>` from the registry."
+
+### Safety Rules
+
+- NEVER delete without explicit user confirmation
+- ALWAYS warn about uncommitted changes before deletion
+- NEVER delete directories outside the registered path
+- ALWAYS show what will be deleted before doing it
+- The registry itself (`~/.claude/starter-kit-projects.json`) is never deleted — only entries are removed

package/.claude/commands/review.md

@@ -0,0 +1,59 @@
+---
+description: Review code for bugs, security issues, and best practices
+scope: project
+allowed-tools: Read, Grep, Glob, Bash(git diff:*)
+---
+
+# Code Review
+
+Review the current changes for:
+
+## Branch Check
+
+Verify the current branch context:
+
+```bash
+git branch --show-current
+```
+
+- If on `main` or `master` and `auto_branch = true` in `claude-mastery-project.conf`: warn — "You're reviewing changes directly on main. Next time, start work on a feature branch."
+- Report which branch is being reviewed in the output header
+- Review is read-only so no auto-branch is created, but the warning reminds the user for future commands
+
+## Context
+- Current diff: !`git diff HEAD`
+- Staged changes: !`git diff --cached`
+
+## Review Checklist
+
+1. **Security** — OWASP Top 10, no secrets in code, proper input validation
+2. **Types** — No `any`, proper null handling, explicit return types
+3. **Error Handling** — No swallowed errors, proper logging, user-friendly messages
+4. **Performance** — No N+1 queries, no memory leaks, proper pagination
+5. **Testing** — New code has tests, tests have explicit assertions
+6. **Database** — StrictDB if installed, otherwise the native driver (in the adapter); never Mongoose, never a raw driver in handlers
+7. **API Versioning** — All endpoints use `/api/v1/` prefix
+
+## RuleCatch Report
+
+After completing the manual review, query RuleCatch for automated violations on the changed files:
+
+- If the RuleCatch MCP server is available: query for violations on the files in the current diff
+- Include results in a dedicated section of the review output (see format below)
+- This catches pattern-based violations the manual review might miss
+- If no MCP available: suggest — "Ask `RuleCatch, what violations happened today?` for automated checks"
+
+## Output Format
+
+For each issue found:
+- **File**: path/to/file.ts:line
+- **Severity**: 🔴 Critical | 🟡 Warning | 🔵 Info
+- **Issue**: Description
+- **Fix**: Suggested change
+
+### RuleCatch Violations
+| File | Rule | Severity | Details |
+|------|------|----------|---------|
+| ... | ... | ... | ... |
+
+If no RuleCatch violations: "RuleCatch: No violations detected"

package/.claude/commands/security-check.md

@@ -0,0 +1,77 @@
+---
+description: Scan project for security issues — exposed secrets, missing .gitignore entries, unsafe patterns
+scope: project
+allowed-tools: Read, Grep, Glob, Bash(git:*), Bash(grep:*), Bash(find:*)
+---
+
+# Security Check
+
+Scan this project for security vulnerabilities.
+
+## Checks to Perform
+
+### 1. Secrets in Code
+```bash
+# Search for common secret patterns in tracked files
+git grep -n -E '(api[_-]?key|secret[_-]?key|password|token)\s*[:=]\s*["\x27][A-Za-z0-9+/=_-]{8,}' -- ':!*.lock' ':!node_modules' 2>/dev/null || echo "No secrets found in code"
+
+# Search for AWS keys
+git grep -n 'AKIA[0-9A-Z]\{16\}' 2>/dev/null || echo "No AWS keys found"
+
+# Search for hardcoded URLs with credentials
+git grep -n -E '(https?://[^:]+:[^@]+@)' 2>/dev/null || echo "No credential URLs found"
+```
+
+### 2. .gitignore Coverage
+Verify these entries exist in .gitignore:
+- [ ] `.env`
+- [ ] `.env.*`
+- [ ] `.env.local`
+- [ ] `node_modules/`
+- [ ] `dist/`
+- [ ] `CLAUDE.local.md`
+- [ ] `*.log`
+
+### 3. Sensitive Files Check
+```bash
+# Check if any sensitive files are tracked by git
+for f in .env .env.local .env.production secrets.json credentials.json id_rsa .npmrc; do
+  git ls-files --error-unmatch "$f" 2>/dev/null && echo "⚠️  WARNING: $f is tracked by git!"
+done
+echo "Sensitive file check complete."
+```
+
+### 4. .env File Verification
+- [ ] `.env` exists but is NOT in git
+- [ ] `.env.example` exists and IS in git
+- [ ] `.env.example` has NO real values (only placeholders)
+
+### 5. Dependency Audit
+```bash
+# Check for known vulnerabilities (if npm project)
+[ -f "package.json" ] && npm audit --production 2>/dev/null | head -20 || echo "Not an npm project"
+```
+
+### 6. RuleCatch Security Violations
+
+Query RuleCatch for security-category violations in the current project:
+
+- If the RuleCatch MCP server is available: query for violations with category "security"
+- Report: rule name, file, severity, and description for each violation
+- This catches patterns the manual scan might miss (insecure dependencies, unsafe type coercions, missing rate limiting, etc.)
+- If no MCP available: suggest — "Install RuleCatch MCP for automated security monitoring — `npx @rulecatch/mcp-server init`"
+
+## Output Format
+
+| Check | Status | Details |
+|-------|--------|---------|
+| Secrets in code | ✅/❌ | ... |
+| .gitignore coverage | ✅/❌ | ... |
+| Sensitive files tracked | ✅/❌ | ... |
+| .env handling | ✅/❌ | ... |
+| Dependencies | ✅/❌ | ... |
+| RuleCatch security | ✅/❌ | ... |
+
+**Overall: PASS / FAIL**
+
+List any specific remediation steps needed.