@feelingmindful/thinking-graph 1.10.0 → 1.11.0

package/dist/index.js

@@ -12,6 +12,10 @@ import { learnSchema, learnHandler } from './tools/learn.js';
 import { exportSchema, exportHandler } from './tools/export.js';
 import { researchSchema, researchHandler } from './tools/research.js';
 import { recommendSkillsSchema, recommendSkillsHandler } from './tools/recommend-skills.js';
+import { routeSkillsSchema, routeSkillsHandler } from './tools/route-skills.js';
+import { planSkillsSchema, planSkillsHandler } from './tools/plan-skills.js';
+import { executePlanSchema, executePlanHandler } from './tools/execute-plan.js';
+import { executeSkillsSchema, executeSkillsHandler } from './tools/execute-skills.js';
 // Legacy compat shim removed — use `think` tool directly
 // ─── Storage setup ───────────────────────────────────────
 const memoryOnly = process.env.THINKING_GRAPH_MEMORY_ONLY === 'true';
@@ -49,6 +53,10 @@ server.tool('learn', 'Store durable knowledge — code facts, tech debt, insight
 server.tool('export', 'Export the thinking graph as JSON or a human-readable markdown summary.', exportSchema.shape, async (input) => exportHandler(graph, input));
 server.tool('research', 'Research a topic using Perplexity/Firecrawl, then ingest findings into the graph and Obsidian vault. Two-phase: call once to get an action plan, then again with findings to store them.', researchSchema.shape, async (input) => researchHandler(graph, input, vault, projectSlug));
 server.tool('recommend-skills', 'Recommend installed marketplace skills by area, verb, platform, or what they produce/detect. Use during reasoning to find skills that can help with the current task.', recommendSkillsSchema.shape, async (input) => recommendSkillsHandler(graph, input));
+server.tool('route-skills', 'Shortlist and rank installed skills for a task using routing heuristics based on platform, verb, areas, detections, and graph context.', routeSkillsSchema.shape, async (input) => routeSkillsHandler(graph, input));
+server.tool('plan-skills', 'Convert a request into an ordered skill execution plan with explicit approval gates before execution. This tool plans but does not execute skills.', planSkillsSchema.shape, async (input) => planSkillsHandler(graph, input));
+server.tool('execute-plan', 'Start or resume a planned workflow run: persist plan state, create/select a runId, enforce approval gates, and return the next runnable step. If multiple runs exist, use availableRunIds to choose the right one.', executePlanSchema.shape, async (input) => executePlanHandler(graph, input));
+server.tool('execute-skills', 'Record the outcome of a planned skill step for a specific executionId/runId, including skill_result, decision, and tech_debt nodes linked back to that run.', executeSkillsSchema.shape, async (input) => executeSkillsHandler(graph, input, vault, projectSlug));
 // ─── Startup ─────────────────────────────────────────────
 async function main() {
     await storage.initialize();

package/dist/tools/execute-plan.d.ts

@@ -0,0 +1,195 @@
+import { z } from 'zod';
+import type { ThinkingGraph } from '../engine/graph.js';
+import type { Node, Session } from '../engine/types.js';
+import { type ApprovalGate, type SkillPlanStep } from './skill-routing.js';
+export declare const skillPlanStepSchema: z.ZodObject<{
+    stepNumber: z.ZodNumber;
+    invocation: z.ZodString;
+    plugin: z.ZodString;
+    skill: z.ZodString;
+    verb: z.ZodOptional<z.ZodString>;
+    purpose: z.ZodString;
+    approvalGateIds: z.ZodArray<z.ZodString, "many">;
+}, "strip", z.ZodTypeAny, {
+    invocation: string;
+    skill: string;
+    stepNumber: number;
+    plugin: string;
+    purpose: string;
+    approvalGateIds: string[];
+    verb?: string | undefined;
+}, {
+    invocation: string;
+    skill: string;
+    stepNumber: number;
+    plugin: string;
+    purpose: string;
+    approvalGateIds: string[];
+    verb?: string | undefined;
+}>;
+export declare const approvalGateSchema: z.ZodObject<{
+    id: z.ZodString;
+    title: z.ZodString;
+    beforeStepNumber: z.ZodNumber;
+    reason: z.ZodString;
+    prompt: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    id: string;
+    title: string;
+    beforeStepNumber: number;
+    reason: string;
+    prompt: string;
+}, {
+    id: string;
+    title: string;
+    beforeStepNumber: number;
+    reason: string;
+    prompt: string;
+}>;
+export declare const executePlanSchema: z.ZodObject<{
+    planId: z.ZodOptional<z.ZodString>;
+    runId: z.ZodOptional<z.ZodString>;
+    request: z.ZodOptional<z.ZodString>;
+    plan: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        stepNumber: z.ZodNumber;
+        invocation: z.ZodString;
+        plugin: z.ZodString;
+        skill: z.ZodString;
+        verb: z.ZodOptional<z.ZodString>;
+        purpose: z.ZodString;
+        approvalGateIds: z.ZodArray<z.ZodString, "many">;
+    }, "strip", z.ZodTypeAny, {
+        invocation: string;
+        skill: string;
+        stepNumber: number;
+        plugin: string;
+        purpose: string;
+        approvalGateIds: string[];
+        verb?: string | undefined;
+    }, {
+        invocation: string;
+        skill: string;
+        stepNumber: number;
+        plugin: string;
+        purpose: string;
+        approvalGateIds: string[];
+        verb?: string | undefined;
+    }>, "many">>;
+    approvalGates: z.ZodDefault<z.ZodOptional<z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        title: z.ZodString;
+        beforeStepNumber: z.ZodNumber;
+        reason: z.ZodString;
+        prompt: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        id: string;
+        title: string;
+        beforeStepNumber: number;
+        reason: string;
+        prompt: string;
+    }, {
+        id: string;
+        title: string;
+        beforeStepNumber: number;
+        reason: string;
+        prompt: string;
+    }>, "many">>>;
+    approvedGateIds: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    sessionId: z.ZodOptional<z.ZodString>;
+    projectId: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    approvalGates: {
+        id: string;
+        title: string;
+        beforeStepNumber: number;
+        reason: string;
+        prompt: string;
+    }[];
+    sessionId?: string | undefined;
+    projectId?: string | undefined;
+    plan?: {
+        invocation: string;
+        skill: string;
+        stepNumber: number;
+        plugin: string;
+        purpose: string;
+        approvalGateIds: string[];
+        verb?: string | undefined;
+    }[] | undefined;
+    request?: string | undefined;
+    planId?: string | undefined;
+    runId?: string | undefined;
+    approvedGateIds?: string[] | undefined;
+}, {
+    sessionId?: string | undefined;
+    projectId?: string | undefined;
+    plan?: {
+        invocation: string;
+        skill: string;
+        stepNumber: number;
+        plugin: string;
+        purpose: string;
+        approvalGateIds: string[];
+        verb?: string | undefined;
+    }[] | undefined;
+    approvalGates?: {
+        id: string;
+        title: string;
+        beforeStepNumber: number;
+        reason: string;
+        prompt: string;
+    }[] | undefined;
+    request?: string | undefined;
+    planId?: string | undefined;
+    runId?: string | undefined;
+    approvedGateIds?: string[] | undefined;
+}>;
+export type ExecutePlanInput = z.infer<typeof executePlanSchema>;
+export interface StoredPlan {
+    nodeId: string;
+    planId: string;
+    request?: string;
+    plan: SkillPlanStep[];
+    approvalGates: ApprovalGate[];
+}
+export interface ExecutionProgress {
+    approvedGateIds: Set<string>;
+    stepResults: Map<number, Node>;
+    completedSteps: number[];
+    failedStep: {
+        stepNumber: number;
+        node: Node;
+    } | null;
+    nextStep: SkillPlanStep | null;
+    blockingGate: ApprovalGate | null;
+}
+export interface StoredExecutionInstance {
+    nodeId: string;
+    executionId: string;
+    planId: string;
+    runId: string;
+    legacy?: boolean;
+}
+export declare function parseExecutionId(executionId: string): {
+    projectScope: string;
+    planId: string;
+    runId: string;
+} | null;
+export declare function findStoredPlan(graph: ThinkingGraph, _sessionId: string, projectId: string | undefined, planId: string): Promise<StoredPlan | null>;
+export declare function buildExecutionId(planId: string, projectId?: string): string;
+export declare function buildExecutionInstanceId(planId: string, projectId: string | undefined, runId?: string): string;
+export declare function findExecutionInstances(graph: ThinkingGraph, projectId: string | undefined, planId: string): Promise<StoredExecutionInstance[]>;
+export declare function resolveExecutionInstance(graph: ThinkingGraph, session: Session, projectId: string | undefined, storedPlan: StoredPlan, requestedRunId?: string): Promise<{
+    instance?: StoredExecutionInstance;
+    error?: string;
+    availableRunIds?: string[];
+}>;
+export declare function getApprovedGateIds(graph: ThinkingGraph, _sessionId: string, projectId: string | undefined, executionId: string): Promise<Set<string>>;
+export declare function getExecutionResults(graph: ThinkingGraph, _sessionId: string, projectId: string | undefined, executionId: string): Promise<Map<number, Node>>;
+export declare function resolveExecutionProgress(graph: ThinkingGraph, sessionId: string, projectId: string | undefined, storedPlan: StoredPlan, executionId: string): Promise<ExecutionProgress>;
+export declare function executePlanHandler(graph: ThinkingGraph, input: ExecutePlanInput): Promise<{
+    content: {
+        type: "text";
+        text: string;
+    }[];
+}>;

