Planner
The Planner converts user intents into executable Plan Drafts through a 6-stage LLM-powered pipeline.
Pipeline Stages
Section titled “Pipeline Stages”| Stage | Purpose | LLM Call |
|---|---|---|
| Classify | Categorize intent: actionable, exploratory, or ambiguous | Yes |
| Extract | Extract structured goal + parameters | Yes |
| Score | Rank capabilities by relevance | Yes |
| Chain | Backward chaining: goal → gaps → providers | Yes |
| Assemble | Build Plan Draft from chain result | No |
| Enrich | Convert Draft to Full Plan IR | No |
Response Modes
Section titled “Response Modes”The Planner produces one of three response modes:
GENERATE— An executable Plan Draft was producedCLARIFY— The intent is ambiguous; the Planner asks a clarifying questionCONVERSE— 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}Prompt Architecture
Section titled “Prompt Architecture”The Planner uses a 6-layer prompt system to assemble context for every LLM call. Two of these layers are developer-controlled:
| Layer | Name | Source | Editable |
|---|---|---|---|
| 1 | Core Prompt | @zakardo/core built-in | No |
| 2 | Application Context | config.llm.application_prompt | Yes |
| 3 | Capability Context | Auto-generated from Capability Registry | No |
| 4 | Planning Hints | config.llm.planning_hints + per-request | Yes |
| 5 | User Context | Auto-populated from request | No |
| 6 | User Message | The intent itself | No |
Configuring Layer 2: Application Prompt
Section titled “Configuring Layer 2: Application Prompt”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. `, },};Configuring Layer 4: Planning Hints
Section titled “Configuring Layer 4: Planning Hints”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.
LLM Call Types
Section titled “LLM Call Types”The planner makes up to 9 distinct LLM calls, each with a call-type-specific sub-prompt:
| Call Type | When Used |
|---|---|
intent_classification | Classify stage |
goal_extraction | Extract stage |
capability_scoring | Score stage |
alternative_evaluation | Chain stage (evaluating alternatives) |
gap_interpretation | Chain stage (analyzing gaps) |
plan_naming | Assemble stage |
clarification_composition | CLARIFY response mode |
conversational_response | CONVERSE response mode |
condition_generation | Generating conditional expressions |
Each call type determines which additional instructions the LLM receives alongside the 6 layers.
Plan Library Integration
Section titled “Plan Library Integration”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.
Key Types
Section titled “Key Types”PlannerRequest
Section titled “PlannerRequest”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; };}PlannerResponse
Section titled “PlannerResponse”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;}PromptAssemblyConfig
Section titled “PromptAssemblyConfig”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;}Further Reading
Section titled “Further Reading”- Configuring the Planner — complete guide to writing effective prompts and hints
- Plan Library — plan reuse and trust lifecycle
- Planner Specification — full technical specification