@wbern/claude-instructions 1.9.0 → 1.10.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 wbern
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -21,6 +21,10 @@ TDD workflow commands for Claude Code CLI.
 
 ```bash
 npx @wbern/claude-instructions
+
+// or
+
+pnpm dlx @wbern/claude-instructions
 ```
 
 The interactive installer lets you choose:
@@ -57,13 +61,14 @@ This ensures commands are regenerated whenever anyone runs `npm install`, `pnpm
 
 | Option | Description |
 |--------|-------------|
-| `--variant=with-beads` | Include Beads MCP integration |
-| `--variant=without-beads` | Standard commands only |
-| `--scope=project` | Install to `.claude/commands` in current directory |
-| `--scope=user` | Install to `~/.claude/commands` (global) |
-| `--prefix=my-` | Add prefix to command names (e.g., `my-commit.md`) |
-| `--skip-template-injection` | Don't inject CLAUDE.md template content |
+| `--variant=with-beads` | Command variant (with-beads, without-beads) |
+| `--scope=project` | Installation scope (project, user) |
+| `--prefix=my-` | Add prefix to command names |
 | `--commands=commit,red,green` | Install only specific commands |
+| `--skip-template-injection` | Skip injecting project CLAUDE.md customizations |
+| `--update-existing` | Only update already-installed commands |
+| `--overwrite` | Overwrite conflicting files without prompting |
+| `--skip-on-conflict` | Skip conflicting files without prompting |
 
 ## Customizing Commands
 
@@ -190,14 +195,6 @@ flowchart TB
 - `/issue` - Analyze GitHub issue and create TDD implementation plan
 - `/plan` - Create implementation plan from feature/requirement with PRD-style discovery and TDD acceptance criteria
 
-### Workflow
-
-- `/commit` - Create a git commit following project standards
-- `/busycommit` - Create multiple atomic git commits, one logical change at a time
-- `/pr` - Creates a pull request using GitHub MCP
-- `/summarize` - Summarize conversation progress and next steps
-- `/gap` - Analyze conversation context for unaddressed items and gaps
-
 ### Test-Driven Development
 
 - `/spike` - Execute TDD Spike Phase - exploratory coding to understand problem space before TDD
@@ -207,6 +204,15 @@ flowchart TB
 - `/refactor` - Execute TDD Refactor Phase - improve code structure while keeping tests green
 - `/cycle` - Execute complete TDD cycle - Red, Green, and Refactor phases in sequence
 
+### Workflow
+
+- `/commit` - Create a git commit following project standards
+- `/busycommit` - Create multiple atomic git commits, one logical change at a time
+- `/pr` - Creates a pull request using GitHub MCP
+- `/summarize` - Summarize conversation progress and next steps
+- `/gap` - Analyze conversation context for unaddressed items and gaps
+- `/code-review` - Code review using dynamic category detection and domain-specific analysis
+
 ### Ship / Show / Ask
 
 - `/ship` - Ship code directly to main - for small, obvious changes that don't need review

package/bin/cli.js

@@ -119,6 +119,7 @@ init_esm_shims();
 import {
   select,
   text,
+  multiselect,
   groupMultiselect,
   isCancel,
   intro,
@@ -496,7 +497,7 @@ var CATEGORY_ORDER = [
   "Utilities",
   "Ship / Show / Ask"
 ];
-async function getCommandsGroupedByCategory(variant) {
+async function loadCommandsMetadata(variant) {
   const sourcePath = path2.join(
     __dirname2,
     "..",
@@ -505,7 +506,10 @@ async function getCommandsGroupedByCategory(variant) {
   );
   const metadataPath = path2.join(sourcePath, "commands-metadata.json");
   const metadataContent = await fs.readFile(metadataPath, "utf-8");
-  const metadata = JSON.parse(metadataContent);
+  return JSON.parse(metadataContent);
+}
+async function getCommandsGroupedByCategory(variant) {
+  const metadata = await loadCommandsMetadata(variant);
   const grouped = {};
   for (const [filename, data] of Object.entries(metadata)) {
     const category = data.category;
@@ -519,6 +523,11 @@ async function getCommandsGroupedByCategory(variant) {
       selectedByDefault: data.selectedByDefault !== false
     });
   }
+  for (const category of Object.keys(grouped)) {
+    if (!CATEGORY_ORDER.includes(category)) {
+      throw new Error(`Unknown category: ${category}`);
+    }
+  }
   for (const category of Object.keys(grouped)) {
     grouped[category].sort((a, b) => {
       const orderA = metadata[a.value].order;
@@ -527,12 +536,7 @@ async function getCommandsGroupedByCategory(variant) {
     });
   }
   const sortedCategories = Object.keys(grouped).sort((a, b) => {
-    const indexA = CATEGORY_ORDER.indexOf(a);
-    const indexB = CATEGORY_ORDER.indexOf(b);
-    if (indexA !== -1 && indexB !== -1) return indexA - indexB;
-    if (indexA !== -1) return -1;
-    if (indexB !== -1) return 1;
-    return a.localeCompare(b);
+    return CATEGORY_ORDER.indexOf(a) - CATEGORY_ORDER.indexOf(b);
   });
   const sortedGrouped = {};
   for (const category of sortedCategories) {
@@ -540,6 +544,25 @@ async function getCommandsGroupedByCategory(variant) {
   }
   return sortedGrouped;
 }
+function extractLabelFromTool(tool) {
+  const match = tool.match(/^Bash\(([^:]+):/);
+  return match ? match[1] : tool;
+}
+async function getRequestedToolsOptions(variant) {
+  const metadata = await loadCommandsMetadata(variant);
+  const allTools = /* @__PURE__ */ new Set();
+  for (const data of Object.values(metadata)) {
+    if (data["_requested-tools"]) {
+      for (const tool of data["_requested-tools"]) {
+        allTools.add(tool);
+      }
+    }
+  }
+  return Array.from(allTools).map((tool) => ({
+    value: tool,
+    label: extractLabelFromTool(tool)
+  }));
+}
 function getDestinationPath(outputPath, scope) {
   if (outputPath) {
     return outputPath;
@@ -596,6 +619,20 @@ async function generateToDirectory(outputPath, variant, scope, options) {
   } else {
     await fs.copy(sourcePath, destinationPath, {});
   }
+  if (options?.allowedTools && options.allowedTools.length > 0) {
+    for (const file of files) {
+      const filePath = path2.join(destinationPath, file);
+      const content = await fs.readFile(filePath, "utf-8");
+      const allowedToolsYaml = `allowed-tools: ${options.allowedTools.join(", ")}`;
+      const modifiedContent = content.replace(
+        /^---\n/,
+        `---
+${allowedToolsYaml}
+`
+      );
+      await fs.writeFile(filePath, modifiedContent);
+    }
+  }
   if (options?.commandPrefix) {
     for (const file of files) {
       const oldPath = path2.join(destinationPath, file);
@@ -770,11 +807,26 @@ async function main(args) {
   let scope;
   let commandPrefix;
   let selectedCommands;
+  let selectedAllowedTools;
+  let cachedExistingFiles;
   if (args?.variant && args?.scope && args?.prefix !== void 0) {
     variant = args.variant;
     scope = args.scope;
     commandPrefix = args.prefix;
     selectedCommands = args.commands;
+    if (args.updateExisting) {
+      cachedExistingFiles = await checkExistingFiles(
+        void 0,
+        variant,
+        scope,
+        { commandPrefix: commandPrefix || "" }
+      );
+      selectedCommands = cachedExistingFiles.map((f) => f.filename);
+      if (selectedCommands.length === 0) {
+        log.warn("No existing commands found in target directory");
+        return;
+      }
+    }
   } else {
     variant = await select({
       message: "Select variant",
@@ -799,9 +851,34 @@ async function main(args) {
     if (isCancel(commandPrefix)) {
       return;
     }
-    const groupedCommands = await getCommandsGroupedByCategory(
+    let groupedCommands = await getCommandsGroupedByCategory(
       variant
     );
+    if (args?.updateExisting) {
+      cachedExistingFiles = await checkExistingFiles(
+        void 0,
+        variant,
+        scope,
+        { commandPrefix: commandPrefix || "" }
+      );
+      const existingFilenames = new Set(
+        cachedExistingFiles.map((f) => f.filename)
+      );
+      const filteredGrouped = {};
+      for (const [category, commands] of Object.entries(groupedCommands)) {
+        const filtered = commands.filter(
+          (cmd) => existingFilenames.has(cmd.value)
+        );
+        if (filtered.length > 0) {
+          filteredGrouped[category] = filtered;
+        }
+      }
+      groupedCommands = filteredGrouped;
+      if (Object.keys(groupedCommands).length === 0) {
+        log.warn("No existing commands found in target directory");
+        return;
+      }
+    }
     const enabledCommandValues = Object.values(groupedCommands).flat().filter((cmd) => cmd.selectedByDefault).map((cmd) => cmd.value);
     selectedCommands = await groupMultiselect({
       message: "Select commands to install (Enter to accept all)",
@@ -811,32 +888,47 @@ async function main(args) {
     if (isCancel(selectedCommands)) {
       return;
     }
-  }
-  const existingFiles = await checkExistingFiles(
-    void 0,
-    variant,
-    scope,
-    {
-      commandPrefix,
-      commands: selectedCommands
+    const requestedToolsOptions = await getRequestedToolsOptions(
+      variant
+    );
+    if (requestedToolsOptions.length > 0) {
+      selectedAllowedTools = await multiselect({
+        message: "Select allowed tools for commands (optional)",
+        options: requestedToolsOptions
+      });
+      if (isCancel(selectedAllowedTools)) {
+        return;
+      }
     }
-  );
+  }
+  const existingFiles = cachedExistingFiles ?? await checkExistingFiles(void 0, variant, scope, {
+    commandPrefix,
+    commands: selectedCommands
+  });
   const skipFiles = [];
-  for (const file of existingFiles) {
-    if (file.isIdentical) {
-      log.info(`${file.filename} is identical, skipping`);
-      skipFiles.push(file.filename);
-      continue;
+  if (!args?.overwrite && !args?.skipOnConflict) {
+    for (const file of existingFiles) {
+      if (file.isIdentical) {
+        log.info(`${file.filename} is identical, skipping`);
+        skipFiles.push(file.filename);
+        continue;
+      }
+      const stats = getDiffStats(file.existingContent, file.newContent);
+      const diff = formatCompactDiff(file.existingContent, file.newContent);
+      note(diff, `Diff: ${file.filename}`);
+      log.info(`+${stats.added} -${stats.removed}`);
+      const shouldOverwrite = await confirm({
+        message: `Overwrite ${file.filename}?`
+      });
+      if (!shouldOverwrite) {
+        skipFiles.push(file.filename);
+      }
     }
-    const stats = getDiffStats(file.existingContent, file.newContent);
-    const diff = formatCompactDiff(file.existingContent, file.newContent);
-    note(diff, `Diff: ${file.filename}`);
-    log.info(`+${stats.added} -${stats.removed}`);
-    const shouldOverwrite = await confirm({
-      message: `Overwrite ${file.filename}?`
-    });
-    if (!shouldOverwrite) {
-      skipFiles.push(file.filename);
+  } else if (args?.skipOnConflict) {
+    for (const file of existingFiles) {
+      if (!file.isIdentical) {
+        skipFiles.push(file.filename);
+      }
     }
   }
   const result = await generateToDirectory(
@@ -847,7 +939,8 @@ async function main(args) {
       commandPrefix,
       skipTemplateInjection: args?.skipTemplateInjection,
       commands: selectedCommands,
-      skipFiles
+      skipFiles,
+      allowedTools: selectedAllowedTools
     }
   );
   const fullPath = scope === "project" ? `${process.cwd()}/.claude/commands` : `${os2.homedir()}/.claude/commands`;
@@ -860,36 +953,111 @@ Happy TDD'ing!`
   );
 }
 
