@pharaoh-so/mcp 0.3.8 → 0.3.9

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@pharaoh-so/mcp",
   "mcpName": "so.pharaoh/pharaoh",
-  "version": "0.3.8",
+  "version": "0.3.9",
   "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",

package/skills/plan/SKILL.md

@@ -1,8 +1,8 @@
 ---
 name: plan
 prompt-name: plan-with-pharaoh
-description: "Deep plan review before implementing any feature, refactor, or significant code change. Enters plan mode — no code changes, just evaluation and interactive decision-making."
-version: 0.4.0
+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
 homepage: https://pharaoh.so
 user-invocable: true
 metadata: {"emoji": "☥", "tags": ["planning", "architecture", "blast-radius", "pharaoh", "review", "interactive"]}
@@ -10,18 +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.**
 
-**You are in plan mode. Do NOT make any code changes. Think, evaluate, 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.
 
 ## 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.
 
-## Document Review
-
-If the user provides a document, PRD, prompt, or artifact alongside this command, that IS the plan to review. Still run Step 1 (Reconnaissance) — always verify against the actual codebase. Then apply all review sections to that document. Do not treat it as background context — it is the subject of evaluation.
-
 ## Engineering Preferences (guide all recommendations)
 
 - DRY: flag repetition aggressively
@@ -32,61 +30,64 @@ If the user provides a document, PRD, prompt, or artifact alongside this command
 - Subtraction > addition; target zero or negative net LOC
 - Every export must have a caller; unwired code doesn't exist
 
-## Step 1: Reconnaissance (Required — do this BEFORE reviewing)
-
-Do NOT review from memory or assumptions. Query the actual codebase first.
+## Step 1: Pharaoh Reconnaissance (Required — do this BEFORE reviewing)
 
-### If Pharaoh MCP tools are available:
+Do NOT review from memory or assumptions. Query the actual codebase first:
 
 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
-6. `check_reachability` on the primary target to verify it's reachable from entry points
 
-### Without Pharaoh:
+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.
 
-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 you'll touch
+## Step 1b: Reconnaissance Dashboard
 
-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.
+After running recon, present a visual summary before proceeding. This shows the user what Pharaoh found.
+
+**Surface all ★ Pharaoh insight blocks verbatim** — they contain pre-formatted bar charts, risk meters, and flow diagrams. Do not summarize or paraphrase them.
 
-## Step 2: Mode Selection (MANDATORY — ask before proceeding)
+Then compose a **Recon Summary** table:
 
-**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:
+| 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 |
 
-> **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
+If any signal is surprising (high blast radius, circular deps, existing code that overlaps the plan), call it out before moving to Mode Selection.
 
-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 2: Mode Selection
+
+Ask the user which mode before starting the review:
+
+**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.
 
 ## Step 3: Review Sections
 
-Adapt depth to change size. Skip sections that don't apply. **After each section, pause and ask for feedback before moving on.**
+Adapt depth to change size. Skip sections that don't apply.
 
 ### Section 1 — Architecture (skip for small/single-file changes)
 
 - Component boundaries and coupling concerns
 - Dependency graph: does this change shrink or expand surface area?
 - Data flow bottlenecks and single points of failure
-- Does this need new code at all, or can an existing pattern solve it?
+- Does this need new code at all, or can a human process / existing pattern solve it?
 
 ### Section 2 — Code Quality (always)
 
 - Organization, module structure, DRY violations (be aggressive)
 - Error handling gaps and missing edge cases (call out explicitly)
 - Technical debt: shortcuts, hardcoded values, magic strings
-- Over-engineered or under-engineered relative to preferences above
+- Over-engineered or under-engineered relative to my preferences
 - Reuse: does code for this already exist somewhere?
 
 ### Section 3 — Wiring & Integration (always)
 
 - Are all new exports called from a production entry point?
