Design Proposal: Integrating a Prompt Decomposition Engine (PDE) into mia-code

Document Purpose: This document outlines a detailed design for integrating a Prompt Decomposition Engine (PDE) into the mia-code CLI tool. The objective is to evolve mia-code from a direct prompt-response wrapper into an intelligent, plan-driven agentic orchestrator, aligning with the principles of structured thinking and ceremonial development.

1. Analysis of Current mia-code Architecture

Based on a review of the /a/src/mia-code repository, the current architecture is as follows:

• Technology: A Node.js application written in TypeScript, using commander.js for CLI command parsing.
• Core Functionality: It serves as a user-friendly terminal interface that wraps the Gemini and Claude CLI tools in their headless modes.
• Execution Flow:
  1. The user runs mia-code chat or mia-code prompt.
  2. src/cli.ts and src/index.ts parse the command and manage the interactive session.
  3. User input is passed to the runGeminiHeadless function in src/geminiHeadless.ts.
  4. This function spawns the appropriate backend CLI (e.g., gemini) as a child process, passing the user's raw prompt and other flags.
  5. It captures and parses the stream-json or json output from the backend, optionally running it through a unifier for ceremonial interpretation.
• Limitation: The current design sends the user's prompt directly to the backend LLM. It lacks a mechanism to decompose complex, multi-step user intents, leading to potential failures, incomplete responses, or a lack of transparency for the user.

2. Proposed Architectural Vision: PDE Integration

We propose embedding the PDE directly into the mia-code CLI's command execution lifecycle. This transforms mia-code into a "thinking" client that plans its work before executing it.

High-Level Workflow:

```mermaid sequenceDiagram participant User participant MiaCodeCLI as mia-code CLI participant PDE as Prompt Decomposition Engine (API) participant Gemini as Gemini/Claude Backend

User->>+MiaCodeCLI: mia-code chat --pde "Complex multi-step request"
MiaCodeCLI->>+PDE: Decompose(request)
PDE-->>-MiaCodeCLI: Return Structured Plan (ExecutionPlan)
MiaCodeCLI->>User: Display Ceremonial Plan for Approval<br/>(EAST, SOUTH, WEST, NORTH stages)
User->>+MiaCodeCLI: "y" (approves plan)

loop For Each Step in Plan
    MiaCodeCLI->>+Gemini: Execute Step N (prompt from plan)
    Gemini-->>-MiaCodeCLI: Return Step N Result
    MiaCodeCLI->>User: Display Step N Result/Status
end

MiaCodeCLI-->>-User: Final Summary

```

3. Detailed Technical Design

This section details the specific code-level changes and additions required to implement the PDE integration.

3.1. New src/pde/ Module

A new directory will be created at /a/src/mia-code/src/pde/ to encapsulate all PDE-related logic.

• pde-types.ts: This file will define the TypeScript interfaces for the data structures exchanged with the PDE, primarily the ExecutionPlan.

  ```typescript // /a/src/mia-code/src/pde/pde-types.ts

  export type MedicineWheelDirection = "EAST" | "SOUTH" | "WEST" | "NORTH";

  export interface PdeTask { id: string; description: string; agentCommand: string; // e.g., "gemini" or "claude" prompt: string; // The specific prompt for this step expectedOutputs: string[]; dependencies: string[]; }

  export interface PdeStage { stageId: string; direction: MedicineWheelDirection; directionDescription: string; // e.g., "Vision & Inquiry" tasks: PdeTask[]; }

  export interface ExecutionPlan { workflowId: string; overallIntention: string; stages: PdeStage[]; } ```

• pde-client.ts: This client will handle communication with the PDE API. Initially, it can be a mock that returns a hardcoded plan for testing.

  ```typescript // /a/src/mia-code/src/pde/pde-client.ts import { ExecutionPlan } from "./pde-types";

  export async function decomposePrompt(prompt: string): Promise<ExecutionPlan> { // In the future, this will make an HTTP call to the PDE API // For now, return a mock plan for development console.log([PDE Client] Decomposing: "${prompt}"); // ... Mock implementation // Example: const mockPlan: ExecutionPlan = { /* ... structured plan ... */ }; return mockPlan; } ```

3.2. CLI Command Enhancements (src/cli.ts)

1. Add --pde Flag: The chat command will be updated to include a --pde flag to activate the planning workflow.

   ```typescript // in src/cli.ts, inside the 'chat' command action await runInteractiveCli({ // ... existing options usePde: opts.pde // new option }); ```

