Skip to content

Configuring the Planner

The AI planner is only as good as the context you give it. Without configuration, it has no idea what your application does, who your users are, or what business rules to follow — and it will generate poor or unusable plans.

This guide covers the two developer-controlled layers of the planner’s prompt system:

  • application_prompt (Layer 2) — your app’s identity, injected into every LLM call
  • planning_hints (Layer 4) — targeted rules for specific situations

Every planner LLM call is built from 6 layers stacked together:

LayerNameWho controls it
1Core PromptZakardo framework (not editable)
2Application ContextYou — via application_prompt
3Capability ContextZakardo runtime (auto-generated from your registered capabilities)
4Planning HintsYou — via planning_hints
5User ContextRuntime (auto-populated from the request — user roles, tenant, etc.)
6User MessageEnd user (the intent text)

Layers 1 and 3 are handled automatically. Layers 5 and 6 come from the request. Layers 2 and 4 are yours — they are the primary way you shape planner behavior for your domain.

The application_prompt is a plain text description of your application that is injected as system context into every planner LLM call. It tells the planner:

  • What your application does
  • Who the users are and what roles they have
  • Key domain concepts and entities
  • Business rules and constraints
  • Tone and behavioral preferences

In your config/zakardo.ts (or wherever you define your ZakardoConfig):

const config: ZakardoConfig = {
name: 'my-crm',
version: '0.0.1',
llm: {
// ... provider config ...
application_prompt: `
This is a B2B CRM application for a SaaS company.
Users:
- Sales representatives: manage their contacts, create deals, log activities.
- Sales managers: view team pipeline, approve discounts, run reports.
- Administrators: manage users, configure system settings.
Key domain concepts:
- Contacts belong to Accounts. Each Account has one owner (a sales rep).
- Deals progress through stages: Prospecting → Qualification → Proposal → Negotiation → Closed Won / Closed Lost.
- Activities (calls, emails, meetings) are logged against Contacts or Deals.
Business rules:
- Deals over $50,000 require manager approval before moving to Closed Won.
- Contacts cannot be deleted, only archived (status = 'inactive').
- A sales rep can only see their own contacts unless they have the 'view_all' permission.
Tone: professional but concise. Avoid jargon in user-facing messages.
`,
},
// ...
};

Be specific. The planner uses this to decide which capabilities to invoke, what parameters to pass, and how to interpret ambiguous intents.

IncludeExampleWhy
Domain description”B2B CRM for SaaS”Frames all reasoning
User roles”sales reps, managers, admins”Planner checks role-based access
Entity relationships”Contacts belong to Accounts”Helps resolve data flow between steps
Business rules”Deals over $50K need approval”Planner can proactively add approval gates
Constraints”Contacts cannot be deleted”Prevents planner from choosing destructive capabilities
Naming conventions“‘close’ a deal means move to Closed Won”Resolves ambiguous language

Common mistakes:

  • Too short: "A CRM app" — the planner has almost nothing to work with
  • Too generic: "An app for managing data" — doesn’t help select capabilities
  • Missing roles: Without user roles, the planner can’t reason about permissions
  • Missing business rules: The planner may generate plans that violate your domain logic

Without application_prompt — intent: “close the deal with Acme”

The planner has no context. It might:

  • Not know what “close” means in your domain
  • Select a delete_deal capability instead of update_deal_stage
  • Not know that deals over $50K need approval
  • Generate a plan that any user can execute, ignoring role restrictions

With the CRM application_prompt above — same intent:

The planner knows:

  • “Close” means move to “Closed Won” stage
  • It should use update_deal_stage with stage: 'Closed Won'
  • It should check the deal amount and add an approval gate if over $50K
  • It should verify the user has the sales_rep role

Planning hints are short, targeted instructions for specific situations. Unlike the application prompt (which applies to every call), hints can be tag-filtered so they are only injected when relevant capabilities are in scope.

const config: ZakardoConfig = {
// ...
llm: {
// ...
planning_hints: [
// Always included (no tags)
'When multiple capabilities could work, prefer the one with the narrower effect class (READ over WRITE_INTERNAL).',
// Only included when deal-related capabilities are in scope
// (when using the PlanningHint object format via the Runtime API)
'When a user asks to "close" a deal, they mean move it to the Closed Won stage, not delete it.',
'If a user asks to send an email, always confirm the recipient and subject before sending.',
],
},
};

You can also inject hints on a per-request basis through the planning_context field:

const result = await client.intent.submit({
intent: { expressed: 'Show me my pipeline' },
planning_context: {
hints: ['The user is currently viewing the Q1 dashboard, so emphasize Q1 data.'],
data: {
current_quarter: 'Q1 2026',
user_territory: 'West Coast',
},
},
});

Per-request hints are useful when context changes based on where the user is in the app or what they were doing before submitting the intent.

Use application_prompt forUse planning_hints for
General domain descriptionSpecific edge cases
User roles and permissionsDisambiguation rules
Entity relationshipsBehavioral preferences per feature area
Business rules that always applyContext-dependent guidance
Tone and stylePer-request dynamic context

The Zakardo CLI checks your prompt configuration:

Terminal window
# Check all config including application_prompt
zakardo validate config

The validator will warn if:

  • application_prompt is missing or empty (ZAKARDO_W001)
  • application_prompt is suspiciously short (ZAKARDO_W002)
  • application_prompt contains TODO placeholder text (ZAKARDO_W003)

The zakardo dev command also prints a warning at startup if the application prompt is missing or contains a TODO placeholder.

The best way to validate your prompt configuration is to submit intents and inspect the results:

  1. Start the dev server: zakardo dev
  2. Open Studio: navigate to the Intent Playground
  3. Submit test intents that cover your key use cases
  4. Inspect the generated plans — do they use the right capabilities? Pass the right parameters?
  5. Iterate on your application_prompt and planning_hints until plans are consistently good

You can also use the Training System to create a dataset of intents with expected outcomes and run automated regression testing.