iaip-mcp-pde 2.0.2

package/rispecs/pde-resources.rispec.md

@@ -0,0 +1,101 @@
+# PDE-MCP Resources Specification
+> MCP Resource Definitions for Prompt Decomposition Engine v2
+
+**Version**: 2.0.0
+**Document ID**: pde-mcp-resources-v2
+
+## Creative Intent
+
+### Desired Outcome
+LLM agents **access** two static resources that expose the canonical DecompositionResult schema and Four Directions metadata — enabling agents to understand the expected output format and direction semantics.
+
+## Resource Definitions
+
+### Resource 1: `pde://schema/decomposition-result`
+
+**Purpose**: The canonical JSON schema for prompt decomposition output
+
+**Content Type**: `application/json`
+
+**What This Enables**: Agents understand the exact structure they need to parse and store after calling their LLM with the `pde-decompose` system prompt.
+
+**Schema**:
+```json
+{
+  "description": "DecompositionResult — the output of PDE prompt decomposition",
+  "schema": {
+    "primary": {
+      "action": "string",
+      "target": "string",
+      "urgency": "immediate|session|persistent",
+      "confidence": "0.0-1.0"
+    },
+    "secondary": [{
+      "action": "string",
+      "target": "string",
+      "implicit": "boolean",
+      "dependency": "string|null",
+      "confidence": "0.0-1.0"
+    }],
+    "context": {
+      "files_needed": ["string"],
+      "tools_required": ["string"],
+      "assumptions": ["string"]
+    },
+    "outputs": {
+      "artifacts": ["string"],
+      "updates": ["string"],
+      "communications": ["string"]
+    },
+    "directions": {
+      "east":  [{"text": "string", "confidence": "0.0-1.0", "implicit": "boolean"}],
+      "south": [{"text": "string", "confidence": "0.0-1.0", "implicit": "boolean"}],
+      "west":  [{"text": "string", "confidence": "0.0-1.0", "implicit": "boolean"}],
+      "north": [{"text": "string", "confidence": "0.0-1.0", "implicit": "boolean"}]
+    },
+    "actionStack": [{
+      "text": "string",
+      "direction": "east|south|west|north",
+      "dependency": "string|null",
+      "completed": "boolean"
+    }],
+    "ambiguities": [{
+      "text": "string",
+      "suggestion": "string"
+    }]
+  }
+}
+```
+
+---
+
+### Resource 2: `pde://directions`
+
+**Purpose**: Four Directions metadata for Medicine Wheel direction semantics
+
+**Content Type**: `application/json`
+
+**What This Enables**: Agents create accurate direction assignments and render direction-aware UI (colors, emojis, descriptions).
+
+**Schema** (matches `DIRECTION_META` constant in `types.ts`):
+```json
+{
+  "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" }
+}
+```
+
+## Resource Access Patterns
+
+### URI Scheme
+Resources use the `pde://` scheme:
+- `pde://schema/decomposition-result` — DecompositionResult JSON schema
+- `pde://directions` — Four Directions metadata
+
+### Caching
+Resources are static (derived from compile-time constants) and can be cached indefinitely.
+
+### Versioning
+Resource content reflects the v2 `DecompositionResult` schema (lowercase directions: east/south/west/north). Earlier v1 specs used uppercase EAST/SOUTH/WEST/NORTH — these are no longer used.

package/rispecs/pde-tools.rispec.md

