@pharaoh-so/mcp 0.3.51 → 0.3.52

package/.mcp.json

@@ -3,7 +3,7 @@
 		"pharaoh": {
 			"command": "npx",
 			"args": [
-				"@pharaoh-so/mcp@0.3.51"
+				"@pharaoh-so/mcp@0.3.52"
 			]
 		}
 	}

package/CHANGELOG.md

@@ -5,6 +5,18 @@ All notable changes to `@pharaoh-so/mcp` will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.3.52] - 2026-10-23
+
+### Added
+- The proxy tells Pharaoh which client it serves (its `initialize` name and version) and whether Pharaoh's Claude Code plugin is enabled in `~/.claude/settings.json`, once per upstream session. Pharaoh stores it with that session, to compare adoption with and without the plugin. Nothing else is sent.
+
+### Removed
+- The `sessions` and `parallel` skills, the `/sessions` slash command and their MCP prompts (`session-decomposition`, `parallel-agents`). Claude Code and Codex now run subagents and parallel sessions on their own.
+- The installer deletes the `~/.claude/commands/sessions.md` it wrote, only while it carries the `# managed-by: pharaoh-mcp` marker. A file of your own with that name, or a symlink, is kept.
+
+### Fixed
+- `npx @pharaoh-so/mcp --version` (or `-v`) prints the version and exits, as README § Custom Server says. It used to start setup: in a terminal it deleted saved credentials and signed in again against mcp.pharaoh.so; on a pipe it started the proxy.
+
 ## [0.3.51] - 2026-10-23
 
 ### Added

package/README.md

@@ -166,9 +166,10 @@ claude mcp add --scope user pharaoh -- npx @pharaoh-so/mcp@<version> --server ht
 | `~/.pharaoh/` | `0700`, set again on every start | Always | Credentials and the Claude Code plugin marketplace |
 | `~/.pharaoh/credentials.json` | `0600` | After sign-in | Access token, refresh token, expiry |
 | `~/.pharaoh/claude-marketplace/` | — | `~/.claude/` exists | The one-plugin marketplace Claude Code installs as `pharaoh@pharaoh`: the skills and the Grep routing hook. Rewritten when the package version changes |
-| `~/.claude/commands/plan.md`, `review.md`, `sessions.md` | — | `~/.claude/` exists | Slash commands. A file is written only when it is absent or is Pharaoh's: it carries the front-matter comment `# managed-by: pharaoh-mcp`, or has the exact header and `$ARGUMENTS` footer of a Pharaoh command from 0.3.46 or earlier. Any other file with that name is yours: it is kept, a symlink is never followed, and the setup output names it. Rename your file to keep both |
+| `~/.claude/commands/plan.md`, `review.md` | — | `~/.claude/` exists | Slash commands. A file is written only when it is absent or is Pharaoh's: it carries the front-matter comment `# managed-by: pharaoh-mcp`, or has the exact header and `$ARGUMENTS` footer of a Pharaoh command from 0.3.46 or earlier. Any other file with that name is yours: it is kept, a symlink is never followed, and the setup output names it. Rename your file to keep both. 0.3.51 and earlier also wrote `sessions.md`; later versions delete it while it carries the marker |
 | `~/.claude.json` | — | Interactive setup | Removes earlier `pharaoh` entries, then `claude mcp add --scope user pharaoh -- npx @pharaoh-so/mcp@<version>` |
 | `~/.claude/settings.json` | — | Interactive setup, and only if the file already exists | Adds to `permissions.allow`, each by full name: `mcp__pharaoh__get_codebase_map`, `mcp__pharaoh__get_module_context`, `mcp__pharaoh__search_functions`, `mcp__pharaoh__get_blast_radius`, `mcp__pharaoh__get_unused_code`, `mcp__pharaoh__pharaoh_recon`, `mcp__pharaoh__pharaoh_account`. The setup prints a line saying what it did. The proxy never creates this file and never touches it on a start |