2. Add decompose Command: A new command will be added for users who only want to see the plan without executing it.

   ```typescript // in src/index.ts, add a new command program .command("decompose <text>") .description("Decompose a complex prompt into an executable plan using PDE") .action(async (text) => { const plan = await decomposePrompt(text); displayPlan(plan); // A new rendering function }); ```

3.3. Core Logic Modification (src/index.ts & a new pde-executor.ts)

The primary change will be in runInteractiveCli. It needs a new conditional path for PDE-enabled prompts.

1. Modify runInteractiveCli:

   ```typescript // in src/cli.ts // ... inside processInput function if (config.usePde) { // Assume config is updated with the flag console.log(chalk.magenta("🧬 Decomposing prompt via PDE...")); const plan = await decomposePrompt(trimmed);

   displayPlan(plan); // Render the ceremonial plan
   
   const { enquirer } = await import('enquirer');
   const { confirm } = await enquirer.prompt({
       type: 'confirm',
       name: 'confirm',
       message: 'Proceed with execution?'
   });
   
   if (confirm) {
       await executePdePlan(plan, config, rl);
   } else {
       console.log(chalk.yellow("Execution cancelled."));
   }
   

   } else { // ... existing runGeminiHeadless logic } ```

2. Create pde-executor.ts: To keep the logic clean, a new file will handle the step-by-step execution.

   ```typescript // /a/src/mia-code/src/pde-executor.ts import { ExecutionPlan, PdeStage } from "./pde/pde-types"; import { runGeminiHeadless } from "./geminiHeadless"; // ... other imports

   export async function executePdePlan(plan: ExecutionPlan, config: MiaCodeConfig, rl: Interface) { console.log("\n" + chalk.bold.green("🚀 Starting Execution...")); const context: Record<string, any> = {}; // To store results of steps

   for (const stage of plan.stages) {
       displayStageHeader(stage);
       for (const task of stage.tasks) {
           // ... logic to check if dependencies are met from `context`
           
           console.log(chalk.dim(`  - Executing task: ${task.description}`));
           const result = await runGeminiHeadless({
               prompt: task.prompt,
               config,
               // Session management needs to be adapted for multi-step execution
           });
   
           // Store result in context for dependent tasks
           context[task.id] = result; 
           
           // ... render task result
       }
   }
   console.log("\n" + chalk.bold.green("✅ Plan execution complete."));
   

   } ```

3.4. Ceremonial UI Integration (src/formatting.ts)

New functions will be added to render the plan in a way that reflects its ceremonial structure.

```typescript // /a/src/mia-code/src/formatting.ts

const directionColors = { EAST: chalk.hex('#FFD700'), // Gold for Vision SOUTH: chalk.hex('#32CD32'), // Green for Growth WEST: chalk.hex('#4682B4'), // SteelBlue for Integration NORTH: chalk.hex('#FFFFFF') // White for Wisdom };

export function displayPlan(plan: ExecutionPlan) { console.log(\n${chalk.bold.magenta('🧬 Decomposed Plan:')} ${plan.overallIntention}); for (const stage of plan.stages) { const color = directionColors[stage.direction] || chalk.white; console.log(color(\n${stage.direction}: ${stage.directionDescription})); for (const task of stage.tasks) { console.log(chalk.dim( - [ ] ${task.description})); if (task.dependencies.length > 0) { console.log(chalk.dim( (depends on: ${task.dependencies.join(', ')}))); } } } console.log(""); } ```

4. Phased Implementation Roadmap

1. Phase 1: Foundation & Mocking

   • Implement the pde/ directory with types and a mocked pde-client.
   • Implement the UI rendering functions in formatting.ts.
   • Add the decompose command to cli.ts to test the plan rendering.

2. Phase 2: Core Execution Logic

   • Add the --pde flag and the conditional logic in cli.ts.
   • Implement the pde-executor.ts file with the core loop for step-by-step execution.
   • Adapt session handling in geminiHeadless.ts to work across multiple calls within a single plan.

3. Phase 3: Live Integration & Refinement

   • Replace the mocked pde-client with a real HTTP client to call the live PDE API.
   • Implement robust error handling, dependency management, and state tracking in the pde-executor.
   • Conduct user testing to refine the CLI's interactive experience for plan approval and execution feedback.

5. Conclusion

Integrating the Prompt Decomposition Engine into mia-code represents a significant architectural evolution. It elevates the tool from a simple command-line wrapper to a sophisticated agentic assistant that brings transparency, control, and resilience to complex development tasks. By grounding this technical design in the project's ceremonial philosophy, we create a tool that is not only more powerful but also more intuitive and aligned with its intended purpose.