@@ -0,0 +1,179 @@
+# PDE-MCP Tools Specification
+> MCP Tool Definitions for Prompt Decomposition Engine v2
+
+**Version**: 2.0.0
+**Document ID**: pde-mcp-tools-v2
+
+## Creative Intent
+
+### Desired Outcome
+LLM agents **create** structured decompositions of complex prompts through a two-step LLM-driven workflow: first building a system prompt, then parsing and persisting the LLM response.
+
+## Two-Step Workflow
+
+```
+pde_decompose(prompt) → { systemPrompt, userMessage }
+  ↓ agent sends to LLM
+pde_parse_response(llm_response, original_prompt) → StoredDecomposition
+```
+
+## Tool Definitions
+
+### Tool 1: `pde_decompose`
+
+**Purpose**: Build system prompt + user message for LLM-driven prompt decomposition
+
+**What Users Create**: A ready-to-send LLM payload that produces a DecompositionResult JSON
+
+**Input Schema**:
+```typescript
+interface DecomposeInput {
+  prompt: string;          // The complex prompt to decompose
+  options?: {
+    extractImplicit?: boolean;  // Extract implicit intents (default: true)
+    mapDependencies?: boolean;  // Map dependencies between actions (default: true)
+  };
+}
+```
+
+**Output** (JSON):
+```typescript
+{
+  instructions: string;    // "Send systemPrompt + userMessage to your LLM, then call pde_parse_response"
+  systemPrompt: string;    // Full system prompt instructing LLM to produce DecompositionResult JSON
+  userMessage: string;     // Formatted user message: 'Prompt to decompose: "<prompt>"'
+  original_prompt: string; // Echo of the original prompt
+}
+```
+
+**Behavior**:
+1. Merges options with defaults (`extractImplicit: true`, `mapDependencies: true`)
+2. Builds system prompt via `buildSystemPrompt(opts)`
+3. Returns both messages — does NOT call any LLM itself
+
+---
+
+### Tool 2: `pde_parse_response`
+
+**Purpose**: Parse an LLM response into a structured DecompositionResult and persist it to `.pde/`
+
+**What Users Create**: A stored decomposition as `.pde/<uuid>.json` + `.pde/<uuid>.md`
+
+**Input Schema**:
+```typescript
+interface ParseResponseInput {
+  llm_response: string;    // Raw LLM response text containing DecompositionResult JSON
+  original_prompt: string; // The original prompt that was decomposed
+  workdir?: string;        // Working directory for .pde/ storage (defaults to cwd)
+  options?: {
+    extractImplicit?: boolean;
+    mapDependencies?: boolean;
+  };
+}
+```
+
+**Output** (`StoredDecomposition`):
+```typescript
+interface StoredDecomposition {
+  id: string;              // UUID
+  timestamp: string;       // ISO timestamp
+  prompt: string;          // Original prompt
+  result: DecompositionResult;
+  options: DecompositionOptions;
+  markdownPath?: string;   // Path to .pde/<id>.md
+}
+```
+
+**Behavior**:
+1. Calls `parseDecompositionResponse(llm_response)` — handles markdown code fences, raw JSON, substring extraction
+2. Generates UUID
+3. Saves to `.pde/<uuid>.json` (full StoredDecomposition)
+4. Exports `.pde/<uuid>.md` (git-diffable markdown with Four Directions headers)
+5. Returns the full StoredDecomposition
+
+---
+
+### Tool 3: `pde_get`
+
+**Purpose**: Retrieve a stored decomposition by ID from `.pde/`
+
+**What Users Create**: Access to a previously stored decomposition for review or re-export
+
+**Input Schema**:
+```typescript
+interface GetDecompositionInput {
+  id: string;       // Decomposition UUID
+  workdir?: string; // Working directory
+}
+```
+
+**Output**: Full `StoredDecomposition` JSON, or error if not found
+
+---
+
+### Tool 4: `pde_list`
+
+**Purpose**: List stored decompositions from `.pde/`
+
+**What Users Create**: Visibility into decomposition history
+
+**Input Schema**:
+```typescript
+interface ListDecompositionsInput {
+  workdir?: string;
+  limit?: number;   // Default: 10
+}
+```
+
+**Output** (summary array):
+```typescript
+Array<{
+  id: string;
+  timestamp: string;
+  primaryAction: string;       // "action target" from primary intent
+  secondaryCount: number;
+  ambiguityCount: number;
+  actionStackCount: number;
+}>
+```
+
+---
+
+### Tool 5: `pde_export_markdown`
+
+**Purpose**: Export a stored decomposition as a git-diffable markdown document with Four Directions headers
+
+**What Users Create**: A human-readable, editable document committed alongside code
+
+**Input Schema**:
+```typescript
+interface ExportMarkdownInput {
+  id: string;       // Decomposition UUID
+  workdir?: string;
+}
+```
+
+**Output**: Markdown string with structure:
+```
+# Prompt Decomposition
+## Directions          — Four Directions header block
+## Original Prompt
+## Primary Intent
+## Secondary Intents
+## Context Requirements
+## Four Directions Analysis
+## Action Stack        — ordered checklist with direction + dependency
+## Ambiguity Flags
+## Expected Outputs
+```
+
+**Note**: The markdown is also auto-written to `.pde/<id>.md` during `pde_parse_response`. This tool re-generates it on demand.
+
+## Error Handling
+
+Each tool returns `{ isError: true, content: [{ text: "..." }] }` on failure:
+
+- **Missing required parameter**: `"Missing required parameter: prompt"`
+- **Decomposition not found**: `"Decomposition <id> not found"`
+- **Parse failure**: Thrown as `PDEParseError` with description of what failed
+- **General errors**: Caught and returned as `"Error: <message>"`

