Skip to content

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.

Zakardo uses a two-layer plan format:

LayerProduced ByPurpose
Plan DraftPlanner (LLM)Minimal, human-readable sequence of steps with simplified bindings
Full Plan IREnrichment 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.

{
"goal": "List all VIP contacts",
"steps": [
{
"capability": "contacts_list",
"version": "1.0.0",
"description": "Retrieve contacts filtered by VIP tag",
"inputs": { "tag": "VIP" }
}
]
}

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_on relationships computed from data flow
  • Step indices — Deterministic ordering with output_key assignments
  • Plan metadata — Unique plan_id, version, name, lifecycle state
  • Error policy — Retry behavior, compensation steps, error handlers
  • Execution constraints — Timeouts, mode requirements

The Planner generates plans using backward chaining — starting from the desired output and working backwards to fill gaps:

  1. Identify the goal output the user wants
  2. Find capabilities that can produce that output
  3. Check if the capability’s inputs are available
  4. If not, find capabilities that produce the missing inputs
  5. Repeat until all inputs are satisfied or provided by the user

This produces minimal plans — only the capabilities actually needed to achieve the goal.

Plans move through a trust lifecycle managed by the Plan Library:

CANDIDATE → SHADOW → PROMOTED → DEPRECATED
↓
QUARANTINED
StateMeaning
CANDIDATENewly generated, unproven plan
SHADOWBeing tested against training datasets in parallel
PROMOTEDProven reliable — used as the first source for matching intents
DEPRECATEDReplaced by a better plan, no longer used for new intents
QUARANTINEDFailed 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.

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 response

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.