Design decisions¶
Every load-bearing choice in Kampong Agents is written down as an architecture decision record
(ADR): what was decided, the alternatives, and the trade-off. They're the memory of why the system
is shaped the way it is. The full set lives in docs/adr/; here they are grouped by theme.
Shape of the product¶
- ADR-0001: Single-agent scope for v1
- ADR-0002: YAML as source of truth, one-way export (source-of-truth wording superseded by ADR-0054)
- ADR-0005: A local web app, not a desktop app
- ADR-0008: External-edit-first workflow (local mode; narrowed by ADR-0054)
- ADR-0053: First user, business model, and agent count are not positioning
- ADR-0054: The spec is the truth; YAML is its interchange format
- ADR-0055: Step addressing and the spec mutation API
- ADR-0021: Real-world workflows direction (V9)
- ADR-0022: Deployment model — two paths, one foundation
- ADR-0023: V10 monetization model
- ADR-0024: V10 hosting and credential custody
Runtime and execution¶
- ADR-0003: Mastra + TypeScript runtime
- ADR-0004: No LLM gateway for the MVP
- ADR-0009: Confidence signal and workflow execution
- ADR-0010: Exported runtime is vendored, not re-templated
Canvas, storage, and stack¶
Authorable real-world workflows (V9–V11)¶
The platform primitives that let a real workflow be authored, run unattended and exported: an expression language, typed step output, a durable state store, a component repository, and the step kinds built on them.
- ADR-0025: Component model and repository
- ADR-0026: Component trust tiers, vetting, and MCP as an import layer
- ADR-0027: Expression language and data model
- ADR-0028: A durable state store
- ADR-0029: Connector manifest schema
- ADR-0030: First-party components and legacy desugaring
- ADR-0031: Component permissions: what is enforced
- ADR-0032: Credential probes in
kampong doctor - ADR-0033: An export verifies its components
- ADR-0034: Record and replay at the invoke boundary
- ADR-0035: Retry for module ops
- ADR-0036: The canvas shows component trust
- ADR-0037: Revocation and release signing
- ADR-0038: Structured step output
- ADR-0039: Local Variables panel
- ADR-0040: Schedule trigger
- ADR-0041:
transform,validateanddedupesteps - ADR-0042: Persisted pending approvals
- ADR-0043: The
foreachstep - ADR-0044: Supabase and Alpha Vantage components
- ADR-0045: The
branchandstopsteps - ADR-0046: Templates and market-etl
- ADR-0047: Webhook auth presets and trigger filter
- ADR-0048: Gmail over IMAP as a separate component
- ADR-0049: Slack approvals on a laptop
- ADR-0050: The poll trigger
- ADR-0051: Record and replay for model calls
- ADR-0052: YAML serialisation keeps the author's style
- ADR-0053: First user, business model and agent count
- ADR-0054: The spec is internal, YAML is the interchange
- ADR-0055: Step addressing and the mutation API
- ADR-0056: The hosted server runs spec 1.1
- ADR-0057: Hosted webhook secret per deployment
- ADR-0058: Hosted egress guard
- ADR-0059: Canvas v2 look and feel
- ADR-0060: Workflow assistant (chat builder)
- ADR-0062: Undo and redo of canvas edits
Hosted mode and the roadmap¶
The hosted backend and its canvas UI (ADR-0013 to 0020) are built but not yet deployed. Sub-agents and governance (ADR-0011, 0017) are still planned; the workflow assistant (ADR-0060) is the first part of spec generation (ADR-0012).
- ADR-0011: Sub-agents data model and org-chart canvas
- ADR-0012: Spec generation, evaluation, and fallback
- ADR-0013: V5 hosting, deployment, and gateway topology
- ADR-0014: V5 database and multi-tenancy model
- ADR-0015: V5 auth and account model
- ADR-0016: V5 BYOK secret custody
- ADR-0017: V6 enterprise governance model
- ADR-0018: Workspace-member bootstrap under RLS
- ADR-0019: Authenticated, workspace-scoped routes
- ADR-0020: Canvas hosted mode and spec selection
Adding a new one¶
When a decision turns out to be load-bearing, it gets its own docs/adr/NNNN-*.md, numbered
sequentially. Keep them short and immutable-ish: an ADR records what was decided at a point in
time, not the current state of the code.