Architecture decisions
ADR Index.
Every Architecture Decision Record at a glance, with status and a one-line summary. Full text lives in the Source Library.
Architecture Decision Records
The decisions that shaped Agency OS, newest at the bottom. This index is generated straight from the ADR files in docs/adr/, so a new record appears here the moment it ships. Each links to its full text in the Source Library. Two records share the number 0007.
| ADR | Decision | Status |
|---|---|---|
| 0001 | Clean Agency OS Repository Build Agency OS in a fresh Cloudflare-first repository rather than extending the old Supabase-shaped repo, which stays reference-only. |
Accepted |
| 0002 | Hosted Platform Build Loop Control Plane Run the hosted build loop on Cloudflare Workers/Containers with GitHub as repo and PR surface only, not GitHub Actions as CI. |
Accepted |
| 0003 | Hosted Team Agent Work Intake Use the always-on Worker to notice, queue, and assess Asana-delegated Jessie tasks into durable D1 run state. |
Accepted |
| 0004 | Hosted Team Agent Execution MVP Add the first hosted execution slice so a ready task produces a review-required artifact, leased ready-to-running. |
Accepted |
| 0005 | Live Plunkett SEO Data Snapshot MVP Fetch real Search Console and GA4 data via Secrets Store credentials so hosted SEO reviews use live, internal-only data. |
Accepted |
| 0006 | Cloudflare Client Data Plane Build a Cloudflare-native client data plane owning registry, ingestion, normalized facts, and dashboards instead of live API proxying. |
Accepted |
| 0007 | Jessie Teams Conversation Slice Add a Teams bot for Jessie as a conversation and approval surface; Asana and Agency OS stay the systems of record. |
Accepted |
| 0007 | Tracked Keyword Performance As Optional Primary SEO Rank Evidence When a rank tracker is configured, tracked-keyword aggregates become the primary SEO rank facts. Shares the 0007 number. |
Accepted |
| 0008 | Box Client Context Ingestion Treat Box as a governed context source ingested into immutable Context Pack Versions with freshness gates, not live browsing. |
Accepted |
| 0009 | Team Agent Runtime Extraction Extract a behaviour-preserving slice of run state, watchdog, and feedback SQL out of the Worker index.ts for locality. |
Accepted |
| 0010 | Team Agent Runtime Observability Add compact D1 run-step traces and deduped platform-issue records with operator endpoints to make runtime phase inspectable. |
Accepted |
| 0011 | Live AI Gateway Model-Call Adapter Add one central Cloudflare AI Gateway adapter for live model calls, starting with bounded narrative drafting, payload logging off. |
Accepted |
| 0012 | Major-Task Architecture Logging Hook Require every major task to record architectural changes in ADRs, decisions, CONTEXT.md, and the change log surfaced on this site. |
Accepted |
| 0013 | Asana-Sourced Jessie Scheduling and Standing Work Keep Asana as the source of truth for scheduled and recurring work, with Cloudflare owning the execution clock and projections. |
Accepted |
| 0014 | LLM-First Client-Context-Aware Team Agent Runtime Make insight skills LLM-first via AI Gateway with approved client-context capsules; keep deterministic code for data and guardrails. |
Accepted |
| 0015 | R2-Backed Client Context Lake Build a derived R2/D1/Vectorize context lake from Box files with a prompt-readiness gate that fails closed when no pack exists. |
Accepted |
| 0016 | Single Live Production Client Environment Make prod the only live client data environment until a dev environment is designed; fixture and dev become historical labels. |
Accepted |
| 0017 | Approved Strategy Task Creation Let Jessie create Asana tasks from an approved strategy plan, gated by explicit consultant approval with idempotent reuse and audit traces. |
Accepted |
| 0018 | Agency Brain Lean Context Runtime Give Jessie a small task context capsule with tool pointers for deeper retrieval and background memory maintenance, avoiding prompt dumps. |
Accepted |
| 0019 | Agent-Loop Execution Core for Team Agent Work Replace bespoke per-skill TypeScript pipelines with a pluggable execution adapter that runs CLI agent harnesses in Cloudflare Sandboxes against executable SKILL.md docs, keeping the existing governance shell (Asana, queues, D1/R2, approval gates). |
Accepted |
Source References
- docs/adr/
- docs/Claude/Claude_08_duffle_architecture_site_revamp.md