package/rispecs/relation-to-mcp-structural-thinking.kin.md

@@ -0,0 +1,66 @@
+# Relation to mcp-structural-thinking
+
+> Kinship document describing the envisioned relationship between **mcp-pde** (Prompt Decomposition Engine) and **mcp-structural-thinking** (Structural Thinking diagnostic layer).
+
+## The Relationship
+
+**mcp-pde** decomposes complex prompts into structured `DecompositionResult` objects with actions mapped to Four Directions (EAST/SOUTH/WEST/NORTH). **mcp-structural-thinking** validates the *quality* of those decompositions through structural observation, question generation, and three-universe consensus.
+
+Together they form a **decompose → validate** pair:
+
+```
+User Prompt
+    │
+    ▼
+mcp-pde (pde_decompose → pde_parse_response)
+    │ DecompositionResult
+    ▼
+mcp-structural-thinking (structural_thinking_observe → validate_three_universe)
+    │ Validated DecompositionResult + Questions
+    ▼
+Agent proceeds with confidence (or returns to user with questions)
+```
+
+## Shared Vocabulary
+
+The Four Directions mapping aligns between both projects:
+
+| Direction | mcp-pde Action Type | mcp-structural-thinking Question Type |
+|-----------|--------------------|------------------------------------|
+| 🌅 EAST | Vision / Intent actions | Information questions |
+| 🔥 SOUTH | Analysis / Research actions | Clarification questions |
+| 🌊 WEST | Validation / Reflection actions | Implication questions |
+| ❄️ NORTH | Execution / Action items | Discrepancy questions |
+
+## Envisioned Workflow
+
+1. Agent receives complex user prompt
+2. Agent calls `mcp-pde.pde_decompose(prompt)` → gets systemPrompt + userMessage
+3. LLM processes → agent calls `mcp-pde.pde_parse_response(llm_response)` → DecompositionResult stored in `.pde/`
+4. Agent calls `mcp-structural-thinking.structural_thinking_observe(decomposition_text)` → gets questions and pattern detection
+5. Agent calls `mcp-structural-thinking.detect_reactive_patterns(decomposition_text)` → checks for reactive framing in the decomposition
+6. Agent calls `mcp-structural-thinking.validate_three_universe(decomposition_text)` → gets three-universe consensus
+7. If reactive score > moderate OR consensus FALSE OR questions reveal gaps → agent asks user for clarification before proceeding
+8. If clean → agent proceeds to execute actions with structural confidence
+
+## What mcp-pde Offers to mcp-structural-thinking
+
+- **DecompositionResult JSON** — structured material for observation (explicit actions, directions, dependencies)
+- **Four Directions mapping** — shared directional vocabulary
+- **`.pde/` storage** — persistent decompositions that can be re-validated
+
+## What mcp-structural-thinking Offers to mcp-pde
+
+- **Quality gate** — validation that decompositions maintain creative orientation
+- **Question generation** — reveals gaps in decompositions before execution
+- **Reactive pattern detection** — catches problem-solving framing in action descriptions
+- **Three-universe consensus** — multi-lens validation of decomposition quality
+
+## Accountability
+
+- Changes to mcp-pde's DecompositionResult schema should be reviewed for impact on mcp-structural-thinking's observation and validation tools
+- Changes to mcp-structural-thinking's question type taxonomy should remain aligned with mcp-pde's Four Directions mapping
+
+---
+
+*Created: 2026-03-31 | Steward: Guillaume (jgwill)*

