Plans
A plan is the core artifact in Zakardo. It is a structured, versioned, executable program that defines exactly what the agent will do — which capabilities to invoke, in what order, with what data, and under what governance rules.
Plans are not emergent behavior from prompt engineering. They are inspectable programs that can be reviewed, validated, tested, versioned, and promoted through a trust lifecycle.
Two-Layer Design
Section titled “Two-Layer Design”Zakardo uses a two-layer plan format:
| Layer | Produced By | Purpose |
|---|---|---|
| Plan Draft | Planner (LLM) | Minimal, human-readable sequence of steps with simplified bindings |
| Full Plan IR | Enrichment Pipeline (deterministic) | Fully typed, execution-ready format with schemas, dependency graph, metadata, and error policies |
The LLM only produces the minimal Plan Draft. All type inference, dependency analysis, and metadata generation happens deterministically in the Enrichment Pipeline.
Plan Draft (LLM Output)
Section titled “Plan Draft (LLM Output)”{ "goal": "List all VIP contacts", "steps": [ { "capability": "contacts_list", "version": "1.0.0", "description": "Retrieve contacts filtered by VIP tag", "inputs": { "tag": "VIP" } } ]}Full Plan IR (Enriched)
Section titled “Full Plan IR (Enriched)”After enrichment, the plan includes:
- Resolved schemas — Input/output JSON Schemas inferred from capability definitions
- Typed bindings — Path expressions referencing the Execution Context
- Dependency graph —
depends_onrelationships computed from data flow - Step indices — Deterministic ordering with
output_keyassignments - Plan metadata — Unique
plan_id, version, name, lifecycle state - Error policy — Retry behavior, compensation steps, error handlers
- Execution constraints — Timeouts, mode requirements
Backward Chaining
Section titled “Backward Chaining”The Planner generates plans using backward chaining — starting from the desired output and working backwards to fill gaps:
- Identify the goal output the user wants
- Find capabilities that can produce that output
- Check if the capability’s inputs are available
- If not, find capabilities that produce the missing inputs
- Repeat until all inputs are satisfied or provided by the user
This produces minimal plans — only the capabilities actually needed to achieve the goal.
Plan Lifecycle
Section titled “Plan Lifecycle”Plans move through a trust lifecycle managed by the Plan Library:
CANDIDATE → SHADOW → PROMOTED → DEPRECATED ↓ QUARANTINED| State | Meaning |
|---|---|
| CANDIDATE | Newly generated, unproven plan |
| SHADOW | Being tested against training datasets in parallel |
| PROMOTED | Proven reliable — used as the first source for matching intents |
| DEPRECATED | Replaced by a better plan, no longer used for new intents |
| QUARANTINED | Failed reliability thresholds, removed from active use |
Promotion and quarantine are driven by trust scoring — a weighted composite of execution success rate, training pass rate, user approval rate, and other signals.
Data Flow Between Steps
Section titled “Data Flow Between Steps”Steps in a plan communicate through the Execution Context — a runtime accumulator that holds all step outputs. Bindings use path expressions to reference data:
$context.steps.step_0.output.contacts → Output of step 0$context.plan.inputs.tag → Plan-level input$context.interaction.step_1.response → User interaction responsePlans Always Succeed
Section titled “Plans Always Succeed”A core design principle: plans always succeed. The Planner is policy-aware — before including a capability in a plan, it checks whether the user has permission to execute it. If a capability is blocked by policy, the Planner finds an alternative (e.g., submitting a deletion request instead of deleting directly). A plan presented to the user is a promise: if approved, it will work.
Further Reading
Section titled “Further Reading”- Enrichment Pipeline API — the 8 deterministic steps
- Validator API — the 10 checks every plan must pass
- Plan Library API — lifecycle management and trust scoring