-- Run `get_blast_radius` on new/changed functions — zero callers = not done
+- Run `get_blast_radius` on any new/changed functions — zero callers = not done
 - `check_reachability` on new exports — verify reachable from API handlers, crons, or event handlers
 - Does the plan declare WHERE new code gets called from? If not, flag it
 - Integration points: how does this connect to what already exists?
@@ -104,14 +105,14 @@ Adapt depth to change size. Skip sections that don't apply. **After each section
 - Memory concerns, caching opportunities
 - Slow or high-complexity code paths
 
-### Section 6 — Security & Attack Surface (only for new endpoints/routes/APIs)
+### Section 6 — Security & Attack Surface (always for new endpoints/routes/APIs; skip for pure refactors)
 
-- **Authentication model** — what authenticates requests? Where validated? What happens on failure?
-- **Sensitive data in URLs** — tokens, session IDs, or tenant identifiers in URL paths/params leak via Referer, history, logs
-- **Authorization boundaries** — what prevents User A from accessing User B's data?
-- **Input trust boundary** — user input flowing into shell commands, queries, HTML rendering, or file paths
-- **Error and response surface** — do error responses expose internals to unauthenticated callers?
-- **New attack surface** — new public URLs, webhooks, API routes each need rate limiting, auth, and input validation
+- **Authentication model** — what authenticates requests in this plan? Where is it validated? What happens on auth failure (redirect, 401, silent pass-through)? Use `search_functions` to find existing auth middleware and confirm reuse.
+- **Sensitive data in URLs** — does the design put tokens, session IDs, or tenant identifiers in URL paths or query params? These leak via Referer headers, browser history, logs, and link sharing.
+- **Authorization boundaries** — what prevents User A from accessing User B's data? Is there an ownership check, or just an "is logged in" check? Use `get_blast_radius` on existing ownership-check functions to see where they're already enforced.
+- **Input trust boundary** — does the plan accept user input that flows into shell commands, database queries, HTML rendering, or file paths? Each is an injection vector.
+- **Error and response surface** — will error responses or API payloads expose internals (stack traces, DB schemas, internal IDs) to unauthenticated callers?
+- **New attack surface** — does the plan introduce new public URLs, webhooks, API routes, or WebSocket endpoints? Each needs: rate limiting, authentication, and input validation. Use `get_module_context` on the receiving module to check what protections exist.
 
 ## For Each Issue Found
 
@@ -120,23 +121,21 @@ For every specific issue (bug, smell, design concern, risk, missing wiring):
 1. **Describe concretely** — file, line/function reference, what's wrong
 2. **Present 2-3 options** including "do nothing" where reasonable
 3. **For each option** — implementation effort, risk, blast radius, maintenance burden
-4. **Recommend one** mapped to the preferences above, and say why
-5. **Ask** whether the user agrees or wants a different direction
-
-Number each issue (1, 2, 3...) and letter each option (A, B, C...). Recommended option listed first.
+4. **Recommend one** mapped to my preferences above, and say why
+5. **Ask** whether I agree or want a different direction
 
-## Wiring Checkpoints
+Number each issue (1, 2, 3...) and letter each option (A, B, C...). Recommended option is always listed first. Use AskUserQuestion with clear labels like "Issue 1 Option A", "Issue 1 Option B".
 
-Use these throughout the review, not just at the end:
+## Pharaoh Checkpoints (use throughout, not just at the end)
 
 - **Before reviewing**: recon (Step 1 above)
-- **During review**: check blast radius when evaluating impact; search for existing functions before suggesting new code
-- **After decisions**: verify all new exports are reachable; check for disconnected code
-- **Final sweep**: every new export must have a caller from a production entry point, or the plan is incomplete
+- **During review**: `get_blast_radius` when evaluating impact of changes; `search_functions` before suggesting new code
+- **After decisions**: `check_reachability` on all new exports; `get_unused_code` to catch disconnections
+- **Final sweep**: `get_blast_radius` on ALL new exports — zero callers on non-entry-points = plan is incomplete
 
 ## 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 the user will regret later
+- Challenge the approach if you see a better one — your job is to find problems I'll regret later