Skip to content

Design Principles

These principles guide every decision in the Zakardo framework — from API design to governance model to frontend architecture. They are not aspirational; they are implemented.

Plans are the core artifact of Zakardo. They are not an implementation detail, a log entry, or an emergent property of prompt engineering. They are structured, versioned, inspectable programs that can be reviewed, validated, tested, promoted, and audited.

A plan defines exactly what will happen before it happens. Users can preview plans before approving execution.

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 — for example, submitting a deletion request instead of deleting directly (the Request Pattern).

A plan presented to the user is a promise: if you approve this, it will work.

3. Capabilities Declare Effects Explicitly

Section titled “3. Capabilities Declare Effects Explicitly”

No hidden side effects. Every capability states what it reads, writes, or destroys (effect class) and where it runs (boundary). This explicit declaration enables automatic governance without per-capability configuration.

effect_class: 'DESTRUCTIVE' // The runtime knows this destroys data
boundary: 'REMOTE' // The runtime knows this calls an external service

4. External Side Effects Are Governed and Gated

Section titled “4. External Side Effects Are Governed and Gated”

Nothing leaves the system boundary without policy evaluation. External writes (WRITE_EXTERNAL) are staged in an outbox and only committed after all plan steps succeed. Destructive operations require human approval gates by default.

Developers bring their own database and ORM (Prisma, Drizzle, etc.). Capabilities access business data through the developer’s data layer. Zakardo stores only its own runtime data (checkpoints, traces, events) in a separate ZakardoStore.

This means Zakardo never becomes a bottleneck for your data access patterns, and you are free to use any database, ORM, or data architecture you prefer.

The v1 runtime, capabilities, and SDK are TypeScript with strict mode. Type safety flows from capability schemas through the enrichment pipeline to execution. Other languages are supported via the REMOTE boundary (capabilities implemented as HTTP/gRPC services).

Trust is earned by running plans against known datasets and verifying results — not by assertion. The Training System executes plans, compares outputs against expectations, detects regressions, and automatically promotes or quarantines plans based on measured reliability.

Every execution produces an immutable, append-only trace that records everything that happened. Traces are not disposable logs — they are structured, typed records that enable:

  • Auditing — complete record of what happened and why
  • Debugging — step-by-step replay of execution
  • Regression testing — compare current behavior against previous runs
  • Plan promotion — trust scores are computed from trace data

The presentation layer uses A2UI (Agent-to-UI protocol) — a declarative, streaming, framework-agnostic UI specification. Capabilities declare what UI they produce. The runtime streams A2UI messages as plans execute. Developers build their app shell in their preferred framework (React, Vue, Angular) and embed Zakardo surfaces where agent-driven UI should appear.

10. Full-Stack Framework, Not an Integration Library

Section titled “10. Full-Stack Framework, Not an Integration Library”

Zakardo provides the complete development experience: Hono-based backend, data layer adapters, A2UI frontend, CLI tooling, and Zakardo Studio. Not everything goes through intents — a Foundation Layer handles non-agentic concerns (auth, billing, CRUD, webhooks).

11. Open Framework, Commercial Control Plane

Section titled “11. Open Framework, Commercial Control Plane”

The full-stack framework is open source (Apache 2.0). The governance, registry, and monitoring layer (Zakardo Cloud) is the commercial product. The runtime functions independently without the cloud.