@pharaoh-so/mcp 0.2.6 → 0.2.8

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@pharaoh-so/mcp",
   "mcpName": "so.pharaoh/pharaoh",
-  "version": "0.2.6",
+  "version": "0.2.8",
   "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/{pharaoh-audit-tests → audit-tests}/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: pharaoh-audit-tests
+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

package/skills/{pharaoh-brainstorm → brainstorm}/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: pharaoh-brainstorm
+name: brainstorm
 description: "Explore intent, requirements, and design before implementation. Collaborative dialogue to turn ideas into specs. Ask clarifying questions one at a time, propose 2-3 approaches with trade-offs, get approval before writing any code. Prevents wasted work from unexamined assumptions."
 version: 0.2.0
 homepage: https://pharaoh.so

package/skills/{pharaoh-debt → debt}/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: pharaoh-debt
+name: 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

package/skills/{pharaoh-debug → debug}/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: pharaoh-debug
+name: debug
 description: "Systematic 4-phase debugging methodology. Root cause investigation before any fixes. Read errors carefully, reproduce consistently, trace data flow, form hypotheses, test minimally. If 3+ fixes fail, question the architecture. No guessing, no quick patches, no symptom fixes."
 version: 0.2.0
 homepage: https://pharaoh.so

package/skills/{pharaoh-execute → execute}/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: pharaoh-execute
+name: execute
 description: "Execute a written implementation plan with review checkpoints. Load plan, review critically, execute tasks sequentially with verification at each step. Stop and ask when blocked — never guess through ambiguity. Finish with branch completion workflow."
 version: 0.2.0
 homepage: https://pharaoh.so

package/skills/{pharaoh-explore → explore}/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: pharaoh-explore
+name: explore
 description: "Deep-dive into a single codebase module using Pharaoh knowledge graph. Four-step free-tier workflow: full structure with functions, exports, and complexity scores; blast radius of what depends on it; upstream and downstream dependency mapping; and related function discovery. Produces a module briefing with purpose, key functions, dependencies, risk areas, and external API surface."
 version: 0.2.0
 homepage: https://pharaoh.so

package/skills/{pharaoh-finish → finish}/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: pharaoh-finish
+name: finish
 description: "Complete a development branch after implementation. Verify all tests pass, present structured options (merge locally, create PR, keep branch, or discard), execute the chosen workflow, and clean up worktrees. Never merge broken code or delete work without confirmation."
 version: 0.2.0
 homepage: https://pharaoh.so

package/skills/{pharaoh-health → health}/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: pharaoh-health
+name: health
 description: "Full codebase health sweep using Pharaoh knowledge graph. Six-step pro-tier workflow: module map with metrics, dead code detection, test coverage gaps, duplicate logic, regression risk scoring, and spec drift analysis. Produces an A-F grade, top 5 risks, tech debt hotspots (high-complexity + low-coverage + high-volatility intersections), spec drift summary, and prioritized actions with effort estimates."
 version: 0.2.0
 homepage: https://pharaoh.so

package/skills/{pharaoh-investigate → investigate}/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: pharaoh-investigate
+name: investigate
 description: "Full architectural context gathering before modifying a function, file, or module using Pharaoh knowledge graph. Four-step free-tier workflow: module structure, blast radius of downstream callers, related function discovery, and dependency mapping. Blocks code suggestions until all context is gathered. Produces an investigation report with structure, blast radius, related functions, dependency context, and risk assessment."
 version: 0.2.0
 homepage: https://pharaoh.so

package/skills/{pharaoh-onboard → onboard}/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: pharaoh-onboard
+name: onboard
 description: "Quick codebase orientation using Pharaoh knowledge graph. Five-step workflow using only free-tier tools: full module map, deep-dive into the three largest modules, entry point discovery, critical path blast radius, and core data flow mapping. Produces an onboarding summary with module descriptions, entry points, data flow, and key functions to read first."
 version: 0.2.0
 homepage: https://pharaoh.so

package/skills/orchestrate/SKILL.md

