@claude-code-mastery/starter-kit 1.0.0

package/.claude/commands/set-project-profile-default.md

@@ -0,0 +1,79 @@
+---
+description: Set the default profile for /new-project
+scope: starter-kit
+allowed-tools: Read, Edit, AskUserQuestion
+---
+
+# Set Project Profile Default
+
+Set which profile `/new-project` uses by default when no profile is specified.
+
+**Arguments:** $ARGUMENTS
+
+## Usage
+
+```
+/set-project-profile-default go              → sets default_profile = go
+/set-project-profile-default clean           → sets default_profile = clean
+/set-project-profile-default default         → sets default_profile = default
+/set-project-profile-default python-api      → sets default_profile = python-api
+/set-project-profile-default mongo next tailwind docker
+  → creates/updates [user-default] profile with those settings
+  → sets default_profile = user-default
+/set-project-profile-default (no args)
+  → shows current default, asks what to change
+```
+
+## Steps
+
+### 1. Read the config file
+
+Read `claude-mastery-project.conf` from the project root. If not found, check `~/.claude/claude-mastery-project.conf`.
+
+Extract:
+- All `[section]` names (these are the available profiles)
+- Current `default_profile` value from `[global]` (if set)
+
+### 2. Parse arguments
+
+**$ARGUMENTS** can be:
+
+**A) No arguments** — show current state and ask:
+- Display the current `default_profile` value (or "not set" if absent)
+- List all available profiles with a one-line summary of each
+- Ask via AskUserQuestion: "Which profile should be the default?"
+  - Options: list all profile section names from the conf file
+- After selection, proceed to Step 3
+
+**B) Single argument matching an existing `[section]` name** (e.g., `go`, `clean`, `default`, `api`, `vue`, `python-api`):
+- Proceed to Step 3 with that profile name
+
+**C) Multiple arguments** (e.g., `mongo next tailwind docker`):
+- Parse as shorthand options using the same parser as `/new-project`:
+  - **Languages:** `node`, `go`, `python`
+  - **Frameworks:** `vite`, `react`, `next`, `vue`, `nuxt`, `svelte`, `sveltekit`, `angular`, `astro`, `fastify`, `express`, `hono`, `gin`, `chi`, `echo`, `fiber`, `stdlib`, `fastapi`, `django`, `flask`
+  - **Database:** `mongo`, `postgres`, `mysql`, `mssql`, `sqlite`
+  - **Hosting:** `dokploy`, `vercel`, `static`
+  - **Package managers:** `pnpm`, `npm`, `bun`, `pip`, `uv`, `poetry`
+  - **Options:** `seo`, `ssr`, `tailwind`, `prisma`, `docker`, `ci`, `multiregion`
+  - **Analytics:** `rybbit`
+  - **MCP:** `playwright`, `context7`, `rulecatch`
+- Create or update a `[user-default]` section in the conf file with the parsed settings
+- Set `default_profile = user-default` in `[global]`
+- Proceed to Step 4 (confirmation)
+
+### 3. Set default_profile in `[global]`
+
+In the `[global]` section:
+- If `default_profile` already exists → change its value to the chosen profile
+- If `default_profile` does not exist → add it after the last line in `[global]` (before the next `[section]`)
+
+### 4. Confirm
+
+Read the file back and confirm the change was applied. Show the updated `[global]` section to the user.
+
+Tell the user:
+
+> Done. `/new-project PROJECTNAME` will now use the `<profile>` profile by default. You can still override with `/new-project PROJECTNAME <other-profile>` or any other profile name.
+
+If the user used multiple shorthand arguments (option C), also show the `[user-default]` section that was created/updated.

package/.claude/commands/setup.md

