iaip-mcp-pde 2.0.2

package/dist/types.d.ts

@@ -0,0 +1,108 @@
+/**
+ * PDE-MCP Types v2
+ *
+ * Canonical types from IAIP/lib/pde/types.ts — the LLM-driven Prompt Decomposition Engine.
+ * This replaces the v1 regex-based types with the proven DecompositionResult schema
+ * that powers the IAIP web UI and is designed for reuse across MCP, CLI, and UI contexts.
+ *
+ * Lineage: IAIP/lib/pde/types.ts → mcp-pde/src/types.ts
+ */
+export interface DecompositionOptions {
+    extractImplicit: boolean;
+    mapDependencies: boolean;
+}
+export declare const DEFAULT_OPTIONS: DecompositionOptions;
+export interface DecompositionResult {
+    primary: PrimaryIntent;
+    secondary: SecondaryIntent[];
+    context: ContextRequirements;
+    outputs: ExpectedOutputs;
+    directions: DirectionMap;
+    actionStack: ActionItem[];
+    ambiguities: AmbiguityFlag[];
+}
+export interface PrimaryIntent {
+    action: string;
+    target: string;
+    urgency: Urgency;
+    confidence: number;
+}
+export type Urgency = "immediate" | "session" | "persistent";
+export interface SecondaryIntent {
+    action: string;
+    target: string;
+    implicit: boolean;
+    dependency: string | null;
+    confidence: number;
+}
+export interface ContextRequirements {
+    files_needed: string[];
+    tools_required: string[];
+    assumptions: string[];
+}
+export interface ExpectedOutputs {
+    artifacts: string[];
+    updates: string[];
+    communications: string[];
+}
+export type Direction = "east" | "south" | "west" | "north";
+export interface DirectionItem {
+    text: string;
+    confidence: number;
+    implicit: boolean;
+}
+export type DirectionMap = Record<Direction, DirectionItem[]>;
+export interface ActionItem {
+    text: string;
+    direction: Direction;
+    dependency: string | null;
+    completed?: boolean;
+}
+export interface AmbiguityFlag {
+    text: string;
+    suggestion: string;
+}
+export interface DirectionMeta {
+    name: string;
+    desc: string;
+    emoji: string;
+    color: string;
+}
+export declare const DIRECTION_META: Record<Direction, DirectionMeta>;
+export declare const DIRECTIONS: Direction[];
+export interface StoredDecomposition {
+    id: string;
+    timestamp: string;
+    prompt: string;
+    result: DecompositionResult;
+    options: DecompositionOptions;
+    /** Path to the exported markdown file, if any */
+    markdownPath?: string;
+    /** UUID of parent PDE (for parent-child relationships) */
+    parent_pde_id?: string;
+    /** Folder name, e.g. "2604041200--83a2d7f9-..." */
+    folder_name?: string;
+}
+export interface DecomposeInput {
+    prompt: string;
+    options?: Partial<DecompositionOptions>;
+    /** Working directory for .pde/ storage. Defaults to cwd. */
+    workdir?: string;
+    /** UUID of parent PDE for parent-child nesting */
+    parent_pde_id?: string;
+}
+export interface GetDecompositionInput {
+    id: string;
+    workdir?: string;
+}
+export interface ListDecompositionsInput {
+    workdir?: string;
+    limit?: number;
+    /** Filter to children of a specific parent PDE */
+    parent_id?: string;
+}
+export interface ExportMarkdownInput {
+    id: string;
+    workdir?: string;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/dist/types.js

@@ -0,0 +1,24 @@
+"use strict";
+/**
+ * PDE-MCP Types v2
+ *
+ * Canonical types from IAIP/lib/pde/types.ts — the LLM-driven Prompt Decomposition Engine.
+ * This replaces the v1 regex-based types with the proven DecompositionResult schema
+ * that powers the IAIP web UI and is designed for reuse across MCP, CLI, and UI contexts.
+ *
+ * Lineage: IAIP/lib/pde/types.ts → mcp-pde/src/types.ts
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DIRECTIONS = exports.DIRECTION_META = exports.DEFAULT_OPTIONS = void 0;
+exports.DEFAULT_OPTIONS = {
+    extractImplicit: true,
+    mapDependencies: true,
+};
+exports.DIRECTION_META = {
+    east: { name: "VISION", desc: "What is being asked?", emoji: "🌅", color: "#f59e0b" },
+    south: { name: "ANALYSIS", desc: "What needs to be learned?", emoji: "🔥", color: "#ef4444" },
+    west: { name: "VALIDATION", desc: "What needs reflection?", emoji: "🌊", color: "#3b82f6" },
+    north: { name: "ACTION", desc: "What executes the cycle?", emoji: "❄️", color: "#10b981" },
+};
+exports.DIRECTIONS = ["east", "south", "west", "north"];
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":";AAAA;;;;;;;;GAQG;;;AAWU,QAAA,eAAe,GAAyB;IACnD,eAAe,EAAE,IAAI;IACrB,eAAe,EAAE,IAAI;CACtB,CAAC;AA0EW,QAAA,cAAc,GAAqC;IAC9D,IAAI,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,sBAAsB,EAAE,KAAK,EAAE,IAAI,EAAE,KAAK,EAAE,SAAS,EAAE;IACrF,KAAK,EAAE,EAAE,IAAI,EAAE,UAAU,EAAE,IAAI,EAAE,2BAA2B,EAAE,KAAK,EAAE,IAAI,EAAE,KAAK,EAAE,SAAS,EAAE;IAC7F,IAAI,EAAE,EAAE,IAAI,EAAE,YAAY,EAAE,IAAI,EAAE,wBAAwB,EAAE,KAAK,EAAE,IAAI,EAAE,KAAK,EAAE,SAAS,EAAE;IAC3F,KAAK,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,0BAA0B,EAAE,KAAK,EAAE,IAAI,EAAE,KAAK,EAAE,SAAS,EAAE;CAC3F,CAAC;AAEW,QAAA,UAAU,GAAgB,CAAC,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,CAAC"}

package/package.json

@@ -0,0 +1,63 @@
+{
+  "name": "iaip-mcp-pde",
+  "version": "2.0.2",
+  "description": "Prompt Decomposition Engine as MCP Server - LLM-driven decomposition into structured JSON with Four Directions mapping, ambiguity detection, and .pde/ storage",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "bin": {
+    "mcp-pde": "./dist/cli.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "start": "node dist/index.js",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "lint": "eslint src --ext .ts",
+    "clean": "rm -rf dist"
+  },
+  "keywords": [
+    "mcp",
+    "prompt-decomposition",
+    "llm",
+    "ai-agents",
+    "indigenous-ai",
+    "medicine-wheel",
+    "ceremonial-technology"
+  ],
+  "author": "Guillaume Descoteaux-Isabelle <jgi@jgwill.com>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jgwill/mcp-pde.git"
+  },
+  "bugs": {
+    "url": "https://github.com/jgwill/mcp-pde/issues"
+  },
+  "homepage": "https://github.com/jgwill/mcp-pde#readme",
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@anthropic-ai/sdk": "^0.80.0",
+    "@modelcontextprotocol/sdk": "^1.27.1",
+    "minimist": "^1.2.8",
+    "uuid": "^9.0.0",
+    "zod": "^3.22.0"
+  },
+  "devDependencies": {
+    "@types/minimist": "^1.2.5",
+    "@types/node": "^20.10.0",
+    "@types/uuid": "^9.0.0",
+    "typescript": "^5.3.0",
+    "vitest": "^1.0.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "files": [
+    "dist",
+    "rispecs",
+    "scenarios"
+  ]
+}

package/rispecs/pde-data-models.rispec.md

@@ -0,0 +1,182 @@
+# PDE-MCP Data Models Specification
+> TypeScript Interface Definitions for Prompt Decomposition Engine v2
+
+**Version**: 2.0.0
+**Document ID**: pde-mcp-data-models-v2
+
+## Creative Intent
+
+### Desired Outcome
+Developers **create** type-safe implementations using the canonical IAIP/lib/pde types — a zero-dependency, reusable schema shared across MCP server, CLI, and web UI contexts.
+
+### Lineage
+All types flow from `IAIP/lib/pde/types.ts`. This file is a direct port.
+
+## Core DecompositionResult Schema
+
+```typescript
+/**
+ * Root output of a PDE decomposition.
+ * Produced by the LLM when given the buildSystemPrompt() instructions.
+ */
+export interface DecompositionResult {
+  primary: PrimaryIntent;
+  secondary: SecondaryIntent[];
+  context: ContextRequirements;
+  outputs: ExpectedOutputs;
+  directions: DirectionMap;
+  actionStack: ActionItem[];
+  ambiguities: AmbiguityFlag[];
+}
+```
+
+### Primary Intent
+
+```typescript
+export interface PrimaryIntent {
+  action: string;           // The main verb/operation
+  target: string;           // What is being acted upon
+  urgency: Urgency;         // "immediate" | "session" | "persistent"
+  confidence: number;       // 0.0 - 1.0
+}
+
+export type Urgency = "immediate" | "session" | "persistent";
+```
+
+### Secondary Intents
+
+```typescript
+export interface SecondaryIntent {
+  action: string;
+  target: string;
+  implicit: boolean;        // true = inferred from hedging language
+  dependency: string | null; // what this intent depends on, or null
+  confidence: number;        // 0.0 - 1.0
+}
+```
+
+### Context Requirements
+
+```typescript
+export interface ContextRequirements {
+  files_needed: string[];   // Files the agent should read before acting
+  tools_required: string[]; // MCP tools or CLI tools needed
+  assumptions: string[];    // Statements in the prompt assumed true but unverified
+}
+```
+
+### Expected Outputs
+
+```typescript
+export interface ExpectedOutputs {
+  artifacts: string[];      // New files to create
+  updates: string[];        // Existing files to update
+  communications: string[]; // PRs, issues, docs, notifications
+}
+```
+
+### Direction Map (Four Directions)
+
+```typescript
+export type Direction = "east" | "south" | "west" | "north";
+
+export interface DirectionItem {
+  text: string;
+  confidence: number;       // 0.0 - 1.0
+  implicit: boolean;
+}
+
+export type DirectionMap = Record<Direction, DirectionItem[]>;
+```
+
+Direction semantics:
+- **east** 🌅 VISION — What is being asked?
+- **south** 🔥 ANALYSIS — What needs to be learned?
+- **west** 🌊 VALIDATION — What needs reflection?
+- **north** ❄️ ACTION — What executes the cycle?
+
+### Action Stack
+
+```typescript
+export interface ActionItem {
+  text: string;
+  direction: Direction;     // "east" | "south" | "west" | "north"
+  dependency: string | null; // Task this depends on, or null
+  completed?: boolean;       // Defaults to false
+}
+```
+
+The actionStack is an ordered list of tasks respecting dependencies, each mapped to a direction.
+
+### Ambiguity Flags
+
+```typescript
+export interface AmbiguityFlag {
+  text: string;       // The vague/ambiguous phrase or aspect
+  suggestion: string; // How to clarify it
+}
+```
+
+## Direction Metadata
+
+```typescript
+export interface DirectionMeta {
+  name: string;   // "VISION" | "ANALYSIS" | "VALIDATION" | "ACTION"
+  desc: string;   // Short description of what the direction handles
+  emoji: string;  // "🌅" | "🔥" | "🌊" | "❄️"
+  color: string;  // Hex color for visualization
+}
+
+export const DIRECTION_META: Record<Direction, DirectionMeta> = {
+  east:  { name: "VISION",     desc: "What is being asked?",       emoji: "🌅", color: "#f59e0b" },
+  south: { name: "ANALYSIS",   desc: "What needs to be learned?",  emoji: "🔥", color: "#ef4444" },
+  west:  { name: "VALIDATION", desc: "What needs reflection?",     emoji: "🌊", color: "#3b82f6" },
+  north: { name: "ACTION",     desc: "What executes the cycle?",   emoji: "❄️", color: "#10b981" },
+};
+```
+
+## Storage Types
+
+```typescript
+/**
+ * Persisted to .pde/<uuid>.json
+ */
+export interface StoredDecomposition {
+  id: string;               // UUID
+  timestamp: string;        // ISO 8601
+  prompt: string;           // Original prompt text
+  result: DecompositionResult;
+  options: DecompositionOptions;
+  markdownPath?: string;    // Path to .pde/<id>.md, set after export
+}
+```
+
+## MCP Tool Input Types
+
+```typescript
+export interface DecompositionOptions {
+  extractImplicit: boolean;   // Extract implicit intents (default: true)
+  mapDependencies: boolean;   // Map dependencies between actions (default: true)
+}
+
+export interface DecomposeInput {
+  prompt: string;
+  options?: Partial<DecompositionOptions>;
+  workdir?: string;           // Working directory for .pde/ storage
+}
+
+export interface GetDecompositionInput {
+  id: string;
+  workdir?: string;
+}
+
+export interface ListDecompositionsInput {
+  workdir?: string;
+  limit?: number;
+}
+
+export interface ExportMarkdownInput {
+  id: string;
+  workdir?: string;
+}
+```

package/rispecs/pde-overview.rispec.md

@@ -0,0 +1,157 @@
+# PDE-MCP Overview Specification
+> Prompt Decomposition Engine as Model Context Protocol Server
+
+**Version**: 2.0.0
+**Document ID**: pde-mcp-overview-v2
+**Last Updated**: 2026-02-22
+**Attribution**: Indigenous-AI Collaborative Platform
+
+## Creative Intent
+
+### Desired Outcome
+LLM terminal agents (claude-code, gemini-cli, copilot-cli) **create** well-decomposed, ceremonially-aligned decompositions from complex user prompts — stored as git-diffable markdown in `.pde/` — enabling transparent, human-in-the-loop review of multi-intent workflows.
+
+### Current Reality
+Terminal agents receive complex prompts with:
+- Multiple implicit intentions
+- Nested requirements and action sequences
+- Context requiring cross-referencing
+- Ambiguities that need surfacing before execution
+
+Without decomposition, agents miss secondary intentions, lose context, and fail to track multi-step progress.
+
+### Structural Tension
+The natural resolution moves agents from "blind execution" to "conscious ceremony" where each task is:
+1. **Understood** (East 🌅 — Vision: what is being asked?)
+2. **Analyzed** (South 🔥 — Analysis: what needs to be learned?)
+3. **Validated** (West 🌊 — Validation: what needs reflection?)
+4. **Executed** (North ❄️ — Action: what executes the cycle?)
+
+## System Architecture
+
+### LLM-Driven Two-Step Pipeline (v2)
+
+```
+Step 1: Build Prompt
+  pde_decompose(prompt) → { systemPrompt, userMessage }
+      ↓ agent sends to their own LLM
+  LLM → DecompositionResult JSON
+
+Step 2: Parse & Store
+  pde_parse_response(llm_response, original_prompt)
+      → StoredDecomposition saved to .pde/<uuid>.json
+      → Markdown export to .pde/<uuid>.md (git-diffable)
+```
+
+The engine does **not** embed an LLM. The calling agent (Copilot CLI, Gemini CLI, mia-code) feeds the system prompt to their own LLM provider.
+
+### MCP Integration Points
+
+The PDE exposes capabilities through three MCP primitives:
+
+1. **Tools** — Active operations: `pde_decompose`, `pde_parse_response`, `pde_get`, `pde_list`, `pde_export_markdown`
+2. **Resources** — Static content: `pde://schema/decomposition-result`, `pde://directions`
+3. **Prompts** — Single reusable prompt: `pde-decompose`
+
+### Storage Layout
+
+```
+.pde/
+  <uuid>.json    — StoredDecomposition (full structured JSON)
+  <uuid>.md      — Markdown export (human-editable, git-diffable)
+```
+
+## Core Concepts
+
+### DecompositionResult Schema
+Canonical output structure (from IAIP/lib/pde lineage):
+- **primary**: Single most important action (action, target, urgency, confidence)
+- **secondary**: All other intents, explicit and implicit
+- **context**: Files needed, tools required, assumptions
+- **outputs**: Artifacts, updates, communications expected
+- **directions**: Items mapped to east/south/west/north
+- **actionStack**: Ordered task list with direction and dependency
+- **ambiguities**: Vague aspects with clarification suggestions
+
+### Direction Mapping (Four Directions)
+- **east** 🌅 VISION: Understanding what is being asked, clarifying requirements
+- **south** 🔥 ANALYSIS: Research, learning, investigation, growth tasks
+- **west** 🌊 VALIDATION: Testing, reflection, review, accountability tasks
+- **north** ❄️ ACTION: Implementation, execution, delivery, wisdom tasks
+
+### Lineage
+- Canonical types: `IAIP/lib/pde/types.ts`
+- System prompts: `IAIP/lib/pde/prompts.ts`
+- Parser: `IAIP/lib/pde/parser.ts`
+- Web UI reference: `IAIP/app/prompt-decomposer/page.tsx`
+
+## Advancing Patterns
+
+### What Users Create
+1. **Structured decompositions** — Complex prompts fully understood before execution
+2. **Git-diffable plans** — Markdown exports enable human review and editing
+3. **Surfaced ambiguities** — Vague intent flagged for clarification
+4. **Ceremonially-aligned tasks** — Four Directions organizing principle
+
+### Natural Progression
+1. Agent calls `pde_decompose` with user prompt → receives system prompt + user message
+2. Agent sends messages to their LLM → receives DecompositionResult JSON
+3. Agent calls `pde_parse_response` → stored in `.pde/<uuid>.json` + `.pde/<uuid>.md`
+4. User reviews markdown, edits if needed; `git diff` shows changes
+5. Ambiguities become discussion threads for future clarification
+
+## Integration with Terminal Agents
+
+### Workflow Pattern
+```
+# Step 1: Get decomposition prompt
+pde_decompose({ prompt: "Create user auth with JWT, PostgreSQL, tests" })
+→ { systemPrompt, userMessage }
+
+# Step 2: Agent sends to LLM, gets JSON back
+# Step 3: Store result
+pde_parse_response({ llm_response: "<json>", original_prompt: "..." })
+→ StoredDecomposition { id, timestamp, result, markdownPath }
+
+# Step 4: Retrieve or export
+pde_get({ id: "<uuid>" })
+pde_export_markdown({ id: "<uuid>" })
+```
+
+### Expected Markdown Output (`.pde/<uuid>.md`)
+```markdown
+# Prompt Decomposition
+
+## Directions
+- 🌅 **EAST** — VISION: What is being asked?
+- 🔥 **SOUTH** — ANALYSIS: What needs to be learned?
+- 🌊 **WEST** — VALIDATION: What needs reflection?
+- ❄️ **NORTH** — ACTION: What executes the cycle?
+
+## Primary Intent
+**Action:** create  **Target:** user auth system  **Urgency:** immediate
+
+## Action Stack
+- [ ] 🌅 Clarify JWT token lifespan (no deps)
+- [ ] 🔥 Design PostgreSQL schema
+- [ ] 🔥 Implement JWT auth service (depends on schema)
+- [ ] 🌊 Write and run test suite
+- [ ] ❄️ Deploy to staging
+
+## Ambiguity Flags
+- **"PostgreSQL"** — Suggestion: Confirm DB host / connection string
+```
+
+## Quality Criteria
+
+### RISE Alignment
+- ✅ **Creating Focus**: Agents create structured decompositions, not solve decomposition problems
+- ✅ **Structural Dynamics**: Natural flow from vision to action via Four Directions
+- ✅ **Advancing Patterns**: Each stored decomposition builds toward informed execution
+- ✅ **Desired Outcomes**: Actionable action stack + surfaced ambiguities at each call
+
+### Anti-Patterns Avoided
+- ❌ Embedding LLM — engine builds prompts only; callers supply their own LLM
+- ❌ Opacity — all decompositions persisted as human-readable markdown
+- ❌ Single-shot execution — two-step workflow enables review before acting
+- ❌ Lost ambiguities — explicit `ambiguities[]` array surfaces vague intent