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, runtime maps, hosted Jessie execution status, marketing skill prompts, and runbooks for the team building and operating Agency OS.
Hosted Execution
7 Jessie paths
SEO, GA4, Google Ads, Meta Ads, Integrated Performance Report, technical SEO audit, and the Jessie workbench run from Asana intake.
Evidence Library
Staff-only registry
Report artifacts, files, provenance, and revision rounds are indexed in D1 with larger packages referenced from R2.
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.
Admin config drives agent readiness
The Agency OS web interface now separates Manage Users and Manage Clients. Client setup is captured as Sources, Context, and Users so agents know which tools and facts are safe to use.
Evidence stays inspectable
Jessie still posts artifacts to Asana, but the Report Artifact Registry gives staff a durable index for reuse, auditability, evidence lookup, and revision history.
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 for dashboards, Report Library, and Admin & Configuration CRUD. | Has encrypted Pages secrets for the API origin and internal service token, office-IP middleware restriction, report artifact views, and admin deep links by Business Unit. |
| Workers | agency-os-dev-platform-build-control-plane | API, Asana webhook intake, queue consumer, Admin Registry, Report Artifact Registry, Client Data Plane fixture/data endpoints, health checks. | Current public dev worker runs on workers.dev; Admin Registry, Report Artifact Registry, and Client Data Plane routes require X-Agency-OS-Internal-Token. |
| D1 | agency-os-dev-platform-build-runs | Operational database for build runs, Team Agent runs, report artifact registry, Client Data Plane setup, facts, access grants, and access logs. | Binding: PLATFORM_BUILD_DB. Registry tables index artifacts, files, channel provenance, and revision rounds. |
| R2 | agency-os-dev-technical-seo-audits | Stores larger generated artifact packages such as technical SEO crawl/evidence bundles. | D1 stores stable keys and metadata for audit packages. |
| R2 | agency-os-dev-client-data-plane | Stores Raw Source Snapshot payloads for Client Data Plane ingestion runs. | Binding: CLIENT_DATA_PLANE_BUCKET. Strategic Settlements manual GA4/GSC refresh writes raw snapshots here while D1 stores metadata and curated facts. |
| 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, Google Ads, Meta, 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 task and task-comment story 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, needs clarification, 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 or manually refreshed | Activate source assets, data products, subscription data views, dashboard inclusion, and GA4/GSC fact refreshes. | D1 setup/fact tables, R2 raw snapshots |
| 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 |
Report Artifact Registry
Staff-only evidence library
Jessie produces a review artifact
SEO, GA4, Google Ads, Meta Ads, Integrated Performance Report, technical SEO audit, and useful general workbench runs keep their existing Asana attachment/comment write-back.
Worker registers metadata in D1
The control-plane Worker writes report_artifacts, report_artifact_files, report_channel_provenance, and report_revision_rounds rows tied to the Team Agent run and Asana task.
R2 holds larger packages
Technical SEO crawl data, CSV exports, raw debug JSON, screenshots, and future larger evidence bundles live in R2 when available; D1 stores stable keys and references.
Web interface exposes the library
The staff-only /reports/ view lists artifacts by Business Unit, period, skill, status, files, channel provenance, Asana task link, and revision history.
Boundary
- Asana remains canonical: task discussion, consultant approval, and feedback rounds stay on the original Asana task.
- D1 indexes artifacts: the registry is the durable lookup surface for artifact reuse, auditability, and evidence discovery.
- Staff-only: the library is not a client portal and does not publish, email, or expose reports to clients.
- Sanitized metadata: no credentials, provider tokens, or raw sensitive payloads are returned by the registry API by default.
Agent Marketing Skills
Open skill library
Organic search
SEO Reporting
Live dev smoke-tested
Builds a detailed internal forensic SEO report from live Search Console, GA4, rank/SERP, backlink, and bounded crawl evidence.
Please do an SEO report for Plunkett Homes last month.
Analytics
GA4 Analysis & Reporting
Live data smoke-tested
Builds an internal GA4 analytics report with major wins, major issues, and watch items first, followed by supporting movement detail.
Please do a GA4 report for Plunkett Homes last month.
Paid search
Google Ads Reporting
Live data smoke-tested
Builds an internal paid-search performance report from Google Ads evidence with GA4 outcome context and bounded landing-page checks.
Please do a Google Ads report for Plunkett Homes last month.
Paid social
Meta Ads Reporting
Live API path implemented
Builds an internal Meta Ads performance report from the Meta Marketing API with campaign, ad set, creative, placement, and action evidence.
Please do a Meta Ads report for Plunkett Homes last month.
Multi-channel
Integrated Performance Report
Live dev smoke-tested
Builds a review-required client report package from SEO, GA4, Google Ads, and Meta evidence, with an internal appendix and structured evidence model.
Jessie, create an Integrated Performance Report for Plunkett Homes for April 2026 covering SEO, GA4, Google Ads, and Meta Ads.
Crawl audit
Technical SEO Audit
Hosted audit path
Runs a public-site crawl audit with Browser Run, deterministic technical SEO checks, PageSpeed evidence, and an R2/Asana evidence package.
Run a technical SEO audit for https://www.example.com.au.
Workbench
General Jessie Workbench
Planner live
Handles arbitrary Jessie-assigned consultant requests by interpreting the brief, asking clarifying questions when needed, selecting approved tools, and executing read-only analysis only when the plan is confident.
Please analyse the existing SEO keyword list for Plunkett Homes in AccuRanker and find gaps using any other tool at your disposal.
Recent System Changes
Hosted Jessie path
Multi-skill hosted execution
The Team Agent queue can execute SEO reporting, GA4 reporting, Google Ads reporting, Meta Ads reporting, Integrated Performance Report, technical SEO audit, and governed Jessie workbench requests.
Integrated report package
The aggregate-performance-reporting route now produces `client-report.html`, `consultant-appendix.html`, and `evidence.json` on the same Asana task for consultant approval.
Report Artifact Registry
Review artifacts, package files, channel provenance, and revision rounds are indexed in D1 and visible in the staff-only Report Library.
Performance snapshot evidence fix
The Integrated Performance Report now renders actual channel performance evidence in Performance Snapshot and What Changed instead of channel draft-label text.
Post-review feedback rounds
Human comments after review_ready are classified as acceptance, revision request, discussion, scope change, or no-op, then processed on the same canonical Asana task.
Crawl and PageSpeed audit hardening
Technical SEO audit packages use Browser Run, R2, Asana evidence links, and incomplete-crawl findings instead of silent empty success reports.
Jessie workbench direction
Generic Jessie requests now plan, clarify, or use approved read-only analysis tools when confidently matched, including Plunkett Meta creative frequency and Plunkett SEO keyword-gap analysis.
Review artifact delivery
Hosted skills attach or link review-required artifacts to the source Asana task and keep client delivery consultant-mediated.
Admin Registry UX and readiness fix
Admin now focuses on Manage Users and Manage Clients, with client setup split into Sources, Context, and Users. Dashboard cards distinguish Dashboard Needed from Setup Needed, and list readiness is recomputed from current records.
Dashboard surface provisioning
Ready Business Units now expose Create dashboard on the Dashboards page. The Admin Registry Worker upserts an active staff-preview dashboard surface and the web interface opens slugged dashboard routes such as /dashboards/strategic-settlements/.
Strategic Settlements manual ingestion
The first real Client Data Plane ingestion slice adds Refresh data for GA4 and Search Console Source Assets, R2 Raw Source Snapshots, D1 curation runs, current facts, fact versions, and dashboard fact retrieval.
Client Data Plane
Dashboard facts
Admin-led onboarding
Agency staff configure the client group, Business Unit, source assets, context folder, staff access, and dashboard surface inclusion.
Manual SEO refresh
POST /admin-registry/business-units/:businessUnitId/refresh-data runs the configured GA4 and Google Search Console Source Assets for that Business Unit. Strategic Settlements is the first real client slice.
Raw snapshots
The Worker uses Google OAuth credentials from Cloudflare Secrets Store, stores minimized raw GA4/GSC payloads in CLIENT_DATA_PLANE_BUCKET, and writes raw_source_snapshots metadata rows in D1.
Normalized facts
Curation runs upsert current_client_facts and client_fact_versions with lineage linking source assets, ingestion runs, raw object keys, date range, and transformation version.
Web interface
Staff dashboards expose a Refresh data action and then 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, Google Ads credentials, Meta token, Accuranker, DataForSEO, Semrush, Ahrefs, and Browser Run.
Web interface API origin and service token
The web interface uses encrypted Pages secrets for AGENCY_OS_API_BASE_URL and AGENCY_OS_INTERNAL_API_TOKEN. The architecture site does not have these secrets.
Internal route guard
The Worker requires X-Agency-OS-Internal-Token on /client-data-plane/* and /report-artifacts/*, then compares it with the AGENCY_OS_INTERNAL_API_TOKEN secret binding before serving staff-only metadata.
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.
Admin Registry + Readiness
Updated 21 May 2026
Admin entry point
Admin & Configuration has two primary modes: Manage Users and Manage Clients. Manage Clients starts with a Business Unit selector and a Create Client action.
Client setup tabs
Each Business Unit is configured through Sources, Context, and Users tabs. Source IDs such as Asana project GID, GA4 property, Search Console site, Accuranker project, Google Ads, Meta, and HubSpot live in Sources.
Context and team authority
Context stores the Box client context folder binding. Users stores internal staff assignments now and leaves room for external client access later.
Readiness source of truth
The Worker recomputes readiness from current records for source assets, staff mappings, Business Unit roles, Jessie service identity, and no-live-connector policy. Dashboard lists no longer trust stale persisted readiness snapshots.
Dashboard surface status
A Business Unit with passed admin setup but no dashboard route is shown as Dashboard Needed with a Create dashboard action. The Worker creates an active staff-preview dashboard_surface_configurations record, then the card switches to Open dashboard.
Manual fact refresh
Business Unit dashboards now expose Refresh data. The action calls Admin Registry, validates GA4/GSC Source Assets, persists raw snapshots, and lets the dashboard render current facts.
Why This Matters
- Strategic Settlements: setup readiness is passed, the staff-preview dashboard surface can be provisioned, and GA4/GSC manual refresh now fills the dashboard with stored facts.
- Operator clarity: admins see exactly whether they need to edit Sources, Context, Users, or create/open the dashboard route.
- Dashboard routes: non-Plunkett Business Units use slugged dashboard URLs such as /dashboards/strategic-settlements/ after surface creation.
- Agent safety: setup readiness describes whether the agent has the source IDs, context, staff authority, and service identity it needs before execution.
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, real Business Unit dashboard routes with Refresh data, dashboard registry, staff-only Report Library, simplified Admin & Configuration CRUD, and staff-preview dashboard creation for ready Business Units.
- Worker API: health, Asana webhook intake, task-comment follow-up handling, queue consumers, hosted Team Agent execution, Admin Registry, Report Artifact Registry, dashboard surface provisioning, manual GA4/GSC data refresh, Client Data Plane fixture seed, dashboard fact feed, and metadata-level agent fact query logging.
- Hosted Team Agent skills: SEO reporting, GA4 reporting, Google Ads reporting, Meta Ads reporting, Integrated Performance Report, technical SEO audit, and the governed Jessie workbench.
- D1: migrations include build runs, Team Agent runs and event history, report artifacts/files/provenance/revisions, Client Data Plane setup, facts, dashboard configuration, and agent data access logs.
- R2: technical SEO audit bucket stores generated audit packages. CLIENT_DATA_PLANE_BUCKET stores raw source snapshots for manual GA4/GSC ingestion.
- Queues: Platform Build and Team Agent queues are configured to keep webhook intake fast and processing retryable.
Near-Term Roadmap
Next build slices- Dashboard surface governance: expand the new staff-preview creation path with access grants, inclusion controls, publish states, and audit history.
- Admin configuration depth: extend the Sources, Context, and Users tabs with richer validation, safer edit history, and external client access grants after staff-only setup is proven.
- Scheduled ingestion: promote the manual GA4/GSC refresh path into scheduled/daily refreshes, then add 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
41 indexedWhere Skills Live
- Repo skills: skills/*/SKILL.md stores Agency OS delivery skills such as SEO reporting, GA4 reporting, and Google Ads reporting.
- Agent skills: .agents/skills/*/SKILL.md stores repo-local operating skills for builders, triage, diagnostics, handoff, and architecture work.
- Marketing skill pages: /marketing-skills/ exposes the hosted Jessie marketing skills, their natural-language prompts, source prompt text, data sources, outputs, and guardrails.
- 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 22 May 2026- 2026-05-21 Workers VPC WAN destinations: no immediate architecture change, but relevant if future connectors need private network access through Cloudflare WAN, Tunnel, or Mesh.
- 2026-05-20 DNS records UX: no direct architecture change, but confirms Cloudflare is continuing to improve dashboard-native operational UI patterns.
- 2026-05-19 Cloudflare as Access identity provider: relevant for future staff-only protection of Pages surfaces without a separate IdP dependency.
- 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.
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, staff-only Report Library, 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