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 callplanning_hints(Layer 4) — targeted rules for specific situations
The 6-Layer Prompt System
Section titled “The 6-Layer Prompt System”Every planner LLM call is built from 6 layers stacked together:
| Layer | Name | Who controls it |
|---|---|---|
| 1 | Core Prompt | Zakardo framework (not editable) |
| 2 | Application Context | You — via application_prompt |
| 3 | Capability Context | Zakardo runtime (auto-generated from your registered capabilities) |
| 4 | Planning Hints | You — via planning_hints |
| 5 | User Context | Runtime (auto-populated from the request — user roles, tenant, etc.) |
| 6 | User Message | End 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.
Application Prompt (Layer 2)
Section titled “Application Prompt (Layer 2)”What it is
Section titled “What it is”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
Where to configure it
Section titled “Where to configure it”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. `, }, // ...};How to write a good application prompt
Section titled “How to write a good application prompt”Be specific. The planner uses this to decide which capabilities to invoke, what parameters to pass, and how to interpret ambiguous intents.
| Include | Example | Why |
|---|---|---|
| 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
Before and after
Section titled “Before and after”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_dealcapability instead ofupdate_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_stagewithstage: 'Closed Won' - It should check the deal amount and add an approval gate if over $50K
- It should verify the user has the
sales_reprole
Planning Hints (Layer 4)
Section titled “Planning Hints (Layer 4)”What they are
Section titled “What they are”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.
Global hints (in config)
Section titled “Global hints (in config)”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.', ], },};Per-request hints (via Runtime API)
Section titled “Per-request hints (via Runtime API)”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.
When to use hints vs. application prompt
Section titled “When to use hints vs. application prompt”Use application_prompt for | Use planning_hints for |
|---|---|
| General domain description | Specific edge cases |
| User roles and permissions | Disambiguation rules |
| Entity relationships | Behavioral preferences per feature area |
| Business rules that always apply | Context-dependent guidance |
| Tone and style | Per-request dynamic context |
Validating Your Configuration
Section titled “Validating Your Configuration”The Zakardo CLI checks your prompt configuration:
# Check all config including application_promptzakardo validate configThe validator will warn if:
application_promptis missing or empty (ZAKARDO_W001)application_promptis suspiciously short (ZAKARDO_W002)application_promptcontains 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.
Testing Your Prompts
Section titled “Testing Your Prompts”The best way to validate your prompt configuration is to submit intents and inspect the results:
- Start the dev server:
zakardo dev - Open Studio: navigate to the Intent Playground
- Submit test intents that cover your key use cases
- Inspect the generated plans — do they use the right capabilities? Pass the right parameters?
- Iterate on your
application_promptandplanning_hintsuntil 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.
Further Reading
Section titled “Further Reading”- Planner API Reference — pipeline stages, response modes, and prompt assembly
- Training & Validation — automated testing of planner behavior
- Planner Specification — full technical specification (Section 6: Prompt Architecture)