Skip to content
agora

Decision records

This section holds the accepted Architecture Decision Records (ADRs) for agora. The format follows Michael Nygard’s “Context / Decision / Consequences” template: each ADR opens with the forces in tension, states the choice, and records the consequences (what becomes easier, what becomes harder, what trade-offs were accepted).

Each ADR is immutable once accepted. Superseding a decision means adding a new ADR that references the old one, not editing the existing file.

Index

Section titled “Index”
  • 0001 — Agora packages publish under the @quarry-systems/agora-* npm scope.
  • 0002 — Agora lives in a dedicated repository, not inside an existing Quarry Systems monorepo.
  • 0003 — The RuntimeAdapter interface ships in MVP with the Claude Code adapter as the sole implementation.
  • 0004 — Lifecycle event vocabulary is closed at six kinds for MVP and extensible at minor versions.
  • 0005 — Privileged deploy-time operations (register, assign) are never reachable through agora-mcp.
  • 0006 — agora-mcp authentication is “whoever launched the server”; host-level IAM is the trust boundary.
  • 0007 — Inline secret TTL is auto-computed from dispatch timeout plus a 5-minute cleanup grace.
  • 0008 — needs_input uses request-stop-restart (Shape A), not in-flight ask.
  • 0009 — needs_input is signaled by a sentinel file at a documented path, not by an exit code.
  • 0010 — No agora.workflow() / agora.procedure() primitive in MVP; integrators wrap dispatch() themselves. (Partially superseded by 0018.)
  • 0011 — No entrypoint override at dispatch time; customization goes through worker images or agora-setup.sh.
  • 0012 — Notifications live in two homes by design: capability content (behavior-tied) and dispatch field (operational).
  • 0013 — MVP is strictly single-namespace; no public cross-namespace addressing.
  • 0014 — Stdout is capped at 4 MiB and stderr at 256 KiB on DispatchResult, with explicit truncation markers.
  • 0015 — Capability size cap is 50 MiB, rejected synchronously at register() time.
  • 0016 — cancel() is in MVP, not v0.2; best-effort cancellation via provider stop + worker SIGTERM trap.
  • 0017 — Agora is source-available under BSL 1.1 (no hosted-service Additional Use Grant; 4yr → Apache-2.0), superseding the earlier FSL-1.1-MIT choice.
  • 0018 — agora ships orchestration as a separate opt-in layer (agora-orchestrator / offload), partially superseding ADR-0010’s “orchestration only above agora / out of scope forever” posture. The client-SDK workflow-primitive rejection still stands.

Source

Section titled “Source”

These ADRs were extracted from §10.1 of the agora MVP design spec (docs/superpowers/specs/2026-05-21-agora-mvp-design.md). Each ADR’s ## Decision section quotes the relevant spec passage verbatim.