Skip to content

LeoYeAI/agent-master-skills / skills/agent-mode-upgrades

agentic-loop-upgrade

Flagged

Enhanced agentic loop with planning, parallel execution, confidence gates, semantic error recovery, and observable state machine. Includes Mode dashboard UI for easy configuration.

src/planning/planner.ts

View on GitHub
/**
 * Planning and Reflection
 * 
 * Generates execution plans and assesses progress after actions.
 */

import type {
  TaskPlan,
  PlanStep,
  ReflectionResult,
  LLMCaller,
  ToolCall,
  ToolResult,
  PlanningConfig,
} from "../types.js";

// ============================================================================
// Plan Generation
// ============================================================================

const PLAN_GENERATION_PROMPT = `Given the user's goal, create a structured execution plan.

Goal: {goal}

Create a plan with:
1. Clear subtasks (2-7 steps, max {maxSteps})
2. Dependencies between steps (which steps must complete before others)
3. Success criteria for each step
4. Estimated complexity (low/medium/high)

Format your response as JSON:
{
  "steps": [
    {
      "id": "step_1",
      "title": "Step title",
      "action": "What to do",
      "dependencies": [],
      "successCriteria": "How to know it's done",
      "complexity": "low|medium|high"
    }
  ],
  "assumptions": ["Any assumptions made"],
  "notes": "Optional notes about the plan"
}

Be concise. Only include steps that require tool use or significant work.`;

/**
 * Check if planning is needed for this goal.
 * Creates a new plan if: no plan exists, existing plan is completed/stale,
 * or the user's goal has pivoted away from the existing plan.
 */
