@pharaoh-so/mcp 0.3.13 → 0.3.15

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
 	"name": "pharaoh",
 	"version": "0.2.3",
-	"description": "Codebase knowledge graph with 23 development workflow skills. Query architecture, dependencies, blast radius, and more instead of reading files one at a time.",
+	"description": "Codebase knowledge graph with focused development workflow skills. Query architecture, dependencies, blast radius, and more instead of reading files one at a time.",
 	"author": {
 		"name": "Pharaoh",
 		"email": "hello@pharaoh.so",

package/commands/plan.md

@@ -0,0 +1,5 @@
+---
+description: Architecture-aware planning with Pharaoh reconnaissance
+---
+
+Invoke the `pharaoh-plan` skill to handle this request. Pass through any arguments: $ARGUMENTS

package/commands/review.md

@@ -0,0 +1,5 @@
+---
+description: Architecture-aware code review with Pharaoh
+---
+
+Invoke the `pharaoh-review` skill to handle this request. Pass through any arguments: $ARGUMENTS

package/dist/install-skills.d.ts

@@ -6,8 +6,12 @@
  */
 export declare function detectOpenClaw(home?: string): boolean;
 /**
- * Copy all bundled skill directories to ~/.openclaw/skills/.
- * Overwrites existing skill dirs on reinstall (cpSync recursive + force).
+ * Install bundled skills to `~/.openclaw/skills/` with the same `pharaoh-`
+ * prefix that Claude Code installs use. Keeps naming consistent across both
+ * platforms and avoids collision with other OpenClaw skills that may ship
+ * bare names like `plan` or `review`.
+ *
+ * Overwrites existing skill dirs on reinstall.
  *
  * @param home - Home directory override (defaults to os.homedir()).
  * @returns Number of skill directories copied.

package/dist/install-skills.js

@@ -5,7 +5,7 @@
  * OpenClaw's ~/.openclaw/skills/ directory (fallback). Also merges
  * the Pharaoh MCP server config into the target platform.
  */
-import { cpSync, existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
+import { cpSync, existsSync, mkdirSync, readdirSync, readFileSync, rmSync, writeFileSync, } from "node:fs";
 import { homedir } from "node:os";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
@@ -15,6 +15,22 @@ const __dirname = dirname(fileURLToPath(import.meta.url));
 const PKG_ROOT = join(__dirname, "..");
 /** Path to the bundled skills directory. */
 const BUNDLED_SKILLS_DIR = join(PKG_ROOT, "skills");
+/** Path to the bundled slash commands directory. */
+const BUNDLED_COMMANDS_DIR = join(PKG_ROOT, "commands");
+/**
+ * Namespace prefix applied to every installed skill. Prevents collision with
+ * other plugins that ship same-named bare skills (e.g. `plan`, `review`).
+ *
+ * Why not use `pharaoh:<skill>` colon-form instead? Claude Code's skill
+ * resolver only auto-namespaces skills from plugins installed via the
+ * marketplace path (`~/.claude/plugins/cache/<marketplace>/...`). Plugins
+ * installed directly to `~/.claude/plugins/data/` — where `npx
+ * @pharaoh-so/mcp --install-skills` installs this package — get their
+ * skills registered as BARE names without any `<plugin>:` prefix. Applying
+ * the prefix as part of the skill's own `name:` field is the only way to
+ * get collision-safe distinctive names on this install path.
+ */
+const SKILL_PREFIX = "pharaoh-";
 // ── Detection ───────────────────────────────────────────────────────
 /**
  * Detect whether Claude Code is installed by checking for ~/.claude/.
@@ -37,11 +53,17 @@ export function detectOpenClaw(home = homedir()) {
 // ── Claude Code installer ───────────────────────────────────────────
 /**
  * Install Pharaoh as a Claude Code plugin by copying the full plugin
- * structure (`.claude-plugin/`, `skills/`, `.mcp.json`) to a persistent
- * directory under `~/.claude/plugins/data/pharaoh/`.
+ * structure (`.claude-plugin/`, `skills/`, `.mcp.json`, `commands/`) to a
+ * persistent directory under `~/.claude/plugins/data/pharaoh/`, plus user-
+ * level slash command templates under `~/.claude/commands/`.
+ *
+ * Claude Code auto-discovers skills from the `skills/` subdirectory when
+ * the plugin manifest (`.claude-plugin/plugin.json`) is present.
  *
- * Claude Code auto-discovers skills from the `skills/` subdirectory
- * when the plugin manifest (`.claude-plugin/plugin.json`) is present.
+ * Each skill is installed with a `pharaoh-` prefix (see SKILL_PREFIX) to
+ * avoid collision with other plugins that may ship same-named bare skills.
+ * The source directory keeps its bare name — the prefix is applied
+ * mechanically during copy with no drift possible.
  *
  * @param home - Home directory override (defaults to os.homedir()).
  * @returns Number of skill directories installed, or -1 on failure.
@@ -59,33 +81,14 @@ function installClaudeCodePlugin(home = homedir()) {
         process.stderr.write("Pharaoh: .claude-plugin/ manifest not found in package — cannot install.\n");
         return -1;
     }
-    // Copy skills/ and generate pharaoh-* prefixed aliases
-    let skillCount = 0;
-    if (existsSync(BUNDLED_SKILLS_DIR)) {
-        cpSync(BUNDLED_SKILLS_DIR, join(pluginDir, "skills"), { recursive: true, force: true });
-        const entries = readdirSync(BUNDLED_SKILLS_DIR, { withFileTypes: true });
-        const skillDirs = entries.filter((e) => e.isDirectory());
-        skillCount = skillDirs.length;
-        // Auto-generate pharaoh-* prefixed copies so both `/plan` and `pharaoh:plan`
-        // resolve to the same content. Without this, prefixed copies drift and users
-        // get a stripped skeleton when invoking via the pharaoh: prefix.
-        for (const dir of skillDirs) {
-            if (dir.name === "pharaoh" || dir.name.startsWith("pharaoh-"))
-                continue;
-            const prefixedName = `pharaoh-${dir.name}`;
-            const prefixedDir = join(pluginDir, "skills", prefixedName);
-            const srcSkill = join(pluginDir, "skills", dir.name, "SKILL.md");
-            if (!existsSync(srcSkill))
-                continue;
-            mkdirSync(prefixedDir, { recursive: true });
-            const content = readFileSync(srcSkill, "utf-8");
-            // Rewrite the name field in YAML frontmatter only (between --- delimiters).
-            // Using a whole-file /m regex would match `name:` in body content too.
-            const rewritten = content.replace(/^(---\n[\s\S]*?)(name:\s*).+(\n[\s\S]*?---)/, `$1$2${prefixedName}$3`);
-            writeFileSync(join(prefixedDir, "SKILL.md"), rewritten);
-            skillCount++;
-        }
-    }
+    // Install skills under the pharaoh- prefix for collision-safe names.
+    const skillsDst = join(pluginDir, "skills");
+    const skillCount = installPrefixedSkills(BUNDLED_SKILLS_DIR, skillsDst, SKILL_PREFIX);
+    // Migrate: delete any bare-name skill dirs left from prior installs
+    // that used the dual bare+prefixed layout. Without this, users who
+    // upgrade keep both copies and Claude Code's prompt-name dedupe picks
+    // the wrong one.
+    cleanupBareNameSkills(BUNDLED_SKILLS_DIR, skillsDst);
     // Copy .mcp.json
     const mcpSrc = join(PKG_ROOT, ".mcp.json");
     if (existsSync(mcpSrc)) {
@@ -93,6 +96,111 @@ function installClaudeCodePlugin(home = homedir()) {
     }
     return skillCount;
 }
+/**
+ * Copy every skill directory from `srcDir` to `dstDir`, prefixing both the
+ * target directory name and the `name:` field in its SKILL.md frontmatter
+ * with `prefix`.
+ *
+ * Exception: a source directory whose name equals the prefix stripped of
+ * its trailing dash is copied WITHOUT a double-prefix. Example: with
+ * `prefix = "pharaoh-"`, the source dir `pharaoh/` is copied to `pharaoh/`
+ * unchanged, not `pharaoh-pharaoh/`. This keeps the flagship skill's name
+ * clean.
+ *
+ * @param srcDir - Source skills directory (bundled with the package).
+ * @param dstDir - Destination skills directory (inside the plugin path).
+ * @param prefix - Namespace prefix to apply (e.g., `"pharaoh-"`).
+ * @returns Number of skill directories installed.
+ */
+function installPrefixedSkills(srcDir, dstDir, prefix) {
+    if (!existsSync(srcDir))
+        return 0;
+    mkdirSync(dstDir, { recursive: true });
+    // `pharaoh-` → `pharaoh` — the source directory name that's exempt from
+    // the prefix to avoid `pharaoh-pharaoh`.
+    const exemptName = prefix.replace(/-$/, "");
+    const entries = readdirSync(srcDir, { withFileTypes: true });
+    let count = 0;
+    for (const entry of entries) {
+        if (!entry.isDirectory())
+            continue;
+        const srcSkill = join(srcDir, entry.name);
+        const srcSkillMd = join(srcSkill, "SKILL.md");
+        if (!existsSync(srcSkillMd))
+            continue;
+        const dstName = entry.name === exemptName ? entry.name : `${prefix}${entry.name}`;
+        const dstSkill = join(dstDir, dstName);
+        // Copy the full source tree (SKILL.md + any supporting files).
+        cpSync(srcSkill, dstSkill, { recursive: true, force: true });
+        // Rewrite the frontmatter `name:` field only if we applied the prefix.
+        if (dstName !== entry.name) {
+            const dstSkillMd = join(dstSkill, "SKILL.md");
+            const content = readFileSync(dstSkillMd, "utf-8");
+            const rewritten = content.replace(/^(---\n[\s\S]*?)(name:\s*).+(\n[\s\S]*?---)/, `$1$2${dstName}$3`);
+            writeFileSync(dstSkillMd, rewritten);
+        }
+        count++;
+    }
+    return count;
+}
+/**
+ * Delete bare-name skill directories from prior installs that used the dual
+ * bare+prefixed layout. Only removes directories that match the name of a
+ * bundled source skill (so we don't accidentally delete user-installed
+ * skills from other sources that happen to share the `pharaoh/skills/`
+ * install path).
+ *
+ * @param srcDir - Bundled source skills directory.
+ * @param dstDir - Installed skills directory.
+ * @returns Number of stale directories removed.
+ */
+function cleanupBareNameSkills(srcDir, dstDir) {
+    if (!existsSync(srcDir) || !existsSync(dstDir))
+        return 0;
+    const exemptName = SKILL_PREFIX.replace(/-$/, "");
+    const sourceNames = new Set(readdirSync(srcDir, { withFileTypes: true })
+        .filter((e) => e.isDirectory() && e.name !== exemptName)
+        .map((e) => e.name));
+    let removed = 0;
+    for (const name of sourceNames) {
+        const staleDir = join(dstDir, name);
+        if (existsSync(staleDir)) {
+            rmSync(staleDir, { recursive: true, force: true });
+            removed++;
+        }
+    }
+    return removed;
+}
+/**
+ * Copy bundled slash command templates (`.md` files in the package's
+ * `commands/` directory) to `~/.claude/commands/`, unconditionally
+ * overwriting any existing file with the same name.
+ *
+ * Overwriting is intentional: the install contract is "slash commands just
+ * work out of the box," so the canonical shipped versions take precedence
+ * over user customizations. Users who want custom command behavior should
+ * use different filenames.
+ *
+ * @param home - Home directory override (defaults to os.homedir()).
+ * @returns Number of commands installed.
+ */
+function installClaudeCodeCommands(home) {
+    if (!existsSync(BUNDLED_COMMANDS_DIR))
+        return 0;
+    const commandsDst = join(home, ".claude", "commands");
+    mkdirSync(commandsDst, { recursive: true });
+    const entries = readdirSync(BUNDLED_COMMANDS_DIR, { withFileTypes: true });
+    let count = 0;
+    for (const entry of entries) {
+        if (!entry.isFile() || !entry.name.endsWith(".md"))
+            continue;
+        const src = join(BUNDLED_COMMANDS_DIR, entry.name);
+        const dst = join(commandsDst, entry.name);
+        cpSync(src, dst, { force: true });
+        count++;
+    }
+    return count;
+}
 /**
  * Register Pharaoh in Claude Code's installed_plugins.json (v2 format).
  * Adds a new entry or updates the version/lastUpdated of an existing one.
@@ -152,8 +260,12 @@ function registerClaudeCodePlugin(home = homedir()) {
 }
 // ── OpenClaw installer ──────────────────────────────────────────────
 /**
- * Copy all bundled skill directories to ~/.openclaw/skills/.
- * Overwrites existing skill dirs on reinstall (cpSync recursive + force).
+ * Install bundled skills to `~/.openclaw/skills/` with the same `pharaoh-`
+ * prefix that Claude Code installs use. Keeps naming consistent across both
+ * platforms and avoids collision with other OpenClaw skills that may ship
+ * bare names like `plan` or `review`.
+ *
+ * Overwrites existing skill dirs on reinstall.
  *
  * @param home - Home directory override (defaults to os.homedir()).
  * @returns Number of skill directories copied.
@@ -163,14 +275,11 @@ export function installSkills(home = homedir()) {
     if (!existsSync(targetDir)) {
         mkdirSync(targetDir, { recursive: true });
     }
-    const entries = readdirSync(BUNDLED_SKILLS_DIR, { withFileTypes: true });
-    const skillDirs = entries.filter((e) => e.isDirectory()).map((e) => e.name);
-    for (const skillName of skillDirs) {
-        const src = join(BUNDLED_SKILLS_DIR, skillName);
-        const dst = join(targetDir, skillName);
-        cpSync(src, dst, { recursive: true, force: true });
-    }
-    return skillDirs.length;
+    // Prefix skills for collision safety (same rationale as Claude Code path).
+    const count = installPrefixedSkills(BUNDLED_SKILLS_DIR, targetDir, SKILL_PREFIX);
+    // Also clean up any bare-name leftovers from prior installs.
+    cleanupBareNameSkills(BUNDLED_SKILLS_DIR, targetDir);
+    return count;
 }
 /**
  * Read ~/.openclaw/openclaw.json, add the Pharaoh MCP server under `mcpServers`,
@@ -263,6 +372,7 @@ export function runInstallSkills(home = homedir(), options) {
         const count = installClaudeCodePlugin(home);
         if (count >= 0) {
             const regResult = registerClaudeCodePlugin(home);
+            const commandCount = installClaudeCodeCommands(home);
             // Silently ensure Pharaoh tools auto-approve (no user prompt on first use)
             configureClaudeCodePermissions(home);
             if (!silent) {
@@ -272,10 +382,14 @@ export function runInstallSkills(home = homedir(), options) {
                     current: "Plugin already registered and up-to-date",
                     error: "Could not update installed_plugins.json",
                 };
+                const commandLine = commandCount > 0
+                    ? `  → Installed ${commandCount} slash command${commandCount === 1 ? "" : "s"} to ~/.claude/commands/`
+                    : null;
                 process.stderr.write([
                     `Pharaoh: installed ${count} skills as Claude Code plugin`,
                     `  → ~/.claude/plugins/data/pharaoh/`,
                     `  → ${regMessages[regResult]}`,
+                    ...(commandLine ? [commandLine] : []),
                     "",
                     ...(regResult === "added" ? ["Restart Claude Code to pick up the new skills.", ""] : []),
                 ].join("\n"));

package/inspect-tools.json

@@ -724,46 +724,46 @@
     },
     {
       "name": "pharaoh_account",
-      "description": "View your Pharaoh subscription status and manage billing. Toggle PR Guard and trigger graph refreshes.\n\nCALL THIS WHEN:\n• You want to check your subscription status\n• You need to update payment method, view invoices, or cancel\n• You want to know what plan you're on\n• You want to change which repo is active on the free tier\n• You want to enable or disable PR Guard on a repo\n• You want to refresh a repo's graph (re-map with latest code)\n• You want to open the Pharaoh dashboard to manage repos and settings visually",
+      "description": "View your Pharaoh subscription status and manage billing. Toggle PR Guard and trigger graph refreshes.\n\nPick one action and provide its fields. Each action has its own required and\noptional parameters; invalid combinations are rejected at parse time.\n\n• status — full account overview (plan, subscriptions, PR Guard, dashboard URL)\n• set_free_repo { repo } — change which repo is active on the free tier\n• refresh_repo { repo, full? } — re-map a single repo you own\n• refresh_all { force?, full? } — re-map every repo across your accessible orgs\n• enable_pr_guard { repos: [...] } — enable PR Guard on one or more repos, returns full status\n• disable_pr_guard { repos: [...] } — disable PR Guard on one or more repos, returns full status\n\nCALL THIS WHEN:\n• You want to check your subscription status\n• You need to update payment method, view invoices, or cancel\n• You want to know what plan you're on\n• You want to change which repo is active on the free tier\n• You want to enable or disable PR Guard on a repo\n• You want to refresh a repo's graph (re-map with latest code)\n• You want to open the Pharaoh dashboard to manage repos and settings visually\n\nFlag reference:\n  force = skip smart-skip (already-on-current-version check). Bulk refresh only.\n  full  = force full remap, bypassing incremental diff. Use after schema changes.",
       "inputSchema": {
         "$schema": "http://json-schema.org/draft-07/schema#",
         "type": "object",
         "properties": {
-          "enable_pr_guard": {
-            "description": "Repo slugs (owner/repo) to enable PR Guard on",
-            "type": "array",
-            "items": {
-              "type": "string"
-            }
+          "action": {
+            "type": "string",
+            "enum": [
+              "status",
+              "set_free_repo",
+              "refresh_repo",
+              "refresh_all",
+              "enable_pr_guard",
+              "disable_pr_guard"
+            ],
+            "description": "Which account action to perform"
+          },
+          "repo": {
+            "description": "Used by: set_free_repo (required), refresh_repo (required). Repo slug (owner/repo).",
+            "type": "string"
           },
-          "disable_pr_guard": {
-            "description": "Repo slugs (owner/repo) to disable PR Guard on",
+          "repos": {
+            "description": "Used by: enable_pr_guard, disable_pr_guard (required). Repo slugs (owner/repo) to toggle.",
             "type": "array",
             "items": {
               "type": "string"
             }
           },
-          "set_free_repo": {
-            "description": "Repo slug (owner/repo) to set as your active free-tier repo",
-            "type": "string"
-          },
-          "refresh_repo": {
-            "description": "Repo slug (owner/repo) to re-map. Must belong to your org.",
-            "type": "string"
-          },
-          "refresh_all": {
-            "description": "Re-map all repos in your org (rate limited: once per hour)",
-            "type": "boolean"
-          },
           "force": {
-            "description": "Bulk refresh only (refresh_all): skip the 'already on current version' check. Does NOT force full remap — use `full: true` for that. Ignored with refresh_repo.",
+            "description": "Used by: refresh_all. Skip the 'already on current version' smart-skip check. Does NOT force full remap — use `full` for that.",
             "type": "boolean"
           },
           "full": {
-            "description": "Force full remap, bypassing incremental-diff detection. Use after schema changes or to rebuild the graph from scratch. Combine with refresh_repo or refresh_all.",
+            "description": "Used by: refresh_repo, refresh_all. Force full remap, bypassing incremental diff. Use after schema changes or to rebuild the graph from scratch.",
             "type": "boolean"
           }
-        }
+        },
+        "required": [
+          "action"
+        ]
       },
       "annotations": {
         "title": "Account Management",

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@pharaoh-so/mcp",
   "mcpName": "so.pharaoh/pharaoh",
-  "version": "0.3.13",
+  "version": "0.3.15",
   "description": "MCP proxy for Pharaoh — maps codebases into queryable knowledge graphs for AI agents. Enables Claude Code in headless environments (VPS, SSH, CI) via device flow auth.",
   "type": "module",
   "main": "dist/index.js",
@@ -12,6 +12,7 @@
   "files": [
     "dist",
     "skills",
+    "commands",
     ".claude-plugin",
     ".mcp.json",
     "inspect-tools.json",

package/skills/brainstorm/SKILL.md

@@ -56,7 +56,7 @@ Save the validated design to a spec file and commit it. Ask the user to review b
 
 ### 7. Transition
 
-Once the spec is approved, move to implementation planning. Use `pharaoh:execute` to carry out the plan.
+Once the spec is approved, move to implementation. Use the `plan` skill to break the work into verified steps, then build.
 
 ## Working in Existing Codebases
 

package/skills/plan/SKILL.md

@@ -1,8 +1,8 @@
 ---
 name: plan
 prompt-name: plan-with-pharaoh
-description: Deep plan review with Pharaoh reconnaissance, wiring verification, and structured issue tracking. Use before implementing any feature, refactor, or significant code change. Enters plan mode (no code changes) and provides structured review with decision points.
-version: 0.5.0
+description: Architecture-aware plan review adapted from Garry Tan's framework for AI-assisted development. Pharaoh reconnaissance, mandatory mode selection, structured six-section review with decision points. Drop-in replacement that supersedes the legacy ~/.claude/skills/plan-review skill — every section of the legacy skill is present here, plus graceful fallback when Pharaoh is unavailable, stronger mode-selection enforcement, and an explicit framework reference.
+version: 0.6.0
 homepage: https://pharaoh.so
 user-invocable: true
 metadata: {"emoji": "☥", "tags": ["planning", "architecture", "blast-radius", "pharaoh", "review", "interactive"]}
@@ -10,12 +10,16 @@ metadata: {"emoji": "☥", "tags": ["planning", "architecture", "blast-radius",
 
 # Plan Review
 
+Architecture-aware plan review before implementation. Adapted from [Garry Tan's planning framework](https://www.youtube.com/watch?v=bMknfKXIFA8) for AI-assisted development.
+
 **You are now in plan mode. Do NOT make any code changes. Think, evaluate, and present decisions.**
 
 ## Document Review
 
 If the user provides a document, PRD, prompt, or artifact alongside this command, that IS the plan to review. Apply all review sections to that document. Do not treat it as background context — it is the subject of evaluation.
 
+Still run Step 1 (Reconnaissance) even when reviewing a document — always verify the plan against the actual codebase state.
+
 ## Project Overrides
 
 If a `.claude/plan-review.md` file exists in this project, read it now and apply those rules on top of this baseline. Project rules take precedence where they conflict.
@@ -32,42 +36,40 @@ If a `.claude/plan-review.md` file exists in this project, read it now and apply
 
 ## Step 1: Pharaoh Reconnaissance (Required — do this BEFORE reviewing)
 
-Do NOT review from memory or assumptions. Query the actual codebase first:
+Do NOT review from memory or assumptions. Query the actual codebase first.
+
+### If Pharaoh MCP tools are available:
 
 1. `get_codebase_map` — current modules, hot files, dependency graph
 2. `search_functions` for keywords related to the plan — find existing code to reuse/extend
 3. `get_module_context` on affected modules — entry points, patterns, conventions
 4. `query_dependencies` between affected modules — coupling, circular deps
+5. `get_blast_radius` on the primary target of the change — know what breaks
+6. `check_reachability` on the primary target — verify it's actually reachable from entry points before worrying about it
 
-Ground every recommendation in what actually exists. If you propose adding something, confirm it doesn't already exist. If you propose changing something, know its blast radius.
-
-## Step 1b: Reconnaissance Dashboard
-
-After running recon, present a visual summary before proceeding. This shows the user what Pharaoh found.
+### Without Pharaoh (graceful fallback):
 
-**Surface all ★ Pharaoh insight blocks verbatim** — they contain pre-formatted bar charts, risk meters, and flow diagrams. Do not summarize or paraphrase them.
+1. Search the codebase for files and functions related to the plan (grep, glob)
+2. Read the entry points and module structure of affected areas
+3. Check existing tests for the modules the plan will touch
+4. Trace imports manually to estimate blast radius
 
-Then compose a **Recon Summary** table:
-
-| Signal | Value | Source |
-|--------|-------|--------|
-| Modules affected | N | get_codebase_map |
-| Blast radius | LOW/MED/HIGH + caller count | get_blast_radius |
-| Existing functions found | N matches | search_functions |
-| Cross-module coupling | deps + circular? | query_dependencies |
+Ground every recommendation in what actually exists. If you propose adding something, confirm it doesn't already exist. If you propose changing something, know its blast radius.
 
-If any signal is surprising (high blast radius, circular deps, existing code that overlaps the plan), call it out before moving to Mode Selection.
+## Step 2: Mode Selection (MANDATORY — ask before proceeding)
 
-## Step 2: Mode Selection
+**STOP and ask the user which mode before starting the review.** This is a hard gate — do not infer, assume, or skip this question even if the user says "yes", "go ahead", or "yes to all". Present both options and wait for an explicit choice:
 
-Ask the user which mode before starting the review:
+> **BIG CHANGE or SMALL CHANGE?**
+>
+> - **BIG CHANGE**: Full interactive review, all relevant sections, up to 4 top issues per section
+> - **SMALL CHANGE**: One question per section, only sections 2-4
 
-**BIG CHANGE**: Full interactive review, all relevant sections, up to 4 top issues per section.
-**SMALL CHANGE**: One question per section, only sections 2-4.
+If the user's response is ambiguous (e.g. "just do it", "yes to all"), ask again: "I need to know — BIG or SMALL change?" Do not proceed to Step 3 without an answer.
 
 ## Step 3: Review Sections
 
-Adapt depth to change size. Skip sections that don't apply.
+Adapt depth to change size. Skip sections that don't apply. **After each section, pause and ask for feedback before moving on.**
 
 ### Section 1 — Architecture (skip for small/single-file changes)
 
@@ -135,7 +137,7 @@ Number each issue (1, 2, 3...) and letter each option (A, B, C...). Recommended
 
 ## Workflow Rules
 
-- After each section, pause and ask for feedback before moving on
+- **After each section, pause and ask for feedback before moving on**
 - Do not assume priorities on timeline or scale
 - If you see a better approach to the entire plan, say so BEFORE section-by-section review
 - Challenge the approach if you see a better one — your job is to find problems I'll regret later

package/skills/audit-tests/SKILL.md

@@ -1,89 +0,0 @@
----
-name: audit-tests
-prompt-name: audit-tests
-description: "Classify tests by real value: ceremony versus protection. Mutation score over line coverage — tests that can't detect mutations are theater. Identify tests that prove nothing, tests that duplicate coverage, and gaps where real protection is missing. Produce an actionable audit with keep, rewrite, and delete verdicts."
-version: 0.2.0
-homepage: https://pharaoh.so
-user-invocable: true
-metadata: {"emoji": "☥", "tags": ["test-audit", "mutation-testing", "test-quality", "coverage", "testing"]}
----
-
-# Test Audit
-
-Classify tests by whether they actually protect against regressions. Line coverage is vanity — mutation score is truth. A test that can't detect a mutation in the code it covers is theater.
-
-## When to Use
-
-- Before refactoring a module — know which tests actually protect you
-- After inheriting a codebase — separate real coverage from ceremony
-- When test suite is slow — find tests to delete without losing protection
-- When coverage numbers are high but bugs still ship
-
-## Process
-
-### 1. Inventory
-
-List all test files for the target module or area. For each test file, note:
-
-- What production code it exercises
-- Whether it uses mocks or real implementations
-- Approximate assertion count
-
-If Pharaoh tools are available, call `get_test_coverage` to see which modules have tests and which don't.
-
-### 2. Classify Each Test
-
-| Category | Definition | Action |
-|----------|-----------|--------|
-| **Guardian** | Tests real behavior with real code. Would catch a regression. | Keep |
-| **Ceremony** | Passes regardless of code changes. Tests mocks, not behavior. | Rewrite or delete |
-| **Duplicate** | Same behavior tested multiple times across files. | Keep one, delete rest |
-| **Snapshot** | Records current output without asserting correctness. | Evaluate — keep if output matters, delete if not |
-| **Fragile** | Breaks on irrelevant changes (formatting, ordering, timing). | Rewrite to test behavior, not implementation |
-
-### 3. Mutation Check
-
-For critical tests, mentally (or actually) apply mutations to the code under test:
-
-- Change `>` to `>=`
-- Remove an `if` branch
-- Return early
-- Swap function arguments
-- Delete a line
-
-**If the test still passes after any of these mutations, it's not testing what you think.**
-
-### 4. Gap Analysis
-
-Identify code that has:
-- No tests at all
-- Only ceremony tests (effectively no real coverage)
-- Tests that mock the thing they're supposed to verify
-
-Prioritize gaps by risk: code in hot paths, security-sensitive code, and code with high blast radius (use `get_blast_radius` if available) needs real tests first.
-
-### 5. Produce Audit Report
-
-For each test file:
-
-- **Verdict:** KEEP, REWRITE, or DELETE
-- **Reason:** one sentence explaining why
-- **Priority:** if REWRITE, how urgent (based on risk of the code it covers)
-
-## What Makes a Test Valuable
-
-| Valuable | Not valuable |
-|----------|-------------|
-| Tests behavior through public API | Tests private implementation details |
-| Uses real dependencies | Mocks the thing under test |
-| Has hardcoded expected values | Computes expected values from production code |
-| Fails when behavior changes | Passes regardless of code changes |
-| Describes WHAT should happen | Describes HOW it's currently implemented |
-
-## Key Principles
-
-- **Mutation score > line coverage** — a test that can't detect mutations is worth zero
-- **One real integration test > ten mock-heavy unit tests** — mocks hide bugs
-- **Hardcoded expectations** — tests that compute their expected output prove nothing
-- **Delete with confidence** — removing a ceremony test loses nothing and speeds up the suite
-- **If you can't describe what makes a test fail, it's worthless**

package/skills/debt/SKILL.md

@@ -1,34 +0,0 @@
----
-name: debt
-prompt-name: find-tech-debt
-description: "Categorized technical debt report using Pharaoh knowledge graph. Four-step pro-tier workflow: dead code detection, duplicate logic discovery, undocumented complex functions via spec gaps, and volatile high-complexity module identification. Categorizes findings as DELETE, CONSOLIDATE, DOCUMENT, STABILIZE, or TEST — each with the specific function or file, effort estimate, and risk of ignoring."
-version: 0.2.0
-homepage: https://pharaoh.so
-user-invocable: true
-metadata: {"emoji": "☥", "tags": ["tech-debt", "dead-code", "consolidation", "pharaoh", "documentation", "volatility", "test-coverage"]}
----
-
-# Find Tech Debt
-
-Categorized technical debt report. Uses `find-tech-debt` — a 4-step pro-tier workflow that finds and categorizes every class of debt: dead code, duplicates, undocumented complexity, volatile modules, and untested functions. Requires Pro tools.
-
-## When to Use
-
-Invoke when asked to find technical debt, prioritize a cleanup sprint, or understand where the codebase has degraded. Use it before planning a refactoring effort or when the codebase has accumulated changes without systematic review.
-
-## Workflow
-
-1. Call `get_unused_code` for the target repository to find dead exports and orphaned functions.
-2. Call `get_consolidation_opportunities` for the target repository to find duplicated logic across modules.
-3. Call `get_vision_gaps` for the target repository to find undocumented complex functions and unimplemented specs.
-4. Call `get_codebase_map` for the target repository with `include_metrics` to find volatile and high-complexity modules.
-
-## Output
-
-Categorized findings with one entry per item:
-
-- **DELETE:** Dead code safe to remove (unreachable, no callers) — with function/file name, effort (small/medium/large), risk of ignoring
-- **CONSOLIDATE:** Duplicated logic that should be unified — with affected modules, effort, risk of ignoring
-- **DOCUMENT:** Complex functions lacking specs or documentation — with function name, complexity score, effort, risk of ignoring
-- **STABILIZE:** Volatile modules that change too often (likely fragile) — with volatility data, effort, risk of ignoring
-- **TEST:** High-complexity functions with no test coverage — with function name, complexity score, effort, risk of ignoring