phewsh-mcp-server 0.2.0

package/README.md

@@ -0,0 +1,161 @@
+# phewsh-mcp-server
+
+**Your projects have intelligence. Now your agents can use it.**
+
+PHEWSH MCP gives any AI agent — Claude Code, Cursor, custom bots — instant access to your project's vision, plan, constraints, and task queue. The agent starts a session, gets a structured task with verification criteria, executes it, reports back, and automatically gets the next one.
+
+You shape the intent. Agents do the work. PHEWSH keeps the thread.
+
+## The experience
+
+**If you've never used an MCP server before:** this lets your AI assistant know what you're building, what matters, and what to do next — without you re-explaining it every time. Set it up once, and every conversation starts with full context.
+
+**If you build with agents:** this is the coordination protocol. Structured dispatch packets (not chat prompts), smart task ordering, verification gates, blocker tracking, session history across agents, and auto-chaining. Your agents share a brain.
+
+## Quick start
+
+### 1. Install
+
+```bash
+npm install -g phewsh-mcp-server
+```
+
+Or if you have the PHEWSH repo:
+
+```bash
+cd mcp && npm install
+```
+
+### 2. Configure Claude Code
+
+Add to `~/.claude/settings.json`:
+
+```json
+{
+  "mcpServers": {
+    "phewsh": {
+      "command": "npx",
+      "args": ["-y", "phewsh-mcp-server"]
+    }
+  }
+}
+```
+
+Or with a local install:
+
+```json
+{
+  "mcpServers": {
+    "phewsh": {
+      "command": "node",
+      "args": ["/path/to/phewsh/mcp/src/index.js"]
+    }
+  }
+}
+```
+
+### 3. Sync your projects
+
+If you use the PHEWSH CLI:
+
+```bash
+phewsh mcp sync
+```
+
+If you use the web app at phewsh.com/intent, export your projects from the settings menu.
+
+The server also automatically reads any `.intent/` directory in your current working directory.
+
+### 4. Start working
+
+Open Claude Code in your project and say:
+
+> "Check phewsh for what I should work on next"
+
+Claude will call `phewsh_start`, get your full project briefing and first task, and begin executing. When it finishes, it reports back and gets the next task automatically.
+
+## How it works
+
+```
+You shape intent          PHEWSH coordinates          Agents execute
+(web app or CLI)    -->   (MCP server)          -->   (Claude, Cursor, etc.)
+                               ^                            |
+                               |______ results _____________|
+```
+
+1. You define what you're building in PHEWSH (vision, plan, constraints, tasks)
+2. The MCP server exposes this as structured dispatch packets
+3. Any agent connects, pulls a task, and gets: objective, constraints, verification criteria, rollback plan
+4. Agent executes, reports result — server auto-chains to the next task
+5. Session history tracks what happened across agents and sessions
+
+The dispatch packet is NOT a chat prompt. It's an execution contract:
+
+```
+Objective     "Deploy the landing page to production"
+Success       "Live and accessible at target URL"
+Constraints   Budget: $0 | Urgency: urgent | Autonomy: guided
+Verification  [ ] Accessible at URL  [ ] No error responses
+Rollback      Reversible — redeploy previous version
+After         Report back, then: "Set up analytics tracking"
+```
+
+## Tools
+
+| Tool | Purpose |
+|------|---------|
+| `phewsh_start` | **Start here.** Full project briefing + first task in one call. |
+| `phewsh_next_task` | Get next highest-priority task as a dispatch packet. |
+| `phewsh_complete_task` | Report results. Auto-chains to the next task. |
+| `phewsh_check_verification` | Confirm what needs to be true before marking done. |
+| `phewsh_flag_blocker` | Flag a blocked task. Suggests alternative work. |
+| `phewsh_list_projects` | List all projects with progress and constraints. |
+| `phewsh_get_context` | Deep project briefing — vision, plan, gate, state. |
+| `phewsh_session_history` | What agents have done — completions, blockers, sessions. |
+
+## Prompts
+
+Pre-built workflows agents can invoke:
+
+| Prompt | What it does |
+|--------|-------------|
+| `work_session` | Full autonomous session: get briefed, execute up to N tasks, report results. |
+| `status_check` | Quick status: what's done, what's pending, any blockers. No execution. |
+| `review_results` | Human oversight: review what agents did, what failed, what needs attention. |
+
+## Resources
+
+Project artifacts are readable as MCP resources:
+
+- `phewsh://projects/{id}/briefing` — full project context
+- `phewsh://projects/{id}/artifacts/vision` — vision artifact
+- `phewsh://projects/{id}/artifacts/plan` — plan artifact
+
+## What makes this different
+
+**Smart ordering.** Tasks aren't first-in-first-out. Priority considers urgency, execution type, category freshness, and age. Agents get the highest-impact work first.
+
+**Auto-chaining.** Complete a task, get the next one in the response. No extra calls. Agents can run through an entire work queue in a single session.
+
+**Blocker awareness.** Can't do a task? Flag it and get an alternative. The human gets notified. No one wastes time.
+
+**Agent identity.** Every session start, completion, and blocker is tagged with who did it. Multiple agents work on the same project without confusion.
+
+**Verification gates.** Every task has concrete "done when" criteria. Agents know exactly what to prove before reporting complete.
+
+**Constraint-aware.** Budget, time, skill level, urgency, autonomy — all flow into dispatch packets. An agent won't suggest a $500 service on a $0 budget.
+
+## Project sources
+
+The server loads projects from:
+
+1. **`.intent/` in cwd** — automatically loaded as the "local" project
+2. **`~/.phewsh/projects.json`** — synced via `phewsh mcp sync` or web app export
+
+## Philosophy
+
+PHEWSH is the coordination layer, not another agent. It doesn't execute — it remembers, reasons about constraints, orders work, and verifies results. The agent does the work. PHEWSH makes sure it's the right work, done right.
+
+---
+
+*Built by [PHEWSH](https://phewsh.com) — software that adapts to you.*

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "phewsh-mcp-server",
+  "version": "0.2.0",
+  "description": "Connect AI agents to your project intelligence. One call to start. One call to finish. Everything in between is execution.",
+  "type": "module",
+  "main": "src/index.js",
+  "bin": {
+    "phewsh-mcp": "src/index.js"
+  },
+  "scripts": {
+    "start": "node src/index.js",
+    "dev": "node --watch src/index.js"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "phewsh",
+    "intent",
+    "dispatch",
+    "agent",
+    "coordination",
+    "ai-agents",
+    "claude-code",
+    "cursor",
+    "project-management"
+  ],
+  "author": "Phewsh <hello@phewsh.com>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/cleverIdeaz/phewsh",
+    "directory": "mcp"
+  },
+  "homepage": "https://phewsh.com/intent",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "files": [
+    "src/",
+    "README.md"
+  ]
+}