package/dist/tools/execute-plan.js

@@ -0,0 +1,416 @@
+import { z } from 'zod';
+import { buildPlanId } from './skill-routing.js';
+export const skillPlanStepSchema = z.object({
+    stepNumber: z.coerce.number().int().min(1),
+    invocation: z.string(),
+    plugin: z.string(),
+    skill: z.string(),
+    verb: z.string().optional(),
+    purpose: z.string(),
+    approvalGateIds: z.array(z.string()),
+});
+export const approvalGateSchema = z.object({
+    id: z.string(),
+    title: z.string(),
+    beforeStepNumber: z.coerce.number().int().min(1),
+    reason: z.string(),
+    prompt: z.string(),
+});
+export const executePlanSchema = z.object({
+    planId: z.string().optional().describe('Stable ID returned by plan-skills'),
+    runId: z.string().optional().describe('Execution instance ID for this plan within the project. Provide a stable runId when starting parallel runs, and reuse a value from availableRunIds when resuming an ambiguous execution.'),
+    request: z.string().optional().describe('Original request used to create the plan'),
+    plan: z.array(skillPlanStepSchema).optional().describe('Ordered plan to execute; required the first time unless the plan was already stored'),
+    approvalGates: z.array(approvalGateSchema).optional().default([]),
+    approvedGateIds: z.array(z.string()).optional().describe('Gate IDs newly approved on this call for the selected run'),
+    sessionId: z.string().optional(),
+    projectId: z.string().optional(),
+});
+function asRecord(value) {
+    return value && typeof value === 'object' ? value : {};
+}
+function normalizeProjectScope(projectId) {
+    return projectId && projectId.trim().length > 0 ? projectId : 'global';
+}
+function normalizeRunId(runId) {
+    return runId && runId.trim().length > 0 ? runId.trim() : 'run-1';
+}
+function parseStoredPlan(node) {
+    const metadata = asRecord(node.metadata);
+    if (metadata.kind !== 'execution_plan' || typeof metadata.planId !== 'string')
+        return null;
+    if (!Array.isArray(metadata.plan) || !Array.isArray(metadata.approvalGates))
+        return null;
+    return {
+        nodeId: node.id,
+        planId: metadata.planId,
+        request: typeof metadata.request === 'string' ? metadata.request : undefined,
+        plan: metadata.plan,
+        approvalGates: metadata.approvalGates,
+    };
+}
+async function resolveSession(graph, sessionId, projectId) {
+    if (!sessionId)
+        return graph.getCurrentSession();
+    return (await graph.storage.getSession(sessionId)) ?? graph.createSession({ id: sessionId, projectId });
+}
+function parseStoredExecutionInstance(node) {
+    const metadata = asRecord(node.metadata);
+    if (metadata.kind !== 'execution_instance')
+        return null;
+    if (typeof metadata.executionId !== 'string' || typeof metadata.planId !== 'string' || typeof metadata.runId !== 'string') {
+        return null;
+    }
+    return {
+        nodeId: node.id,
+        executionId: metadata.executionId,
+        planId: metadata.planId,
+        runId: metadata.runId,
+    };
+}
+export function parseExecutionId(executionId) {
+    const prefix = 'execution:';
+    if (!executionId.startsWith(prefix))
+        return null;
+    const remainder = executionId.slice(prefix.length);
+    const parts = remainder.split(':');
+    if (parts.length === 2) {
+        return {
+            projectScope: parts[0],
+            planId: parts[1],
+            runId: 'run-1',
+        };
+    }
+    if (parts.length >= 3) {
+        return {
+            projectScope: parts[0],
+            planId: parts[1],
+            runId: parts.slice(2).join(':'),
+        };
+    }
+    return null;
+}
+export async function findStoredPlan(graph, _sessionId, projectId, planId) {
+    const result = await graph.findNodes({ type: 'decision', projectId, limit: 500 });
+    for (const node of result.items) {
+        const stored = parseStoredPlan(node);
+        if (stored?.planId === planId)
+            return stored;
+    }
+    return null;
+}
+async function ensurePlanStored(graph, session, projectId, storedPlan) {
+    const existing = await findStoredPlan(graph, session.id, projectId, storedPlan.planId);
+    if (existing)
+        return existing;
+    const node = await graph.addNode({
+        type: 'decision',
+        content: storedPlan.request
+            ? `Execution plan selected for ${storedPlan.request}`
+            : `Execution plan ${storedPlan.planId}`,
+        sessionId: session.id,
+        projectId,
+        metadata: {
+            kind: 'execution_plan',
+            planId: storedPlan.planId,
+            request: storedPlan.request,
+            plan: storedPlan.plan,
+            approvalGates: storedPlan.approvalGates,
+        },
+    });
+    return { ...storedPlan, nodeId: node.id };
+}
+export function buildExecutionId(planId, projectId) {
+    return `execution:${normalizeProjectScope(projectId)}:${planId}:${normalizeRunId(undefined)}`;
+}
+export function buildExecutionInstanceId(planId, projectId, runId) {
+    return `execution:${normalizeProjectScope(projectId)}:${planId}:${normalizeRunId(runId)}`;
+}
+function buildLegacyExecutionId(planId, projectId) {
+    return `execution:${normalizeProjectScope(projectId)}:${planId}`;
+}
+export async function findExecutionInstances(graph, projectId, planId) {
+    const result = await graph.findNodes({ type: 'decision', projectId, limit: 1000 });
+    const instances = result.items
+        .map(parseStoredExecutionInstance)
+        .filter((instance) => Boolean(instance && instance.planId === planId));
+    const legacyExecutionId = buildLegacyExecutionId(planId, projectId);
+    const [approvedGateIds, stepResults] = await Promise.all([
+        getApprovedGateIds(graph, '', projectId, legacyExecutionId),
+        getExecutionResults(graph, '', projectId, legacyExecutionId),
+    ]);
+    if (approvedGateIds.size > 0 || stepResults.size > 0) {
+        const hasExplicitRunOne = instances.some(instance => instance.runId === 'run-1');
+        if (!hasExplicitRunOne) {
+            instances.push({
+                nodeId: '',
+                executionId: legacyExecutionId,
+                planId,
+                runId: 'run-1',
+                legacy: true,
+            });
+        }
+    }
+    return instances.sort((a, b) => a.runId.localeCompare(b.runId));
+}
+async function ensureExecutionInstanceStored(graph, session, projectId, storedPlan, runId) {
+    const existing = (await findExecutionInstances(graph, projectId, storedPlan.planId))
+        .find(instance => instance.runId === runId);
+    if (existing)
+        return existing;
+    const executionId = buildExecutionInstanceId(storedPlan.planId, projectId, runId);
+    const node = await graph.addNode({
+        type: 'decision',
+        content: `Execution instance ${runId} for ${storedPlan.planId}`,
+        sessionId: session.id,
+        projectId,
+        metadata: {
+            kind: 'execution_instance',
+            executionId,
+            planId: storedPlan.planId,
+            runId,
+        },
+    });
+    await graph.addEdge({
+        sourceId: node.id,
+        targetId: storedPlan.nodeId,
+        type: 'supports',
+        reasoning: 'Execution instance created for this stored plan.',
+    });
+    return {
+        nodeId: node.id,
+        executionId,
+        planId: storedPlan.planId,
+        runId,
+    };
+}
+export async function resolveExecutionInstance(graph, session, projectId, storedPlan, requestedRunId) {
+    const instances = await findExecutionInstances(graph, projectId, storedPlan.planId);
+    if (requestedRunId) {
+        const runId = normalizeRunId(requestedRunId);
+        const existing = instances.find(instance => instance.runId === runId);
+        if (existing)
+            return { instance: existing };
+        return { instance: await ensureExecutionInstanceStored(graph, session, projectId, storedPlan, runId) };
+    }
+    if (instances.length === 0) {
+        return { instance: await ensureExecutionInstanceStored(graph, session, projectId, storedPlan, 'run-1') };
+    }
+    if (instances.length === 1) {
+        return { instance: instances[0] };
+    }
+    return {
+        error: `Multiple execution instances exist for ${storedPlan.planId}. Specify runId to continue and reuse one of availableRunIds when resuming.`,
+        availableRunIds: instances.map(instance => instance.runId).sort(),
+    };
+}
+export async function getApprovedGateIds(graph, _sessionId, projectId, executionId) {
+    const result = await graph.findNodes({ type: 'decision', projectId, limit: 500 });
+    const approved = new Set();
+    for (const node of result.items) {
+        const metadata = asRecord(node.metadata);
+        if (metadata.kind === 'approval_gate' && metadata.executionId === executionId && typeof metadata.gateId === 'string') {
+            approved.add(metadata.gateId);
+        }
+    }
+    return approved;
+}
+async function recordApprovals(graph, session, projectId, executionId, plan, gateIds) {
+    if (gateIds.length === 0)
+        return;
+    const existing = await getApprovedGateIds(graph, session.id, projectId, executionId);
+    for (const gateId of gateIds) {
+        if (existing.has(gateId))
+            continue;
+        const gate = plan.approvalGates.find(candidate => candidate.id === gateId);
+        if (!gate)
+            continue;
+        const approval = await graph.addNode({
+            type: 'decision',
+            content: `Approved gate ${gate.title} before step ${gate.beforeStepNumber}`,
+            sessionId: session.id,
+            projectId,
+            metadata: {
+                kind: 'approval_gate',
+                executionId,
+                planId: plan.planId,
+                gateId: gate.id,
+                beforeStepNumber: gate.beforeStepNumber,
+            },
+        });
+        await graph.addEdge({
+            sourceId: approval.id,
+            targetId: plan.nodeId,
+            type: 'supports',
+            reasoning: 'Approval recorded for this execution plan.',
+        });
+    }
+}
+export async function getExecutionResults(graph, _sessionId, projectId, executionId) {
+    const result = await graph.findNodes({ type: 'skill_result', projectId, limit: 1000 });
+    const relevant = result.items
+        .filter(node => asRecord(node.metadata).executionId === executionId)
+        .sort((a, b) => b.createdAt.localeCompare(a.createdAt));
+    const latestByStep = new Map();
+    for (const node of relevant) {
+        const stepNumber = asRecord(node.metadata).stepNumber;
+        if (typeof stepNumber === 'number' && !latestByStep.has(stepNumber))
+            latestByStep.set(stepNumber, node);
+    }
+    return latestByStep;
+}
+export async function resolveExecutionProgress(graph, sessionId, projectId, storedPlan, executionId) {
+    const approvedGateIds = await getApprovedGateIds(graph, sessionId, projectId, executionId);
+    const stepResults = await getExecutionResults(graph, sessionId, projectId, executionId);
+    const completedSteps = [...stepResults.entries()]
+        .filter(([, node]) => asRecord(node.metadata).status === 'completed')
+        .map(([stepNumber]) => stepNumber)
+        .sort((a, b) => a - b);
+    const failedEntry = [...stepResults.entries()]
+        .find(([, node]) => asRecord(node.metadata).status === 'failed');
+    const failedStep = failedEntry
+        ? { stepNumber: failedEntry[0], node: failedEntry[1] }
+        : null;
+    const nextStep = storedPlan.plan.find(step => !completedSteps.includes(step.stepNumber)) ?? null;
+    const blockingGate = nextStep
+        ? storedPlan.approvalGates.find(gate => gate.beforeStepNumber === nextStep.stepNumber && !approvedGateIds.has(gate.id)) ?? null
+        : null;
+    return {
+        approvedGateIds,
+        stepResults,
+        completedSteps,
+        failedStep,
+        nextStep,
+        blockingGate,
+    };
+}
+export async function executePlanHandler(graph, input) {
+    const session = await resolveSession(graph, input.sessionId, input.projectId);
+    const explicitPlanId = input.planId ?? (input.plan ? buildPlanId({
+        request: input.request,
+        plan: input.plan,
+        approvalGates: (input.approvalGates ?? []),
+    }) : undefined);
+    if (!explicitPlanId) {
+        return { content: [{ type: 'text', text: JSON.stringify({ status: 'error', error: 'planId or plan is required' }) }] };
+    }
+    const suppliedPlan = input.plan
+        ? {
+            nodeId: '',
+            planId: explicitPlanId,
+            request: input.request,
+            plan: input.plan,
+            approvalGates: (input.approvalGates ?? []),
+        }
+        : await findStoredPlan(graph, session.id, input.projectId, explicitPlanId);
+    if (!suppliedPlan) {
+        return { content: [{ type: 'text', text: JSON.stringify({ status: 'error', error: `No stored plan found for ${explicitPlanId}. Provide the plan structure.` }) }] };
+    }
+    const storedPlan = await ensurePlanStored(graph, session, input.projectId, suppliedPlan);
+    const executionInstance = await resolveExecutionInstance(graph, session, input.projectId, storedPlan, input.runId);
+    if (!executionInstance.instance) {
+        return {
+            content: [{
+                    type: 'text',
+                    text: JSON.stringify({
+                        status: 'error',
+                        planId: storedPlan.planId,
+                        error: executionInstance.error,
+                        availableRunIds: executionInstance.availableRunIds ?? [],
+                    }),
+                }],
+        };
+    }
+    const { executionId, runId } = executionInstance.instance;
+    await recordApprovals(graph, session, input.projectId, executionId, storedPlan, input.approvedGateIds ?? []);
+    const progress = await resolveExecutionProgress(graph, session.id, input.projectId, storedPlan, executionId);
+    if (progress.failedStep) {
+        const { stepNumber, node } = progress.failedStep;
+        return {
+            content: [{
+                    type: 'text',
+                    text: JSON.stringify({
+                        status: 'failed',
+                        planId: storedPlan.planId,
+                        executionId,
+                        runId,
+                        approvedGateIds: [...progress.approvedGateIds],
+                        completedSteps: progress.completedSteps,
+                        failedStep: {
+                            stepNumber,
+                            invocation: asRecord(node.metadata).invocation,
+                            summary: node.content,
+                        },
+                        nextAction: `Investigate step ${stepNumber} and record a successful retry with execute-skills before continuing.`,
+                    }),
+                }],
+        };
+    }
+    if (!progress.nextStep) {
+        return {
+            content: [{
+                    type: 'text',
+                    text: JSON.stringify({
+                        status: 'completed',
+                        planId: storedPlan.planId,
+                        executionId,
+                        runId,
+                        approvedGateIds: [...progress.approvedGateIds],
+                        completedSteps: progress.completedSteps,
+                        nextStep: null,
+                        nextAction: 'Execution is complete.',
+                    }),
+                }],
+        };
+    }
+    if (progress.blockingGate) {
+        return {
+            content: [{
+                    type: 'text',
+                    text: JSON.stringify({
+                        status: 'awaiting_approval',
+                        planId: storedPlan.planId,
+                        executionId,
+                        runId,
+                        approvedGateIds: [...progress.approvedGateIds],
+                        completedSteps: progress.completedSteps,
+                        blockedByGate: progress.blockingGate,
+                        nextStep: progress.nextStep,
+                        nextAction: `Approve ${progress.blockingGate.id} and rerun execute-plan with runId ${runId} to continue at step ${progress.nextStep.stepNumber}.`,
+                    }),
+                }],
+        };
+    }
+    return {
+        content: [{
+                type: 'text',
+                text: JSON.stringify({
+                    status: 'ready_to_execute',
+                    planId: storedPlan.planId,
+                    executionId,
+                    runId,
+                    approvedGateIds: [...progress.approvedGateIds],
+                    completedSteps: progress.completedSteps,
+                    nextStep: progress.nextStep,
+                    executeSkillCall: {
+                        tool: 'execute-skills',
+                        args: {
+                            executionId,
+                            planId: storedPlan.planId,
+                            runId,
+                            stepNumber: progress.nextStep.stepNumber,
+                            invocation: progress.nextStep.invocation,
+                            plugin: progress.nextStep.plugin,
+                            skill: progress.nextStep.skill,
+                            purpose: progress.nextStep.purpose,
+                            resultSummary: '<summarize what the step produced>',
+                            status: 'completed',
+                            decisions: [{ content: '<decision extracted from the skill output>' }],
+                            techDebt: [{ content: '<tech debt or follow-up surfaced by the step>' }],
+                        },
+                    },
+                    nextAction: `Invoke ${progress.nextStep.invocation}, then record the result with execute-skills using executionId ${executionId} (runId ${runId}).`,
+                }),
+            }],
+    };
+}