+| `~/.agents/skills/pharaoh-review/` | — | `~/.codex/` exists | The review skill for Codex (`$pharaoh-review`), rewritten on every start. Other tools share `~/.agents/skills/`, so nothing else there is touched |
 | `~/.openclaw/skills/`, `~/.openclaw/openclaw.json` | — | `~/.openclaw/` exists | Skills prefixed `pharaoh-`, and an `mcpServers.pharaoh` entry running `npx @pharaoh-so/mcp@<version>`. An entry that is not an `npx @pharaoh-so/mcp` command is left alone |
 
 Versions 0.3.46 and earlier wrote one rule, `mcp__pharaoh`, on every proxy start. That prefix auto-approved every Pharaoh tool, including account deletion and `pharaoh_admin`, so a prompt injection could run them without a human prompt. The next interactive setup replaces that rule with the list above; account deletion, `pharaoh_admin` and any tool not listed prompt before they run. To take the blanket rule out by hand, delete `mcp__pharaoh` from `permissions.allow`.

package/dist/backend.d.ts

@@ -17,6 +17,22 @@
  */
 import type { CallToolResult, ClientCapabilities, Tool } from "@modelcontextprotocol/sdk/types.js";
 import type { DeviceFlowGateway } from "./gateway.js";
+/**
+ * Notification that tells Pharaoh which client the proxy serves. Pharaoh sees
+ * the proxy itself as `pharaoh-proxy`; this lands on the session's row.
+ * Mirrors PROXY_CLIENT_NOTIFICATION in src/mcp/server.ts.
+ */
+export declare const CLIENT_NOTIFICATION = "notifications/pharaoh/client";
+/** What the proxy reports about the client behind it. */
+export type DownstreamClient = {
+    /** The client's own `initialize` clientInfo (e.g. claude-code 2.1.3). */
+    client: {
+        name?: string;
+        version?: string;
+    };
+    /** Pharaoh's Claude Code plugin as ~/.claude/settings.json lists it. */
+    plugin: "enabled" | "disabled" | "absent";
+};
 /** The contract ProxyServer uses to delegate tool handling. */
 export interface Backend {
     readonly name: "auth-required" | "sse";
@@ -34,6 +50,8 @@ export interface Backend {
     waitForExit?(): Promise<void>;
     /** Return an unstarted replacement only if the negotiated UI support changed. */
     withClientCapabilities?(capabilities: ClientCapabilities): Backend;
+    /** Report the client behind the proxy to every upstream session, reconnects included. */
+    identifyClient?(downstream: DownstreamClient): void;
 }
 /**
  * Pre-auth backend. Every tool call triggers a device-flow state step via the
@@ -78,7 +96,20 @@ export declare class SseProxyBackend implements Backend {
     private stopped;
     private reconnectPromise;
     private readonly clientCapabilities;
+    private downstream;
+    /** The client whose `connect` has finished; null while connecting or after its transport closed. */
+    private connectedClient;
+    /** Set once a report fails; see reportClient. */
+    private reportsOff;
     constructor(sseUrl: string, token: string, capabilities?: ClientCapabilities);
+    identifyClient(downstream: DownstreamClient): void;
+    /**
+     * Tell the connected session which client the proxy serves. Never awaited.
+     * The SDK also hands a failed POST to the transport's onerror, which
+     * reconnects, so after one failure this backend stops reporting: a server
+     * that rejects reports costs one reconnect, not a loop.
+     */
+    private reportClient;
     withClientCapabilities(capabilities: ClientCapabilities): Backend;
     start(): Promise<void>;
     /**

package/dist/backend.js

@@ -21,6 +21,12 @@ import { loadBundledCatalog } from "./catalog.js";
 import { classifySSEError, TenantSuspendedError, TokenExpiredError } from "./proxy.js";
 import { TRACE_MIME_TYPE } from "./trace-resource.js";
 import { getPackageVersion } from "./version.js";
+/**
+ * Notification that tells Pharaoh which client the proxy serves. Pharaoh sees
+ * the proxy itself as `pharaoh-proxy`; this lands on the session's row.
+ * Mirrors PROXY_CLIENT_NOTIFICATION in src/mcp/server.ts.
+ */
+export const CLIENT_NOTIFICATION = "notifications/pharaoh/client";
 /**
  * Pre-auth backend. Every tool call triggers a device-flow state step via the
  * gateway; returns a structured auth-required response. Once the gateway
@@ -145,6 +151,11 @@ export class SseProxyBackend {
     stopped = false;
     reconnectPromise = null;
     clientCapabilities;
+    downstream = null;
+    /** The client whose `connect` has finished; null while connecting or after its transport closed. */
+    connectedClient = null;
+    /** Set once a report fails; see reportClient. */
+    reportsOff = false;
     constructor(sseUrl, token, capabilities = {}) {
         this.sseUrl = sseUrl;
         this.token = token;
@@ -156,6 +167,29 @@ export class SseProxyBackend {
                 ? { extensions: { "io.modelcontextprotocol/ui": { mimeTypes: [TRACE_MIME_TYPE] } } }
                 : {};
     }
+    identifyClient(downstream) {
+        this.downstream = downstream;
+        void this.reportClient();
+    }
+    /**
+     * Tell the connected session which client the proxy serves. Never awaited.
+     * The SDK also hands a failed POST to the transport's onerror, which
+     * reconnects, so after one failure this backend stops reporting: a server
+     * that rejects reports costs one reconnect, not a loop.
+     */
+    async reportClient() {
+        const client = this.connectedClient;
+        if (!client || !this.downstream || this.reportsOff)
+            return;
+        await client
+            .notification({ method: CLIENT_NOTIFICATION, params: this.downstream })
+            .catch((error) => {
+            // ALLOWED-CATCH: telemetry; reportsOff bounds the reconnect a failed POST triggers
+            this.reportsOff = true;
+            const msg = error instanceof Error ? error.message : String(error);
+            process.stderr.write(`Pharaoh: client report not sent, not retrying (${msg})\n`);
+        });
+    }
     withClientCapabilities(capabilities) {
         const next = new SseProxyBackend(this.sseUrl, this.token, capabilities);
         return JSON.stringify(next.clientCapabilities) === JSON.stringify(this.clientCapabilities)
@@ -207,6 +241,13 @@ export class SseProxyBackend {
                 classifySSEError(error);
             throw error;
         }
+        // A stop or a newer connect while this one was in flight owns the backend now.
+        if (this.stopped || this.client !== client)
+            return;
+        this.connectedClient = client;
+        // Every new upstream session (reconnects too) hears which client this is,
+        // without holding up startup or reconnect supervision.
+        void this.reportClient();
     }
     /** Wait for the current transport to close, then decide what to do. */
     waitForClose() {
@@ -216,8 +257,14 @@ export class SseProxyBackend {
                 return;
             }
             const sse = this.transport;
-            sse.onclose = () => resolve();
+            // The client is gone the moment its transport closes or errors,
+            // whichever way the loop then leaves (backoff or typed recovery).
+            sse.onclose = () => {
+                this.connectedClient = null;
+                resolve();
+            };
             sse.onerror = (err) => {
+                this.connectedClient = null;
                 try {
                     classifySSEError(err);
                 }
@@ -302,6 +349,7 @@ export class SseProxyBackend {
     }
     async stop() {
         this.stopped = true;
+        this.connectedClient = null;
         if (this.transport) {
             await this.transport.close().catch(() => { });
             this.transport = null;

package/dist/helpers.js

@@ -42,7 +42,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 credentials, MCP config and the Claude Code plugin, then exit", "  --clean           Remove Pharaoh's MCP entries and plugin from Claude Code config", "  --install-skills  Reinstall the Claude Code plugin and OpenClaw skills", "  --help, -h        Show this help", "", "Get started:", `  ${NPX_COMMAND}`, "");
+    printLines("Usage: pharaoh-mcp [options]", "", "Options:", "  --server <url>    Pharaoh server URL (default: https://mcp.pharaoh.so)", "  --logout          Clear credentials, MCP config and the Claude Code plugin, then exit", "  --clean           Remove Pharaoh's MCP entries and plugin from Claude Code config", "  --install-skills  Reinstall the Claude Code plugin and OpenClaw skills", "  --version, -v     Print the version", "  --help, -h        Show this help", "", "Get started:", `  ${NPX_COMMAND}`, "");
 }
 /**
  * Validate that a server-supplied SSE URL shares the same origin as the configured server.

package/dist/index.js

@@ -37,6 +37,11 @@ async function main() {
         printUsage();
         process.exit(0);
     }
+    // Stdout, alone on its line, so a script can capture the version to pin
+    if (args.includes("--version") || args.includes("-v")) {
+        process.stdout.write(`${getPackageVersion()}\n`);
+        return;
+    }
     // Inspect mode — serve tool schemas over stdio for Glama directory inspection
     if (args.includes("--inspect")) {
         const { runInspect } = await import("./inspect.js");

package/dist/install-skills.d.ts

@@ -1,11 +1,11 @@
 import { type ClaudeCli } from "./setup.js";
 /**
- * Detect whether OpenClaw is installed by checking for ~/.openclaw/.
+ * Pharaoh's Claude Code plugin as ~/.claude/settings.json lists it. The proxy
+ * reports this to Pharaoh, so adoption can be compared with and without it.
  *
  * @param home - Home directory override (defaults to os.homedir()).
- * @returns True if ~/.openclaw/ exists.
  */
-export declare function detectOpenClaw(home?: string): boolean;
+export declare function claudePluginState(home?: string): "enabled" | "disabled" | "absent";
 /**
  * Uninstall Pharaoh's Claude Code plugin: through the CLI, then the local
  * marketplace directory and any pre-marketplace install.

package/dist/install-skills.js

@@ -63,7 +63,7 @@ function detectCodex(home = homedir()) {
  * @param home - Home directory override (defaults to os.homedir()).
  * @returns True if ~/.openclaw/ exists.
  */
-export function detectOpenClaw(home = homedir()) {
+function detectOpenClaw(home = homedir()) {
     return existsSync(join(home, ".openclaw"));
 }
 // ── Claude Code plugin ──────────────────────────────────────────────
@@ -151,6 +151,18 @@ function pluginSetting(home) {
         return undefined;
     }
 }
+/**
+ * Pharaoh's Claude Code plugin as ~/.claude/settings.json lists it. The proxy
+ * reports this to Pharaoh, so adoption can be compared with and without it.
+ *
+ * @param home - Home directory override (defaults to os.homedir()).
+ */
+export function claudePluginState(home = homedir()) {
+    const setting = pluginSetting(home);
+    if (setting === undefined)
+        return "absent";
+    return setting ? "enabled" : "disabled";
+}
 /**
  * Install the plugin through Claude Code's CLI (both commands are idempotent).
  * Skipped when it's already enabled, and when the user disabled it: that choice stands.
@@ -408,6 +420,13 @@ function cleanupRemovedSkills(srcDir, dstDir, oldManifest) {
  * and is left alone (security review SC-7).
  */
 export const PHARAOH_COMMAND_MARKER = "# managed-by: pharaoh-mcp";
+/**
+ * Commands an earlier installer wrote that this version no longer ships. Each
+ * is deleted only while it is still Pharaoh's marked file; a user's own file
+ * or a symlink with the name stays. A pre-marker copy (0.3.46 and earlier) is
+ * left too: without the bundled file there is nothing to prove it is ours.
+ */
+const RETIRED_COMMANDS = ["sessions.md"];
 /** The full marker line, with the one thing a reader of the file needs to know. */
 const COMMAND_MARKER_LINE = `${PHARAOH_COMMAND_MARKER} (rewritten by npx ${PACKAGE_NAME} on upgrade; rename this file to keep your own version)`;
 /** The front-matter block of a bundled command, `---` to `---` inclusive. */
@@ -438,13 +457,14 @@ function isPharaohCommand(existing, bundled) {
  * Install the bundled slash commands (`.md` files in the package's `commands/`
  * directory) to `~/.claude/commands/`. A destination that is missing or is
  * Pharaoh's own file is written; anything else (the user's file, or a symlink,
- * which is never followed) is kept and reported.
+ * which is never followed) is kept and reported. Pharaoh's copies of
+ * `RETIRED_COMMANDS` are removed.
  *
  * @param home - Home directory override (defaults to os.homedir()).
- * @returns How many commands were written, and the names of the files kept.
+ * @returns How many commands were written, and the names of the files kept and removed.
  */
 function installClaudeCodeCommands(home) {
-    const result = { installed: 0, kept: [] };
+    const result = { installed: 0, kept: [], removed: [] };
     if (!existsSync(BUNDLED_COMMANDS_DIR))
         return result;
     const commandsDst = join(home, ".claude", "commands");
@@ -463,6 +483,15 @@ function installClaudeCodeCommands(home) {
         writeFileSync(dst, markCommand(bundled));
         result.installed++;
     }
+    for (const name of RETIRED_COMMANDS) {
+        const dst = join(commandsDst, name);
+        if (!lstatSync(dst, { throwIfNoEntry: false })?.isFile())
+            continue;
+        if (!readFileSync(dst, "utf-8").includes(PHARAOH_COMMAND_MARKER))
+            continue;
+        rmSync(dst);
+        result.removed.push(name);
+    }
     return result;
 }
 /**
@@ -691,6 +720,7 @@ export function runInstallSkills(home = homedir(), options) {
                     ]
                     : []),
                 ...(keptLine ? [`  → ${keptLine}`] : []),
+                ...commands.removed.map((name) => `  → Removed retired ~/.claude/commands/${name}`),
                 "",
             ].join("\n"));
         }

package/dist/proxy-server.d.ts

@@ -37,6 +37,7 @@ export declare class ProxyServer {
     private stopping;
     private clientCapabilities;
     private clientInitialized;
+    private downstream;
     private capabilityUpdate;
     private transportClosed;
     private transportClosedResolve;

package/dist/proxy-server.js

@@ -24,9 +24,10 @@
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { CallToolRequestSchema, ListToolsRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
-import { AuthRequiredBackend, createSseBackend } from "./backend.js";
+import { AuthRequiredBackend, createSseBackend, } from "./backend.js";
 import { loadBundledCatalog } from "./catalog.js";
 import { createGateway } from "./gateway.js";
+import { claudePluginState } from "./install-skills.js";
 import { TenantSuspendedError, TokenExpiredError } from "./proxy.js";
 import { registerTraceResource } from "./trace-resource.js";
 import { getPackageVersion } from "./version.js";
@@ -42,6 +43,7 @@ export class ProxyServer {
     stopping = false;
     clientCapabilities = {};
     clientInitialized = false;
+    downstream = null;
     capabilityUpdate = Promise.resolve();
     transportClosed;
     transportClosedResolve;
@@ -64,10 +66,21 @@ export class ProxyServer {
             if (this.clientInitialized)
                 return;
             this.clientInitialized = true;
+            const info = this.server.getClientVersion();
+            const downstream = {
+                client: { name: info?.name, version: info?.version },
+                plugin: claudePluginState(),
+            };
+            this.downstream = downstream;
             this.clientCapabilities = this.server.getClientCapabilities() ?? {};
             const next = this.backend.withClientCapabilities?.(this.clientCapabilities) ?? this.backend;
-            if (next === this.backend)
+            // Only the backend that serves this client is told about it: a warm
+            // session replaced below never takes a tool call. setBackend names the
+            // client to its replacement once that has started.
+            if (next === this.backend) {
+                this.backend.identifyClient?.(downstream);
                 return;
+            }
             // Warm startup happens before the frontend initializes. Replace that
             // conservative connection only when real UI support is negotiated.
             this.capabilityUpdate = this.setBackend(next).catch((error) => {
@@ -75,6 +88,7 @@ export class ProxyServer {
                     throw error;
                 // UI negotiation is optional: keep the already-started plain-text
                 // backend healthy when its replacement hits a transient failure.
+                this.backend.identifyClient?.(downstream);
                 process.stderr.write("Pharaoh: compact UI negotiation unavailable; continuing with text responses.\n");
             });
             this.capabilityUpdate.catch(() => {
@@ -201,6 +215,9 @@ export class ProxyServer {
             return;
         }
         this.backend = next;
+        // Read the client after start: it may have initialized during the await.
+        if (this.downstream)
+            next.identifyClient?.(this.downstream);
         this.capabilityUpdate = Promise.resolve();
         // Fire the notification after the swap so a client that races a list
         // request against it sees the new catalog.

package/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "@pharaoh-so/mcp",
 	"mcpName": "so.pharaoh/pharaoh",
-	"version": "0.3.51",
+	"version": "0.3.52",
 	"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/commands/sessions.md

@@ -1,101 +0,0 @@
----
-description: Decompose work into parallel, isolated sessions using git worktrees
----
-
-# Session Decomposition
-
-Break large tasks into parallel, isolated work sessions. Each session runs in its own git worktree with fresh context, focused scope, and atomic commits.
-
-## When to Use
-
-- Task is too large for a single context window
-- Work has 3+ independent sub-tasks that don't touch the same files
-- You need to preserve context quality across a multi-hour effort
-- Multiple features or fixes can proceed in parallel
-
-## Do Not Use When
-
-- Sub-tasks share files or state
-- Work is sequential (each step depends on the previous)
-- Task fits comfortably in one session
-
-## Step 1: Reconnaissance
-
-If Pharaoh MCP tools are available, call `get_codebase_map` and `get_module_context` on affected modules to understand the current landscape before decomposing.
-
-## Step 2: Decompose
-
-Break the task into sessions. Each session must:
-
-- Have a clear, narrow goal (one feature, one fix, one module)
-- Touch a distinct set of files — no overlap between sessions
-- Be independently verifiable (tests pass, build succeeds)
-- Produce atomic commits that make sense on their own
-
-## Step 3: Write Session Prompts
-
-For each session, write a complete prompt containing:
-
-- **Goal:** what this session produces (1-2 sentences)
-- **Scope:** which files/modules to touch (explicit list)
-- **Constraints:** what NOT to change
-- **Verification:** how to confirm the work is correct
-- **Context:** any architectural decisions or patterns to follow
-
-## Step 4: Present for Review (MANDATORY — do NOT skip)
-
-**STOP. Paste every session prompt into the chat as a numbered list.**
-
-For each session, show:
-1. The session name
-2. The full prompt text
-3. Which sessions need `/plan` review (flag anything non-trivial)
-
-**Wait for the user to approve, modify, add, remove, or reorder sessions before proceeding.** Do not create worktrees or execute any work until the user explicitly approves the decomposition.
-
-If the user says "looks good" or similar, proceed. If they request changes, update the prompts and present again.
-
-## Step 5: Create Worktrees
-
-Only after user approval. For each session, create an isolated worktree:
-
-```bash
-git worktree add .worktrees/<session-name> -b <branch-name>
-```
-
-Install dependencies in each worktree. Verify clean baseline (tests pass).
-
-## Step 6: Execute Sessions
-
-Run each session independently. Sessions should not reference each other's work-in-progress — they operate on the same base commit.
-
-## Step 7: Integrate
-
-After all sessions complete:
-
-1. Verify each branch independently (tests pass, build succeeds)
-2. Merge branches sequentially into the target branch
-3. Resolve any conflicts (rare if decomposition was clean)
-4. Run full verification on the integrated result
-
-## Decomposition Rules
-
-| Good decomposition | Bad decomposition |
-|---|---|
-| Session A: auth module, Session B: billing module | Session A: backend, Session B: frontend (likely share types) |
-| Session A: new feature, Session B: unrelated bugfix | Session A: write code, Session B: write tests (coupled) |
-| Session A: parser, Session B: renderer (clear interface) | Session A: first half of file, Session B: second half |
-
-## Key Principles
-
-- **No shared files** — if two sessions touch the same file, merge them into one
-- **Fresh context per session** — don't carry state between sessions
-- **Atomic commits** — each session's output should be a coherent, reviewable unit
-- **Verify before integrating** — never merge a session that doesn't pass its own checks
-- **Decomposition is the hard part** — spend time getting boundaries right before starting work
-- **The user reviews before execution** — always present prompts, never skip to building
----
-
-Here is the task to decompose into sessions:
-
-$ARGUMENTS

package/skills/parallel/SKILL.md

@@ -1,75 +0,0 @@
----
-name: parallel
-prompt-name: parallel-agents
-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
-user-invocable: true
-metadata: {"emoji": "☥", "tags": ["parallel", "subagents", "concurrency", "delegation", "efficiency"]}
----
-
-# Parallel Dispatch
-
-Delegate independent tasks to specialized agents running concurrently. Each agent gets isolated context and focused scope. Never share your session history — construct exactly what each agent needs.
-
-## When to Use
-
-- 2+ independent tasks with no shared state
-- Multiple failures across different subsystems
-- Each problem can be understood without context from others
-- Agents won't edit the same files
-
-## Do Not Use When
-
-- Failures are related (fixing one might fix others)
-- Tasks require understanding full system state
-- Agents would edit the same files or resources
-- You don't yet know what's broken (investigate first)
-
-## The Pattern
-
-### 1. Identify Independent Domains
-
-Group work by what's independent:
-- Different test files with different root causes
-- Different modules with unrelated issues
-- Different features with no shared code
-
-### 2. Craft Agent Prompts
-
-Each agent gets:
-
-- **Specific scope:** one file, one module, one subsystem
-- **Clear goal:** what success looks like
-- **Constraints:** what NOT to change
-- **Context:** error messages, relevant code paths, architectural notes
-- **Expected output:** summary of findings and changes
-
-### 3. Dispatch
-
-Launch all agents simultaneously. They run concurrently with no coordination needed.
-
-### 4. Review and Integrate
-
-When agents return:
-
-1. Read each summary — understand what changed
-2. Check for conflicts — did agents edit overlapping code?
-3. Run full test suite — verify all fixes work together
-4. Spot-check results — agents can make systematic errors
-
-## Prompt Quality
-
-| Bad | Good |
-|-----|------|
-| "Fix all the tests" | "Fix the 3 failures in agent-abort.test.ts" |
-| "Fix the race condition" | "Fix timing in abort test — here are the error messages: ..." |
-| No constraints | "Do NOT change production code, fix tests only" |
-| "Fix it" | "Return: root cause summary + what you changed" |
-
-## Iron Rules
-
-- **One task per agent** — focused agents produce better results than broad ones
-- **No shared state** — agents must not depend on each other's output
-- **Never trust agent reports** — verify changes independently before integrating
-- **Construct context, don't inherit** — give each agent exactly what it needs, nothing more

package/skills/sessions/SKILL.md

@@ -1,102 +0,0 @@
----
-name: sessions
-prompt-name: session-decomposition
-description: "Decompose work into parallel, isolated sessions using git worktrees. Each session gets fresh context, a narrow scope, and produces atomic commits. Presents session prompts for user review before execution."
-version: 0.3.0
-homepage: https://pharaoh.so
-user-invocable: true
-metadata: {"emoji": "☥", "tags": ["sessions", "worktrees", "parallel-work", "context-management", "decomposition"]}
----
-
-# Session Decomposition
-
-Break large tasks into parallel, isolated work sessions. Each session runs in its own git worktree with fresh context, focused scope, and atomic commits.
-
-## When to Use
-
-- Task is too large for a single context window
-- Work has 3+ independent sub-tasks that don't touch the same files
-- You need to preserve context quality across a multi-hour effort
-- Multiple features or fixes can proceed in parallel
-
-## Do Not Use When
-
-- Sub-tasks share files or state
-- Work is sequential (each step depends on the previous)
-- Task fits comfortably in one session
-
-## Step 1: Reconnaissance
-
-If Pharaoh MCP tools are available, call `get_codebase_map` and `get_module_context` on affected modules to understand the current landscape before decomposing.
-
-## Step 2: Decompose
-
-Break the task into sessions. Each session must:
-
-- Have a clear, narrow goal (one feature, one fix, one module)
-- Touch a distinct set of files — no overlap between sessions
-- Be independently verifiable (tests pass, build succeeds)
-- Produce atomic commits that make sense on their own
-
-## Step 3: Write Session Prompts
-
-For each session, write a complete prompt containing:
-
-- **Goal:** what this session produces (1-2 sentences)
-- **Scope:** which files/modules to touch (explicit list)
-- **Constraints:** what NOT to change
-- **Verification:** how to confirm the work is correct
-- **Context:** any architectural decisions or patterns to follow
-
-## Step 4: Present for Review (MANDATORY — do NOT skip)
-
-**STOP. Paste every session prompt into the chat as a numbered list.**
-
-For each session, show:
-1. The session name
-2. The full prompt text
-3. Which sessions need `/plan` review (flag anything non-trivial)
-
-**Wait for the user to approve, modify, add, remove, or reorder sessions before proceeding.** Do not create worktrees or execute any work until the user explicitly approves the decomposition.
-
-If the user says "looks good" or similar, proceed. If they request changes, update the prompts and present again.
-
-## Step 5: Create Worktrees
-
-Only after user approval. For each session, create an isolated worktree:
-
-```bash
-git worktree add .worktrees/<session-name> -b <branch-name>
-```
-
-Install dependencies in each worktree. Verify clean baseline (tests pass).
-
-## Step 6: Execute Sessions
-
-Run each session independently. Sessions should not reference each other's work-in-progress — they operate on the same base commit.
-
-## Step 7: Integrate
-
-After all sessions complete:
-
-1. Verify each branch independently (tests pass, build succeeds)
-2. Merge branches sequentially into the target branch
-3. Resolve any conflicts (rare if decomposition was clean)
-4. Run full verification on the integrated result
-
-## Decomposition Rules
-
-| Good decomposition | Bad decomposition |
-|---|---|
-| Session A: auth module, Session B: billing module | Session A: backend, Session B: frontend (likely share types) |
-| Session A: new feature, Session B: unrelated bugfix | Session A: write code, Session B: write tests (coupled) |
-| Session A: parser, Session B: renderer (clear interface) | Session A: first half of file, Session B: second half |
-
-## Key Principles
-
-- **No shared files** — if two sessions touch the same file, merge them into one
-- **Fresh context per session** — don't carry state between sessions
-- **Atomic commits** — each session's output should be a coherent, reviewable unit
-- **Verify before integrating** — never merge a session that doesn't pass its own checks
-- **Decomposition is the hard part** — spend time getting boundaries right before starting work
-- **The user reviews before execution** — always present prompts, never skip to building