-// scripts/bin.ts
-var STRING_ARGS = ["variant", "scope", "prefix"];
-var ARRAY_ARGS = ["commands"];
-var BOOLEAN_FLAGS = [
-  { flag: "--skip-template-injection", key: "skipTemplateInjection" }
+// scripts/cli-options.ts
+init_esm_shims();
+var CLI_OPTIONS = [
+  {
+    flag: "--variant",
+    key: "variant",
+    type: "string",
+    description: "Command variant (with-beads, without-beads)",
+    example: "--variant=with-beads"
+  },
+  {
+    flag: "--scope",
+    key: "scope",
+    type: "string",
+    description: "Installation scope (project, user)",
+    example: "--scope=project"
+  },
+  {
+    flag: "--prefix",
+    key: "prefix",
+    type: "string",
+    description: "Add prefix to command names",
+    example: "--prefix=my-"
+  },
+  {
+    flag: "--commands",
+    key: "commands",
+    type: "array",
+    description: "Install only specific commands",
+    example: "--commands=commit,red,green"
+  },
+  {
+    flag: "--skip-template-injection",
+    key: "skipTemplateInjection",
+    type: "boolean",
+    description: "Skip injecting project CLAUDE.md customizations"
+  },
+  {
+    flag: "--update-existing",
+    key: "updateExisting",
+    type: "boolean",
+    description: "Only update already-installed commands"
+  },
+  {
+    flag: "--overwrite",
+    key: "overwrite",
+    type: "boolean",
+    description: "Overwrite conflicting files without prompting"
+  },
+  {
+    flag: "--skip-on-conflict",
+    key: "skipOnConflict",
+    type: "boolean",
+    description: "Skip conflicting files without prompting"
+  }
 ];
+function generateHelpText() {
+  const lines = [
+    "Usage: npx @wbern/claude-instructions [options]",
+    "",
+    "Options:"
+  ];
+  for (const opt of CLI_OPTIONS) {
+    const suffix = opt.type === "string" ? "=<value>" : opt.type === "array" ? "=<list>" : "";
+    const padding = 28 - (opt.flag.length + suffix.length);
+    lines.push(
+      `  ${opt.flag}${suffix}${" ".repeat(Math.max(1, padding))}${opt.description}`
+    );
+  }
+  lines.push("  --help, -h                  Show this help message");
+  return lines.join("\n");
+}
+
+// scripts/bin.ts
 function parseArgs(argv) {
   const args = {};
+  const booleanOpts = CLI_OPTIONS.filter((o) => o.type === "boolean");
+  const stringOpts = CLI_OPTIONS.filter((o) => o.type === "string");
+  const arrayOpts = CLI_OPTIONS.filter((o) => o.type === "array");
   for (const arg of argv) {
-    for (const { flag, key } of BOOLEAN_FLAGS) {
-      if (arg === flag) {
-        args[key] = true;
+    for (const opt of booleanOpts) {
+      if (arg === opt.flag) {
+        args[opt.key] = true;
       }
     }
-    for (const key of STRING_ARGS) {
-      const prefix = `--${key}=`;
+    for (const opt of stringOpts) {
+      const prefix = `${opt.flag}=`;
       if (arg.startsWith(prefix)) {
-        args[key] = arg.slice(prefix.length);
+        args[opt.key] = arg.slice(prefix.length);
       }
     }
-    for (const key of ARRAY_ARGS) {
-      const prefix = `--${key}=`;
+    for (const opt of arrayOpts) {
+      const prefix = `${opt.flag}=`;
       if (arg.startsWith(prefix)) {
-        args[key] = arg.slice(prefix.length).split(",");
+        args[opt.key] = arg.slice(prefix.length).split(",");
       }
     }
   }
   return args;
 }
 async function run(argv) {
+  if (argv.includes("--help") || argv.includes("-h")) {
+    console.log(generateHelpText());
+    return;
+  }
   const args = parseArgs(argv);
   await main(args);
 }

package/downloads/with-beads/busycommit.md

@@ -17,6 +17,22 @@ Create multiple atomic git commits, committing the smallest possible logical uni
 
 Include any of the following info if specified: $ARGUMENTS
 
+## Commit Message Rules
+
+Follows [Conventional Commits](https://www.conventionalcommits.org/) standard.
+
+1. **Format**: `type(#issue): description`
+   - Use `#123` for local repo issues
+   - Use `owner/repo#123` for cross-repo issues
+   - Common types: `feat`, `fix`, `docs`, `refactor`, `test`, `chore`
+
+2. **AI Credits**: **NEVER include AI credits in commit messages**
+   - No "Generated with Claude Code"
+   - No "Co-Authored-By: Claude" or "Co-Authored-By: Happy"
+   - Focus on the actual changes made, not conversation history
+
+3. **Content**: Write clear, concise commit messages describing what changed and why
+
 ## Process
 
 1. Run `git status` and `git diff` to review changes

package/downloads/with-beads/code-review.md

@@ -0,0 +1,248 @@
+---
+description: Code review using dynamic category detection and domain-specific analysis
+argument-hint: (optional) [branch, PR#, or PR URL] - defaults to current branch
+  - Bash(git diff:*)
+  - Bash(git status:*)
+  - Bash(git log:*)
+  - Bash(git rev-parse:*)
+  - Bash(git merge-base:*)
+  - Bash(git branch:*)
+---
+
+## General Guidelines
+
+### Output Style
+
+- **Never explicitly mention TDD** in code, comments, commits, PRs, or issues
+- Write natural, descriptive code without meta-commentary about the development process
+- The code should speak for itself - TDD is the process, not the product
+
+Beads is available for task tracking. Use `mcp__beads__*` tools to manage issues (the user interacts via `bd` commands).
+
+# Code Review
+
+Perform a code review using dynamic category detection.
+
+## Phase 0: Setup & Categorization
+
+### Determine What to Review
+
+Parse the argument to determine the review target:
+
+| Input | Action |
+|-------|--------|
+| No argument | Detect divergence point, confirm scope with user |
+| Branch name | Use specified branch as base |
+| PR number (e.g., `123`) | Fetch PR diff from GitHub |
+| PR URL (e.g., `https://github.com/owner/repo/pull/123`) | Extract PR number and fetch diff |
+
+**For GitHub PRs:**
+
+1. Try GitHub MCP first: `mcp__github__pull_request_read` with `method: "get_diff"`
+2. Fall back to `gh` CLI: `gh pr diff <number>`
+3. If neither works, report error and stop
+
+**For local branches (no argument or branch name provided):**
+
+1. **Get current branch**: `git rev-parse --abbrev-ref HEAD`
+
+2. **Check for uncommitted changes**: `git status --porcelain`
+   - If output is non-empty, note that uncommitted changes exist
+
+3. **Detect divergence point** (skip if branch name was provided as argument):
+   - Get all local branches except current: `git branch --format='%(refname:short)'`
+   - For each branch, find merge-base: `git merge-base HEAD <branch>`
+   - Count commits from merge-base to HEAD: `git rev-list --count <merge-base>..HEAD`
+   - The branch with the **fewest commits back** (closest merge-base) is the likely parent
+   - If no other branches exist, fall back to `main`, `master`, or `develop` if they exist as remote tracking branches
+
+4. **Confirm scope with user** using `AskUserQuestion`:
+
+   **Question 1 - "Review scope"** (header: "Base branch"):
+   - Option A: `From <detected-branch>` — "Review N commits since diverging from <branch>"
+   - Option B: `Different branch` — "Specify another branch to compare against"
+   - Option C: `Uncommitted only` — "Review only staged/unstaged changes, skip committed work"
+
+   **Question 2 - "Include uncommitted?"** (header: "Uncommitted", only ask if uncommitted changes exist AND user didn't pick option C):
+   - Option A: `Yes` — "Include N staged/unstaged files in review"
+   - Option B: `No` — "Review only committed changes"
+
+5. **Collect changed files** based on user selection:
+   - From branch: `git diff --name-only <base>...HEAD`
+   - Uncommitted unstaged: `git diff --name-only`
+   - Uncommitted staged: `git diff --name-only --cached`
+   - Combine and deduplicate the file list
+
+6. **If no changes**: Report "Nothing to review" and stop
+
+### Categorize Files
+
+Check for CLAUDE.md - if it exists, note any project-specific review patterns.
+
+Categorize each changed file into ONE primary category based on these patterns:
+
+| Category | File Patterns |
+|----------|---------------|
+| Frontend/UI | `*.tsx`, `*.jsx`, `components/`, `pages/`, `views/`, `*.vue` |
+| Frontend/Styling | `*.css`, `*.scss`, `*.less`, `styles/`, `*.tailwind*`, `*.styled.*` |
+| Backend/API | `routes/`, `api/`, `controllers/`, `services/`, `*.controller.*`, `*.service.*`, `*.resolver.*` |
+| Backend/Data | `migrations/`, `models/`, `prisma/`, `schema.*`, `*.model.*`, `*.entity.*` |
+| Tooling/Config | `scripts/`, `*.config.*`, `package.json`, `tsconfig.*`, `vite.*`, `webpack.*`, `eslint.*` |
+| CI/CD | `.github/`, `.gitlab-ci.*`, `Dockerfile`, `docker-compose.*`, `*.yml` in CI paths |
+| Tests | `*.test.*`, `*.spec.*`, `__tests__/`, `__mocks__/`, `*.stories.*` |
+| Docs | `*.md`, `docs/`, `README*`, `CHANGELOG*` |
+
+Output the categorization:
+
+```
+## Categorization
+
+Base branch: <branch>
+Total files changed: <n>
+
+| Category | Files |
+|----------|-------|
+| <category> | <count> |
+...
+```
+
+## Phase 1: Branch Brief
+
+From the diff and recent commit messages (`git log <base>...HEAD --oneline`), infer:
+
+- **Goal**: What this branch accomplishes (1-3 sentences)
+- **Constraints**: Any implied requirements (security, performance, backwards compatibility)
+- **Success checklist**: What must work after this change, what must not break
+
+```
+## Branch Brief
+
+**Goal**: ...
+**Constraints**: ...
+**Checklist**:
+- [ ] ...
+```
+
+## Phase 2: Category Reviews
+
+For each detected category with changes, run a targeted review. Skip categories with no changes.
+
+### Frontend/UI Review Criteria
+
+- Accessibility: ARIA attributes, keyboard navigation, screen reader support
+- Component patterns: Composition, prop drilling, context usage
+- State management: Unnecessary re-renders, stale closures
+- Performance: memo/useMemo/useCallback usage, lazy loading, bundle impact
+
+### Frontend/Styling Review Criteria
+
+- Responsive design: Breakpoints, mobile-first
+- Design system: Token usage, consistent spacing/colors
+- CSS specificity: Overly specific selectors, !important usage
+- Theme support: Dark mode, CSS variables
+
+### Backend/API Review Criteria
+
+- Input validation: Sanitization, type checking, bounds
+- Security: Authentication checks, authorization, injection risks
+- Error handling: Proper status codes, meaningful messages, logging
+- Performance: N+1 queries, missing indexes, pagination
+
+### Backend/Data Review Criteria
+
+- Migration safety: Reversibility, data preservation
+- Data integrity: Constraints, foreign keys, nullability
+- Index usage: Queries have appropriate indexes
+- Backwards compatibility: Existing data still works
+
+### Tooling/Config Review Criteria
+
+- Breaking changes: Does this affect developer workflow?
+- Dependency compatibility: Version conflicts, peer deps
+- Build performance: Added build time, bundle size
+
+### CI/CD Review Criteria
+
+- Secrets exposure: Credentials in logs, env vars
+- Pipeline efficiency: Caching, parallelization
+- Failure handling: Notifications, rollback strategy
+
+### Tests Review Criteria
+
+- Coverage: Edge cases, error paths, boundaries
+- Assertion quality: Specific assertions, not just "no error"
+- Flaky patterns: Timing dependencies, order dependencies, shared state
+
+### Docs Review Criteria
+
+- Technical accuracy: Code examples work, APIs documented correctly
+- Completeness: All new features documented
+- Clarity: Easy to follow, good examples
+
+**Output format per category:**
+
+```
+## <Category> Review (<n> files)
+
+### file:line - [blocker|risky|nit] Title
+Description of the issue and why it matters.
+Suggested fix or question to investigate.
+
+...
+```
+
+## Phase 3: Cross-Cutting Analysis
+
+After reviewing all categories, check for cross-cutting issues:
+
+- API changed but tests didn't update?
+- New feature but no documentation?
+- Migration added but no rollback tested?
+- Config changed but README not updated?
+- Security-sensitive code without corresponding test?
+
+```
+## Cross-Cutting Issues
+
+- [ ] <issue description>
+...
+```
+
+## Phase 4: Summary
+
+### PR Description (draft)
+
+Provide a ready-to-paste PR description:
+
+```
+## What changed
+- <by category, 1-2 bullets each>
+
+## Why
+- <motivation>
+
+## Testing
+- <how to verify>
+
+## Notes
+- <migration steps, breaking changes, etc.>
+```
+
+### Review Checklist
+
+```
+## Before Merge
+
+### Blockers (must fix)
+- [ ] ...
+
+### Risky (highlight to reviewers)
+- [ ] ...
+
+### Follow-ups (can defer)
+- [ ] ...
+```
+
+---
+
+Review target (branch name, PR number, or PR URL - leave empty for current branch): $ARGUMENTS

package/downloads/with-beads/commands-metadata.json

@@ -24,6 +24,20 @@
     "category": "Workflow",
     "order": 2
   },
+  "code-review.md": {
+    "description": "Code review using dynamic category detection and domain-specific analysis",
+    "hint": "Review code",
+    "category": "Workflow",
+    "order": 35,
+    "_requested-tools": [
+      "Bash(git diff:*)",
+      "Bash(git status:*)",
+      "Bash(git log:*)",
+      "Bash(git rev-parse:*)",
+      "Bash(git merge-base:*)",
+      "Bash(git branch:*)"
+    ]
+  },
   "commit.md": {
     "description": "Create a git commit following project standards",
     "hint": "Git commit",

package/downloads/with-beads/commit.md

@@ -17,6 +17,22 @@ Create a git commit following project standards
 
 Include any of the following info if specified: $ARGUMENTS
 
+## Commit Message Rules
+
+Follows [Conventional Commits](https://www.conventionalcommits.org/) standard.
+
+1. **Format**: `type(#issue): description`
+   - Use `#123` for local repo issues
+   - Use `owner/repo#123` for cross-repo issues
+   - Common types: `feat`, `fix`, `docs`, `refactor`, `test`, `chore`
+
+2. **AI Credits**: **NEVER include AI credits in commit messages**
+   - No "Generated with Claude Code"
+   - No "Co-Authored-By: Claude" or "Co-Authored-By: Happy"
+   - Focus on the actual changes made, not conversation history
+
+3. **Content**: Write clear, concise commit messages describing what changed and why
+
 ## Process
 
 1. Run `git status` and `git diff` to review changes

package/downloads/with-beads/gap.md

@@ -19,6 +19,7 @@ Analyze the current conversation context and identify things that have not yet b
 2. **Unused variables/results** - Values that were captured but never used
 3. **Missing tests** - Functionality without test coverage
 4. **Open issues** - Beads issues that are still open or in progress
+
 5. **User requests** - Things the user asked for that weren't fully completed
 6. **TODO comments** - Any TODOs mentioned in conversation
 7. **Error handling gaps** - Missing error cases or edge cases

package/downloads/with-beads/plan.md

@@ -21,8 +21,7 @@ Beads is available for task tracking. Use `mcp__beads__*` tools to manage issues
 
 $ARGUMENTS
 
-(If no input provided, check conversation context or run `bd ready` to see existing work
-)
+(If no input provided, check conversation context or run `bd ready` to see existing work)
 
 ## Input Processing
 

package/downloads/without-beads/busycommit.md

@@ -15,6 +15,22 @@ Create multiple atomic git commits, committing the smallest possible logical uni
 
 Include any of the following info if specified: $ARGUMENTS
 
+## Commit Message Rules
+
+Follows [Conventional Commits](https://www.conventionalcommits.org/) standard.
+
+1. **Format**: `type(#issue): description`
+   - Use `#123` for local repo issues
+   - Use `owner/repo#123` for cross-repo issues
+   - Common types: `feat`, `fix`, `docs`, `refactor`, `test`, `chore`
+
+2. **AI Credits**: **NEVER include AI credits in commit messages**
+   - No "Generated with Claude Code"
+   - No "Co-Authored-By: Claude" or "Co-Authored-By: Happy"
+   - Focus on the actual changes made, not conversation history
+
+3. **Content**: Write clear, concise commit messages describing what changed and why
+
 ## Process
 
 1. Run `git status` and `git diff` to review changes

package/downloads/without-beads/code-review.md

@@ -0,0 +1,246 @@
+---
+description: Code review using dynamic category detection and domain-specific analysis
+argument-hint: (optional) [branch, PR#, or PR URL] - defaults to current branch
+  - Bash(git diff:*)
+  - Bash(git status:*)
+  - Bash(git log:*)
+  - Bash(git rev-parse:*)
+  - Bash(git merge-base:*)
+  - Bash(git branch:*)
+---
+
+## General Guidelines
+
+### Output Style
+
+- **Never explicitly mention TDD** in code, comments, commits, PRs, or issues
+- Write natural, descriptive code without meta-commentary about the development process
+- The code should speak for itself - TDD is the process, not the product
+
+# Code Review
+
+Perform a code review using dynamic category detection.
+
+## Phase 0: Setup & Categorization
+
+### Determine What to Review
+
+Parse the argument to determine the review target:
+
+| Input | Action |
+|-------|--------|
+| No argument | Detect divergence point, confirm scope with user |
+| Branch name | Use specified branch as base |
+| PR number (e.g., `123`) | Fetch PR diff from GitHub |
+| PR URL (e.g., `https://github.com/owner/repo/pull/123`) | Extract PR number and fetch diff |
+
+**For GitHub PRs:**
+
+1. Try GitHub MCP first: `mcp__github__pull_request_read` with `method: "get_diff"`
+2. Fall back to `gh` CLI: `gh pr diff <number>`
+3. If neither works, report error and stop
+
+**For local branches (no argument or branch name provided):**
+
+1. **Get current branch**: `git rev-parse --abbrev-ref HEAD`
+
+2. **Check for uncommitted changes**: `git status --porcelain`
+   - If output is non-empty, note that uncommitted changes exist
+
+3. **Detect divergence point** (skip if branch name was provided as argument):
+   - Get all local branches except current: `git branch --format='%(refname:short)'`
+   - For each branch, find merge-base: `git merge-base HEAD <branch>`
+   - Count commits from merge-base to HEAD: `git rev-list --count <merge-base>..HEAD`
+   - The branch with the **fewest commits back** (closest merge-base) is the likely parent
+   - If no other branches exist, fall back to `main`, `master`, or `develop` if they exist as remote tracking branches
+
+4. **Confirm scope with user** using `AskUserQuestion`:
+
+   **Question 1 - "Review scope"** (header: "Base branch"):
+   - Option A: `From <detected-branch>` — "Review N commits since diverging from <branch>"
+   - Option B: `Different branch` — "Specify another branch to compare against"
+   - Option C: `Uncommitted only` — "Review only staged/unstaged changes, skip committed work"
+
+   **Question 2 - "Include uncommitted?"** (header: "Uncommitted", only ask if uncommitted changes exist AND user didn't pick option C):
+   - Option A: `Yes` — "Include N staged/unstaged files in review"
+   - Option B: `No` — "Review only committed changes"
+
+5. **Collect changed files** based on user selection:
+   - From branch: `git diff --name-only <base>...HEAD`
+   - Uncommitted unstaged: `git diff --name-only`
+   - Uncommitted staged: `git diff --name-only --cached`
+   - Combine and deduplicate the file list
+
+6. **If no changes**: Report "Nothing to review" and stop
+
+### Categorize Files
+
+Check for CLAUDE.md - if it exists, note any project-specific review patterns.
+
+Categorize each changed file into ONE primary category based on these patterns:
+
+| Category | File Patterns |
+|----------|---------------|
+| Frontend/UI | `*.tsx`, `*.jsx`, `components/`, `pages/`, `views/`, `*.vue` |
+| Frontend/Styling | `*.css`, `*.scss`, `*.less`, `styles/`, `*.tailwind*`, `*.styled.*` |
+| Backend/API | `routes/`, `api/`, `controllers/`, `services/`, `*.controller.*`, `*.service.*`, `*.resolver.*` |
+| Backend/Data | `migrations/`, `models/`, `prisma/`, `schema.*`, `*.model.*`, `*.entity.*` |
+| Tooling/Config | `scripts/`, `*.config.*`, `package.json`, `tsconfig.*`, `vite.*`, `webpack.*`, `eslint.*` |
+| CI/CD | `.github/`, `.gitlab-ci.*`, `Dockerfile`, `docker-compose.*`, `*.yml` in CI paths |
+| Tests | `*.test.*`, `*.spec.*`, `__tests__/`, `__mocks__/`, `*.stories.*` |
+| Docs | `*.md`, `docs/`, `README*`, `CHANGELOG*` |
+
+Output the categorization:
+
+```
+## Categorization
+
+Base branch: <branch>
+Total files changed: <n>
+
+| Category | Files |
+|----------|-------|
+| <category> | <count> |
+...
+```
+
+## Phase 1: Branch Brief
+
+From the diff and recent commit messages (`git log <base>...HEAD --oneline`), infer:
+
+- **Goal**: What this branch accomplishes (1-3 sentences)
+- **Constraints**: Any implied requirements (security, performance, backwards compatibility)
+- **Success checklist**: What must work after this change, what must not break
+
+```
+## Branch Brief
+
+**Goal**: ...
+**Constraints**: ...
+**Checklist**:
+- [ ] ...
+```
+
+## Phase 2: Category Reviews
+
+For each detected category with changes, run a targeted review. Skip categories with no changes.
+
+### Frontend/UI Review Criteria
+
+- Accessibility: ARIA attributes, keyboard navigation, screen reader support
+- Component patterns: Composition, prop drilling, context usage
+- State management: Unnecessary re-renders, stale closures
+- Performance: memo/useMemo/useCallback usage, lazy loading, bundle impact
+
+### Frontend/Styling Review Criteria
+
+- Responsive design: Breakpoints, mobile-first
+- Design system: Token usage, consistent spacing/colors
+- CSS specificity: Overly specific selectors, !important usage
+- Theme support: Dark mode, CSS variables
+
+### Backend/API Review Criteria
+
+- Input validation: Sanitization, type checking, bounds
+- Security: Authentication checks, authorization, injection risks
+- Error handling: Proper status codes, meaningful messages, logging
+- Performance: N+1 queries, missing indexes, pagination
+
+### Backend/Data Review Criteria
+
+- Migration safety: Reversibility, data preservation
+- Data integrity: Constraints, foreign keys, nullability
+- Index usage: Queries have appropriate indexes
+- Backwards compatibility: Existing data still works
+
+### Tooling/Config Review Criteria
+
+- Breaking changes: Does this affect developer workflow?
+- Dependency compatibility: Version conflicts, peer deps
+- Build performance: Added build time, bundle size
+
+### CI/CD Review Criteria
+
+- Secrets exposure: Credentials in logs, env vars
+- Pipeline efficiency: Caching, parallelization
+- Failure handling: Notifications, rollback strategy
+
+### Tests Review Criteria
+
+- Coverage: Edge cases, error paths, boundaries
+- Assertion quality: Specific assertions, not just "no error"
+- Flaky patterns: Timing dependencies, order dependencies, shared state
+
+### Docs Review Criteria
+
+- Technical accuracy: Code examples work, APIs documented correctly
+- Completeness: All new features documented
+- Clarity: Easy to follow, good examples
+
+**Output format per category:**
+
+```
+## <Category> Review (<n> files)
+
+### file:line - [blocker|risky|nit] Title
+Description of the issue and why it matters.
+Suggested fix or question to investigate.
+
+...
+```
+
+## Phase 3: Cross-Cutting Analysis
+
+After reviewing all categories, check for cross-cutting issues:
+
+- API changed but tests didn't update?
+- New feature but no documentation?
+- Migration added but no rollback tested?
+- Config changed but README not updated?
+- Security-sensitive code without corresponding test?
+
+```
+## Cross-Cutting Issues
+
+- [ ] <issue description>
+...
+```
+
+## Phase 4: Summary
+
+### PR Description (draft)
+
+Provide a ready-to-paste PR description:
+
+```
+## What changed
+- <by category, 1-2 bullets each>
+
+## Why
+- <motivation>
+
+## Testing
+- <how to verify>
+
+## Notes
+- <migration steps, breaking changes, etc.>
+```
+
+### Review Checklist
+
+```
+## Before Merge
+
+### Blockers (must fix)
+- [ ] ...
+
+### Risky (highlight to reviewers)
+- [ ] ...
+
+### Follow-ups (can defer)
+- [ ] ...
+```
+
+---
+
+Review target (branch name, PR number, or PR URL - leave empty for current branch): $ARGUMENTS

package/downloads/without-beads/commands-metadata.json

@@ -24,6 +24,20 @@
     "category": "Workflow",
     "order": 2
   },
+  "code-review.md": {
+    "description": "Code review using dynamic category detection and domain-specific analysis",
+    "hint": "Review code",
+    "category": "Workflow",
+    "order": 35,
+    "_requested-tools": [
+      "Bash(git diff:*)",
+      "Bash(git status:*)",
+      "Bash(git log:*)",
+      "Bash(git rev-parse:*)",
+      "Bash(git merge-base:*)",
+      "Bash(git branch:*)"
+    ]
+  },
   "commit.md": {
     "description": "Create a git commit following project standards",
     "hint": "Git commit",

package/downloads/without-beads/commit.md

@@ -15,6 +15,22 @@ Create a git commit following project standards
 
 Include any of the following info if specified: $ARGUMENTS
 
+## Commit Message Rules
+
+Follows [Conventional Commits](https://www.conventionalcommits.org/) standard.
+
+1. **Format**: `type(#issue): description`
+   - Use `#123` for local repo issues
+   - Use `owner/repo#123` for cross-repo issues
+   - Common types: `feat`, `fix`, `docs`, `refactor`, `test`, `chore`
+
+2. **AI Credits**: **NEVER include AI credits in commit messages**
+   - No "Generated with Claude Code"
+   - No "Co-Authored-By: Claude" or "Co-Authored-By: Happy"
+   - Focus on the actual changes made, not conversation history
+
+3. **Content**: Write clear, concise commit messages describing what changed and why
+
 ## Process
 
 1. Run `git status` and `git diff` to review changes

package/downloads/without-beads/gap.md

@@ -16,6 +16,7 @@ Analyze the current conversation context and identify things that have not yet b
 1. **Incomplete implementations** - Code that was started but not finished
 2. **Unused variables/results** - Values that were captured but never used
 3. **Missing tests** - Functionality without test coverage
+
 4. **User requests** - Things the user asked for that weren't fully completed
 5. **TODO comments** - Any TODOs mentioned in conversation
 6. **Error handling gaps** - Missing error cases or edge cases

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wbern/claude-instructions",
-  "version": "1.9.0",
+  "version": "1.10.0",
   "description": "TDD workflow commands for Claude Code CLI",
   "type": "module",
   "bin": "./bin/cli.js",
@@ -34,6 +34,7 @@
     "test:quick-manual": "pnpm build:cli && node bin/cli.js",
     "generate": "tsx scripts/cli-generator.ts",
     "test": "vitest run",
+    "test:coverage": "vitest run --coverage",
     "test:watch": "vitest",
     "typecheck": "tsc --noEmit",
     "knip": "knip",
@@ -45,13 +46,13 @@
     "@eslint/js": "^9.39.1",
     "@types/fs-extra": "^11.0.4",
     "@types/node": "^24.10.1",
+    "@vitest/coverage-v8": "^4.0.15",
     "diff": "^8.0.2",
     "eslint": "^9.39.1",
     "husky": "^9.1.7",
     "jscpd": "^4.0.5",
     "knip": "^5.70.2",
     "lint-staged": "^16.2.7",
-    "markdown-magic": "^4.0.4",
     "markdownlint-cli": "^0.46.0",
     "picocolors": "^1.1.1",
     "prettier": "^3.7.2",
@@ -59,7 +60,7 @@
     "tsx": "^4.20.6",
     "typescript": "^5.9.3",
     "typescript-eslint": "^8.48.0",
-    "vitest": "^4.0.8"
+    "vitest": "^4.0.15"
   },
   "dependencies": {
     "@clack/prompts": "^0.11.0",