package/src/index.js

@@ -0,0 +1,1029 @@
+#!/usr/bin/env node
+
+/**
+ * PHEWSH MCP Server v0.2.0
+ *
+ * The coordination layer between humans and AI agents.
+ *
+ * Any MCP-capable agent connects here and immediately knows:
+ *   - What project they're working on
+ *   - What needs to happen next (structured, not vague)
+ *   - What constraints to respect
+ *   - How to prove they did it right
+ *   - What to do after they finish
+ *
+ * One call to start. One call to finish. Everything in between is execution.
+ */
+
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import {
+  CallToolRequestSchema,
+  ListToolsRequestSchema,
+  ListResourcesRequestSchema,
+  ReadResourceRequestSchema,
+  ListPromptsRequestSchema,
+  GetPromptRequestSchema,
+} from "@modelcontextprotocol/sdk/types.js";
+import { readFileSync, writeFileSync, existsSync, readdirSync, mkdirSync } from "fs";
+import { join, resolve } from "path";
+import { homedir } from "os";
+
+// ─── Config ─────────────────────────────────────────────────────────────────
+
+const PHEWSH_DIR = join(homedir(), ".phewsh");
+const PROJECTS_FILE = join(PHEWSH_DIR, "projects.json");
+const RESULTS_DIR = join(PHEWSH_DIR, "results");
+const SESSIONS_DIR = join(PHEWSH_DIR, "sessions");
+
+// Ensure directories exist
+[PHEWSH_DIR, RESULTS_DIR, SESSIONS_DIR].forEach(dir => {
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+});
+
+// ─── Project Loading ────────────────────────────────────────────────────────
+
+function loadProjects() {
+  const projects = [];
+
+  // 1. Check for local .intent/ directory
+  const localIntent = join(process.cwd(), ".intent");
+  if (existsSync(localIntent)) {
+    const local = loadLocalIntentProject(localIntent);
+    if (local) projects.push(local);
+  }
+
+  // 2. Check for synced projects from web app
+  if (existsSync(PROJECTS_FILE)) {
+    try {
+      const data = JSON.parse(readFileSync(PROJECTS_FILE, "utf-8"));
+      if (Array.isArray(data)) {
+        projects.push(...data);
+      }
+    } catch { /* ignore parse errors */ }
+  }
+
+  return projects;
+}
+
+function loadLocalIntentProject(dir) {
+  const project = {
+    id: "local",
+    name: "Current Project",
+    source: "local",
+    artifacts: {},
+    actions: [],
+    decisionGate: null,
+  };
+
+  // Read standard .intent/ files
+  const files = ["vision.md", "plan.md", "next.md", "status.md", "narrative.md"];
+  for (const file of files) {
+    const path = join(dir, file);
+    if (existsSync(path)) {
+      const kind = file.replace(".md", "");
+      project.artifacts[kind] = {
+        kind,
+        content: readFileSync(path, "utf-8"),
+      };
+      if (kind === "vision") {
+        const firstLine = project.artifacts[kind].content.split("\n").find(l => l.trim().length > 5);
+        if (firstLine) project.name = firstLine.replace(/^#+\s*/, "").trim().slice(0, 60);
+      }
+    }
+  }
+
+  // Read project.json if it exists (has constraints, gate, actions, etc.)
+  const metaPath = join(dir, "project.json");
+  if (existsSync(metaPath)) {
+    try {
+      const meta = JSON.parse(readFileSync(metaPath, "utf-8"));
+      Object.assign(project, meta);
+    } catch { /* ignore */ }
+  }
+
+  return Object.keys(project.artifacts).length > 0 ? project : null;
+}
+
+// ─── Smart Task Ordering ────────────────────────────────────────────────────
+
+const URGENCY_WEIGHT = { critical: 4, urgent: 3, moderate: 2, relaxed: 1 };
+const TYPE_PRIORITY = { agent: 3, ai: 2, human: 1 }; // agents should grab agent tasks first
+
+function scoreTask(action, project) {
+  let score = 0;
+  const gate = project.decisionGate;
+
+  // Urgency from gate constraints
+  if (gate?.constraints?.urgency) {
+    score += (URGENCY_WEIGHT[gate.constraints.urgency] || 2) * 10;
+  }
+
+  // Execution type match — prefer agent-executable tasks
+  const execType = action.executionType || classifyExecutionType(action.intent);
+  score += (TYPE_PRIORITY[execType] || 1) * 5;
+
+  // Category clustering — if previous completed actions share category, boost same-category
+  const completedCategories = (project.actions || [])
+    .filter(a => a.state === "reconciled" && a.reconciliation?.decision === "accept")
+    .slice(-3)
+    .map(a => a.category);
+  if (action.category && !completedCategories.includes(action.category)) {
+    score += 3; // Fresh category = higher priority (avoids tunnel vision)
+  }
+
+  // Recency penalty — older tasks get slight boost
+  if (action.createdAt) {
+    const age = Date.now() - new Date(action.createdAt).getTime();
+    score += Math.min(5, Math.floor(age / (1000 * 60 * 60 * 24))); // +1 per day, max 5
+  }
+
+  return score;
+}
+
+function getOrderedTasks(project, filter = "any") {
+  const pending = (project.actions || []).filter(a => {
+    if (a.state !== "intended") return false;
+    if (filter === "any") return true;
+    const aType = a.executionType || classifyExecutionType(a.intent);
+    return aType === filter;
+  });
+
+  return pending
+    .map(a => ({ action: a, score: scoreTask(a, project) }))
+    .sort((a, b) => b.score - a.score)
+    .map(s => s.action);
+}
+
+// ─── Agent Session Tracking ─────────────────────────────────────────────────
+
+function recordSession(agentId, projectId, event, data = {}) {
+  const session = {
+    agentId: agentId || "anonymous",
+    projectId,
+    event,
+    timestamp: new Date().toISOString(),
+    ...data,
+  };
+
+  const file = join(SESSIONS_DIR, `${projectId}_sessions.json`);
+  let sessions = [];
+  if (existsSync(file)) {
+    try { sessions = JSON.parse(readFileSync(file, "utf-8")); } catch { sessions = []; }
+  }
+  sessions.push(session);
+  // Keep last 100 sessions per project
+  if (sessions.length > 100) sessions = sessions.slice(-100);
+  writeFileSync(file, JSON.stringify(sessions, null, 2));
+  return session;
+}
+
+function getRecentSessions(projectId, limit = 10) {
+  const file = join(SESSIONS_DIR, `${projectId}_sessions.json`);
+  if (!existsSync(file)) return [];
+  try {
+    const sessions = JSON.parse(readFileSync(file, "utf-8"));
+    return sessions.slice(-limit);
+  } catch { return []; }
+}
+
+// ─── Execution Type Classification ─────────────────────────────────────────
+
+function classifyExecutionType(intent) {
+  const lower = intent.toLowerCase();
+  if (/\b(meet|call|email|talk|discuss|decide|choose|buy|purchase|sign up|register|hire|interview|negotiate|pitch|present|attend|schedule|book|contact|reach out|approve)\b/.test(lower)) return "human";
+  if (/\b(deploy|publish|push|install|run|execute|build|compile|test|debug|browse|navigate|click|fill|submit|upload|download|configure|ssh|terminal|git push|npm|docker|automate|scrape|monitor)\b/.test(lower)) return "agent";
+  return "ai";
+}
+
+// ─── Dispatch Packet Generation ─────────────────────────────────────────────
+
+function generatePacket(action, project) {
+  const constraints = project.decisionGate?.constraints || {};
+
+  return {
+    version: "1.0",
+    id: action.id || `task_${Date.now()}`,
+    createdAt: new Date().toISOString(),
+
+    objective: {
+      task: action.intent,
+      category: action.category,
+      successState: deriveSuccessState(action.intent),
+    },
+
+    constraints: {
+      budget: constraints.budget ? `$${constraints.budget}` : undefined,
+      time: constraints.timeHoursPerWeek ? `${constraints.timeHoursPerWeek}h/week available` : undefined,
+      skill: constraints.skillLevel,
+      urgency: constraints.urgency,
+      boundaries: deriveBoundaries(constraints),
+    },
+
+    context: {
+      project: `${project.name}${project.tldr ? ` — ${project.tldr}` : ""}`,
+      vision: project.artifacts?.vision?.content?.slice(0, 600),
+      plan: findRelevantPlan(action.intent, project.artifacts?.plan?.content),
+      priorWork: getPriorWork(action, project),
+    },
+
+    verification: deriveVerification(action.intent),
+    rollback: assessReversibility(action.intent),
+
+    continuation: {
+      reportBack: "When done, call phewsh_complete_task with your result. Include: what you did, what worked, any issues.",
+      nextActions: getNextActions(action, project),
+    },
+
+    runtime: inferRuntime(action.intent),
+  };
+}
+
+function deriveSuccessState(intent) {
+  const lower = intent.toLowerCase();
+  if (/deploy|publish|push|ship/.test(lower)) return "Live and accessible at target URL";
+  if (/set up|configure|install/.test(lower)) return "Service running and verified";
+  if (/write|draft|create/.test(lower)) return "Document complete and saved";
+  if (/research|investigate|analyze/.test(lower)) return "Findings documented with recommendations";
+  if (/fix|debug|resolve/.test(lower)) return "Issue no longer reproducible";
+  if (/build|implement|code/.test(lower)) return "Feature working and integrated";
+  if (/test|verify/.test(lower)) return "All checks pass";
+  return `"${intent}" completed and verified`;
+}
+
+function deriveBoundaries(constraints) {
+  const b = [];
+  if (constraints.budget && constraints.budget < 100) b.push("Do not use paid services without approval");
+  if (constraints.urgency === "critical") b.push("Do not spend time on non-essential polish");
+  if (constraints.autonomy === "hands-on") b.push("Do not make irreversible decisions without presenting options");
+  return b.length > 0 ? b : undefined;
+}
+
+function findRelevantPlan(intent, planContent) {
+  if (!planContent) return undefined;
+  const lines = planContent.split("\n");
+  const words = intent.toLowerCase().split(/\s+/).filter(w => w.length > 4);
+  let bestIdx = -1, bestScore = 0;
+  for (let i = 0; i < lines.length; i++) {
+    const score = words.filter(w => lines[i].toLowerCase().includes(w)).length;
+    if (score > bestScore) { bestScore = score; bestIdx = i; }
+  }
+  if (bestIdx >= 0 && bestScore >= 2) {
+    return lines.slice(Math.max(0, bestIdx - 2), bestIdx + 8).join("\n");
+  }
+  return undefined;
+}
+
+function getPriorWork(action, project) {
+  const done = (project.actions || [])
+    .filter(a => a.id !== action.id && a.state === "reconciled" && a.reconciliation?.decision === "accept")
+    .slice(-5)
+    .map(a => a.intent);
+  return done.length > 0 ? done : undefined;
+}
+
+function getNextActions(action, project) {
+  const next = (project.actions || [])
+    .filter(a => a.id !== action.id && a.state === "intended" && a.category === action.category)
+    .slice(0, 2)
+    .map(a => a.intent);
+  return next.length > 0 ? next : undefined;
+}
+
+function deriveVerification(intent) {
+  const lower = intent.toLowerCase();
+  const criteria = [];
+  if (/deploy|publish/.test(lower)) { criteria.push("Accessible at target URL", "No error responses"); }
+  else if (/build|implement|code/.test(lower)) { criteria.push("Compiles without errors", "Feature works as described"); }
+  else if (/write|draft/.test(lower)) { criteria.push("Content complete and coherent", "Saved to expected location"); }
+  else if (/set up|configure/.test(lower)) { criteria.push("Responds to test interaction", "Persists across restart"); }
+  else { criteria.push("Objective achieved as described", "No unintended side effects"); }
+  return { criteria };
+}
+
+function assessReversibility(intent) {
+  const lower = intent.toLowerCase();
+  if (/delete|remove|send email|publish|announce/.test(lower)) return { canRevert: false, warning: "Confirm before executing" };
+  if (/deploy|push|migrate/.test(lower)) return { canRevert: true, how: "Redeploy previous version" };
+  return { canRevert: true };
+}
+
+function inferRuntime(intent) {
+  const lower = intent.toLowerCase();
+  if (/deploy|push|git|npm|build|compile|test|ssh|terminal/.test(lower)) return { preferred: "claude-code", needs: ["filesystem", "terminal"] };
+  if (/browse|navigate|click|fill|submit|sign up|scrape/.test(lower)) return { preferred: "browser-agent", needs: ["browser", "network"] };
+  if (/meet|call|email|discuss|decide|buy|hire/.test(lower)) return { preferred: "human", needs: ["judgment", "social"] };
+  return { preferred: "claude-code", needs: ["text-generation"] };
+}
+
+// ─── Project Summary Helpers ────────────────────────────────────────────────
+
+function summarizeProject(p) {
+  const actions = p.actions || [];
+  const total = actions.length;
+  const done = actions.filter(a => a.state === "reconciled" && a.reconciliation?.decision === "accept").length;
+  const pending = actions.filter(a => a.state === "intended").length;
+  const dispatched = actions.filter(a => a.state === "dispatched").length;
+  const gate = p.decisionGate;
+
+  return {
+    id: p.id,
+    name: p.name,
+    tldr: p.tldr,
+    source: p.source || "synced",
+    progress: total > 0 ? { done, total, percent: Math.round(done / total * 100) } : null,
+    pending,
+    dispatched,
+    feasibility: gate?.feasibility,
+    constraints: gate?.constraints ? {
+      budget: gate.constraints.budget || null,
+      timePerWeek: gate.constraints.timeHoursPerWeek || null,
+      urgency: gate.constraints.urgency,
+      autonomy: gate.constraints.autonomy,
+    } : null,
+  };
+}
+
+function buildFullBriefing(project) {
+  const sections = [];
+  sections.push(`# ${project.name}`);
+  if (project.tldr) sections.push(`> ${project.tldr}`);
+  sections.push("");
+
+  // Gate + Constraints
+  const gate = project.decisionGate;
+  if (gate) {
+    sections.push("## Your Operating Reality");
+    if (gate.goal) sections.push(`**Goal:** ${gate.goal}`);
+    if (gate.feasibility) sections.push(`**Feasibility:** ${gate.feasibility}`);
+    const c = gate.constraints || {};
+    const constraintLines = [];
+    if (c.budget) constraintLines.push(`Budget: $${c.budget}`);
+    if (c.timeHoursPerWeek) constraintLines.push(`Time: ${c.timeHoursPerWeek}h/week`);
+    if (c.skillLevel) constraintLines.push(`Skill: ${c.skillLevel}`);
+    if (c.urgency) constraintLines.push(`Urgency: ${c.urgency}`);
+    if (c.autonomy) constraintLines.push(`Autonomy: ${c.autonomy}`);
+    if (constraintLines.length > 0) {
+      sections.push("");
+      constraintLines.forEach(l => sections.push(`- ${l}`));
+    }
+    if (gate.successCriteria?.length > 0) {
+      sections.push("");
+      sections.push("**Success looks like:**");
+      gate.successCriteria.forEach(c => sections.push(`- ${c}`));
+    }
+    sections.push("");
+  }
+
+  // Vision (condensed)
+  if (project.artifacts?.vision?.content) {
+    sections.push("## Vision");
+    sections.push(project.artifacts.vision.content.slice(0, 800));
+    sections.push("");
+  }
+
+  // Plan (condensed)
+  if (project.artifacts?.plan?.content) {
+    sections.push("## Plan");
+    sections.push(project.artifacts.plan.content.slice(0, 1200));
+    sections.push("");
+  }
+
+  // Execution state
+  const actions = project.actions || [];
+  if (actions.length > 0) {
+    const done = actions.filter(a => a.state === "reconciled" && a.reconciliation?.decision === "accept");
+    const pending = actions.filter(a => a.state === "intended");
+    const dispatched = actions.filter(a => a.state === "dispatched");
+
+    sections.push("## Execution State");
+    sections.push(`Progress: ${done.length}/${actions.length} complete (${Math.round(done.length / actions.length * 100)}%)`);
+
+    if (dispatched.length > 0) {
+      sections.push("");
+      sections.push("**In progress:**");
+      dispatched.forEach(a => sections.push(`- ${a.intent}`));
+    }
+
+    if (done.length > 0) {
+      sections.push("");
+      sections.push("**Recently completed:**");
+      done.slice(-5).forEach(a => sections.push(`- ${a.intent}`));
+    }
+
+    if (pending.length > 0) {
+      sections.push("");
+      sections.push("**Ready for you:**");
+      const ordered = getOrderedTasks(project, "any").slice(0, 8);
+      ordered.forEach(a => {
+        const type = a.executionType || classifyExecutionType(a.intent);
+        sections.push(`- [${type}] ${a.intent}`);
+      });
+      if (pending.length > 8) sections.push(`  ...and ${pending.length - 8} more`);
+    }
+    sections.push("");
+  }
+
+  return sections.join("\n");
+}
+
+// ─── MCP Server ─────────────────────────────────────────────────────────────
+
+const server = new Server(
+  { name: "phewsh", version: "0.2.0" },
+  { capabilities: { tools: {}, resources: {}, prompts: {} } }
+);
+
+// ── Tools ──
+
+server.setRequestHandler(ListToolsRequestSchema, async () => ({
+  tools: [
+    {
+      name: "phewsh_start",
+      description: "Start a work session. Returns everything you need: project context, constraints, what changed, and your next task — all in one call. Call this first.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          project_id: { type: "string", description: "Project ID (use 'local' for .intent/ project in cwd). Omit to auto-detect." },
+          agent_id: { type: "string", description: "Your agent identifier (e.g. 'claude-code', 'cursor', 'custom-agent')" },
+        },
+      },
+    },
+    {
+      name: "phewsh_next_task",
+      description: "Get the next highest-priority task as a structured dispatch packet. Contains objective, constraints, verification criteria, and what to do after. Call this when you're ready for more work.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          project_id: { type: "string", description: "Project ID" },
+          type: { type: "string", enum: ["agent", "ai", "human", "any"], description: "Filter by who can do it (default: agent)" },
+          skip_ids: { type: "array", items: { type: "string" }, description: "Task IDs to skip (already attempted)" },
+        },
+        required: ["project_id"],
+      },
+    },
+    {
+      name: "phewsh_complete_task",
+      description: "Report that you finished a task. Include what you did and whether it worked. Returns the next task automatically — keep the momentum going.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          project_id: { type: "string", description: "Project ID" },
+          task_id: { type: "string", description: "The task ID from the dispatch packet" },
+          result: { type: "string", description: "What you accomplished — be specific about outputs and artifacts" },
+          success: { type: "boolean", description: "Did it work?" },
+          issues: { type: "string", description: "Problems encountered, decisions made, or things the human should know" },
+          agent_id: { type: "string", description: "Your agent identifier" },
+        },
+        required: ["project_id", "task_id", "result", "success"],
+      },
+    },
+    {
+      name: "phewsh_list_projects",
+      description: "List all available projects with their progress, constraints, and pending task counts.",
+      inputSchema: { type: "object", properties: {} },
+    },
+    {
+      name: "phewsh_get_context",
+      description: "Get the full project briefing — vision, plan, constraints, execution state. Use when you need deeper context on a specific project.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          project_id: { type: "string", description: "Project ID" },
+        },
+        required: ["project_id"],
+      },
+    },
+    {
+      name: "phewsh_check_verification",
+      description: "Before marking a task complete, check its verification criteria. Returns what you need to confirm.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          task_id: { type: "string", description: "The task ID to check verification for" },
+          project_id: { type: "string", description: "Project ID" },
+        },
+        required: ["task_id", "project_id"],
+      },
+    },
+    {
+      name: "phewsh_flag_blocker",
+      description: "Flag a task as blocked — something is preventing execution. The human will be notified.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          project_id: { type: "string", description: "Project ID" },
+          task_id: { type: "string", description: "Task ID that's blocked" },
+          reason: { type: "string", description: "What's blocking execution" },
+          needs: { type: "string", description: "What you need to unblock (e.g. 'API key', 'human decision', 'access to service')" },
+          agent_id: { type: "string", description: "Your agent identifier" },
+        },
+        required: ["project_id", "task_id", "reason"],
+      },
+    },
+    {
+      name: "phewsh_session_history",
+      description: "See what agents have done on this project — completions, blockers, session starts. Useful for understanding context across sessions.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          project_id: { type: "string", description: "Project ID" },
+          limit: { type: "number", description: "Number of events to return (default: 20)" },
+        },
+        required: ["project_id"],
+      },
+    },
+  ],
+}));
+
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+  const { name, arguments: args } = request.params;
+  const projects = loadProjects();
+
+  switch (name) {
+    // ─── START SESSION ──────────────────────────────────────────────────────
+    case "phewsh_start": {
+      // Auto-detect project if none specified
+      let projectId = args.project_id;
+      if (!projectId) {
+        if (projects.length === 1) projectId = projects[0].id;
+        else if (projects.find(p => p.id === "local")) projectId = "local";
+        else {
+          return { content: [{ type: "text", text: `Multiple projects available. Specify one:\n${projects.map(p => `- ${p.id}: ${p.name}`).join("\n")}` }] };
+        }
+      }
+
+      const project = projects.find(p => p.id === projectId);
+      if (!project) {
+        return { content: [{ type: "text", text: `Project "${projectId}" not found. Available: ${projects.map(p => `${p.id} (${p.name})`).join(", ")}` }] };
+      }
+
+      // Record session start
+      recordSession(args.agent_id, projectId, "session_start");
+
+      const sections = [];
+
+      // Greeting + orientation
+      sections.push(`# Session Started: ${project.name}`);
+      if (args.agent_id) sections.push(`Agent: ${args.agent_id}`);
+      sections.push("");
+
+      // What changed since last session
+      const recentSessions = getRecentSessions(projectId, 20);
+      const recentCompletions = recentSessions.filter(s => s.event === "task_complete" && s.timestamp > new Date(Date.now() - 24 * 60 * 60 * 1000).toISOString());
+      const recentBlockers = recentSessions.filter(s => s.event === "blocker_flagged" && !s.resolved);
+
+      if (recentCompletions.length > 0 || recentBlockers.length > 0) {
+        sections.push("## Since Last Session");
+        if (recentCompletions.length > 0) {
+          sections.push("**Completed:**");
+          recentCompletions.slice(-5).forEach(s => sections.push(`- ${s.result?.split("\n")[0] || s.taskId}`));
+        }
+        if (recentBlockers.length > 0) {
+          sections.push("**Blocked:**");
+          recentBlockers.forEach(s => sections.push(`- ${s.reason} (needs: ${s.needs || "unknown"})`));
+        }
+        sections.push("");
+      }
+
+      // Full briefing
+      sections.push(buildFullBriefing(project));
+
+      // Your first task
+      const nextTasks = getOrderedTasks(project, "any");
+      if (nextTasks.length > 0) {
+        const first = nextTasks[0];
+        const packet = generatePacket(first, project);
+        sections.push("---");
+        sections.push("## Your First Task");
+        sections.push("");
+        sections.push(`**${packet.objective.task}**`);
+        sections.push(`Done when: ${packet.objective.successState}`);
+        sections.push(`Task ID: \`${packet.id}\``);
+        sections.push("");
+        if (packet.constraints.boundaries) {
+          sections.push("Boundaries:");
+          packet.constraints.boundaries.forEach(b => sections.push(`- ${b}`));
+          sections.push("");
+        }
+        sections.push("Verify before completing:");
+        packet.verification.criteria.forEach(c => sections.push(`- [ ] ${c}`));
+        sections.push("");
+        if (!packet.rollback.canRevert) {
+          sections.push(`**Warning:** This action is not easily reversible. ${packet.rollback.warning || "Confirm before executing."}`);
+          sections.push("");
+        }
+        if (packet.continuation.nextActions?.length > 0) {
+          sections.push("After this, next up:");
+          packet.continuation.nextActions.forEach(a => sections.push(`- ${a}`));
+          sections.push("");
+        }
+        sections.push(`When done, call \`phewsh_complete_task\` with task_id: "${packet.id}"`);
+      } else {
+        sections.push("---");
+        sections.push("## No Pending Tasks");
+        sections.push("All tasks are complete or dispatched. Check back later or ask the project owner for new work.");
+      }
+
+      return { content: [{ type: "text", text: sections.join("\n") }] };
+    }
+
+    // ─── NEXT TASK ──────────────────────────────────────────────────────────
+    case "phewsh_next_task": {
+      const project = projects.find(p => p.id === args.project_id);
+      if (!project) return { content: [{ type: "text", text: `Project "${args.project_id}" not found.` }] };
+
+      const typeFilter = args.type || "agent";
+      const skipIds = args.skip_ids || [];
+      let ordered = getOrderedTasks(project, typeFilter);
+      ordered = ordered.filter(a => !skipIds.includes(a.id));
+
+      if (ordered.length === 0) {
+        // Try broader filter
+        if (typeFilter !== "any") {
+          ordered = getOrderedTasks(project, "any").filter(a => !skipIds.includes(a.id));
+          if (ordered.length > 0) {
+            return { content: [{ type: "text", text: `No "${typeFilter}" tasks pending. ${ordered.length} tasks available with type filter "any". Call again with type: "any" if you can handle them.` }] };
+          }
+        }
+        return { content: [{ type: "text", text: "All caught up. No pending tasks matching your criteria." }] };
+      }
+
+      const action = ordered[0];
+      const packet = generatePacket(action, project);
+      const remaining = ordered.length - 1;
+
+      const output = {
+        ...packet,
+        _meta: {
+          remaining_tasks: remaining,
+          queue_position: 1,
+          total_in_project: (project.actions || []).length,
+        },
+      };
+
+      return { content: [{ type: "text", text: JSON.stringify(output, null, 2) }] };
+    }
+
+    // ─── COMPLETE TASK ──────────────────────────────────────────────────────
+    case "phewsh_complete_task": {
+      const result = {
+        projectId: args.project_id,
+        taskId: args.task_id,
+        result: args.result,
+        success: args.success,
+        issues: args.issues,
+        agentId: args.agent_id,
+        reportedAt: new Date().toISOString(),
+      };
+
+      // Save result to disk
+      const resultFile = join(RESULTS_DIR, `${args.task_id}_${Date.now()}.json`);
+      writeFileSync(resultFile, JSON.stringify(result, null, 2));
+
+      // Record session event
+      recordSession(args.agent_id, args.project_id, "task_complete", {
+        taskId: args.task_id,
+        success: args.success,
+        result: args.result?.slice(0, 200),
+      });
+
+      // Update local .intent/status.md if applicable
+      if (args.project_id === "local") {
+        const intentDir = join(process.cwd(), ".intent");
+        if (existsSync(intentDir)) {
+          const statusFile = join(intentDir, "status.md");
+          const entry = `\n- [${args.success ? "x" : "!"}] ${args.result.split("\n")[0]} (${new Date().toISOString().split("T")[0]})${args.agent_id ? ` [${args.agent_id}]` : ""}\n`;
+          try {
+            if (existsSync(statusFile)) {
+              const existing = readFileSync(statusFile, "utf-8");
+              writeFileSync(statusFile, existing + entry);
+            } else {
+              writeFileSync(statusFile, `# Execution Log\n${entry}`);
+            }
+          } catch { /* non-critical — skip if write fails */ }
+        }
+      }
+
+      // Build response with auto-chain
+      const sections = [];
+      if (args.success) {
+        sections.push(`Task "${args.task_id}" completed successfully.`);
+        if (args.issues) sections.push(`Note: ${args.issues}`);
+      } else {
+        sections.push(`Task "${args.task_id}" reported as failed.`);
+        sections.push(`Issues: ${args.issues || args.result}`);
+        sections.push("The project owner will be notified to review.");
+      }
+
+      // Auto-chain: show next task
+      const project = projects.find(p => p.id === args.project_id);
+      if (project && args.success) {
+        const nextTasks = getOrderedTasks(project, "any")
+          .filter(a => a.id !== args.task_id);
+
+        if (nextTasks.length > 0) {
+          const next = nextTasks[0];
+          const packet = generatePacket(next, project);
+          sections.push("");
+          sections.push("---");
+          sections.push("## Next Task");
+          sections.push(`**${packet.objective.task}**`);
+          sections.push(`Done when: ${packet.objective.successState}`);
+          sections.push(`Task ID: \`${packet.id}\``);
+          sections.push("");
+          sections.push("Verify:");
+          packet.verification.criteria.forEach(c => sections.push(`- [ ] ${c}`));
+          sections.push("");
+          sections.push(`${nextTasks.length - 1} more tasks after this.`);
+        } else {
+          sections.push("");
+          sections.push("All tasks complete! Great work.");
+        }
+      }
+
+      return { content: [{ type: "text", text: sections.join("\n") }] };
+    }
+
+    // ─── LIST PROJECTS ──────────────────────────────────────────────────────
+    case "phewsh_list_projects": {
+      const summary = projects.map(summarizeProject);
+      return { content: [{ type: "text", text: JSON.stringify(summary, null, 2) }] };
+    }
+
+    // ─── GET CONTEXT ────────────────────────────────────────────────────────
+    case "phewsh_get_context": {
+      const project = projects.find(p => p.id === args.project_id);
+      if (!project) return { content: [{ type: "text", text: `Project "${args.project_id}" not found.` }] };
+      return { content: [{ type: "text", text: buildFullBriefing(project) }] };
+    }
+
+    // ─── CHECK VERIFICATION ─────────────────────────────────────────────────
+    case "phewsh_check_verification": {
+      const project = projects.find(p => p.id === args.project_id);
+      if (!project) return { content: [{ type: "text", text: `Project "${args.project_id}" not found.` }] };
+
+      const action = (project.actions || []).find(a => a.id === args.task_id);
+      if (!action) return { content: [{ type: "text", text: `Task "${args.task_id}" not found.` }] };
+
+      const verification = deriveVerification(action.intent);
+      const rollback = assessReversibility(action.intent);
+
+      const sections = [];
+      sections.push(`# Verification: ${action.intent}`);
+      sections.push("");
+      sections.push("Before marking this complete, confirm ALL of:");
+      sections.push("");
+      verification.criteria.forEach((c, i) => sections.push(`${i + 1}. ${c}`));
+      sections.push("");
+      if (!rollback.canRevert) {
+        sections.push(`**This is irreversible.** ${rollback.warning}`);
+      } else {
+        sections.push("This is reversible if needed.");
+        if (rollback.how) sections.push(`Rollback: ${rollback.how}`);
+      }
+
+      return { content: [{ type: "text", text: sections.join("\n") }] };
+    }
+
+    // ─── FLAG BLOCKER ───────────────────────────────────────────────────────
+    case "phewsh_flag_blocker": {
+      recordSession(args.agent_id, args.project_id, "blocker_flagged", {
+        taskId: args.task_id,
+        reason: args.reason,
+        needs: args.needs,
+      });
+
+      // Write blocker file for visibility
+      const blockerFile = join(RESULTS_DIR, `blocker_${args.task_id}_${Date.now()}.json`);
+      writeFileSync(blockerFile, JSON.stringify({
+        type: "blocker",
+        projectId: args.project_id,
+        taskId: args.task_id,
+        reason: args.reason,
+        needs: args.needs,
+        agentId: args.agent_id,
+        flaggedAt: new Date().toISOString(),
+      }, null, 2));
+
+      // Suggest next task that isn't blocked
+      const project = projects.find(p => p.id === args.project_id);
+      let suggestion = "";
+      if (project) {
+        const nextTasks = getOrderedTasks(project, "any").filter(a => a.id !== args.task_id);
+        if (nextTasks.length > 0) {
+          suggestion = `\n\nMeanwhile, you can work on: "${nextTasks[0].intent}" (task_id: ${nextTasks[0].id})`;
+        }
+      }
+
+      return { content: [{ type: "text", text: `Blocker flagged for task "${args.task_id}". The project owner will be notified.\n\nReason: ${args.reason}\nNeeds: ${args.needs || "Unknown"}${suggestion}` }] };
+    }
+
+    // ─── SESSION HISTORY ────────────────────────────────────────────────────
+    case "phewsh_session_history": {
+      const sessions = getRecentSessions(args.project_id, args.limit || 20);
+      if (sessions.length === 0) {
+        return { content: [{ type: "text", text: "No session history for this project yet." }] };
+      }
+
+      const sections = [`# Session History: ${args.project_id}`, ""];
+      sessions.reverse().forEach(s => {
+        const time = s.timestamp.split("T")[0];
+        const agent = s.agentId || "unknown";
+        switch (s.event) {
+          case "session_start":
+            sections.push(`- [${time}] ${agent} started session`);
+            break;
+          case "task_complete":
+            sections.push(`- [${time}] ${agent} completed: ${s.result || s.taskId} ${s.success ? "OK" : "FAILED"}`);
+            break;
+          case "blocker_flagged":
+            sections.push(`- [${time}] ${agent} blocked on: ${s.reason}`);
+            break;
+          default:
+            sections.push(`- [${time}] ${agent}: ${s.event}`);
+        }
+      });
+
+      return { content: [{ type: "text", text: sections.join("\n") }] };
+    }
+
+    default:
+      return { content: [{ type: "text", text: `Unknown tool: ${name}` }] };
+  }
+});
+
+// ── Prompts (pre-built workflows agents can discover) ──
+
+server.setRequestHandler(ListPromptsRequestSchema, async () => ({
+  prompts: [
+    {
+      name: "work_session",
+      description: "Full work session: get briefed, execute tasks, report results. Best for autonomous agents that want to do as much as possible.",
+      arguments: [
+        { name: "project_id", description: "Project to work on (omit for auto-detect)", required: false },
+        { name: "max_tasks", description: "Maximum tasks to complete this session (default: 5)", required: false },
+      ],
+    },
+    {
+      name: "status_check",
+      description: "Quick status check: what's done, what's pending, any blockers. No execution.",
+      arguments: [
+        { name: "project_id", description: "Project to check", required: false },
+      ],
+    },
+    {
+      name: "review_results",
+      description: "Review recent agent work: what was completed, what failed, what's blocked. For human oversight.",
+      arguments: [
+        { name: "project_id", description: "Project to review", required: false },
+      ],
+    },
+  ],
+}));
+
+server.setRequestHandler(GetPromptRequestSchema, async (request) => {
+  const { name, arguments: args } = request.params;
+  const projects = loadProjects();
+
+  switch (name) {
+    case "work_session": {
+      const projectId = args?.project_id || (projects.length === 1 ? projects[0].id : "local");
+      const maxTasks = args?.max_tasks || 5;
+      const project = projects.find(p => p.id === projectId);
+
+      return {
+        messages: [
+          {
+            role: "user",
+            content: {
+              type: "text",
+              text: `You are an autonomous agent working on the "${project?.name || projectId}" project via PHEWSH coordination.
+
+Your workflow:
+1. Call \`phewsh_start\` with project_id: "${projectId}" to get your briefing and first task
+2. Execute the task described in the dispatch packet
+3. Call \`phewsh_complete_task\` with your results — it will auto-chain to the next task
+4. Repeat until you've completed ${maxTasks} tasks or hit a blocker
+5. If blocked, call \`phewsh_flag_blocker\` and move to the next available task
+
+Rules:
+- Always check verification criteria before marking complete
+- If a task is irreversible, confirm with the user before executing
+- Report issues honestly — failed tasks help the project owner make better decisions
+- Stay within the constraints provided in each dispatch packet
+- You are the executor, not the decision-maker. Execute what's been planned.
+
+Start now by calling phewsh_start.`,
+            },
+          },
+        ],
+      };
+    }
+
+    case "status_check": {
+      const projectId = args?.project_id || (projects.length === 1 ? projects[0].id : "local");
+      return {
+        messages: [
+          {
+            role: "user",
+            content: {
+              type: "text",
+              text: `Give me a quick status check on the "${projectId}" project. Call \`phewsh_list_projects\` and \`phewsh_session_history\` with project_id: "${projectId}" to get the current state. Summarize: what's done, what's pending, any blockers, and what needs my attention.`,
+            },
+          },
+        ],
+      };
+    }
+
+    case "review_results": {
+      const projectId = args?.project_id || (projects.length === 1 ? projects[0].id : "local");
+      return {
+        messages: [
+          {
+            role: "user",
+            content: {
+              type: "text",
+              text: `Review the recent agent work on "${projectId}". Call \`phewsh_session_history\` with project_id: "${projectId}" and limit: 30. Then summarize:
+- What was completed successfully
+- What failed and why
+- Any unresolved blockers
+- Recommendations for what the project owner should do next
+
+Be honest and specific. This is for human oversight.`,
+            },
+          },
+        ],
+      };
+    }
+
+    default:
+      return { messages: [] };
+  }
+});
+
+// ── Resources ──
+
+server.setRequestHandler(ListResourcesRequestSchema, async () => {
+  const projects = loadProjects();
+  const resources = [];
+
+  for (const project of projects) {
+    resources.push({
+      uri: `phewsh://projects/${project.id}/briefing`,
+      name: `${project.name} — Full Briefing`,
+      description: `Complete project context: vision, plan, constraints, execution state`,
+      mimeType: "text/markdown",
+    });
+
+    if (project.artifacts) {
+      for (const [kind, artifact] of Object.entries(project.artifacts)) {
+        if (artifact?.content) {
+          resources.push({
+            uri: `phewsh://projects/${project.id}/artifacts/${kind}`,
+            name: `${project.name} — ${kind}`,
+            description: `${kind} artifact`,
+            mimeType: "text/markdown",
+          });
+        }
+      }
+    }
+  }
+
+  return { resources };
+});
+
+server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
+  const { uri } = request.params;
+  const projects = loadProjects();
+
+  const match = uri.match(/^phewsh:\/\/projects\/([^/]+)\/(briefing|artifacts\/(.+))$/);
+  if (!match) return { contents: [{ uri, text: "Invalid resource URI", mimeType: "text/plain" }] };
+
+  const [, projectId, path, artifactKind] = match;
+  const project = projects.find(p => p.id === projectId);
+  if (!project) return { contents: [{ uri, text: `Project "${projectId}" not found`, mimeType: "text/plain" }] };
+
+  if (path === "briefing") {
+    return { contents: [{ uri, text: buildFullBriefing(project), mimeType: "text/markdown" }] };
+  }
+
+  if (artifactKind && project.artifacts?.[artifactKind]?.content) {
+    return { contents: [{ uri, text: project.artifacts[artifactKind].content, mimeType: "text/markdown" }] };
+  }
+
+  return { contents: [{ uri, text: "Resource not found", mimeType: "text/plain" }] };
+});
+
+// ── Start ──
+
+async function main() {
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+  console.error("PHEWSH MCP Server v0.2.0 — coordination layer active");
+}
+
+main().catch((err) => {
+  console.error("Failed to start PHEWSH MCP server:", err);
+  process.exit(1);
+});