Planner
The Planner is the reasoning component that resolves Intents into Plan Drafts, Clarifications, or Conversational Responses. It is the system’s “brain” — the only component that performs non-deterministic reasoning (via LLM or other strategy). This specification defines its interface, internal pipeline, LLM integration model, and operational behavior.
1. Design Goals
Section titled “1. Design Goals”- Produce executable plans. Every Plan Draft the Planner generates must be executable by the current user. Plans always succeed.
- Be policy-aware from the start. The Planner checks both system-level policy and capability-level constraints before selecting any capability. Policy denial is handled during generation, not after.
- Fall back gracefully. If the Planner cannot produce a plan, it either asks for clarification or explains why. It never fails silently or produces a plan it knows will be rejected.
- Be pluggable. The Planner is a defined interface. The default implementation uses an LLM, but it can be replaced with a rule-based matcher, a remote service, or any other strategy.
- Be stateless. The Planner does not maintain state between invocations. All context it needs (intent, user, capabilities, policies, plan library) is provided per request.
- Be inspectable. Every decision the Planner makes is recorded in a Planner Trace — a structured log of the reasoning process that feeds into the system-wide Trace.
2. Planner Interface
Section titled “2. Planner Interface”2.1 Input Contract
Section titled “2.1 Input Contract”The Planner receives a PlannerRequest:
interface PlannerRequest { intent: Intent; user_context: UserContext; conversation_history?: ConversationTurn[]; // For multi-turn clarification planning_context?: { hints?: string[]; // Per-request planning hints data?: Record<string, any>; // Additional data for gap resolution }; execution_context?: { environment: string; // 'production', 'staging', 'development' default_execution_mode: ExecutionMode; };}
interface Intent { raw_text?: string; // Natural language (expressed intent) structured?: { // Pre-parsed (packaged or structured intent) action: string; parameters: Record<string, any>; }; source: 'expressed' | 'packaged' | 'structured';}
interface UserContext { user_id: string; tenant_id?: string; roles: string[];}
interface ConversationTurn { role: 'user' | 'planner'; content: string; clarification_id?: string; // Links to a prior CLARIFY response}2.2 Output Contract
Section titled “2.2 Output Contract”The Planner returns a PlannerResponse — exactly one of three modes:
type PlannerResponse = PlannerGenerateResponse | PlannerClarifyResponse | PlannerConverseResponse;
interface PlannerGenerateResponse { mode: 'GENERATE'; plan_draft: PlanDraft; // As defined in Plan IR Specification, Section 2 planner_trace: PlannerTrace; // Reasoning log confidence: number; // 0.0 to 1.0 goal_summary: string; // Human-readable: "Submit a deletion request for customer ABC-123" goal_adjusted: boolean; // True if the goal was changed from the original intent (e.g., due to policy) original_goal?: string; // If adjusted, what the user originally wanted adjusted_reason?: string; // Why the goal was adjusted}
interface PlannerClarifyResponse { mode: 'CLARIFY'; clarification_id: string; // Unique ID for this clarification round question: string; // Human-readable question options?: ClarificationOption[]; // Structured options (if applicable) context: string; // Why this clarification is needed planner_trace: PlannerTrace;}
interface ClarificationOption { id: string; label: string; // Human-readable description?: string; intent_refinement: Partial<Intent>; // How selecting this option refines the intent}
interface PlannerConverseResponse { mode: 'CONVERSE'; message: string; // Human-readable response suggestions?: string[]; // Suggested follow-up intents reason: ConverseReason; planner_trace: PlannerTrace;}
type ConverseReason = | 'not_actionable' // Intent is exploratory, advisory, or conversational | 'no_matching_capability' // No capability matches the goal | 'policy_blocked' // All paths blocked by policy, no alternatives | 'capability_unavailable' // Capability exists but is disabled/quarantined | 'out_of_scope'; // Intent is outside the application's domain2.3 Dependencies
Section titled “2.3 Dependencies”The Planner reads from (but does not write to) the following:
| Dependency | Interface | What the Planner Reads |
|---|---|---|
| Capability Registry | Query API | Capability definitions: name, description, input/output schemas, effect class, boundary, tags, constraints, alternatives |
| Plan Library | Search API | Existing validated plans: plan name, intent patterns, input schema, lifecycle state, trust score |
| Policy Engine | Pre-generation check API | ALLOWED/DENIED for a given capability + user context |
| LLM Provider | Chat completion API | Reasoning, scoring, intent parsing (default Planner only) |
The Planner does not access:
- The Execution Engine (it does not execute anything)
- The Trace Store (it produces traces, but does not read them)
- Service Providers / business data (it has no access to application data)
3. Planner Pipeline
Section titled “3. Planner Pipeline”The Planner processes each request through a sequential pipeline. Each stage may terminate the pipeline early by returning a CLARIFY or CONVERSE response.
3.1 Pipeline Stages
Section titled “3.1 Pipeline Stages”Stage 1: INTENT CLASSIFICATION Determine if the intent is actionable, exploratory, or ambiguous. → Not actionable: return CONVERSE → Ambiguous: return CLARIFY → Actionable: proceed
Stage 2: PLAN LIBRARY SEARCH Search for an existing promoted plan that matches the intent. → Match found (high confidence): return GENERATE with the existing plan → Partial match: note it as a candidate, proceed to generation → No match: proceed to generation
Stage 3: GOAL IDENTIFICATION Parse the intent into a goal: what output does the user want? → Clear goal: proceed → Unclear: return CLARIFY
Stage 4: BACKWARD CHAINING (capability selection + policy pre-check) Find terminal capability, check policy, analyze gaps, resolve gaps. → Plan assembled: proceed → Gap unresolvable: return CLARIFY → All paths blocked: return CONVERSE
Stage 5: PLAN DRAFT ASSEMBLY Arrange capabilities in execution order, wire input bindings. → Return GENERATE with Plan Draft
Stage 6: PLANNER TRACE ASSEMBLY Package all decisions, scores, and reasoning into a PlannerTrace. Attached to the response regardless of mode.3.2 Stage 1: Intent Classification
Section titled “3.2 Stage 1: Intent Classification”The Planner first classifies the intent to determine how to process it.
For expressed intents (natural language):
The LLM classifies the intent into one of:
| Classification | Examples | Next Action |
|---|---|---|
| Actionable | ”Delete customer ABC”, “Send the report”, “Create a new deal” | Proceed to Stage 2 |
| Exploratory | ”What can you do?”, “How does billing work?”, “Tell me about capabilities” | CONVERSE (explain, list capabilities, describe features) |
| Advisory | ”Should I delete this account?”, “What’s the best approach for…” | CONVERSE (give advice, recommend) |
| Ambiguous | ”Something about the customer”, “Fix it”, “Do the thing” | CLARIFY (ask what specifically) |
| Conversational | ”Hello”, “Thanks”, “Never mind” | CONVERSE (respond naturally) |
For packaged intents (pre-built):
Skip classification. Packaged intents are always actionable. Proceed directly to Stage 2.
For structured intents (form/wizard):
Skip classification. Structured intents provide action and parameters. Proceed directly to Stage 2 (or Stage 3 if the action maps directly to a capability).
3.3 Stage 2: Plan Library Search
Section titled “3.3 Stage 2: Plan Library Search”Before generating a new plan, the Planner searches the Plan Library for an existing plan that matches the intent.
Search criteria:
- Intent pattern matching: Plans in the library may be tagged with intent patterns they serve. The Planner matches the current intent against these patterns.
- Input compatibility: The plan’s required inputs must be satisfiable from the intent’s data.
- Lifecycle state: Only
PROMOTEDplans are considered.CANDIDATEandSHADOWplans are not returned for production use. - Policy compatibility: The matched plan’s capabilities must pass policy pre-check for the current user.
Match outcomes:
| Confidence | Action |
|---|---|
| High (>0.9): exact or near-exact match to a promoted plan | Return GENERATE with the existing plan’s Plan IR. Skip generation. |
| Medium (0.5-0.9): partial match, some adaptation needed | Note as a starting point. Proceed to generation, using the match as a template. |
| Low (<0.5) or no match | Proceed to generation from scratch. |
Policy check on matched plans: Even for a high-confidence match from the Plan Library, the Planner runs a policy pre-check on all capabilities in the plan. If any capability is now blocked for this user (policies may have changed since the plan was promoted), the Planner either adapts the plan or falls through to generation.
3.4 Stage 3: Goal Identification
Section titled “3.4 Stage 3: Goal Identification”The Planner identifies the desired output from the intent.
For expressed intents: The LLM parses the intent into:
- Goal output: What the user wants to happen (e.g., “email sent”, “customer deleted”, “report generated”)
- Explicit parameters: Data provided in the intent (e.g., customer_id = “ABC-123”, email = “[email protected]”)
- Implicit context: Information available from the system context (e.g., current user, current tenant)
For structured intents: The action field maps to the goal, parameters map to explicit parameters. Minimal LLM involvement.
Failure modes:
- If the LLM cannot extract a clear goal: CLARIFY (“What specifically would you like me to do?”)
- If the goal is clear but too vague to match capabilities: CLARIFY (“Which customer do you mean?” / “What kind of report?“)
3.5 Stage 4: Backward Chaining
Section titled “3.5 Stage 4: Backward Chaining”This is the core generation stage. The protocol is fully defined in the Plan IR Specification (Section 1A.2). Here we define the Planner-specific behavior at each step.
3.5.1 Terminal Capability Selection
Section titled “3.5.1 Terminal Capability Selection”The runtime queries the Capability Registry for capabilities whose output matches the goal.
Query strategy:
- Schema match: Capabilities whose
output_schemais structurally compatible with the goal output. - Tag match: Capabilities whose tags overlap with keywords from the intent.
- Description match: LLM semantic similarity between the intent and capability descriptions.
The runtime returns a ranked candidate list. The LLM scores each candidate:
Candidate scoring prompt (conceptual):
Given the user's intent: "{intent}"And the goal: "{goal}"
Score each capability (0.0 to 1.0) on how well it achieves the goal:
1. {capability_name}: {description} Input: {input_schema_summary} Output: {output_schema_summary} Effect: {effect_class} / {boundary} Score: ___
Select the highest-scoring capability, or indicate if none match.Decision thresholds:
| Score Range | Action |
|---|---|
| Single candidate > 0.85 | Select it. High confidence. |
| 2-3 candidates > 0.7 | LLM selects best. Medium confidence. |
| Multiple candidates, all 0.5-0.7 | CLARIFY — present options to user |
| No candidates > 0.5 | CONVERSE — explain what’s possible |
Tier selection (when capability tiers exist):
When the registry contains multiple capability variants for the same domain action (e.g., send_email, send_email_batch, start_email_campaign), the Planner uses the following heuristics to select the appropriate tier:
| Signal | Select |
|---|---|
| Intent targets a single entity (“send alice an email”) | Atomic (Tier 1) |
Intent targets a small collection (“all”, “every”, “each” + small/medium counts up to the batch capability’s maxItems) | Batch (Tier 2) |
| Intent signals large-scale or background operations (“campaign”, “bulk”, “export”, large counts, or unknown-size collections) | Async Job (Tier 3) |
| A prior step produces an array and the next capability needs one item | Batch (Tier 2) — the batch variant accepts the array directly |
The capability description and alternatives fields are the primary selection mechanism. A batch capability’s description should explicitly state its item limit and direct the Planner to the async alternative for larger sets. See Capability System Specification, Section 16C.
3.5.2 Policy Pre-Check
Section titled “3.5.2 Policy Pre-Check”After selecting a candidate capability, the Planner queries the Policy Engine:
interface PolicyPreCheckRequest { capability_name: string; capability_version: string; effect_class: EffectClass; boundary: Boundary; tags: string[]; constraints?: { required_roles?: string[]; }; user_context: UserContext; environment: string;}
interface PolicyPreCheckResponse { allowed: boolean; reason?: string; // If denied: human-readable explanation denied_by?: string; // Policy name or constraint that blocked}If DENIED: The Planner enters Alternative Capability Search (see Section 3.5.3).
If ALLOWED: Proceed to gap analysis.
3.5.3 Alternative Capability Search
Section titled “3.5.3 Alternative Capability Search”When a capability is policy-blocked, the Planner searches for alternatives:
Search order:
alternativesfield: Check the blocked capability’salternativesfield for explicitly declared alternatives.- Tag-based search: Query the registry for capabilities with the same domain tags (excluding the blocked one).
- Schema-based search: Query for capabilities whose output achieves a version of the goal (e.g.,
request_idinstead ofdeletion_confirmation).
For each alternative found:
- Run policy pre-check. If also blocked, skip.
- LLM scores the alternative against the (possibly adjusted) goal.
- If score > 0.6: use it. Adjust the goal description.
- If no alternative passes: CONVERSE with explanation.
Goal adjustment:
When an alternative is selected, the Planner adjusts:
goal_summary: from “Delete customer ABC-123” to “Submit deletion request for customer ABC-123”goal_adjusted: trueoriginal_goal: “Delete customer ABC-123”adjusted_reason: “Direct deletion requires admin role. A deletion request has been submitted instead.”
This information is included in the GENERATE response so the frontend can inform the user.
3.5.4 Gap Analysis
Section titled “3.5.4 Gap Analysis”After selecting the terminal capability (direct or alternative), the runtime compares its input schema against available data:
Available data sources:
| Source | Contents |
|---|---|
| Intent parameters | Explicit values from the intent (e.g., customer_id = “ABC-123”) |
| System context | Current user_id, tenant_id, roles, timestamp, environment |
| Conversation history | Values collected from prior CLARIFY rounds |
Gap identification:
For each required field in the capability’s input schema:
- Is it available from intent parameters? (name match or type-compatible alias)
- Is it available from system context?
- Is it available from conversation history?
- If none: it’s a gap.
For each optional field:
- If available: include it. If not: skip it (the capability handles defaults).
3.5.5 Gap Resolution
Section titled “3.5.5 Gap Resolution”For each gap, the Planner recurses:
- Runtime queries: Capability Registry for capabilities whose output can fill the gap.
- Policy pre-check: on each candidate bridging capability.
- LLM selects: the best bridging capability.
- Recurse: if the bridging capability has its own gaps.
- Depth limit: Maximum chain depth of 10 capabilities. Beyond this, fall back to CLARIFY.
- Ask the user: If a gap cannot be filled by any capability (e.g., a free-text “reason” field), the Planner may include a CLARIFY for that specific field. Alternatively, it may treat the gap as a value the plan collects at runtime via an Interaction Point.
3.6 Stage 5: Plan Draft Assembly
Section titled “3.6 Stage 5: Plan Draft Assembly”Once all gaps are resolved, the Planner assembles the Plan Draft:
- Reverse the chain: The backward chain is reversed to produce execution order (first capability to call is the one furthest from the goal).
- Wire input bindings: For each capability, specify where each input comes from (intent parameter, prior step output, system context).
- Add conditions: If any step is conditional (e.g., “only send email if user has email opt-in”), express as a natural language condition string (Plan Enrichment converts to structured conditions).
- Name the plan: LLM generates a concise plan name from the goal (e.g., “request_customer_deletion”).
The output is a Plan Draft as defined in Plan IR Specification, Section 2.
3.7 Stage 6: Planner Trace
Section titled “3.7 Stage 6: Planner Trace”Every Planner invocation produces a PlannerTrace — a structured log of the reasoning process:
interface PlannerTrace { trace_id: string; timestamp: string; duration_ms: number; intent_classification: { classification: 'actionable' | 'exploratory' | 'advisory' | 'ambiguous' | 'conversational'; confidence: number; }; plan_library_search?: { query: string; matches: Array<{ plan_id: string; plan_name: string; confidence: number; selected: boolean; }>; }; goal_identification?: { goal_output: string; explicit_parameters: Record<string, any>; confidence: number; }; capability_selection: Array<{ step: 'terminal' | 'bridging'; candidates: Array<{ capability_name: string; score: number; selected: boolean; }>; policy_pre_check: { capability_name: string; allowed: boolean; reason?: string; }; alternative_search?: { triggered: boolean; alternatives_found: number; selected_alternative?: string; goal_adjusted: boolean; }; }>; gaps: Array<{ field: string; resolved_by: 'capability' | 'clarification' | 'default' | 'interaction_point'; bridging_capability?: string; }>; response_mode: 'GENERATE' | 'CLARIFY' | 'CONVERSE'; llm_calls: Array<{ purpose: string; // e.g., "intent_classification", "capability_scoring", "goal_extraction" model: string; prompt_tokens: number; completion_tokens: number; duration_ms: number; }>;}The PlannerTrace is:
- Attached to every PlannerResponse (regardless of mode).
- Persisted as part of the system-wide Trace when a plan is executed.
- Inspectable via the CLI (
zakardo trace inspect) and the Zakardo Cloud dashboard. - Used by the Training System to evaluate Planner performance.
4. Multi-Turn Clarification
Section titled “4. Multi-Turn Clarification”Clarification is not a single request-response. It’s a conversation loop.
4.1 Clarification Flow
Section titled “4.1 Clarification Flow”Turn 1: User sends intentTurn 2: Planner returns CLARIFY (asks a question)Turn 3: User answers the questionTurn 4: Planner re-enters the pipeline with the refined intent → May return GENERATE, CLARIFY (again), or CONVERSEImplementation:
- The Planner returns a
PlannerClarifyResponsewith a uniqueclarification_id. - The frontend presents the question (and options, if provided) to the user.
- The user responds. The frontend sends a new
PlannerRequestwith:- The original intent
- The answer appended to
conversation_history - The
clarification_idto link the answer to the question
- The Planner re-enters the pipeline at Stage 1 with the full context.
4.2 Clarification Types
Section titled “4.2 Clarification Types”| Type | When | Example Question | Example Options |
|---|---|---|---|
| Disambiguation | Multiple viable goals | ”Do you want to delete the customer’s account or their billing profile?” | Option A: “Account”, Option B: “Billing profile” |
| Missing parameter | Required input not in intent | ”Which customer do you want to delete? Please provide a customer ID or name.” | (free-text) |
| Multiple paths | Several capabilities match with similar scores | ”I can generate a PDF report or a live dashboard. Which do you prefer?” | Option A: “PDF report”, Option B: “Live dashboard” |
| Confirmation | High-impact action detected, Planner wants to confirm before building plan | ”You want to delete all inactive accounts (47 total). This is destructive. Should I proceed with building this plan?” | Option A: “Yes, proceed”, Option B: “No, cancel” |
4.3 Clarification Limits
Section titled “4.3 Clarification Limits”- Maximum turns: 5 clarification rounds per intent before the Planner gives up and returns CONVERSE (“I’m having trouble understanding your request. Could you try rephrasing it?”)
- Timeout: If the user doesn’t respond to a clarification within a configurable timeout (default: 5 minutes), the session expires. The user must start over.
5. Plan Library Integration
Section titled “5. Plan Library Integration”5.1 When the Plan Library Short-Circuits Generation
Section titled “5.1 When the Plan Library Short-Circuits Generation”The Plan Library is the first thing the Planner checks. If a promoted plan matches the intent with high confidence, the Planner skips generation entirely:
Intent: "Send welcome email to user 123" → Plan Library: promoted plan "send_welcome_email" matches (confidence: 0.95) → Policy pre-check: all capabilities in the plan are allowed for this user → Return GENERATE with the existing plan (no LLM generation needed)This is the fast path. For common intents with promoted plans, the Planner is essentially a lookup + policy check.
5.2 Plan Matching Strategy
Section titled “5.2 Plan Matching Strategy”Plans in the library are indexed by:
- Intent patterns: Human-authored or auto-extracted patterns (e.g., “send _ email to _”, “delete _ account _”).
- Input schema: The plan’s required inputs. A match requires that the intent provides (or can provide) all required inputs.
- Tags: Domain tags for fuzzy matching.
- Semantic embedding: For LLM-based matching, a vector embedding of the plan’s purpose.
Matching algorithm:
1. Filter: Lifecycle state == PROMOTED2. Filter: All plan capabilities pass policy pre-check for current user3. Score: Combine pattern match score, schema compatibility, tag overlap, semantic similarity4. Rank: Sort by composite score5. Threshold: Top result must be > 0.9 for high-confidence match5.3 Plan Adaptation
Section titled “5.3 Plan Adaptation”When a medium-confidence match (0.5-0.9) is found, the Planner may adapt the existing plan:
- Parameter adaptation: The plan expects input X, the intent provides a variation of X. The LLM maps the intent’s data to the plan’s expected inputs.
- Step addition: The matched plan is close but missing a step. The Planner uses it as a starting point and adds the missing step via backward chaining.
- Step removal: The matched plan has steps not needed for this specific intent. The Planner may propose a trimmed version.
Adapted plans are new CANDIDATE plans, not modifications to the promoted plan.
6. LLM Integration Model
Section titled “6. LLM Integration Model”6.1 Prompt Architecture: Layered Context
Section titled “6.1 Prompt Architecture: Layered Context”Every LLM call in the Planner is composed of layered context. Each layer adds information, and the developer controls several of them.
┌─────────────────────────────────────────────────────────┐│ Layer 1: ZAKARDO CORE PROMPT (built-in, not editable) ││ Defines: Planner role, backward chaining protocol, ││ response modes, JSON output format, safety rules │├─────────────────────────────────────────────────────────┤│ Layer 2: APPLICATION CONTEXT (developer-configured) ││ Defines: App domain, business rules, tone, constraints ││ Source: config/llm.ts -> planner.application_prompt │├─────────────────────────────────────────────────────────┤│ Layer 3: CAPABILITY CONTEXT (auto-generated) ││ Defines: Available capabilities for this call ││ Source: Runtime queries Capability Registry, formats ││ summaries for the LLM (name, description, I/O summary)│├─────────────────────────────────────────────────────────┤│ Layer 4: PLANNING HINTS (developer-injected, optional) ││ Defines: Domain-specific guidance, preferences, rules ││ Source: config/llm.ts -> planner.planning_hints ││ or per-request via Runtime API │├─────────────────────────────────────────────────────────┤│ Layer 5: USER CONTEXT (per-request, auto-populated) ││ Defines: User roles, tenant, environment, conversation ││ history, prior clarifications │├─────────────────────────────────────────────────────────┤│ Layer 6: USER MESSAGE (the intent itself) ││ Source: What the user typed or the packaged intent │└─────────────────────────────────────────────────────────┘Layer 1 and 3 are owned by Zakardo. The developer cannot modify them. Layer 2, 4 are developer-controlled. This is how developers customize the Planner for their application. Layer 5 and 6 are per-request, auto-populated from the PlannerRequest.
6.2 Layer Details
Section titled “6.2 Layer Details”Layer 1: Zakardo Core Prompt (System Role)
Section titled “Layer 1: Zakardo Core Prompt (System Role)”This is the foundation prompt, provided by @zakardo/runtime. It is stable across all applications and all LLM calls within a session. It defines:
- The Planner’s identity and role (“You are a plan generator…”)
- The backward chaining protocol (goal -> terminal capability -> gap analysis -> resolve)
- The three response modes and when to use each
- The JSON output schema expected for this specific call type
- Safety rules: “Never fabricate capabilities”, “Never generate schemas”, “If unsure, ask for clarification”
- The concept of capabilities, effect classes, and boundaries (so the LLM understands the domain model)
The developer cannot edit this layer. It ensures consistent Planner behavior across all Zakardo applications.
Layer 2: Application Context (Developer-Configured)
Section titled “Layer 2: Application Context (Developer-Configured)”The developer provides an application-level prompt that describes their domain. This is configured once in config/llm.ts and injected into every LLM call as part of the system message.
{ planner: { application_prompt: ` This is a CRM application for a B2B SaaS company. Users are sales representatives, sales managers, and administrators.
Key domain concepts: - Customers have accounts, contacts, and deals. - Deals progress through stages: Lead → Qualified → Proposal → Negotiation → Closed Won/Lost. - Sales reps can only see their own accounts. Managers see their team's accounts. Admins see all.
Tone: Professional but friendly. Use business terminology.
Important rules: - Never suggest deleting a customer unless the user explicitly asks for deletion. - Always prefer "update" over "delete + recreate" when modifying records. - When the user says "my accounts", scope to their assigned accounts. `, }}This layer helps the LLM understand the application’s domain, make better capability selections, and generate more natural clarification questions.
Layer 3: Capability Context (Auto-Generated)
Section titled “Layer 3: Capability Context (Auto-Generated)”For each LLM call that involves capability selection or scoring, the runtime generates a capability summary from the Capability Registry. The LLM receives only the relevant candidates (pre-filtered by the runtime), not the entire registry.
Format per capability:
Capability: get_customer_by_idDescription: Retrieves a customer record by ID. Returns full customer details.Effect: READ | LOCALInput: { customer_id: string (uuid, required) }Output: { id, name, email, status, assigned_to, created_at, ... }Tags: [customer, account, read, crm]Constraints: required_roles: [sales_rep, sales_manager, admin]The runtime controls this formatting. The developer cannot modify how capabilities are presented to the LLM.
Layer 4: Planning Hints (Developer-Injected)
Section titled “Layer 4: Planning Hints (Developer-Injected)”Planning hints are optional, domain-specific instructions that guide the Planner’s reasoning. They can be configured globally or injected per-request.
Global hints (in config/llm.ts):
{ planner: { planning_hints: [ { hint: "When a user asks to 'close' a deal, they mean move it to the 'Closed Won' stage, not delete it.", tags: ["deals", "close"], // Only injected when these tags are relevant }, { hint: "For enterprise customers (tier: 'enterprise'), always include the audit_log_action capability in the plan.", tags: ["enterprise", "audit"], }, { hint: "If the user asks about 'pipeline', they mean the deals pipeline dashboard, not a CI/CD pipeline.", tags: ["pipeline", "deals"], }, ], }}Per-request hints (via Runtime API):
// Submitted alongside the intent{ intent: { raw_text: "Show me the Q4 forecast", source: "expressed" }, planning_context: { hints: ["The user is preparing for a board meeting. Prefer summary views over detailed lists."], data: { current_quarter: "Q4-2026", user_team_size: 12, }, },}Hints are injected into the LLM call as additional system context. Tag-based hints are only included when the runtime determines they’re relevant (based on the capabilities being considered).
Per-request data provided in planning_context.data is made available as additional context during gap analysis. If the Planner has a gap for “quarter” and the planning context provides current_quarter: "Q4-2026", the gap is automatically resolved.
Layer 5: User Context (Auto-Populated)
Section titled “Layer 5: User Context (Auto-Populated)”Populated automatically from the PlannerRequest:
User: user_id=u-456, roles=[sales_manager], tenant=acme-corpEnvironment: productionExecution Mode: LIVEConversation History: - User: "Show me inactive customers" - Planner: [CLARIFY] "Inactive for how long? Last 30 days, 90 days, or all time?" - User: "Last 90 days"Layer 6: User Message
Section titled “Layer 6: User Message”The intent itself. For expressed intents, this is the raw text. For packaged/structured intents, this is a formatted representation of the action and parameters.
6.3 LLM Calls in the Pipeline
Section titled “6.3 LLM Calls in the Pipeline”The default Planner makes multiple focused LLM calls per pipeline execution, not one large prompt. Each call has a specific purpose:
| Call | Purpose | Input Layers | Output | Required? |
|---|---|---|---|---|
| Intent classification | Classify intent as actionable/exploratory/ambiguous | L1 + L2 + L3 (summaries only) + L5 + L6 | Classification + confidence | Yes (expressed intents only) |
| Goal extraction | Parse intent into goal + parameters | L1 + L2 + L4 (relevant hints) + L5 + L6 | Goal output, explicit parameters | Yes |
| Capability scoring | Score candidate capabilities against the goal | L1 + L2 + L3 (full candidates) + L4 + L5 + L6 | Scored list | Yes (per selection point) |
| Alternative evaluation | Score alternative capabilities when blocked | L1 + L2 + L3 (alternatives) + L4 + L5 + L6 | Scored list | Only when policy blocks |
| Gap interpretation | Determine if a gap can be defaulted or needs user input | L1 + L2 + L4 + L5 (+ planning_context.data) | Resolution strategy | Only when gaps found |
| Condition generation | Express step conditions in natural language | L1 + L2 + L4 + step context | Condition string | Only for conditional plans |
| Plan naming | Generate a concise plan name | L1 + L2 + goal + capabilities selected | Plan name string | Yes |
| Clarification composition | Formulate a clear question for the user | L1 + L2 + L4 + context of uncertainty | Question text + options | Only for CLARIFY mode |
| Conversational response | Generate a helpful response | L1 + L2 + L4 + L5 + L6 + reason | Response text + suggestions | Only for CONVERSE mode |
6.4 Prompt Design Principles
Section titled “6.4 Prompt Design Principles”- Small, focused prompts. Each LLM call asks one question. No mega-prompts that try to do everything at once.
- Structured output. Every LLM call requests JSON output conforming to a defined schema. The runtime validates the response before proceeding.
- Capability context, not full registry. The LLM receives only the relevant candidates (filtered by the runtime’s registry queries), not the entire capability list.
- No schema generation. The LLM never generates JSON Schema. It selects from existing schemas. Plan Enrichment handles all schema-related computation.
- Incremental reasoning. For multi-step plans, each step is a separate LLM interaction. The runtime validates after each step before asking the LLM for the next one.
- System prompt stability. Layers 1-2 do not change between calls within a session. Only the capability context (L3), hints (L4), user context (L5), and user message (L6) change.
- Developer context is additive. The developer’s application prompt and hints add context. They cannot override Zakardo’s core protocol or safety rules.
6.5 Multi-Provider Support
Section titled “6.5 Multi-Provider Support”Zakardo abstracts LLM access through a Provider Interface:
interface LLMProvider { chat(request: LLMChatRequest): Promise<LLMChatResponse>; supports_structured_output: boolean; supports_streaming: boolean; model_id: string;}
interface LLMChatRequest { messages: Array<{ role: 'system' | 'user' | 'assistant'; content: string }>; response_schema?: JSONSchema; // For structured output temperature: number; max_tokens: number;}Built-in providers (shipped with @zakardo/runtime):
| Provider | Models | Notes |
|---|---|---|
openai | GPT-4, GPT-4o, GPT-4o-mini, etc. | Supports structured output (JSON mode) |
anthropic | Claude 3.5 Sonnet, Claude 3 Opus, etc. | Supports structured output via tool use |
ollama | Any Ollama-hosted model | For local/self-hosted LLMs |
custom | Any model via a developer-provided adapter | Implements the LLMProvider interface |
Configuration:
{ planner: { llm: { // Default provider for all calls default: { provider: 'anthropic', model: 'claude-sonnet-4-20250514', temperature: 0.1, max_tokens: 4096, timeout_ms: 30000, },
// Override per call type (optional) overrides: { intent_classification: { provider: 'anthropic', model: 'claude-haiku-1', // Fast model for simple classification temperature: 0.0, max_tokens: 256, }, capability_scoring: { // Uses default (Sonnet) -- reasoning-heavy }, conversational_response: { temperature: 0.4, // Slightly more creative for conversation max_tokens: 1024, }, }, }, }}This allows developers to use a fast, cheap model for simple classification calls and a more powerful model for reasoning-heavy calls (capability scoring, gap resolution).
6.6 Bring Your Own Key (BYOK)
Section titled “6.6 Bring Your Own Key (BYOK)”Zakardo does not require developers to use a Zakardo-managed LLM service. The developer provides their own API keys.
{ planner: { llm: { default: { provider: 'openai', model: 'gpt-4o', api_key: process.env.OPENAI_API_KEY, // Developer's own key api_base_url: process.env.OPENAI_BASE_URL, // Optional: custom endpoint (Azure OpenAI, proxy, etc.) }, }, }}Multi-tenant BYOK (Zakardo Cloud scenario):
In multi-tenant deployments, different tenants may use different LLM providers or keys:
{ planner: { llm: { resolve: (user_context: UserContext) => { // Per-tenant LLM configuration const tenant_config = getTenantLLMConfig(user_context.tenant_id); return { provider: tenant_config.provider, model: tenant_config.model, api_key: tenant_config.api_key, }; }, }, }}This enables:
- Enterprise deployments: Each customer organization brings their own OpenAI/Anthropic key.
- Compliance: Organizations that require data to stay in specific regions can point to region-specific LLM endpoints.
- Cost control: Each tenant pays for their own LLM usage directly.
6.7 Custom LLM Adapters
Section titled “6.7 Custom LLM Adapters”For LLM providers not built into Zakardo, developers implement the LLMProvider interface:
import { defineLLMProvider } from '@zakardo/runtime';
export default defineLLMProvider({ model_id: 'my-company/internal-llm-v2', supports_structured_output: true, supports_streaming: false,
async chat(request) { const response = await fetch('https://llm.internal.company.com/v1/chat', { method: 'POST', headers: { Authorization: `Bearer ${process.env.INTERNAL_LLM_KEY}` }, body: JSON.stringify({ messages: request.messages, temperature: request.temperature, max_tokens: request.max_tokens, response_format: request.response_schema ? { type: 'json_object', schema: request.response_schema } : undefined, }), });
const data = await response.json(); return { content: data.choices[0].message.content, usage: { prompt_tokens: data.usage.prompt_tokens, completion_tokens: data.usage.completion_tokens, }, }; },});import myLLM from './src/planner/my-llm-adapter';
{ planner: { llm: { default: { provider: myLLM, }, }, }}6.8 LLM Fallback Chain
Section titled “6.8 LLM Fallback Chain”If the primary LLM fails (timeout, invalid response, service down), the Planner can fall through a configured chain:
{ planner: { llm: { default: { provider: 'anthropic', model: 'claude-sonnet-4-20250514' }, fallback: [ { provider: 'openai', model: 'gpt-4o' }, // Try OpenAI next { provider: 'ollama', model: 'llama3.1:70b' }, // Try local next ], max_retries_per_provider: 2, }, }}Fallback order:
- Retry the primary provider (up to
max_retries_per_provider). - Try each fallback provider in order.
- If all providers fail: fall back to Plan Library only (no generation).
- If no library match: return CONVERSE (“Planning service temporarily unavailable”).
- Record the full failure chain in the Planner Trace.
6.9 LLM Cost Tracking
Section titled “6.9 LLM Cost Tracking”Every LLM call is recorded in the Planner Trace with token counts and timing:
interface LLMCallTrace { call_type: string; // 'intent_classification', 'capability_scoring', etc. provider: string; model: string; prompt_tokens: number; completion_tokens: number; duration_ms: number; cached: boolean; // If the response was served from cache retries: number; fallback_used: boolean;}This enables:
- Per-request cost attribution: How much did this planning session cost?
- Per-tenant cost tracking: In multi-tenant BYOK, each tenant’s usage is tracked separately.
- Optimization insights: Which call types are most expensive? Which could use a smaller model?
7. Plan Repair
Section titled “7. Plan Repair”When a plan fails during execution, the Execution Engine may request the Planner to repair it.
7.1 Repair Input
Section titled “7.1 Repair Input”interface PlanRepairRequest { original_plan: PlanIR; // The plan that failed failure: { step_index: number; // Which step failed error: CapabilityError; // The error that occurred execution_trace: StepTrace[]; // What happened up to the failure }; user_context: UserContext;}7.2 Repair Strategy
Section titled “7.2 Repair Strategy”The Planner attempts repair in this order:
- Retry suggestion: If the error is
TRANSIENT_ERRORand the capability isretry_safe: suggest retry (not a new plan, just a retry of the failed step). - Step replacement: If the error is
BUSINESS_ERRORand the failed capability has alternatives: propose a plan that replaces the failed step with an alternative capability. - Partial re-plan: If the error invalidates downstream steps: re-run backward chaining from the point of failure, keeping successful steps.
- Full re-plan: If the plan is fundamentally broken: generate a new plan from scratch with the original intent + the failure context.
- Give up: If no repair is possible: return CONVERSE explaining the failure.
7.3 Repair Output
Section titled “7.3 Repair Output”Repair returns a standard PlannerResponse:
- GENERATE with a modified Plan Draft (for cases 2-4).
- CONVERSE with explanation (for case 5).
- The Planner Trace includes the repair context (what failed, what was attempted).
8. Planner as an Interface (Pluggability)
Section titled “8. Planner as an Interface (Pluggability)”8.1 Interface Definition
Section titled “8.1 Interface Definition”Any Planner implementation must conform to:
interface Planner { resolve(request: PlannerRequest): Promise<PlannerResponse>; repair(request: PlanRepairRequest): Promise<PlannerResponse>;}That’s it. Two methods.
8.2 Default Implementation: LLM Planner
Section titled “8.2 Default Implementation: LLM Planner”The runtime ships with LLMPlanner, which implements the full pipeline described in this specification using an LLM for reasoning.
8.3 Alternative Implementations
Section titled “8.3 Alternative Implementations”| Implementation | Strategy | When to Use |
|---|---|---|
| RuleBasedPlanner | Pattern matching on intent patterns, no LLM | Applications with a fixed set of intents (kiosk, internal tools) |
| LibraryOnlyPlanner | Returns only Plan Library matches, no generation | Production environments where all plans are pre-authored and validated |
| RemotePlanner | Forwards the PlannerRequest to an external HTTP service | When the Planner logic lives in a separate service (microservice architecture) |
| HybridPlanner | Tries Library first, falls back to LLM only if no match | Cost optimization — LLM calls only when needed |
All implementations must:
- Support all three response modes (GENERATE, CLARIFY, CONVERSE).
- Perform policy pre-checks during capability selection.
- Produce a PlannerTrace.
- Respect the PlannerRequest/PlannerResponse contracts.
9. Performance and Cost
Section titled “9. Performance and Cost”9.1 Latency Budget
Section titled “9.1 Latency Budget”| Stage | Target Latency | Notes |
|---|---|---|
| Intent classification | < 500ms | Single LLM call |
| Plan Library search | < 100ms | Database query + in-memory filtering |
| Goal identification | < 500ms | Single LLM call |
| Capability scoring (per selection) | < 800ms | Single LLM call with candidate list |
| Policy pre-check (per capability) | < 50ms | In-memory policy evaluation |
| Gap analysis | < 100ms | Schema comparison, no LLM |
| Plan Draft assembly | < 100ms | Deterministic, no LLM |
Total target: < 3 seconds for a single-capability plan, < 5 seconds for a 3-step plan.
9.2 Cost Optimization
Section titled “9.2 Cost Optimization”- Plan Library first: If a promoted plan matches, zero LLM calls. This is the most common production path.
- Packaged/structured intents: Skip intent classification. Save one LLM call.
- Capability pre-filtering by runtime: The LLM only scores capabilities the runtime has already filtered by schema, tags, and policy. The candidate list is typically 3-8 capabilities, not hundreds.
- Caching: Capability scores for common intent-capability pairs can be cached. Cache key: intent pattern + capability name + capability version.
- Low temperature: Using temperature 0.0-0.2 makes responses more deterministic and cacheable.
10. Error Handling
Section titled “10. Error Handling”10.1 Planner Errors
Section titled “10.1 Planner Errors”The Planner itself can fail (as distinct from returning CONVERSE, which is a graceful response):
| Error | Cause | Handling |
|---|---|---|
PLANNER_LLM_TIMEOUT | LLM call exceeded timeout | Retry, then fallback to library-only |
PLANNER_LLM_INVALID_RESPONSE | LLM returned unparseable output | Retry with same prompt |
PLANNER_LLM_UNAVAILABLE | LLM service is down | Fallback to library-only |
PLANNER_REGISTRY_ERROR | Cannot reach Capability Registry | Return error to frontend (cannot plan without capabilities) |
PLANNER_POLICY_ERROR | Policy Engine is unavailable | Return error to frontend (cannot plan without policy checks) |
PLANNER_INTERNAL_ERROR | Unexpected runtime error | Return error to frontend with trace |
All errors are recorded in the Planner Trace and propagated to the frontend as structured errors (not raw exceptions).
10.2 Error vs. CONVERSE
Section titled “10.2 Error vs. CONVERSE”CONVERSE is a graceful, intentional response: “I can’t build a plan for this, and here’s why.” Error is an unexpected failure: “Something went wrong in the Planner itself.”
The frontend displays them differently. CONVERSE is conversational (“I can’t delete that account because you don’t have admin permissions. I can submit a deletion request instead.”). Errors are system-level (“The planning service is temporarily unavailable. Please try again.”).
11. Security
Section titled “11. Security”11.1 Prompt Injection Defense
Section titled “11.1 Prompt Injection Defense”The Planner’s LLM receives user input (the intent). This creates prompt injection risk.
Mitigations:
- Input sanitization: The Runtime API sanitizes intents before they reach the Planner (strip control characters, limit length, detect known injection patterns).
- Structured prompts: The system prompt and capability context are provided in system/assistant roles. User input is always in the user role. The LLM is instructed to treat user messages as data, not instructions.
- Output validation: Every LLM response is validated against its expected schema. If the response doesn’t conform, it’s rejected and retried.
- Capability-only execution: Even if an injection succeeds in influencing capability selection, the Planner can only select registered capabilities. It cannot invent new ones or execute arbitrary code.
- Policy enforcement: Even a manipulated plan goes through the Validator and per-step policy checks. A prompt injection cannot bypass policy.
11.2 Data Exposure
Section titled “11.2 Data Exposure”The Planner’s LLM receives:
- The user’s intent (expected — this is the input)
- Capability names, descriptions, and schema summaries (not sensitive — these are metadata)
- User roles (for policy context)
The Planner’s LLM does not receive:
- Business data from the database
- Other users’ data or intents
- Full capability implementations
- Policy rule details (only the ALLOWED/DENIED result)
12. Summary of Decisions
Section titled “12. Summary of Decisions”| Decision | Resolution |
|---|---|
| Planner interface | resolve(PlannerRequest): PlannerResponse + repair(PlanRepairRequest): PlannerResponse. Two methods. |
| Three response modes | GENERATE (Plan Draft), CLARIFY (structured question with options), CONVERSE (conversational response with reason code) |
| Stateless | No state between invocations. All context provided per request. Multi-turn clarification uses conversation_history. |
| Pluggable | Defined interface. Default is LLM-based. Alternatives: rule-based, library-only, remote, hybrid. |
| Pipeline architecture | Sequential stages: classify → library search → goal ID → backward chaining → assembly → trace |
| Policy pre-check is mandatory | Part of the interface contract. All implementations must check both system-level policy and capability-level constraints. |
| Plan Library is the fast path | High-confidence matches skip generation entirely. Zero LLM calls for promoted plans. |
| Layered prompt architecture | Six layers: Zakardo core (built-in) → application context (developer) → capability context (auto) → planning hints (developer) → user context (auto) → user message. Developer controls layers 2 and 4. |
| Multiple focused LLM calls | Not one mega-prompt. Each call has one purpose, expects structured JSON output, and uses only the relevant prompt layers. |
| Application context | Developer provides domain description, business rules, and tone in config/llm.ts. Injected into every LLM call. |
| Planning hints | Developer-injected, domain-specific guidance. Can be global (tag-filtered) or per-request. Per-request planning data resolves gaps automatically. |
| Multi-provider support | Abstracted via LLMProvider interface. Built-in: OpenAI, Anthropic, Ollama, custom. Per-call-type model overrides supported. |
| BYOK (Bring Your Own Key) | Developer provides their own LLM API keys. Multi-tenant BYOK via resolver function. No Zakardo-managed LLM required. |
| LLM fallback chain | Primary → fallback providers → Plan Library only → CONVERSE. Full failure chain recorded in trace. |
| Per-call-type model routing | Fast/cheap models for classification, powerful models for reasoning. Configured in planner.llm.overrides. |
| LLM cost tracking | Every call tracked: tokens, duration, provider, cache status. Enables per-request and per-tenant cost attribution. |
| Goal adjustment on policy block | When the original goal is blocked, the Planner adjusts and informs the user (goal_adjusted flag). |
| Clarification is multi-turn | Up to 5 rounds. Conversation history passed in each request. |
| Plan repair | Retry → step replacement → partial re-plan → full re-plan → give up. |
| Prompt injection defense | Input sanitization + role separation + output validation + capability-only execution + policy enforcement. |
| Planner Trace | Every invocation produces a structured trace of all decisions, scores, LLM calls, and timing. |
| Latency target | < 3s for single-cap plans, < 5s for 3-step plans. Plan Library matches are < 200ms. |
| TypeScript-first | Planner interface and default implementation are TypeScript. RemotePlanner allows any language. |
13. Questions Deferred
Section titled “13. Questions Deferred”| Question | Deferred To |
|---|---|
| How exactly are Plan Library intent patterns authored and managed? | Plan Library and Lifecycle Specification |
| What is the exact prompt template for each LLM call? | Implementation detail, not spec. Will be documented in the runtime codebase. |
| How does semantic embedding work for plan matching? | Plan Library and Lifecycle Specification |
| How does the Planner handle concurrent requests? | Runtime API and SDK Specification |
| How is Planner performance monitored? | Trace System Specification |
| How does the Training System evaluate Planner quality? | Training and Validation Specification |
| How does the frontend display CLARIFY options? | Frontend Architecture Specification |