package/scenarios/01-simple-decomposition.md

@@ -0,0 +1,88 @@
+# Scenario 01: Simple Prompt Decomposition
+
+## Objective
+Test that a simple, single-intent prompt is correctly decomposed into a structured execution plan.
+
+## Scenario Description
+A developer wants to create a new feature. The LLM agent should use PDE to decompose this request into actionable steps aligned with the Medicine Wheel framework.
+
+## Input Prompt
+```
+Create a user registration form with email validation
+```
+
+## Expected Behavior
+
+### 1. Intent Extraction (Layer 1)
+The PDE should extract:
+- **Explicit Intent 1**: CREATION intent for "registration form"
+- **Implicit Intent**: VALIDATION requirement for "email validation"
+
+### 2. Direction Assignment (Layer 3)
+- CREATION → SOUTH (Nahat'á - Planning & Growth)
+- VALIDATION aspects → WEST (Iina - Living & Action)
+
+### 3. Workflow Structure (Layer 4)
+Expected stages:
+```
+Stage: SOUTH - Planning & Growth
+  - [ ] Create registration form component
+  - [ ] Design form fields and layout
+
+Stage: WEST - Living & Action
+  - [ ] Implement email validation logic
+  - [ ] Test validation edge cases
+```
+
+## Test Steps for LLM Agent
+
+1. **Configure MCP**
+   ```json
+   {
+     "mcpServers": {
+       "pde": {
+         "command": "node",
+         "args": ["dist/index.js"]
+       }
+     }
+   }
+   ```
+
+2. **Call pde_decompose tool**
+   ```
+   Use tool: pde_decompose
+   Arguments: { "prompt": "Create a user registration form with email validation" }
+   ```
+
+3. **Verify Response**
+   - [ ] Response contains `planId`
+   - [ ] Response contains `workflowId`
+   - [ ] Response contains at least one stage
+   - [ ] SOUTH stage exists with creation tasks
+   - [ ] `overallIntention` mentions "create" and "registration"
+
+4. **Validate the plan**
+   ```
+   Use tool: pde_validate_plan
+   Arguments: { "planId": "<planId from step 2>" }
+   ```
+
+5. **Check Validation**
+   - [ ] `isValid` is true
+   - [ ] `coherenceScore` >= 80
+   - [ ] `completenessScore` >= 80
+
+## Success Criteria
+
+- ✅ Single prompt decomposed into multi-stage plan
+- ✅ Intent correctly classified as CREATION
+- ✅ Medicine Wheel direction (SOUTH) assigned
+- ✅ Plan validation passes
+- ✅ No errors in execution
+
+## Notes
+
+This is the simplest scenario to verify basic PDE functionality. If this fails, check:
+1. MCP server is running and connected
+2. `pde_decompose` tool is registered
+3. TypeScript compilation succeeded

package/scenarios/02-multi-intent-workflow.md

@@ -0,0 +1,112 @@
+# Scenario 02: Multi-Intent Workflow
+
+## Objective
+Test that a complex, multi-intent prompt is correctly decomposed with proper dependency management and parallel execution detection.
+
+## Scenario Description
+A developer provides a complex request containing multiple actions that need to be:
+- Correctly identified as separate intents
+- Properly sequenced based on dependencies
+- Grouped for potential parallel execution
+
+## Input Prompt
+```
+Create a REST API with user authentication using JWT, connect to PostgreSQL database, write comprehensive tests, and deploy to staging environment
+```
+
+## Expected Behavior
+
+### 1. Intent Extraction (Layer 1)
+The PDE should extract multiple intents:
+
+| Intent | Action | Target | Type |
+|--------|--------|--------|------|
+| 1 | create | API | CREATION |
+| 2 | (auth) | authentication | CREATION |
+| 3 | connect | PostgreSQL | INTEGRATION |
+| 4 | write | tests | CREATION |
+| 5 | deploy | staging | COMMUNICATION |
+
+### 2. Dependency Graph (Layer 2)
+Expected dependencies:
+```
+create API → connect PostgreSQL → write tests → deploy
+         ↘ create auth (parallel with connect)
+```
+
+### 3. Direction Assignment (Layer 3)
+- CREATION intents → SOUTH
+- INTEGRATION → WEST
+- DEPLOYMENT → NORTH
+
+### 4. Workflow Structure (Layer 4)
+Expected stages:
+```
+Stage: SOUTH - Planning & Growth
+  [Parallel possible]
+  - [ ] Create REST API structure
+  - [ ] Implement JWT authentication
+
+Stage: WEST - Living & Action
+  - [ ] Connect to PostgreSQL database
+  - [ ] Write comprehensive tests
+
+Stage: NORTH - Assurance & Reflection
+  - [ ] Deploy to staging environment
+```
+
+## Test Steps for LLM Agent
+
+1. **Call pde_decompose tool**
+   ```
+   Use tool: pde_decompose
+   Arguments: { 
+     "prompt": "Create a REST API with user authentication using JWT, connect to PostgreSQL database, write comprehensive tests, and deploy to staging environment"
+   }
+   ```
+
+2. **Verify Intent Count**
+   - [ ] `metadata.totalTasks` >= 4
+   - [ ] Multiple stages exist
+
+3. **Verify Stage Order**
+   - [ ] SOUTH stage comes before WEST
+   - [ ] WEST stage comes before NORTH
+   - [ ] Ceremonial cycle is respected
+
+4. **Check Parallel Opportunities**
+   - [ ] `metadata.parallelizableTasks` > 0
+   - [ ] SOUTH stage has `executionType: 'parallel'` or multiple tasks
+
+5. **Verify Dependencies**
+   - [ ] Deploy task depends on test task
+   - [ ] No circular dependencies (`hasCycles: false` in graph)
+
+6. **Validate Complexity**
+   - [ ] `metadata.estimatedComplexity` is 'medium' or 'high'
+
+## Success Criteria
+
+- ✅ 4+ intents correctly extracted
+- ✅ All four Medicine Wheel directions represented
+- ✅ Proper dependency ordering (create → integrate → test → deploy)
+- ✅ Parallel execution opportunities identified
+- ✅ No circular dependencies
+- ✅ Plan validation passes
+
+## Common Issues
+
+1. **Missing Implicit Intents**: "with JWT" should trigger auth-related tasks
+2. **Wrong Direction**: Deployment should be NORTH, not SOUTH
+3. **Broken Dependencies**: Tests should not run before API is created
+4. **No Parallelization**: Independent CREATION tasks should be parallelizable
+
+## Advanced Verification
+
+Check the dependency graph structure:
+```
+Use resource: pde://ceremonies/medicine-wheel
+```
+
+Verify that the workflow follows the natural cycle:
+EAST (exploration) → SOUTH (creation) → WEST (validation) → NORTH (completion)

package/scenarios/03-ceremonial-alignment.md

@@ -0,0 +1,155 @@
+# Scenario 03: Ceremonial Alignment Verification
+
+## Objective
+Test that the Medicine Wheel ceremonial framework is correctly applied to categorize tasks by their epistemological nature.
+
+## Scenario Description
+This scenario tests the core Indigenous knowledge system integration by verifying that different types of work are correctly aligned with the Four Directions.
+
+## Input Prompts (Test Each Separately)
+
+### Prompt A: EAST Focus (Analysis/Vision)
+```
+Analyze the current system architecture and explore potential improvements
+```
+
+### Prompt B: SOUTH Focus (Creation/Building)
+```
+Build a new authentication module with OAuth2 support
+```
+
+### Prompt C: WEST Focus (Validation/Integration)
+```
+Test the payment gateway integration and verify all edge cases
+```
+
+### Prompt D: NORTH Focus (Completion/Wisdom)
+```
+Deploy the application to production and document the release
+```
+
+## Expected Behavior
+
+### Prompt A: EAST Alignment
+| Aspect | Expected |
+|--------|----------|
+| Primary Direction | EAST |
+| Direction Name | Nitsáhákees |
+| Theme | Thinking & Beginnings |
+| Ceremony Type | vision_inquiry |
+| Color | #FFD700 (Gold) |
+
+Tasks should focus on:
+- Exploration and research
+- Question formation
+- Vision setting
+
+### Prompt B: SOUTH Alignment
+| Aspect | Expected |
+|--------|----------|
+| Primary Direction | SOUTH |
+| Direction Name | Nahat'á |
+| Theme | Planning & Growth |
+| Ceremony Type | wave_counting |
+| Color | #32CD32 (Green) |
+
+Tasks should focus on:
+- Implementation and building
+- Structural design
+- Methodology application
+
+### Prompt C: WEST Alignment
+| Aspect | Expected |
+|--------|----------|
+| Primary Direction | WEST |
+| Direction Name | Iina |
+| Theme | Living & Action |
+| Ceremony Type | talking_circles |
+| Color | #4682B4 (Steel Blue) |
+
+Tasks should focus on:
+- Testing and validation
+- Integration verification
+- Reflection on quality
+
+### Prompt D: NORTH Alignment
+| Aspect | Expected |
+|--------|----------|
+| Primary Direction | NORTH |
+| Direction Name | Siihasin |
+| Theme | Assurance & Reflection |
+| Ceremony Type | elder_council |
+| Color | #FFFFFF (White) |
+
+Tasks should focus on:
+- Deployment and finalization
+- Documentation (wisdom sharing)
+- Completion ceremonies
+
+## Test Steps for LLM Agent
+
+1. **Get Medicine Wheel Reference**
+   ```
+   Read resource: pde://ceremonies/medicine-wheel
+   ```
+   - [ ] Verify all four directions are defined
+   - [ ] Each has Indigenous name, theme, ceremony type, color
+
+2. **Test EAST Alignment (Prompt A)**
+   ```
+   Use tool: pde_decompose
+   Arguments: { "prompt": "Analyze the current system architecture and explore potential improvements" }
+   ```
+   - [ ] Primary stage direction is EAST
+   - [ ] `directionDescription` contains "Thinking" or "Vision"
+   - [ ] Tasks include analysis-type verbs
+
+3. **Test SOUTH Alignment (Prompt B)**
+   ```
+   Use tool: pde_decompose
+   Arguments: { "prompt": "Build a new authentication module with OAuth2 support" }
+   ```
+   - [ ] Primary stage direction is SOUTH
+   - [ ] `directionDescription` contains "Planning" or "Growth"
+   - [ ] Tasks include creation-type verbs
+
+4. **Test WEST Alignment (Prompt C)**
+   ```
+   Use tool: pde_decompose
+   Arguments: { "prompt": "Test the payment gateway integration and verify all edge cases" }
+   ```
+   - [ ] Primary stage direction is WEST
+   - [ ] `directionDescription` contains "Action" or "Integration"
+   - [ ] Tasks include validation-type verbs
+
+5. **Test NORTH Alignment (Prompt D)**
+   ```
+   Use tool: pde_decompose
+   Arguments: { "prompt": "Deploy the application to production and document the release" }
+   ```
+   - [ ] Primary stage direction is NORTH
+   - [ ] `directionDescription` contains "Reflection" or "Assurance"
+   - [ ] Tasks include completion-type verbs
+
+## Success Criteria
+
+- ✅ EAST direction correctly assigned to ANALYSIS intents
+- ✅ SOUTH direction correctly assigned to CREATION intents
+- ✅ WEST direction correctly assigned to VALIDATION/INTEGRATION intents
+- ✅ NORTH direction correctly assigned to COMMUNICATION/DEPLOYMENT intents
+- ✅ Each direction has correct Indigenous metadata
+- ✅ Ceremony types match directions
+
+## Cultural Context
+
+The Medicine Wheel framework honors Indigenous epistemology:
+
+1. **EAST (Nitsáhákees)** - The place of new beginnings, where light first appears. Appropriate for exploration and vision work.
+
+2. **SOUTH (Nahat'á)** - The place of growth and warmth. Appropriate for building and implementation.
+
+3. **WEST (Iina)** - The place of integration and introspection. Appropriate for testing and reflection.
+
+4. **NORTH (Siihasin)** - The place of wisdom and completion. Appropriate for finalization and knowledge sharing.
+
+This ceremonial alignment brings intentionality and structure to AI-assisted development, honoring the natural cycles of creation.