Skip to content

Planner

The Planner converts user intents into executable Plan Drafts through a 6-stage LLM-powered pipeline.

StagePurposeLLM Call
ClassifyCategorize intent: actionable, exploratory, or ambiguousYes
ExtractExtract structured goal + parametersYes
ScoreRank capabilities by relevanceYes
ChainBackward chaining: goal → gaps → providersYes
AssembleBuild Plan Draft from chain resultNo
EnrichConvert Draft to Full Plan IRNo

The Planner produces one of three response modes:

  • GENERATE — An executable Plan Draft was produced
  • CLARIFY — The intent is ambiguous; the Planner asks a clarifying question
  • CONVERSE — The intent is non-actionable; the Planner responds conversationally
import { LLMPlanner } from '@zakardo/core';
const response = await planner.plan({
intent: { text: 'Create a new contact for Alice at Acme' },
user_context: { user_id: 'user_1', roles: ['sales_rep'] },
capabilities: registry.list(),
});
if (response.mode === 'GENERATE') {
const planDraft = response.plan_draft;
// Enrich → Validate → Execute
}

The Planner uses a 6-layer prompt system to assemble context for every LLM call. Two of these layers are developer-controlled:

LayerNameSourceEditable
1Core Prompt@zakardo/core built-inNo
2Application Contextconfig.llm.application_promptYes
3Capability ContextAuto-generated from Capability RegistryNo
4Planning Hintsconfig.llm.planning_hints + per-requestYes
5User ContextAuto-populated from requestNo
6User MessageThe intent itselfNo

The application_prompt is injected into every planner LLM call. It describes your application domain so the planner can make informed decisions:

const config: ZakardoConfig = {
// ...
llm: {
// ... providers ...
application_prompt: `
This is a CRM application for a B2B SaaS company.
Users are sales representatives, sales managers, and administrators.
Contacts belong to Accounts. Deals progress through pipeline stages.
Deals over $50,000 require manager approval.
`,
},
};

Planning hints are short rules for specific situations:

const config: ZakardoConfig = {
// ...
llm: {
// ... providers ...
planning_hints: [
'When a user asks to "close" a deal, they mean move it to Closed Won.',
'Always confirm before sending emails.',
],
},
};

Hints can also be injected per-request via planning_context.hints in the intent submission payload.

For a complete guide on writing effective prompts and hints, see Configuring the Planner.

The planner makes up to 9 distinct LLM calls, each with a call-type-specific sub-prompt:

Call TypeWhen Used
intent_classificationClassify stage
goal_extractionExtract stage
capability_scoringScore stage
alternative_evaluationChain stage (evaluating alternatives)
gap_interpretationChain stage (analyzing gaps)
plan_namingAssemble stage
clarification_compositionCLARIFY response mode
conversational_responseCONVERSE response mode
condition_generationGenerating conditional expressions

Each call type determines which additional instructions the LLM receives alongside the 6 layers.

The Planner checks the Plan Library before generating new plans. If a PROMOTED plan exists that matches the intent, it can be reused without LLM calls — reducing latency and cost.

The input to the planner pipeline:

interface PlannerRequest {
readonly intent: {
readonly text: string;
readonly type?: 'expressed' | 'structured' | 'packaged';
};
readonly user_context: {
readonly user_id: string;
readonly roles: readonly string[];
readonly tenant?: string;
};
readonly capabilities: readonly CapabilityDefinition[];
readonly conversation_history?: readonly ConversationEntry[];
readonly planning_context?: {
readonly hints?: readonly string[];
readonly data?: Record<string, unknown>;
};
readonly execution_context?: {
readonly mode?: ExecutionMode;
};
}

The output of the planner pipeline:

interface PlannerResponse {
readonly mode: 'GENERATE' | 'CLARIFY' | 'CONVERSE';
readonly plan_draft?: PlanDraft; // When mode === 'GENERATE'
readonly clarification?: ClarificationQuestion; // When mode === 'CLARIFY'
readonly message?: string; // When mode === 'CONVERSE'
readonly trace?: PlannerTrace;
}

The configuration passed to assemblePrompt() for building LLM messages:

interface PromptAssemblyConfig {
readonly call_type: string;
readonly request: PlannerRequest;
readonly application_prompt?: string;
readonly planning_hints?: readonly PlanningHint[];
readonly capabilities?: readonly CapabilityDefinition[];
readonly capability_detail?: 'full' | 'summary';
readonly additional_context?: string;
}