@pharaoh-so/mcp 0.2.5 → 0.2.7

package/dist/helpers.js

@@ -40,7 +40,7 @@ export function parseArgs(argv = process.argv.slice(2)) {
     return { server, logout };
 }
 export function printUsage() {
-    printLines("Usage: pharaoh-mcp [options]", "", "Options:", "  --server <url>    Pharaoh server URL (default: https://mcp.pharaoh.so)", "  --logout          Clear stored credentials and exit", "  --install-skills  Install Pharaoh skills to OpenClaw (~/.openclaw/skills/)", "  --help, -h        Show this help", "", "Add to Claude Code:", "  claude mcp add pharaoh -- npx @pharaoh-so/mcp", "");
+    printLines("Usage: pharaoh-mcp [options]", "", "Options:", "  --server <url>    Pharaoh server URL (default: https://mcp.pharaoh.so)", "  --logout          Clear stored credentials and exit", "  --install-skills  Force reinstall Pharaoh skills (Claude Code + OpenClaw)", "  --help, -h        Show this help", "", "Add to Claude Code:", "  claude mcp add pharaoh -- npx @pharaoh-so/mcp", "");
 }
 /**
  * Validate that a server-supplied SSE URL shares the same origin as the configured server.

package/dist/inspect.js

@@ -14,6 +14,17 @@ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 const INSPECT_MSG = "This is Pharaoh's inspection server for directory listings. " +
     "Connect to https://mcp.pharaoh.so for actual usage.";
+/** Read version from package.json (single source of truth). */
+function getPackageVersion() {
+    try {
+        const pkgPath = join(import.meta.dirname, "..", "package.json");
+        const pkg = JSON.parse(readFileSync(pkgPath, "utf-8"));
+        return pkg.version ?? "0.0.0";
+    }
+    catch {
+        return "0.0.0";
+    }
+}
 export async function runInspect() {
     // Load pre-generated schemas (shipped in the npm package)
     const schemasPath = join(import.meta.dirname, "..", "inspect-tools.json");
@@ -25,7 +36,7 @@ export async function runInspect() {
         process.stderr.write("Pharaoh: inspect-tools.json not found — rebuild the package.\n");
         process.exit(1);
     }
-    const server = new McpServer({ name: "pharaoh", version: "0.1.0" }, {
+    const server = new McpServer({ name: "pharaoh", version: getPackageVersion() }, {
         instructions: "Pharaoh turns codebases into knowledge graphs that AI agents can think with. " +
             "Connect at https://mcp.pharaoh.so for full functionality.",
     });

package/dist/install-skills.js

@@ -69,17 +69,18 @@ function installClaudeCodePlugin(home = homedir()) {
         return -1;
     }
     // Copy skills/
+    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 });
+        skillCount = entries.filter((e) => e.isDirectory()).length;
     }
     // Copy .mcp.json
     const mcpSrc = join(PKG_ROOT, ".mcp.json");
     if (existsSync(mcpSrc)) {
         cpSync(mcpSrc, join(pluginDir, ".mcp.json"), { force: true });
     }
-    // Count installed skills
-    const entries = readdirSync(BUNDLED_SKILLS_DIR, { withFileTypes: true });
-    return entries.filter((e) => e.isDirectory()).length;
+    return skillCount;
 }
 /**
  * Register Pharaoh in Claude Code's installed_plugins.json (v2 format).

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@pharaoh-so/mcp",
   "mcpName": "so.pharaoh/pharaoh",
-  "version": "0.2.5",
+  "version": "0.2.7",
   "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-orchestrate/SKILL.md

@@ -0,0 +1,144 @@
+---
+name: pharaoh-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`