@@ -0,0 +1,144 @@
+---
+name: orchestrate
+description: "Execute implementation plans by dispatching one subagent per task with two-stage review (spec compliance then code quality). Sequential task execution with quality gates. Controller stays in session, constructs focused context for each agent, never shares session history. Handles DONE/DONE_WITH_CONCERNS/NEEDS_CONTEXT/BLOCKED status protocol."
+version: 0.2.5
+homepage: https://pharaoh.so
+user-invocable: true
+metadata: {"emoji": "☥", "tags": ["subagents", "orchestration", "plan-execution", "quality-gates", "spec-review", "code-review"]}
+---
+
+# Orchestrate Plan Execution
+
+Execute a plan by dispatching a fresh subagent per task, with two-stage review after each: spec compliance first, then code quality. The controller (you) coordinates — subagents implement and review.
+
+## When to Use
+
+- You have a written implementation plan with 2+ tasks
+- Tasks are mostly independent (different files/modules)
+- You want quality gates between tasks (not just fire-and-forget)
+- You're staying in this session (not dispatching to parallel worktrees)
+
+## When NOT to Use
+
+- Tasks are tightly coupled (use manual execution)
+- You want parallel execution across sessions (use `pharaoh:execute` instead)
+- You don't have a plan yet (use `pharaoh:plan` first)
+- You just need parallel dispatch without review gates (use `pharaoh:parallel`)
+
+## Workflow
+
+### Phase 0 — Setup
+
+1. Read the plan file once. Extract all tasks with full text.
+2. Note cross-task context: shared types, import paths, architectural constraints.
+3. Create a task list tracking each task's status.
+
+### Phase 1 — Per-Task Loop
+
+For each task:
+
+#### 1a. Dispatch Implementer
+
+Launch a subagent with:
+- **Full task text** (paste it, don't make the agent read the file)
+- **Scene-setting context** (where this fits, what's already built, dependencies)
+- **Constraints** (what NOT to change, scope boundaries)
+- **Working directory**
+
+The implementer should:
+1. Ask questions before starting (don't guess)
+2. Implement exactly what the task specifies
+3. Write tests
+4. Commit
+5. Self-review
+6. Report with status: **DONE** / **DONE_WITH_CONCERNS** / **NEEDS_CONTEXT** / **BLOCKED**
+
+#### 1b. Handle Status
+
+- **DONE** → proceed to spec review
+- **DONE_WITH_CONCERNS** → read concerns. If correctness/scope issues, address before review. If observations, note and proceed.
+- **NEEDS_CONTEXT** → provide missing information, re-dispatch
+- **BLOCKED** → assess: provide more context, use a more capable model, break task smaller, or escalate to user
+
+Never ignore an escalation. Never force retry without changes.
+
+#### 1c. Spec Compliance Review
+
+Dispatch a reviewer subagent with:
+- Full task requirements (original spec text)
+- Implementer's report of what they built
+
+The spec reviewer must:
+- Read actual code, not trust the report
+- Check: missing requirements, extra/unneeded work, misinterpretations
+- Verdict: **pass** or **issues found** (with file:line references)
+
+If issues found → implementer fixes → spec reviewer re-reviews → repeat until pass.
+
+#### 1d. Code Quality Review
+
+Only after spec compliance passes. Dispatch a quality reviewer with:
+- What was implemented
+- Git SHAs (base and head)
+- Task requirements
+
+The quality reviewer checks:
+- Single responsibility per file
+- Clean interfaces and decomposition
+- Test quality (assertions that verify behavior, not just coverage)
+- Following existing codebase patterns
+
+If issues found → implementer fixes → quality reviewer re-reviews → repeat until pass.
+
+#### 1e. Mark Complete
+
+Mark the task done. Move to next task.
+
+### Phase 2 — Final Review
+
+After all tasks complete, dispatch one final code reviewer across the entire implementation. Check for:
+- Cross-task integration issues
+- Consistency between tasks
+- Overall architecture coherence
+
+### Phase 3 — Finish
+
+Use `pharaoh:finish` to decide: merge, PR, or cleanup.
+
+## Model Selection
+
+Match model capability to task complexity:
+
+| Task type | Model tier |
+|-----------|-----------|
+| Isolated function, clear spec, 1-2 files | Fast/cheap |
+| Multi-file integration, pattern matching | Standard |
+| Architecture, design, review | Most capable |
+
+## Prompt Quality
+
+| Bad | Good |
+|-----|------|
+| "Implement the auth feature" | Full task text + context + constraints |
+| Sharing session history | Constructing focused context per agent |
+| "Fix it" | Specific report of what's wrong + file references |
+| Skipping spec review | Always spec review before quality review |
+
+## Iron Rules
+
+- **One task at a time** — no parallel implementation (conflicts)
+- **Never skip reviews** — spec compliance AND code quality, in that order
+- **Spec before quality** — wrong order wastes review cycles
+- **Construct context, don't inherit** — each agent gets exactly what it needs
+- **Never trust reports** — reviewers read code, not claims
+- **Fix before proceeding** — no moving to next task with open issues
+- **Escalation is success** — BLOCKED/NEEDS_CONTEXT means the system is working
+
+## Output
+
+After all tasks complete:
+- Summary of what was built (per task)
+- Review findings that were caught and fixed
+- Any concerns flagged by implementers
+- Final reviewer assessment
+- Ready for `pharaoh:finish`

package/skills/{pharaoh-parallel → parallel}/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: pharaoh-parallel
+name: parallel
 description: "Dispatch 2+ independent subagent tasks that run concurrently. Each agent gets focused scope, clear goal, constraints, and expected output. No shared state between agents. Review and integrate results after all complete."
 version: 0.2.0
 homepage: https://pharaoh.so

package/skills/{pharaoh-plan → plan}/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: pharaoh-plan
+name: plan
 description: "Architecture-aware planning workflow using Pharaoh codebase knowledge graph. Four-phase process: reconnaissance with MCP tools, blast radius analysis, approach selection with trade-offs, and step-by-step implementation plan with wiring declarations. Prevents dead exports and overcoupled designs before a line of code is written."
 version: 0.2.0
 homepage: https://pharaoh.so

package/skills/{pharaoh-pr → pr}/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: pharaoh-pr
+name: pr
 description: "Pre-pull-request architectural review checklist using Pharaoh codebase knowledge graph. Covers module context, blast radius per touched module, hidden coupling between modules, duplicate logic detection, regression risk scoring, and vision spec alignment. Produces a structured review summary before opening a PR."
 version: 0.2.0
 homepage: https://pharaoh.so

package/skills/{pharaoh-refactor → refactor}/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: pharaoh-refactor
+name: refactor
 description: "Safe refactoring workflow using Pharaoh codebase knowledge graph. Six-step process: module context, blast radius of downstream callers, reachability verification, dependency mapping, naming conflict detection, and test coverage assessment. Produces a refactoring plan with every caller listed, test files identified, unreachable code flagged, and high-risk paths warned."
 version: 0.2.0
 homepage: https://pharaoh.so

package/skills/{pharaoh-review → review}/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: pharaoh-review
+name: review
 description: "Architecture-aware pre-PR code review using Pharaoh codebase knowledge graph. Four-phase workflow: context gathering with module structure and blast radius, risk assessment with regression scoring and wiring checks, spec alignment against vision docs, and a final verdict of SHIP / SHIP WITH CHANGES / BLOCK. Auto-block rules for unreachable exports, circular dependencies, high regression risk, and spec violations."
 version: 0.2.0
 homepage: https://pharaoh.so

package/skills/{pharaoh-review-codex → review-codex}/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: pharaoh-review-codex
+name: review-codex
 description: "Cross-model security review. Dispatch code to a different AI model or subagent for independent second-opinion review. Evaluator applies AGREE, DISAGREE, or CONTEXT verdicts to each finding. Catches blind spots from single-model reasoning. Use for security-sensitive code, auth flows, data access, and architectural decisions."
 version: 0.2.0
 homepage: https://pharaoh.so

package/skills/{pharaoh-review-receive → review-receive}/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: pharaoh-review-receive
+name: review-receive
 description: "Receive code review feedback with technical rigor. No performative agreement — verify suggestions against codebase reality before implementing. Push back with evidence when feedback is wrong. Clarify all unclear items before implementing any. External feedback is suggestions to evaluate, not orders to follow."
 version: 0.2.0
 homepage: https://pharaoh.so

package/skills/{pharaoh-sessions → sessions}/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: pharaoh-sessions
+name: sessions
 description: "Decompose work into parallel, isolated sessions using git worktrees. Each session gets fresh context, a narrow scope, and produces atomic commits. Prevents context window pollution from large tasks. Coordinate across sessions without shared state."
 version: 0.2.0
 homepage: https://pharaoh.so

package/skills/{pharaoh-tdd → tdd}/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: pharaoh-tdd
+name: tdd
 description: "Test-driven development discipline. Write the failing test first, watch it fail, write minimal code to pass, refactor. No production code without a failing test. No exceptions without explicit permission. Covers red-green-refactor cycle, common rationalizations, and when to start over."
 version: 0.2.0
 homepage: https://pharaoh.so

package/skills/{pharaoh-verify → verify}/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: pharaoh-verify
+name: verify
 description: "Evidence before assertions. Run verification commands and confirm output before claiming work is complete, fixed, or passing. No 'should work now' — run the command, read the output, then claim the result. Covers tests, builds, linting, agent delegation, and requirement checklists."
 version: 0.2.0
 homepage: https://pharaoh.so

package/skills/{pharaoh-wiring → wiring}/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: pharaoh-wiring
+name: wiring
 description: "Wiring validation for a codebase module using Pharaoh knowledge graph. Four-step pro-tier workflow: entry point reachability, caller verification via blast radius, test coverage per function, and dead code detection. Categorizes functions as CONNECTED, UNREACHABLE, DEAD, or UNTESTED. Produces a PASS or FAIL verdict with specific issues listed. Iron law: zero callers on a non-entry-point export means the code is not wired."
 version: 0.2.0
 homepage: https://pharaoh.so

package/skills/{pharaoh-worktree → worktree}/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: pharaoh-worktree
+name: worktree
 description: "Set up isolated git worktrees for feature work. Smart directory selection with safety verification — checks for existing worktree directories, verifies gitignore, auto-detects project setup, and confirms clean test baseline before starting. Prevents accidentally committing worktree contents."
 version: 0.2.0
 homepage: https://pharaoh.so