export function shouldGeneratePlan(
  goal: string,
  existingPlan: TaskPlan | null,
  config: PlanningConfig
): boolean {
  if (!config.enabled) return false;

  // If there's an active plan, check if the goal has pivoted.
  // A pivot = the new goal is substantially different from the existing plan's goal.
  if (existingPlan && existingPlan.status === "active") {
    if (!isGoalPivot(goal, existingPlan.goal)) {
      return false; // Same goal direction, keep existing plan
    }
    // Goal pivoted -- fall through to intent/complexity checks below
    // to decide if the new goal warrants a plan
  }

  const lowerGoal = goal.toLowerCase();

  // ═══════════════════════════════════════════════════════════════════════════
  // INTENT DETECTION - Explicit planning requests trigger immediately
  // ═══════════════════════════════════════════════════════════════════════════
  
  // Direct planning verbs (user explicitly wants a plan)
  const explicitPlanningPatterns = [
    /\bplan\b/i,                          // "plan a website", "help me plan"
    /\bplanning\b/i,                      // "I need help planning"
    /\bfigure out\b/i,                    // "figure out how to..."
    /\bhelp me\b/i,                       // "help me build...", "help me create..."
    /\bwhat('s| is) the best way\b/i,     // "what's the best way to..."
    /\bhow (should|do|can|would) (i|we)\b/i, // "how should I...", "how do I..."
    /\bwhat steps\b/i,                    // "what steps do I need..."
    /\bwalk me through\b/i,               // "walk me through..."
    /\bguide me\b/i,                      // "guide me through..."
    /\bbreak (it |this )?down\b/i,        // "break it down", "break this down"
    /\bstep.by.step\b/i,                  // "do this step by step"
    /\boutline\b/i,                       // "outline the process"
    /\bstrategy for\b/i,                  // "strategy for building..."
    /\bapproach to\b/i,                   // "best approach to..."
    /\bi need to\b/i,                     // "I need to build..."
    /\bi want to\b/i,                     // "I want to create..."
  ];

  if (explicitPlanningPatterns.some(p => p.test(goal))) {
    return true;
  }

  // ═══════════════════════════════════════════════════════════════════════════
  // TASK COMPLEXITY - Multi-step tasks that benefit from planning
  // ═══════════════════════════════════════════════════════════════════════════

  // Complex action verbs (tasks that typically require multiple steps)
  const complexVerbs = /\b(build|create|develop|implement|design|setup|set up|configure|deploy|migrate|refactor|integrate|automate|architect|establish|construct|launch|ship)\b/i;

  // Sequential/multi-part indicators
  const sequentialIndicators = [
    goal.includes(" and "),               // "X and Y"
    goal.includes(" then "),              // "X then Y"
    goal.includes(", then"),              // "X, then Y"
    /\bfirst\b.*\bthen\b/i.test(goal),    // "first... then..."
    /\bafter\b.*\b(do|create|make)\b/i.test(goal), // "after X, do Y"
  ];

  // Task nouns that typically require multi-step work
  const complexTaskNouns = /\b(api|website|site|app|application|service|system|database|server|pipeline|workflow|bot|agent|project|dashboard|interface|platform|infrastructure)\b/i;

  // Complexity indicators
  const complexityIndicators = [
    goal.length > 100,                                    // Long request
    goal.split(/[.!?]/).filter(Boolean).length > 2,       // Multiple sentences  
    complexVerbs.test(goal) && complexTaskNouns.test(goal), // Complex verb + task noun
    /\bfull\b|\bcomplete\b|\bentire\b|\bwhole\b/i.test(goal), // Scope words
    /\bproduction\b|\bprod\b/i.test(goal),                // Production deployment
    /\bfrom scratch\b/i.test(goal),                       // Starting fresh
    /\bend.to.end\b|\be2e\b/i.test(goal),                 // End-to-end
    /\bnew\b/i.test(goal) && complexVerbs.test(goal),     // "new" + complex verb
  ];

  // Count indicators
  const sequentialScore = sequentialIndicators.filter(Boolean).length;
  const complexityScore = complexityIndicators.filter(Boolean).length;
  
  // Plan if: any sequential indicator OR 1+ complexity indicators
  return sequentialScore >= 1 || complexityScore >= 1;
}

/**
 * Generate an execution plan
 */
export async function generatePlan(
  goal: string,
  context: string,
  config: PlanningConfig,
  llmCall: LLMCaller
): Promise<TaskPlan> {
  const prompt = PLAN_GENERATION_PROMPT
    .replace("{goal}", goal)
    .replace("{maxSteps}", String(config.maxPlanSteps));

  const response = await llmCall({
    messages: [
      { role: "system", content: "You are a planning assistant. Output valid JSON only." },
      { role: "user", content: `${prompt}\n\nContext:\n${context}` },
    ],
    maxTokens: 1500,
  });

  // Parse the response
  const parsed = parseJsonFromResponse(response.content);

  if (!parsed || !Array.isArray(parsed.steps)) {
    // Fallback: single-step plan
    return {
      id: generatePlanId(),
      goal,
      steps: [{
        id: "step_1",
        title: "Execute request",
        action: goal,
        dependencies: [],
        successCriteria: "Request completed successfully",
        complexity: "medium",
        status: "pending",
      }],
      assumptions: [],
      createdAt: Date.now(),
      status: "active",
    };
  }

  const steps: PlanStep[] = parsed.steps.map((s: Record<string, unknown>, i: number) => ({
    id: (s.id as string) || `step_${i + 1}`,
    title: (s.title as string) || `Step ${i + 1}`,
    action: (s.action as string) || "",
    dependencies: (s.dependencies as string[]) || [],
    successCriteria: (s.successCriteria as string) || "",
    complexity: (s.complexity as "low" | "medium" | "high") || "medium",
    status: "pending" as const,
  }));

  return {
    id: generatePlanId(),
    goal,
    steps,
    assumptions: (parsed.assumptions as string[]) || [],
    createdAt: Date.now(),
    status: "active",
  };
}

// ============================================================================
// Reflection
// ============================================================================

const REFLECTION_PROMPT = `Given your plan and the last action result, assess progress.

Plan: {plan}

Last action: {action}
Result: {result}

Answer concisely in JSON:
{
  "actionSucceeded": true|false|"partial",
  "onTrack": true|false,
  "decision": "continue"|"replan"|"escalate",
  "reason": "Brief explanation if decision is not 'continue'"
}`;

/**
 * Reflect on progress after a tool execution
 */
export async function reflect(
  plan: TaskPlan,
  lastAction: ToolCall,
  result: ToolResult,
  config: PlanningConfig,
  llmCall: LLMCaller
): Promise<ReflectionResult> {
  if (!config.reflectionAfterTools) {
    // Skip reflection, assume success
    return {
      actionSucceeded: result.success,
      onTrack: result.success,
      decision: result.success ? "continue" : "replan",
    };
  }

  const planSummary = plan.steps
    .map((s, i) => `${i + 1}. [${s.status}] ${s.title}`)
    .join("\n");

  const prompt = REFLECTION_PROMPT
    .replace("{plan}", planSummary)
    .replace("{action}", `${lastAction.name}(${JSON.stringify(lastAction.arguments)})`)
    .replace("{result}", result.error || JSON.stringify(result.output ?? "success"));

  try {
    const response = await llmCall({
      messages: [
        { role: "system", content: "You are assessing progress. Output valid JSON only." },
        { role: "user", content: prompt },
      ],
      maxTokens: 300,
    });

    const parsed = parseJsonFromResponse(response.content);

    if (!parsed) {
      return {
        actionSucceeded: result.success,
        onTrack: result.success,
        decision: result.success ? "continue" : "replan",
      };
    }

    return {
      actionSucceeded: (parsed.actionSucceeded as boolean | "partial") ?? result.success,
      onTrack: (parsed.onTrack as boolean) ?? result.success,
      decision: (parsed.decision as "continue" | "replan" | "escalate") ?? "continue",
      reason: parsed.reason as string | undefined,
    };
  } catch {
    // Reflection failed, continue anyway
    return {
      actionSucceeded: result.success,
      onTrack: result.success,
      decision: result.success ? "continue" : "replan",
    };
  }
}

// ============================================================================
// Replanning
// ============================================================================

const REPLAN_PROMPT = `The current plan needs adjustment.

Original plan:
{originalPlan}

Reason for replanning: {reason}

Current status:
- Completed: {completed}
- Remaining: {remaining}

Create a revised plan that addresses the issue. Keep completed steps, adjust remaining ones.

Output valid JSON with the same format as the original plan.`;

/**
 * Revise the plan based on reflection
 */
export async function replan(
  plan: TaskPlan,
  reason: string,
  config: PlanningConfig,
  llmCall: LLMCaller
): Promise<TaskPlan> {
  const completed = plan.steps
    .filter((s) => s.status === "complete")
    .map((s) => s.title)
    .join(", ") || "none";

  const remaining = plan.steps
    .filter((s) => s.status !== "complete")
    .map((s) => s.title)
    .join(", ") || "none";

  const originalPlan = plan.steps
    .map((s, i) => `${i + 1}. [${s.status}] ${s.title}: ${s.action}`)
    .join("\n");

  const prompt = REPLAN_PROMPT
    .replace("{originalPlan}", originalPlan)
    .replace("{reason}", reason)
    .replace("{completed}", completed)
    .replace("{remaining}", remaining);

  try {
    const response = await llmCall({
      messages: [
        { role: "system", content: "You are revising a plan. Output valid JSON only." },
        { role: "user", content: prompt },
      ],
      maxTokens: 1500,
    });

    const parsed = parseJsonFromResponse(response.content);

    if (!parsed || !Array.isArray(parsed.steps)) {
      // Keep existing plan
      return plan;
    }

    // Preserve completed steps, merge new steps
    const completedSteps = plan.steps.filter((s) => s.status === "complete");
    const newSteps: PlanStep[] = parsed.steps.map((s: Record<string, unknown>, i: number) => ({
      id: (s.id as string) || `step_${completedSteps.length + i + 1}`,
      title: (s.title as string) || `Step ${i + 1}`,
      action: (s.action as string) || "",
      dependencies: (s.dependencies as string[]) || [],
      successCriteria: (s.successCriteria as string) || "",
      complexity: (s.complexity as "low" | "medium" | "high") || "medium",
      status: "pending" as const,
    }));

    return {
      ...plan,
      steps: [...completedSteps, ...newSteps],
      createdAt: Date.now(), // Update timestamp
    };
  } catch {
    // Replanning failed, keep existing
    return plan;
  }
}

// ============================================================================
// Plan Updates
// ============================================================================

/**
 * Mark a plan step as complete
 */
export function completeStep(plan: TaskPlan, stepId: string, result?: string): TaskPlan {
  const steps = plan.steps.map((s) =>
    s.id === stepId ? { ...s, status: "complete" as const, result } : s
  );

  // Check if all steps complete
  const allComplete = steps.every((s) => s.status === "complete");

  return {
    ...plan,
    steps,
    status: allComplete ? "completed" : plan.status,
  };
}

/**
 * Mark a plan step as failed
 */
export function failStep(plan: TaskPlan, stepId: string, error: string): TaskPlan {
  const steps = plan.steps.map((s) =>
    s.id === stepId ? { ...s, status: "failed" as const, result: error } : s
  );

  return {
    ...plan,
    steps,
  };
}

/**
 * Get the next pending step
 */
export function getNextStep(plan: TaskPlan): PlanStep | null {
  // Find first pending step with no pending dependencies
  for (const step of plan.steps) {
    if (step.status !== "pending") continue;

    const depsComplete = step.dependencies.every((depId) => {
      const dep = plan.steps.find((s) => s.id === depId);
      return dep?.status === "complete";
    });

    if (depsComplete) return step;
  }

  return null;
}

/**
 * Format plan for context injection
 */
export function formatPlanForContext(plan: TaskPlan): string {
  const lines = [
    "## Execution Plan",
    "",
    `**Goal:** ${plan.goal}`,
    "",
    "### Steps",
  ];

  for (const step of plan.steps) {
    const status = step.status === "complete" ? "✓" :
                   step.status === "in_progress" ? "◐" :
                   step.status === "failed" ? "✗" : "○";
    lines.push(`${status} **${step.title}**`);
    lines.push(`  - Action: ${step.action}`);
    lines.push(`  - Success: ${step.successCriteria}`);
    if (step.result) {
      lines.push(`  - Result: ${step.result}`);
    }
  }

  if (plan.assumptions.length > 0) {
    lines.push("");
    lines.push("### Assumptions");
    for (const assumption of plan.assumptions) {
      lines.push(`- ${assumption}`);
    }
  }

  return lines.join("\n");
}

// ============================================================================
// Goal Pivot Detection
// ============================================================================

/**
 * Detect if the user's new goal has pivoted away from the existing plan's goal.
 * Uses keyword overlap: if fewer than 20% of significant words overlap,
 * the goal has likely changed. Short/conversational messages (< 20 chars)
 * are not treated as pivots to avoid replanning on follow-ups like "ok" or "yes".
 */
function isGoalPivot(newGoal: string, existingGoal: string): boolean {
  // Short follow-ups (e.g. "yes", "ok", "continue", "go ahead") aren't pivots
  if (newGoal.trim().length < 20) return false;

  const stopWords = new Set([
    "a", "an", "the", "is", "are", "was", "were", "be", "been", "being",
    "have", "has", "had", "do", "does", "did", "will", "would", "shall",
    "should", "may", "might", "must", "can", "could", "to", "of", "in",
    "for", "on", "with", "at", "by", "from", "as", "into", "through",
    "during", "before", "after", "above", "below", "between", "out",
    "off", "over", "under", "again", "further", "then", "once", "here",
    "there", "when", "where", "why", "how", "all", "both", "each",
    "few", "more", "most", "other", "some", "such", "no", "nor", "not",
    "only", "own", "same", "so", "than", "too", "very", "just", "about",
    "it", "its", "i", "me", "my", "we", "our", "you", "your", "he",
    "she", "they", "them", "this", "that", "these", "those", "and", "but",
    "or", "if", "while", "because", "until", "although", "also", "please",
    "help", "need", "want", "let", "make", "get",
  ]);

  const extractKeywords = (text: string): Set<string> => {
    const words = text.toLowerCase().replace(/[^a-z0-9\s]/g, " ").split(/\s+/);
    return new Set(words.filter((w) => w.length > 2 && !stopWords.has(w)));
  };

  const newKeywords = extractKeywords(newGoal);
  const existingKeywords = extractKeywords(existingGoal);

  if (newKeywords.size === 0 || existingKeywords.size === 0) return false;

  // Count overlap
  let overlap = 0;
  for (const word of newKeywords) {
    if (existingKeywords.has(word)) overlap++;
  }

  // If < 20% of the new goal's keywords appear in the existing plan, it's a pivot
  const overlapRatio = overlap / newKeywords.size;
  return overlapRatio < 0.2;
}

// ============================================================================
// Utilities
// ============================================================================

function generatePlanId(): string {
  return `plan_${Date.now()}_${Math.random().toString(36).slice(2, 9)}`;
}

function parseJsonFromResponse(content: string): Record<string, unknown> | null {
  try {
    // Try direct parse first
    return JSON.parse(content);
  } catch {
    // Try to extract JSON from markdown code block
    const match = content.match(/```(?:json)?\s*([\s\S]*?)\s*```/);
    if (match) {
      try {
        return JSON.parse(match[1]);
      } catch {
        return null;
      }
    }
    return null;
  }
}
brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation).Stars: 322kUpdated Claude CodeCodexVerifiedInstall
brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK).Stars: 198kUpdated Claude CodeCodexVerifiedInstall