Cloudflare Runtime
Pages + Workers
Pages hosts the internal reference and web interface; Workers run API, webhook, and queue logic.
Internal Architecture Reference
Agency OS operating architecture
This internal Pages site collects architecture decisions, domain documentation, diagrams, and skill inventory for the team building and operating Agency OS.
State + Artifacts
D1 + R2
D1 stores operational state and current facts; R2 stores larger artifacts, snapshots, and audit packages.
Secrets Boundary
Secrets Store
API tokens and OAuth credentials are bound at runtime, never committed to source or rendered to dashboards.
Executive Summary
CEO briefingAsana is the work front door
Consultants and admins create or update Asana tasks. Asana webhooks notify Agency OS, so tasks can trigger build runs, agent runs, or client data setup work without staff leaving Asana.
Cloudflare is the operating platform
Cloudflare Pages, Workers, Queues, D1, R2, Browser Run, and Secrets Store keep the system serverless and reduce vendor sprawl.
Dashboards consume prepared facts
The Agency OS web interface reads dashboard feeds from the Client Data Plane. It does not query GA4, Search Console, Asana, or ad platforms on page load.
Humans keep approval control
Agents can prepare work, comments, artifacts, and dashboard facts, but review-ready states and visibility decisions remain explicit.
Cloudflare-First Runtime Map
Internal referenceCloudflare Resource Inventory
Current dev runtime| Layer | Resource | Role | Notes |
|---|---|---|---|
| Pages | agency-os-architecture-site | Internal living reference for system architecture, ADRs, docs, diagrams, and skills. | No API proxy and no dashboard data secret. |
| Pages | agency-os-web-interface | Operational Agency OS web interface. Starts with dashboards; later admin configuration and onboarding. | Has encrypted Pages secret AGENCY_OS_API_BASE_URL and office-IP middleware restriction. |
| Workers | agency-os-dev-platform-build-control-plane | API, Asana webhook intake, queue consumer, Client Data Plane fixture/data endpoints, health checks. | Current public dev worker runs on workers.dev. |
| D1 | agency-os-dev-platform-build-runs | Operational database for build runs, Team Agent runs, Client Data Plane setup, facts, access grants, and access logs. | Binding: PLATFORM_BUILD_DB. |
| R2 | agency-os-dev-technical-seo-audits | Stores larger generated artifacts such as technical SEO audit packages. | Future Client Data Plane snapshots and curated payloads also belong in R2. |
| Queues | agency-os-dev-platform-build-runs | Decouples Asana webhook receipt from build-run processing. | Binding: PLATFORM_BUILD_QUEUE. |
| Queues | agency-os-dev-team-agent-runs | Decouples Asana webhook receipt from Team Agent assessment and execution. | Binding: TEAM_AGENT_QUEUE. |
| Secrets Store | Agency OS credential store | Runtime binding for Asana, Google OAuth, Accuranker, DataForSEO, Semrush, Ahrefs, and Browser Run credentials. | Secret values are not stored in Git, D1, R2, Asana comments, or dashboard payloads. |
| AI Gateway | OpenAI provider, gpt-5.5 model config | Central policy/observability point for agent model calls. | Payload logging defaults off unless explicitly enabled. |
| Browser Run | Cloudflare Browser Run API | Crawl/render evidence for SEO reporting and technical audit workflows. | Uses a scoped token from Secrets Store. |
Terminology note: Cloudflare uses D1 for serverless SQL and R2 for object storage. If you see R1 or D2 in discussion notes, read that as R2/D1 unless we deliberately introduce a different product later.
Asana Operating Model
Work source
Platform Build project
Build tasks move through intake, clarification, ready, in progress, review, blocked, merged/done, or error sections.
Jessie Intake project
Team Agent work enters a dedicated intake queue. Current dev requires the task to be assigned to Jessie before hosted execution is eligible.
Client brand projects
Each client account/brand becomes a single Asana project. Subscription sections, such as SEO, group the planned and completed work that can later appear on dashboards.
Client-visible task flag
Tasks are private by default. Consultants or agents can mark selected subscription tasks as client visible when strategy or sprint planning is ready.
Webhook + Queue Flow
Event-driven
Asana sends webhook
Asana calls POST /webhooks/asana when configured projects or tasks change. The Worker supports the X-Hook-Secret handshake.
Worker verifies signature
The Worker requires X-Hook-Signature and validates it against ASANA_WEBHOOK_SECRET before accepting event payloads.
Events are grouped by task
The Worker groups webhook events by Asana task GID and creates idempotent Platform Build and Team Agent candidate messages.
Queues absorb processing
Messages go to PLATFORM_BUILD_QUEUE and TEAM_AGENT_QUEUE so webhook acknowledgement is fast and downstream work can retry safely.
D1 records state
Queue consumers persist run state and event history in D1, detect duplicates, and decide whether a task is ignored, blocked, ready, or review-ready.
Asana Task Lifecycle
Operational control| Area | Asana state or signal | Agency OS action | Stored where |
|---|---|---|---|
| Platform Build | Task enters build project or relevant section | Create candidate Build Run and enqueue processing. | D1 build run tables and events |
| Team Agent | Task assigned to Jessie or matching configured eligibility | Assess skill request, context, credentials, and readiness. | D1 team agent run tables and events |
| Agent Execution | Task is ready | Run the selected skill, create review comment, and attach artifacts when needed. | D1 run state, Asana comments, R2 artifacts when large |
| Client Data Plane | Client brand/subscription setup is approved | Activate source assets, data products, subscription data views, and dashboard inclusion. | D1 setup/fact tables, R2 snapshots later |
| Client-visible Tasks | Task marked client visible and assigned to a subscription section | Expose task name, status, subscription, planned date, or Asana completed time in dashboard facts. | Prepared dashboard fact feed from stored facts |
| Errors | Checks fail or execution cannot continue | Create or update platform error tasks and keep evidence for review. | D1 event history, Asana error/regression section |
Client Data Plane
Dashboard facts
Admin-led onboarding
Agency staff configure the client group, brand, source assets, subscription data views, and dashboard surface inclusion.
Source ingestion
Connectors collect GA4, Search Console, Asana, Accuranker, Google Ads, Meta, HubSpot, and Harvest data as roadmap slots.
Raw snapshots
Raw source responses are retained in R2-shaped object paths for audit and reprocessing.
Normalized facts
Curated facts, freshness state, lineage refs, dashboard access grants, and agent access logs are indexed in D1.
Web interface
Dashboards read prepared fact feeds from the Worker. They do not query source platforms directly on page load.
Secrets + Access Boundary
No secrets in data
Secrets Store
Worker credentials are injected through Cloudflare Secrets Store bindings such as AGENCY_OS_ASANA_AGENT_PAT, Google OAuth credentials, Accuranker, DataForSEO, Semrush, Ahrefs, and Browser Run.
Web interface API origin
The web interface uses an encrypted Pages secret for AGENCY_OS_API_BASE_URL. The architecture site does not have this secret.
Fact and artifact policy
Secrets must not be written into D1 records, R2 objects, Asana comments, generated reports, dashboard HTML, or logs.
Staff now, clients later
The web interface is staff-only during development. Future client credentials and client-shareable access must use explicit grants and separate access controls.
What Exists Now
Live dev- Architecture site: internal Pages site with docs, ADRs, diagrams, resource inventory, and skill inventory.
- Agency OS web interface: separate Pages site serving the fixture-backed Plunkett SEO dashboard.
- Worker API: health, Asana webhook intake, queue consumer, Client Data Plane fixture seed, dashboard fact feed, and metadata-level agent fact query logging.
- D1: migrations include build runs, Team Agent runs, Client Data Plane setup, facts, dashboard configuration, and agent data access logs.
- R2: technical SEO audit bucket is configured for generated audit packages and larger artifacts.
- Queues: Platform Build and Team Agent queues are configured to keep webhook intake fast and processing retryable.
Near-Term Roadmap
Next build slices- Admin configuration UI: create client groups, business units, subscription setup, source assets, and activation checks inside the web interface.
- Real ingestion: replace fixture feeds with scheduled/daily connectors for GA4, Search Console, Asana, Accuranker, Google Ads, Meta, HubSpot analytics, and Harvest reconciliation.
- Cloudflare Workflows and Containers: target path for longer-running builder execution and build/check automation after branch creation.
- R2 SQL: later analytics path for larger historical reporting datasets stored in R2.
- Client access: explicit dashboard access grants and client credentials after staff-only development proves the data and visibility model.
Agent Skills Architecture
38 indexedWhere Skills Live
- Repo skills: skills/*/SKILL.md stores Agency OS delivery skills such as SEO reporting and Google Ads reporting.
- Agent skills: .agents/skills/*/SKILL.md stores repo-local operating skills for builders, triage, diagnostics, handoff, and architecture work.
- System/plugin skills: installed Codex skills live outside this repo and are available to the agent runtime, but the architecture site indexes the repo-owned skills first.
- Skill contract: each SKILL.md explains when to use the skill, required inputs, safety rules, and expected outputs.
How Skills Run
- Trigger: a consultant or admin asks for work in Asana, or an agent receives a build task.
- Assessment: Agency OS checks the task, context, credentials, and requested skill before marking the run ready.
- Execution: the selected skill gathers approved data, prepares artifacts, and writes a review-ready Asana comment or attachment.
- Control: skills do not publish client-facing changes directly unless the workflow explicitly allows it.
Indexed Skill Examples
SKILL
.agents/skills/caveman/SKILL.md
Diagnose
.agents/skills/diagnose/SKILL.md
SKILL
.agents/skills/grill-me/SKILL.md
ADR Format
.agents/skills/grill-with-docs/ADR-FORMAT.md
CONTEXT.md Format
.agents/skills/grill-with-docs/CONTEXT-FORMAT.md
SKILL
.agents/skills/grill-with-docs/SKILL.md
SKILL
.agents/skills/handoff/SKILL.md
Deepening
.agents/skills/improve-codebase-architecture/DEEPENING.md
Interface Design
.agents/skills/improve-codebase-architecture/INTERFACE-DESIGN.md
Language
.agents/skills/improve-codebase-architecture/LANGUAGE.md
Cloudflare Changelog Notes
Checked 20 May 2026- 2026-05-19 Artifacts events: Cloudflare can now emit repository lifecycle events. Useful later for repo-driven build/review automation.
- 2026-05-18 Artifacts CLI: Wrangler can manage Artifacts namespaces and repos, which may simplify future agent-created repository flows.
- 2026-05-18 local tunnels: Wrangler and Vite can expose local dev servers through Cloudflare Tunnel, useful for webhook testing and stakeholder previews.
- 2026-05-15 R2 SQL: JOINs, subqueries, and multi-table queries strengthen the later analytics path over historical R2 data.
- 2026-05-14 Workers Domains tab: Cloudflare improved Worker domain management, useful when moving dev endpoints behind stable domains and access policies.
Primary Architecture Docs
View library- ADR 0006: Cloudflare Client Data Plane docs/adr/0006-cloudflare-client-data-plane.md ADR 0006: Cloudflare Client Data Plane Date: 2026-05-19 Status: Accepted Context Agency OS needs a data and presentation foundation for client onboarding, source configuration, ingestion, dashboards, future reporting, future alerts, and agent access to trusted
- Client Data Plane Specification docs/client-data-plane-specification.md Client Data Plane Specification Status: draft for review Updated: 2026-05-19 Purpose The Client Data Plane is the Cloudflare-first subsystem that stores client onboarding configuration, source bindings, ingestion runs, normalized facts, freshness state, and da
- Client Data Plane Build Blueprint docs/client-data-plane-build-blueprint.md Client Data Plane Build Blueprint Status: draft implementation blueprint Updated: 2026-05-19 Objective Build the first Cloudflare-first Client Data Plane tracer bullet for Agency OS. The first build should prove that Agency OS can onboard a brand/subscription,
- Platform Build Loop MVP docs/architecture/platform-build-loop-mvp.md Platform Build Loop MVP Purpose The Platform Build Loop is the governed operating loop for changing the Agency Operating System itself. It turns Asana Platform Build Tasks into bounded builder-agent work, review artifacts, and human merge decisions. This MVP p
Operating Loops
Current modelPlatform Build Loop
Asana build tasks, builder agents, checks, review artifacts, and human merge decisions.
Team Agent Work
Staff delegate delivery work through governed agent skill execution and human approval.
Client Data Plane
Onboarding setup, source bindings, fixture/dev/prod facts, dashboard feeds, and agent data access logs.
Web Interface
Dashboards, admin configuration, onboarding, and future client-shareable views live on a separate Pages domain.
Related Runtime Surfaces
Different domain boundaryArchitecture Site
Internal living reference for how Agency OS is put together. This site should stay staff-only.
Agency OS Web Interface
Dashboard review today; admin configuration, onboarding, and future client-shareable views later.
Open web interfaceSkill Inventory
View skillsSKILL
.agents/skills/caveman/SKILL.md
Diagnose
.agents/skills/diagnose/SKILL.md
SKILL
.agents/skills/grill-me/SKILL.md
ADR Format
.agents/skills/grill-with-docs/ADR-FORMAT.md
CONTEXT.md Format
.agents/skills/grill-with-docs/CONTEXT-FORMAT.md
SKILL
.agents/skills/grill-with-docs/SKILL.md
SKILL
.agents/skills/handoff/SKILL.md
Deepening
.agents/skills/improve-codebase-architecture/DEEPENING.md