@@ -0,0 +1,337 @@
+---
+description: Interactive project setup — configure .env, GitHub, Docker, analytics, and services
+scope: project
+argument-hint: [--reset]
+allowed-tools: Bash, Read, Write, Edit, AskUserQuestion
+---
+
+# Project Setup
+
+Walk the user through configuring all environment variables and project settings. Creates or updates the `.env` file with real values while keeping `.env.example` as the template.
+
+**Arguments:** $ARGUMENTS
+
+If `--reset` is passed, start fresh (re-ask all questions even if .env already has values).
+
+## Step 0 — Check Current State
+
+```bash
+# Does .env exist?
+ls .env 2>/dev/null
+
+# Does .env.example exist?
+ls .env.example 2>/dev/null
+
+# Is .env in .gitignore?
+grep -q "^\.env$" .gitignore 2>/dev/null && echo ".env is gitignored" || echo "WARNING: .env NOT in .gitignore"
+```
+
+If `.env` doesn't exist, create it from `.env.example`.
+If `.env.example` doesn't exist, create a blank `.env`.
+If `.env` is NOT in `.gitignore`, add it immediately before proceeding.
+
+## Step 0.5 — Development Environment Check (WSL)
+
+Detect the current environment:
+
+```bash
+# Check if running on WSL
+uname -r 2>/dev/null | grep -qi "microsoft\|wsl" && echo "WSL_DETECTED=true" || echo "WSL_DETECTED=false"
+
+# Check if running on Windows (not WSL)
+uname -s 2>/dev/null | grep -qi "mingw\|msys\|cygwin" && echo "WINDOWS_NATIVE=true" || echo "WINDOWS_NATIVE=false"
+
+# Check current working directory — is the project on the Windows filesystem from WSL?
+pwd | grep -q "^/mnt/c\|^/mnt/d" && echo "PROJECT_ON_WINDOWS_FS=true" || echo "PROJECT_ON_WINDOWS_FS=false"
+```
+
+### If on Windows (native, not WSL):
+
+Tell the user:
+
+```
+⚠️  You're running on Windows natively.
+
+STRONGLY RECOMMENDED: Use WSL 2 (Windows Subsystem for Linux) instead.
+
+Why this matters:
+  • HMR (hot module replacement) is 5-10x faster in WSL
+  • Playwright tests run significantly faster on native Linux
+  • File watching (nodemon, tsx watch, next dev) is dramatically more reliable
+  • Node.js filesystem operations avoid the NTFS translation layer
+  • Claude Code itself runs faster with native Linux tools (grep, find, git)
+
+Setup (one time):
+  1. Open PowerShell as admin: wsl --install
+  2. Restart your computer
+  3. Install VS Code extension: "WSL" (ms-vscode-remote.remote-wsl)
+  4. Open VS Code → click green "><" bottom-left → "Connect to WSL"
+  5. Clone your projects INSIDE WSL: ~/projects/ (NOT /mnt/c/)
+
+After setup, VS Code runs its backend inside WSL while the UI stays on Windows.
+Everything just works — terminal, extensions, git, Node.js — all running natively in Linux.
+```
+
+### If on WSL but project is on the Windows filesystem (/mnt/c/ or /mnt/d/):
+
+Tell the user:
+
+```
+⚠️  You're on WSL but your project is on the Windows filesystem (/mnt/c/...).
+
+This kills most WSL performance benefits. File operations between WSL and the
+Windows filesystem go through a slow translation layer — you get the worst of
+both worlds.
+
+MOVE YOUR PROJECT to the native WSL filesystem:
+  mkdir -p ~/projects
+  cp -r /mnt/c/Users/you/projects/my-app ~/projects/my-app
+  cd ~/projects/my-app
+
+Then open VS Code from WSL:
+  code .
+
+This alone can make HMR 5-10x faster and fix unreliable file watching.
+```
+
+### If on WSL with project on Linux filesystem:
+
+```
+✓ WSL detected with project on native Linux filesystem — optimal setup.
+```
+
+### If on macOS or native Linux:
+
+Skip this check entirely — no action needed.
+
+## Step 1 — Read .env.example for Categories
+
+Read `.env.example` to understand what variables this project needs. Group them by category based on comments/sections.
+
+## Step 2 — Interactive Configuration
+
+Ask the user about each category. For each variable, show the current value (if set in .env) and ask if they want to change it. Skip variables that already have real values unless `--reset` was passed.
+
+### Category: Application Basics
+- `NODE_ENV` — Usually `development` (default, don't ask unless --reset)
+- `PORT` — Which port? (show current value)
+
+### Category: GitHub
+- GitHub username — for git remote URLs and PR creation
+- SSH or HTTPS — which auth method for git?
+
+Ask: "What's your GitHub username?"
+Ask: "Do you use SSH or HTTPS for git?"
+
+### Category: Analytics (Rybbit)
+Ask: "Do you use Rybbit analytics?" (yes/no)
+If yes:
+- `NEXT_PUBLIC_RYBBIT_SITE_ID` — "What's your Rybbit site ID for this project? (Find it at https://app.rybbit.io)"
+- `NEXT_PUBLIC_RYBBIT_URL` — Default `https://app.rybbit.io`
+
+### Category: Multi-Region
+
+**Ask first:** "Single-server or multi-region? (Most projects use single-server.)"
+
+Default: **single-server**. If the user picks single-server, skip to the Database category below.
+
+If the user picks **multi-region**, show this complexity warning BEFORE proceeding:
+
+```
+⚠️  Multi-region adds significant complexity:
+
+  • Separate VPS, database, and Dokploy instance PER region
+  • Suffixed environment variables (_US, _EU) for every service
+  • Region-tagged Docker images (:latest for US, :eu for EU)
+  • Region routing logic in your application code
+  • Every deployment must update ALL regions to stay in sync
+
+Most projects don't need this. Single-server handles significant traffic
+and you can always add regions later.
+```
+
+**After showing the warning, ask:** "Continue with multi-region setup? (yes/no)"
+
+If they say no, fall back to single-server. If they confirm yes, proceed with multi-region.
+
+If **yes (confirmed)** — ask: "Which regions?" (default: US + EU). Then EVERY region-specific service gets its own suffixed variables. The `.env` file becomes the **region map** — Claude must ALWAYS check it to know which region is which.
+
+**CRITICAL MULTI-REGION RULES (written to project CLAUDE.md):**
+
+```markdown
+## Multi-Region Architecture
+
+This project deploys to multiple regions. EVERY region has isolated infrastructure.
+
+### Region Map (from .env)
+- `_US` suffix = US region (e.g., STRICTDB_URI_US, DOKPLOY_URL_US)
+- `_EU` suffix = EU region (e.g., STRICTDB_URI_EU, DOKPLOY_URL_EU)
+- No suffix = default/shared (e.g., DOCKER_IMAGE_NAME applies to all regions)
+
+### ABSOLUTE RULES
+- US containers NEVER connect to EU databases. EU containers NEVER connect to US databases.
+- DEPLOY_REGION env var tells the container which region it's in at runtime.
+- When deploying: ALWAYS deploy to ALL regions. Never leave them out of sync.
+- When pushing Docker images: `:latest` for US, `:eu` tag for EU.
+- Each region has its own Dokploy instance, its own VPS, its own database.
+- If you're unsure which region a variable belongs to, READ .env and check the suffix.
+```
+
+### Category: Database
+
+If single-region:
+- Ask: "What database are you using?" (MongoDB / PostgreSQL / MySQL / SQLite / None)
+- Ask for connection string (StrictDB auto-detects backend from URI scheme)
+- Writes: `STRICTDB_URI=...`
+
+If multi-region:
+- Ask for EACH region's database separately:
+  - "What's the database connection string for **US**?" → `STRICTDB_URI_US`
+  - "What's the database connection string for **EU**?" → `STRICTDB_URI_EU`
+- Offer to build from parts for each region (MongoDB example):
+  - US: username, password, cluster → `STRICTDB_URI_US=mongodb+srv://user:pass@us-cluster/dbname`
+  - EU: username, password, cluster → `STRICTDB_URI_EU=mongodb+srv://user:pass@eu-cluster/dbname`
+
+**NEVER display connection strings back.** Just confirm "US database configured ✓" / "EU database configured ✓"
+
+### Category: Docker
+If the project has a Dockerfile or docker-compose.yml:
+- `DOCKER_HUB_USER` — "What's your Docker Hub username?"
+- `DOCKER_IMAGE_NAME` — Suggest `<docker-user>/<project-name>` (shared across regions)
+
+If multi-region, explain the tagging convention:
+```
+US deployment: docker push $DOCKER_IMAGE_NAME:latest
+EU deployment: docker tag $DOCKER_IMAGE_NAME:latest $DOCKER_IMAGE_NAME:eu && docker push $DOCKER_IMAGE_NAME:eu
+```
+
+### Category: Deployment (Dokploy / Hostinger VPS)
+
+Ask: "Are you using Dokploy on Hostinger VPS for deployment?" (yes/no)
+
+If single-region:
+- `DOKPLOY_URL` — "What's your Dokploy URL? (e.g., http://your-vps-ip:3000/api)"
+- `DOKPLOY_API_KEY` — "What's your Dokploy API key?"
+- `DOKPLOY_APP_ID` — "What's your Dokploy application ID?"
+- `DOKPLOY_REFRESH_TOKEN` — "What's your webhook refresh token? (for automated deploys)"
+- `VPS_IP` — "What's your Hostinger VPS IP address?"
+
+If multi-region — ask for EACH region separately:
+
+**US Region:**
+- `VPS_IP_US` — "What's your US Hostinger VPS IP?"
+- `DOKPLOY_URL_US` — Auto-suggest `http://<VPS_IP_US>:3000/api`
+- `DOKPLOY_API_KEY_US` — "Dokploy API key for US?"
+- `DOKPLOY_APP_ID_US` — "Dokploy application ID for US?"
+- `DOKPLOY_REFRESH_TOKEN_US` — "Webhook refresh token for US?"
+
+**EU Region:**
+- `VPS_IP_EU` — "What's your EU Hostinger VPS IP?"
+- `DOKPLOY_URL_EU` — Auto-suggest `http://<VPS_IP_EU>:3000/api`
+- `DOKPLOY_API_KEY_EU` — "Dokploy API key for EU?"
+- `DOKPLOY_APP_ID_EU` — "Dokploy application ID for EU?"
+- `DOKPLOY_REFRESH_TOKEN_EU` — "Webhook refresh token for EU?"
+
+After collecting, explain:
+```
+Region routing:
+  US VPS (<VPS_IP_US>) → Dokploy US → pulls :latest → connects to STRICTDB_URI_US
+  EU VPS (<VPS_IP_EU>) → Dokploy EU → pulls :eu    → connects to STRICTDB_URI_EU
+
+Each container gets DEPLOY_REGION=us or DEPLOY_REGION=eu at runtime.
+The app reads DEPLOY_REGION and picks the right database URI.
+```
+
+### Category: RuleCatch
+Ask: "Do you use RuleCatch for AI monitoring?" (yes/no)
+If yes:
+- `RULECATCH_API_KEY` — "What's your RuleCatch API key? (starts with dc_)"
+- `RULECATCH_REGION` — "Which region?" (us / eu)
+
+### Category: Authentication
+If `JWT_SECRET` is in .env.example:
+- Offer to generate a random JWT secret: `node -e "console.log(require('crypto').randomBytes(64).toString('hex'))"`
+- Or let the user provide their own
+
+### Category: Other Variables
+For any remaining variables in `.env.example` that weren't covered above:
+- Show the variable name and placeholder value
+- Ask for the real value
+
+## Step 3 — Write .env
+
+Write all configured values to `.env`. Format with category comments matching `.env.example`.
+
+**CRITICAL RULES:**
+- NEVER display secrets back to the user after they enter them
+- NEVER commit the .env file
+- Confirm .env is in .gitignore after writing
+- Show a summary of what was configured (category names only, NOT values)
+
+## Step 4 — Update .env.example
+
+If the user added any NEW variables that aren't in `.env.example`, add them with placeholder values so the template stays in sync.
+
+## Step 5 — Write Multi-Region Rules to CLAUDE.md
+
+If multi-region was selected, append the multi-region architecture rules (from the Category section above) to the project's `CLAUDE.md`. This ensures Claude ALWAYS knows the region map for this project.
+
+Also write a region reference comment block at the top of `.env`:
+
+```bash
+# ==========================================
+# REGION MAP
+# ==========================================
+# _US suffix = US region infrastructure
+# _EU suffix = EU region infrastructure
+# No suffix  = shared across all regions
+#
+# US: VPS_IP_US → DOKPLOY_URL_US → STRICTDB_URI_US
+# EU: VPS_IP_EU → DOKPLOY_URL_EU → STRICTDB_URI_EU
+# ==========================================
+```
+
+## Step 6 — Report
+
+**Single-region report:**
+```
+Project Setup Complete
+======================
+✓ Application basics (NODE_ENV, PORT)
+✓ GitHub (username: <username>)
+✓ Analytics (Rybbit configured)
+✓ Database (connected via StrictDB)
+✓ Docker (image: <user>/<project>)
+✓ Deployment (Dokploy on Hostinger)
+✓ RuleCatch (region: us)
+✗ Multi-region (single region)
+
+.env is gitignored: ✓
+.env.example updated: ✓
+```
+
+**Multi-region report:**
+```
+Project Setup Complete
+======================
+✓ Application basics (NODE_ENV, PORT)
+✓ GitHub (username: <username>)
+✓ Analytics (Rybbit configured)
+✓ Multi-region (US + EU)
+✓ Database US (connected via StrictDB)
+✓ Database EU (connected via StrictDB)
+✓ Docker (image: <user>/<project>, tags: :latest for US, :eu for EU)
+✓ Deployment US (Dokploy on Hostinger — <VPS_IP_US>)
+✓ Deployment EU (Dokploy on Hostinger — <VPS_IP_EU>)
+✓ RuleCatch (region: us)
+
+Region routing:
+  US: <VPS_IP_US> → Dokploy US → :latest → STRICTDB_URI_US
+  EU: <VPS_IP_EU> → Dokploy EU → :eu     → STRICTDB_URI_EU
+
+.env is gitignored: ✓
+.env.example updated: ✓
+CLAUDE.md updated with region map: ✓
+```
+
+Show ✓ for configured categories, ✗ for skipped ones.

package/.claude/commands/show-user-guide.md

@@ -0,0 +1,58 @@
+---
+description: Open the comprehensive User Guide in your browser
+scope: project
+allowed-tools: Bash
+---
+
+Open the User Guide for the Claude Code Mastery Project Starter Kit.
+
+## Steps
+
+1. **Check for the HTML file** at `docs/user-guide.html` in the project root.
+
+2. **Open in browser** — try the GitHub Pages URL first, fall back to local file:
+
+   **Primary (online):**
+   ```
+   https://thedecipherist.github.io/claude-code-mastery-project-starter-kit/user-guide.html
+   ```
+
+   **Fallback (local):**
+   ```
+   docs/user-guide.html
+   ```
+
+3. **Detect the environment** and use the correct open command:
+   - **WSL:** `wslview <url>`
+   - **macOS:** `open <url>`
+   - **Linux:** `xdg-open <url>`
+
+4. **Also mention** the markdown version is available at `USER_GUIDE.md` in the project root for reading directly in GitHub or a text editor.
+
+## Detection Logic
+
+```bash
+# Detect platform and open URL
+URL="https://thedecipherist.github.io/claude-code-mastery-project-starter-kit/user-guide.html"
+LOCAL="docs/user-guide.html"
+
+if grep -qi microsoft /proc/version 2>/dev/null; then
+  # WSL
+  wslview "$URL" 2>/dev/null || wslview "$LOCAL" 2>/dev/null || echo "Could not open browser. Visit: $URL"
+elif [[ "$OSTYPE" == "darwin"* ]]; then
+  # macOS
+  open "$URL" 2>/dev/null || open "$LOCAL" 2>/dev/null || echo "Could not open browser. Visit: $URL"
+else
+  # Linux
+  xdg-open "$URL" 2>/dev/null || xdg-open "$LOCAL" 2>/dev/null || echo "Could not open browser. Visit: $URL"
+fi
+```
+
+## Output
+
+After opening, tell the user:
+
+> User Guide opened in your browser.
+> - **Online:** https://thedecipherist.github.io/claude-code-mastery-project-starter-kit/user-guide.html
+> - **Markdown:** `USER_GUIDE.md` (project root)
+> - **Tip:** Use `/help` to see all available commands at any time.

package/.claude/commands/starter-kit.md

@@ -0,0 +1,90 @@
+---
+description: "Manage the @claude-code-mastery/starter-kit installation — update, check status, or add to the current project."
+scope: project
+argument-hint: "update | status | add"
+allowed-tools: Bash, Read, Write, Edit, AskUserQuestion
+---
+
+# /starter-kit
+
+Manage the globally installed @claude-code-mastery/starter-kit.
+
+The kit is installed in `~/.claude/starter-kit/`. Commands and skills are symlinked from there into `~/.claude/commands/` and `~/.claude/skills/`, so updating the starter-kit directory instantly updates everything without needing to re-symlink.
+
+## Detect subcommand
+
+Read the user's argument: **$ARGUMENTS**
+
+- `update` → run Update flow below
+- `status` → run Status flow below
+- `add` → run Add flow below
+- empty or unrecognised → show usage
+
+---
+
+## Update flow
+
+Check whether npm is available, then run:
+
+```bash
+npx @claude-code-mastery/starter-kit update
+```
+
+This overwrites `~/.claude/starter-kit/` with the latest published version, symlinks any new commands or skills that were added, and registers any new hooks in `~/.claude/settings.json`.
+
+After the command completes, report the version that is now installed:
+
+```bash
+cat ~/.claude/starter-kit/version
+```
+
+Tell the user: "✅ Starter kit updated to v<version>. New commands and hooks are active immediately."
+
+If npm / npx is not available, tell the user to install Node.js from https://nodejs.org and then run `npx @claude-code-mastery/starter-kit update` in their terminal.
+
+---
+
+## Status flow
+
+Check the installed version and compare with the registry:
+
+```bash
+npx @claude-code-mastery/starter-kit status
+```
+
+Show the output to the user as-is. If the kit is not installed, tell the user to run `npx @claude-code-mastery/starter-kit init` from any terminal to install it.
+
+---
+
+## Add flow
+
+Install the starter kit into the **current project's** `.claude/` directory. This is the project-level equivalent of the global install — it gives the project its own copy of commands, hooks, and skills that Claude Code picks up automatically.
+
+Steps:
+1. Check whether `~/.claude/starter-kit/` exists. If not, tell the user to run the global install first: `npx @claude-code-mastery/starter-kit init`
+2. Check whether `.claude/` already exists in the current project:
+   - If it does, ask the user: "`.claude/` already exists in this project. Merge the starter-kit files in? Existing files with matching names will NOT be overwritten." (yes / no)
+   - If no: stop.
+3. Copy from `~/.claude/starter-kit/` into `.claude/`:
+   ```bash
+   cp -rn ~/.claude/starter-kit/commands/ .claude/commands/
+   cp -rn ~/.claude/starter-kit/hooks/ .claude/hooks/
+   cp -rn ~/.claude/starter-kit/skills/ .claude/skills/
+   ```
+   (`-n` = no-clobber: never overwrites existing files)
+4. If `.claude/settings.json` does not exist in the project, copy from the starter-kit:
+   ```bash
+   cp ~/.claude/starter-kit/settings.json .claude/settings.json
+   ```
+   If it does exist, remind the user to manually merge the hook entries from `~/.claude/starter-kit/settings.json` if needed.
+5. Report: "✅ Starter kit added to this project's .claude/ directory. Commands and hooks are active for this project."
+
+---
+
+## Usage (when no subcommand given)
+
+```
+/starter-kit update   — update to latest version from npm
+/starter-kit status   — show installed version vs latest
+/starter-kit add      — add kit to current project's .claude/
+```

package/.claude/commands/test-plan.md

@@ -0,0 +1,118 @@
+---
+description: Generate a structured test plan for a feature
+scope: project
+argument-hint: <feature-name>
+---
+
+# Test Plan Generator
+
+Create a structured test plan for: **$ARGUMENTS**
+
+## Auto-Branch (if on main)
+
+Before creating test plan files, 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 test/<feature-name>-plan
+  ```
+  Report: "Created branch `test/<feature>-plan` — 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.
+
+## Template
+
+Generate the following markdown document:
+
+```markdown
+# [Feature] Test Plan
+
+**Created:** [today's date]
+**Feature:** $ARGUMENTS
+**Status:** ⬜ Not Started
+
+---
+
+## Quick Status
+
+Feature Area A:    ⬜ NOT TESTED
+Feature Area B:    ⬜ NOT TESTED
+Feature Area C:    ⬜ NOT TESTED
+
+---
+
+## Prerequisites
+
+- [ ] Required services running
+- [ ] Test data created
+- [ ] Environment variables set
+
+---
+
+## Test 1: [Happy Path]
+
+### 1.1 [Core scenario]
+
+**Action:** [What to do]
+**Expected:** [What should happen — be SPECIFIC]
+
+| Check | Expected | Actual | Status |
+|-------|----------|--------|--------|
+| Response code | 200 | | ⬜ |
+| Data returned | [specific shape] | | ⬜ |
+| UI updated | [specific change] | | ⬜ |
+
+---
+
+## Test 2: [Error Cases]
+
+### 2.1 [Invalid input]
+
+**Action:** [What to do]
+**Expected:** [Specific error message/behavior]
+
+---
+
+## Test 3: [Edge Cases]
+
+### 3.1 [Empty state]
+### 3.2 [Maximum values]
+### 3.3 [Concurrent access]
+
+---
+
+## Pass/Fail Criteria
+
+| Criteria | Pass | Fail |
+|----------|------|------|
+| All happy paths work | Yes | Any failure |
+| Error messages shown | Yes | Silent failure |
+| Data persists | Yes | Lost on refresh |
+
+---
+
+## Sign-Off
+
+| Test | Tester | Date | Status |
+|------|--------|------|--------|
+| Test 1 | | | ⬜ |
+| Test 2 | | | ⬜ |
+| Test 3 | | | ⬜ |
+```
+
+Save to `tests/plans/[feature-name]-test-plan.md`
+
+## RuleCatch Report
+
+After saving the test plan, check RuleCatch:
+
+- If the RuleCatch MCP server is available: query for violations related to testing in the project
+- Report any violations found (missing test coverage, untested features, etc.)
+- If no MCP: suggest checking the RuleCatch dashboard