@claude-code-mastery/starter-kit 1.0.0

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

@@ -0,0 +1,413 @@
+---
+description: Update a starter-kit project with the latest commands, hooks, skills, and rules
+scope: starter-kit
+argument-hint: [--force | --clean]
+allowed-tools: Read, Write, Edit, Bash, Grep, Glob, AskUserQuestion
+---
+
+# Update Starter Kit Project
+
+Update an existing starter-kit project with the latest commands, hooks, skills, and rules from the current starter kit source. Smart merge — replaces starter kit files with newer versions while preserving any custom files the user created themselves.
+
+**Arguments:** $ARGUMENTS
+
+---
+
+## Step 0 — Resolve Source (Starter Kit)
+
+Find the starter kit source directory:
+
+1. If CWD has BOTH `claude-mastery-project.conf` AND `.claude/commands/new-project.md` → use CWD as `$SOURCE`
+2. Else read `~/.claude/starter-kit-source-path` → verify it still has both files
+3. Else ask via AskUserQuestion: "Where is the starter kit cloned?" with a text input
+
+Store as `$SOURCE`.
+
+---
+
+## Step 1 — Registry Picker (Select Target)
+
+1. Read `~/.claude/starter-kit-projects.json`
+   - If file doesn't exist or empty → error: "No projects found. Use `/new-project` to create one first."
+   - If file is invalid JSON → error: "Project registry is corrupted. Check `~/.claude/starter-kit-projects.json`."
+
+2. Filter to projects whose `path` directory still exists on disk
+
+3. If no valid projects remain → error: "No registered projects found on disk. Use `/new-project` to create one."
+
+4. Display list with AskUserQuestion:
+   - "Which project do you want to update?"
+   - Options: up to 4 most recent projects (by `createdAt`), each showing: `name — language/framework — path`
+   - If more than 4: the 4th option should be "Other (type a path)"
+
+5. Store selected path as `$TARGET`
+
+### Validations (all must pass — stop with clear error if any fail)
+
+1. `$TARGET` directory exists → if not: "Directory not found: $TARGET"
+2. `$TARGET` is a git repo → run: `git -C "$TARGET" rev-parse --is-inside-work-tree 2>/dev/null`
+   - If not a git repo: "This project must be a git repo. Run `git init && git commit --allow-empty -m 'init'` first."
+3. `$TARGET` is NOT the starter kit itself (compare resolved paths of `$SOURCE` and `$TARGET`)
+   - If same: "Cannot update the starter kit itself."
+4. `$TARGET` is registered in `~/.claude/starter-kit-projects.json`
+   - If not registered: "This project isn't in the registry. Use `/convert-project-to-starter-kit` instead."
+
+Parse flags from `$ARGUMENTS`:
+- `--force` → set `$FORCE=true` (skips confirmation prompts)
+- `--clean` → set `$CLEAN=true` (skip normal update, jump to **Clean Mode** section below)
+
+---
+
+## Step 2 — Safety Commit
+
+```bash
+cd "$TARGET"
+git status --porcelain
+```
+
+- **If uncommitted changes exist** (git status --porcelain has output):
+  ```bash
+  cd "$TARGET" && git add -A && git commit -m "chore: pre-update snapshot (before starter kit update)"
+  ```
+
+- **If clean** (no uncommitted changes):
+  ```bash
+  cd "$TARGET" && git commit --allow-empty -m "chore: pre-update marker (before starter kit update)"
+  ```
+
+Store the hash: `PRE_UPDATE_HASH=$(git -C "$TARGET" rev-parse HEAD)`
+
+**STOP if git fails** (except "nothing to commit" which is fine — treat as clean).
+
+---
+
+## Step 3 — Inventory & Diff
+
+Build a manifest of what the starter kit currently has vs what the target has.
+
+### Categories to compare
+
+| Category | Source Location | Target Location |
+|----------|----------------|-----------------|
+| Commands | `$SOURCE/.claude/commands/*.md` (scope: project only) | `$TARGET/.claude/commands/*.md` |
+| Hooks | `$SOURCE/.claude/hooks/*.{sh,py}` | `$TARGET/.claude/hooks/*.{sh,py}` |
+| Skills | `$SOURCE/.claude/skills/*/SKILL.md` | `$TARGET/.claude/skills/*/SKILL.md` |
+
+**Command scope filtering:** Only include source commands that have `scope: project` in their YAML frontmatter. Commands with `scope: starter-kit` are kit-management commands and should never be copied to projects. If the target already has a starter-kit-scoped command (e.g., from a previous version), classify it as **CUSTOM** (user-created) — never overwrite or remove it.
+
+### For each file, classify as:
+
+- **NEW** — exists in source, not in target → will be added
+- **UPDATED** — exists in both, content differs (compare with `diff -q`) → will be replaced
+- **UNCHANGED** — exists in both, content is identical → skip
+- **CUSTOM** — exists in target only, not in source → never touched (user-created)
+
+### Display the diff report
+
+```
+=== Starter Kit Update Report ===
+
+Target: $TARGET
+Source: $SOURCE
+
+Commands:
+  + NEW:       update-project.md, show-user-guide.md
+  ↻ UPDATED:   commit.md, review.md (starter kit versions changed)
+  = UNCHANGED: help.md, progress.md, ... (12 files)
+  ○ CUSTOM:    my-custom-command.md (yours, not touched)
+
+Hooks:
+  + NEW:       (none)
+  ↻ UPDATED:   check-branch.sh
+  = UNCHANGED: lint-on-save.sh, verify-no-secrets.sh, ...
+  ○ CUSTOM:    (none)
+
+Skills:     (all unchanged)
+Agents:     (all unchanged)
+
+settings.json: hooks will be deep-merged
+CLAUDE.md:     3 new sections will be appended
+Infrastructure: .gitignore (2 lines to add), .env.example (1 key to add)
+
+Total: N files to add, N files to update, N unchanged, N custom (untouched)
+```
+
+---
+
+## Step 3b — Feature File Inventory
+
+After the infrastructure diff above, also check for feature source files to update.
+
+1. Read `$TARGET/.claude/features.json`
+2. **If exists:** extract the list of installed features from `features` object
+3. **If missing (legacy project):** auto-detect features from file presence:
+   - `strictdb` in `package.json` dependencies → feature `mongo` (or `postgres` — StrictDB handles both)
+   - `vitest.config.ts` exists → feature `vitest`
+   - `playwright.config.ts` exists → feature `playwright`
+   - `scripts/build-content.ts` exists → feature `content`
+   - `Dockerfile` exists → feature `docker`
+   - If any features detected, ask: "Detected features: [list]. Write manifest for future updates?" via AskUserQuestion
+     - **Yes, write manifest** (Recommended) → create `.claude/features.json` with detected features
+     - **No, skip** → continue without manifest
+
+4. For each installed feature, read the feature definitions from `$SOURCE/.claude/commands/add-feature.md` (the Feature Definitions table)
+
+5. For each file listed in the feature definition, compare `$SOURCE/<file>` vs `$TARGET/<file>`:
+   - File exists in both, content differs → **UPDATED**
+   - File exists in both, content identical → **UNCHANGED**
+   - File exists in source only → **NEW** (file was added to the feature since installation)
+   - File exists in target only → **CUSTOM** (user added it, don't touch)
+
+6. Append feature file status to the diff report:
+
+```
+Feature Files:
+  mongo:
+    ↻ UPDATED:   scripts/db-query.ts
+    = UNCHANGED: scripts/db-query.ts, scripts/queries/*
+  vitest:
+    = UNCHANGED: vitest.config.ts
+  (N features, N files updated, N unchanged)
+```
+
+If no features installed or no feature files changed, show:
+```
+Feature Files: (none installed or all unchanged)
+```
+
+---
+
+## Step 4 — Confirm (unless --force)
+
+If not `$FORCE`, ask via AskUserQuestion:
+
+"Apply these updates? N new files, N updated files. Your custom files won't be touched."
+- **Yes, update** (Recommended)
+- **Show me the diffs first** — for each UPDATED file, show `diff` output between source and target, then ask again
+- **No, cancel**
+
+If user selects "No, cancel" → stop immediately with: "Update cancelled. No changes made."
+
+---
+
+## Step 5 — Apply Updates
+
+### 5a. Commands, Hooks, Skills, Agents
+
+For each **NEW** file: copy from source to target.
+For each **UPDATED** file: overwrite target with source version.
+For **CUSTOM** and **UNCHANGED**: skip entirely.
+
+For skills: copy the entire skill directory (e.g., `$SOURCE/.claude/skills/code-review/` → `$TARGET/.claude/skills/code-review/`).
+
+> Never copy `.starter-kit/` into a project. It is kit-internal scaffolding for `/new-project` and has no role in a scaffolded project.
+
+Make hooks executable:
+```bash
+chmod +x "$TARGET/.claude/hooks/"*.sh 2>/dev/null
+chmod +x "$TARGET/.claude/hooks/"*.py 2>/dev/null
+```
+
+### 5b. settings.json — Deep Merge
+
+Same merge logic as `/convert-project-to-starter-kit`:
+
+1. Read both `$SOURCE/.claude/settings.json` and `$TARGET/.claude/settings.json` as JSON
+2. `permissions.deny`: merge arrays, deduplicate by value
+3. For each hook event type (`PreToolUse`, `PostToolUse`, `Stop`):
+   - For each matcher entry in source: check if target already has same matcher string
+   - Same matcher → merge the `hooks` arrays (deduplicate by `command` string)
+   - New matcher → add entire entry to target
+4. NEVER remove existing entries from target
+5. Write merged result to `$TARGET/.claude/settings.json`
+
+If target has no `.claude/settings.json`: copy from source directly.
+
+### 5c. CLAUDE.md — Section Merge
+
+Same as `/convert-project-to-starter-kit`:
+
+1. Parse both by `## ` (h2) headers
+2. For each section in source not in target → append at end of target CLAUDE.md
+3. For Critical Rules: sub-merge by `### ` (h3) numbered rules — add missing rules, keep existing
+4. NEVER remove or replace existing sections
+
+If target has no `CLAUDE.md`: skip (don't create — the project should already have one from initial creation).
+
+### 5d. Feature File Updates
+
+If Step 3b identified any **UPDATED** or **NEW** feature files:
+
+- For each **NEW** file: create directories and copy from source
+- For each **UPDATED** file: overwrite target with source version
+- For **UNCHANGED** and **CUSTOM** files: skip
+
+After copying, update the manifest `$TARGET/.claude/features.json`:
+- For each affected feature, set `updatedAt` to current ISO timestamp
+- Add any new files to the feature's `files` array
+
+If no feature files were changed, skip this step entirely.
+
+### 5e. Infrastructure Files
+
+| File | If Missing in Target | If Exists in Target |
+|------|---------------------|---------------------|
+| `CLAUDE.local.md` | Copy from source | Skip |
+| `claude-mastery-project.conf` | Copy from source | Skip |
+| `project-docs/ARCHITECTURE.md` | Create `project-docs/` dir, copy | Skip |
+| `project-docs/INFRASTRUCTURE.md` | Copy | Skip |
+| `project-docs/DECISIONS.md` | Copy | Skip |
+| `.env.example` | Copy from source | Merge: read both, add lines from source whose key name (before `=`) doesn't exist in target. Append missing lines at end. |
+| `.gitignore` | Copy from source | Merge: add lines from source that don't exist in target. Ensure `.env`, `CLAUDE.local.md`, `_ai_temp/` are present. |
+| `.dockerignore` | Copy from source | Merge: add lines from source that don't exist in target. |
+
+---
+
+## Step 6 — Update Registry
+
+1. Read `~/.claude/starter-kit-projects.json`
+2. Find the project entry by `path` matching `$TARGET`
+3. Add or update `updatedAt` field with current ISO timestamp
+4. Increment `updateCount` field (start at 1 if missing, increment if exists)
+5. Write updated registry back to `~/.claude/starter-kit-projects.json`
+
+---
+
+## Step 7 — Commit + Summary
+
+```bash
+cd "$TARGET"
+git add -A
+git commit -m "chore: update Claude Code Starter Kit infrastructure"
+```
+
+Store: `UPDATE_HASH=$(git -C "$TARGET" rev-parse HEAD)`
+
+**If nothing to commit** (all files unchanged): skip the commit, note "Already up to date."
+
+### Display summary
+
+```
+=== Starter Kit Update Complete ===
+
+Target:   $TARGET
+
+Commands:      N added, N updated, N unchanged, N custom
+Hooks:         N added, N updated, N unchanged, N custom
+Skills:        N added, N updated, N unchanged, N custom
+Agents:        N added, N updated, N unchanged, N custom
+Feature Files: N updated, N unchanged (across N features)
+settings.json: deep merged (N new hooks added) / unchanged / copied
+CLAUDE.md:     N sections added, N skipped (exists)
+Infrastructure: N files added, N merged, N skipped
+
+Pre-update commit:  $PRE_UPDATE_HASH
+Update commit:      $UPDATE_HASH
+
+To undo: git revert HEAD
+To review: git diff $PRE_UPDATE_HASH..HEAD
+
+Next: Run /help to see any new commands.
+```
+
+---
+
+## Edge Cases
+
+1. **Already up to date** — If all files are UNCHANGED and no infrastructure changes needed, report "Already up to date — no changes needed." and skip the update commit.
+
+2. **Target has no .claude/ directory** — This shouldn't happen for registered projects, but if it does, create the directories and treat all files as NEW.
+
+3. **Git fails** — If any git operation fails (commit, add), stop with a clear error. Never leave the project in a half-updated state.
+
+4. **Custom files with same name as starter kit** — If a user happened to create a file with the same name as a starter kit file (e.g., `help.md`), it will show as UPDATED (content differs). The diff report makes this visible before applying.
+
+---
+
+## Clean Mode — `--clean`
+
+**If `$CLEAN` is true, skip Steps 2-7 entirely and run this flow instead.**
+
+Clean mode scans a project for commands that have `scope: starter-kit` in their frontmatter — these are kit-management commands that should NOT be in scaffolded projects. Older versions of the starter kit copied all commands without filtering, so existing projects may have them.
+
+### Clean Step 1 — Scan for starter-kit commands
+
+Read every `.md` file in `$TARGET/.claude/commands/`. For each file, parse the YAML frontmatter and check for `scope: starter-kit`.
+
+Build a list of files to remove.
+
+### Clean Step 2 — Display findings
+
+If no `scope: starter-kit` commands found:
+```
+No cleanup needed — this project has no starter-kit-scoped commands.
+```
+Stop here.
+
+If found, display the list:
+
+```
+=== Clean: Starter-Kit Commands Found ===
+
+These commands are kit-management tools that don't belong in project repos:
+
+  1. new-project.md          — Create a new project with all scaffolding rules applied
+  2. update-project.md       — Update a starter-kit project with the latest commands, hooks, skills, and rules
+  3. install-global.md       — Install global Claude config
+  4. convert-project-to-starter-kit.md — Merge starter kit into an existing project
+  5. quickstart.md           — Interactive first-run walkthrough for new users
+  6. projects-created.md     — List all projects created by the starter kit
+  7. remove-project.md       — Remove a project from the registry
+  8. set-project-profile-default.md — Set the default profile for /new-project
+  9. add-project-setup.md    — Create a named project profile
+  10. add-feature.md          — Add capabilities to an existing project
+
+Found N starter-kit commands that should be removed.
+```
+
+### Clean Step 3 — Ask what to remove
+
+Use AskUserQuestion:
+
+"Which commands do you want to remove?"
+- **Remove all N** (Recommended) — Delete all starter-kit-scoped commands
+- **Let me pick** — Show each file and ask individually
+
+**If "Remove all":** delete all listed files.
+
+**If "Let me pick":** for each file, ask via AskUserQuestion (batch up to 4 at a time):
+- "Remove `<filename>`? (<description>)"
+  - Yes, remove it
+  - No, keep it
+
+### Clean Step 4 — Execute removal
+
+For each file to remove:
+```bash
+rm "$TARGET/.claude/commands/<filename>"
+```
+
+### Clean Step 5 — Commit + Summary
+
+```bash
+cd "$TARGET"
+git add -A
+git commit -m "chore: remove starter-kit-scoped commands (clean)"
+```
+
+Display summary:
+
+```
+=== Clean Complete ===
+
+Removed N starter-kit commands:
+  - new-project.md
+  - update-project.md
+  - ...
+
+Kept N project commands.
+
+To undo: git revert HEAD
+```
+
+**If nothing was removed** (user said "no" to everything): skip the commit, note "No changes made."

package/.claude/commands/what-is-my-ai-doing.md

@@ -0,0 +1,42 @@
+---
+description: Live monitor of everything your AI is doing — tokens, cost, violations, tool usage
+scope: project
+argument-hint: [--json]
+allowed-tools: Bash, AskUserQuestion
+---
+
+# What Is My AI Doing?
+
+Launch the RuleCatch AI-Pooler live monitor to see everything your AI is doing in real time.
+
+**Arguments:** $ARGUMENTS
+
+## Step 1 — Launch the Free Monitor
+
+Tell the user:
+
+```
+The AI-Pooler monitor runs in a SEPARATE terminal window.
+Open a new terminal and run:
+
+  npx @rulecatch/ai-pooler@latest monitor --no-api-key
+
+This is free monitor mode — no API key, no account, no setup.
+It shows you a live view of:
+  • Every tool call Claude makes (Read, Write, Edit, Bash, etc.)
+  • Token usage per turn
+  • Cost per session
+  • Which files are being accessed
+
+Press Ctrl+C to stop the monitor.
+```
+
+## Step 2 — Remind
+
+After providing the instructions, remind the user:
+
+- The monitor runs **outside** Claude's context — zero token overhead
+- It watches ALL Claude sessions, not just this one
+- This is the free preview — it shows what's happening but doesn't persist data
+- **Want violation tracking, dashboards, and alerts?** Sign up at https://rulecatch.ai for a 7-day free trial, then run `npx @rulecatch/ai-pooler init --api-key=dc_your_key --region=us` to unlock the full experience
+- With an API key, you also get the RuleCatch MCP server — Claude can query its own violations: "RuleCatch, what was violated today?"

package/.claude/commands/worktree.md

@@ -0,0 +1,124 @@
+---
+description: Create a git worktree + branch for an isolated task
+scope: project
+argument-hint: <branch-name> [base-branch]
+allowed-tools: Bash, Read, AskUserQuestion
+---
+
+# Git Worktree — Isolated Task Branch
+
+Create a new git worktree so this task runs on its own branch in its own directory. Main stays untouched. If anything goes wrong, delete the branch — zero risk.
+
+**Arguments:** $ARGUMENTS
+
+## Step 0 — Parse Arguments
+
+- **First argument:** branch name (required). If not provided, ASK the user.
+- **Second argument:** base branch to branch from (optional, defaults to `main` or `master`)
+
+Branch naming convention: `task/<descriptive-name>`
+- If the user provides just a name like `auth-fix`, prefix it: `task/auth-fix`
+- If they already include a prefix like `feat/login`, use as-is
+
+## Step 1 — Verify Git State
+
+Before creating anything, verify:
+
+```bash
+# Must be in a git repo
+git rev-parse --git-dir
+
+# Check for uncommitted changes on current branch
+git status --porcelain
+```
+
+**If there are uncommitted changes:** WARN the user. Ask if they want to:
+- Stash changes first (`git stash`)
+- Commit changes first
+- Abort
+
+**NEVER create a worktree with dirty state** — changes could bleed between worktrees.
+
+## Step 2 — Determine Base Branch
+
+```bash
+# Find the default branch (main or master)
+git symbolic-ref refs/remotes/origin/HEAD 2>/dev/null | sed 's@^refs/remotes/origin/@@'
+```
+
+If no remote, fall back to checking if `main` or `master` exists locally.
+
+Use the second argument if provided, otherwise use the detected default branch.
+
+## Step 3 — Create Branch + Worktree
+
+The worktree directory goes next to the current repo as `../<repo-name>--<branch-name>`:
+
+```bash
+# Example: if repo is at ~/projects/my-app and branch is task/auth-fix
+# Worktree goes to ~/projects/my-app--task-auth-fix
+
+REPO_NAME=$(basename "$(git rev-parse --show-toplevel)")
+BRANCH_NAME="$1"
+WORKTREE_DIR="../${REPO_NAME}--${BRANCH_NAME//\//-}"
+
+# Create the branch and worktree in one step
+git worktree add -b "$BRANCH_NAME" "$WORKTREE_DIR" "$BASE_BRANCH"
+```
+
+## Step 4 — Verify
+
+```bash
+# List all worktrees to confirm
+git worktree list
+```
+
+## Step 5 — Report
+
+Output a summary:
+
+```
+Git Worktree Created
+====================
+Branch:    task/auth-fix
+Base:      main
+Directory: ~/projects/my-app--task-auth-fix
+Main repo: ~/projects/my-app (untouched)
+
+Next steps:
+  cd ~/projects/my-app--task-auth-fix
+  claude                          # start a new Claude session here
+
+When done:
+  cd ~/projects/my-app
+  git merge task/auth-fix         # merge into main (or open a PR)
+  git worktree remove ../my-app--task-auth-fix
+  git branch -d task/auth-fix
+
+If something went wrong:
+  git worktree remove ../my-app--task-auth-fix --force
+  git branch -D task/auth-fix     # main was never touched
+```
+
+## When the Task Is Done
+
+When the user says they're done with work on a worktree branch, ALWAYS:
+
+1. **Review the diff** — show `git diff main...HEAD` summary (files changed, insertions, deletions)
+2. **Ask about RuleCatch** — "Do you want RuleCatch to check if any violations happened on this branch?"
+   - If yes AND the RuleCatch MCP server is available: query it for violations on this branch's files
+   - If yes but no MCP: suggest `npx @rulecatch/ai-pooler check` or checking the RuleCatch dashboard
+   - If no: skip and proceed to merge/PR
+3. **Ask about merge** — "Ready to merge into main, or do you want to open a PR?"
+
+This ensures every branch gets a quality check before it touches main.
+
+## Quick Reference — Worktree Management
+
+These commands manage ALL worktrees from the main repo:
+
+```bash
+git worktree list                           # see all active worktrees
+git worktree remove ../my-app--branch-name  # clean up finished task
+git worktree prune                          # remove stale entries
+```

package/.claude/hooks/block-dangerous-bash.py

@@ -0,0 +1,55 @@
+#!/usr/bin/env python3
+"""PreToolUse (Bash) — block destructive or unsafe shell commands.
+
+Covers the gaps the other Bash hooks don't: rm -rf, curl|sh (the remote-script-
+into-a-shell pattern), force-pushing to main/master, chmod 777, and database
+drops. Secrets at commit time are handled by verify-no-secrets.sh, and direct
+commits to main by check-branch.sh, so this stays focused on irreversible damage.
+Exit 2 blocks; run it yourself if you truly mean it.
+"""
+import json
+import re
+import sys
+
+DANGER = [
+    (re.compile(r"\brm\s+.*-[a-z]*r[a-z]*f", re.I), "rm -rf (recursive force-remove)"),
+    (re.compile(r"\brm\s+.*-[a-z]*f[a-z]*r", re.I), "rm -fr (recursive force-remove)"),
+    (re.compile(r"\b(curl|wget)\b[^|]*\|\s*(sudo\s+)?(ba)?sh\b", re.I),
+     "piping a remote script straight into a shell (curl | sh)"),
+    (re.compile(r"\bgit\s+push\b.*--force(-with-lease)?\b.*\b(main|master)\b", re.I),
+     "force-pushing to main/master"),
+    (re.compile(r"\bgit\s+push\b.*\b(main|master)\b.*--force", re.I),
+     "force-pushing to main/master"),
+    (re.compile(r"\bchmod\s+-?R?\s*777\b", re.I), "chmod 777"),
+    (re.compile(r"\bDROP\s+(DATABASE|TABLE|COLLECTION)\b", re.I),
+     "a destructive database drop"),
+    (re.compile(r"\.drop(Database)?\(\s*\)", re.I), "dropping a MongoDB database/collection"),
+]
+
+
+def main():
+    try:
+        data = json.load(sys.stdin)
+    except Exception:
+        sys.exit(0)
+
+    if data.get("tool_name") != "Bash":
+        sys.exit(0)
+
+    cmd = (data.get("tool_input", {}) or {}).get("command", "") or ""
+    if not cmd:
+        sys.exit(0)
+
+    for rx, label in DANGER:
+        if rx.search(cmd):
+            sys.stderr.write(
+                "Blocked: " + label + " is not allowed by the kit's safety hook. "
+                "If this is genuinely intended, run it yourself outside the agent.\n"
+            )
+            sys.exit(2)
+
+    sys.exit(0)
+
+
+if __name__ == "__main__":
+    main()