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.
1. Plans Are First-Class Programs
Section titled “1. Plans Are First-Class Programs”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.
2. Plans Always Succeed
Section titled “2. 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 — 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 databoundary: 'REMOTE' // The runtime knows this calls an external service4. 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.
5. Zakardo Does Not Own Business Data
Section titled “5. Zakardo Does Not Own Business Data”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.
6. TypeScript First
Section titled “6. TypeScript First”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).
7. Learning Is Execution-Validated
Section titled “7. Learning Is Execution-Validated”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.
8. Replay and Trace Are Core Features
Section titled “8. Replay and Trace Are Core Features”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
9. The Frontend Is Plan-Aware
Section titled “9. The Frontend Is Plan-Aware”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.