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.

Marketing Skills Open Library

Cloudflare Runtime

Pages + Workers + D1

Pages hosts internal surfaces; Workers, Queues, D1, R2, Browser Run, and AI Gateway run Jessie and platform APIs.

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.

Model Calls

AI Gateway live

A central adapter routes bounded Jessie narrative drafting through Cloudflare AI Gateway with payload logging disabled.

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 briefing

Asana 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, AI Gateway, 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 reference

Cloudflare 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 consumers, Team Agent Runtime shell, Team Agent runtime observability endpoints, Admin Registry, Report Artifact Registry, Client Data Plane fixture/data endpoints, health checks.	Current public dev worker runs on workers.dev. Team Agent run state, run events, run-step traces, platform issues, feedback rounds, execution candidate factories, and watchdog runtime now live in focused modules called by the Worker shell.
D1	agency-os-dev-platform-build-runs	Operational database for build runs, Team Agent runs, Team Agent run-step traces, platform issue dedupe, report artifact registry, Client Data Plane setup, facts, access grants, and access logs.	Binding: PLATFORM_BUILD_DB. Runtime observability tables store compact sanitized traces; 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 SEO refresh writes GA4, Search Console, and optional Accuranker 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	Cloudflare AI Gateway REST API to OpenAI/gpt-5.5	Central model-call adapter and observability path for bounded Jessie narrative drafting.	TEAM_AGENT_AI_GATEWAY_MODEL_CALLS_ENABLED is enabled in dev. Payload logging is disabled with cf-aig-collect-log-payload:false and the token is supplied from Secrets Store.
Agents SDK	agents@0.13.2 isolated TeamAgentTaskAgent prototype	Prototype runtime substrate for Durable Object-backed task agents, durable execution, Workflows, MCP, sub-agents, queue/schedule APIs, and runtime observability.	Dependency and synthetic D1-trace bridge are integrated, but not wired into live Jessie or Asana execution. The repo keeps min-release-age=7 by default and uses exact reviewed versions for Cloudflare package spikes.
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.

Runtime modules own Team Agent internals

The Worker shell now calls focused state, watchdog, and observability modules for Team Agent run leases, run events, run-step traces, feedback rounds, revision recovery, stale runner requeue/failure behavior, and platform issue indexing.

Team Agent Runtime

Extraction slice 1

Worker shell stays deployed

The Cloudflare Worker still owns fetch, queue, scheduled entry points, HTTP/admin routes, Asana webhook verification, and adapter composition. Existing exported functions remain available for tests and scripts.

State modules own D1 SQL

Team Agent run lookup, status transitions, execution lease acquisition, watchdog listing/recovery, append-only run events, processed feedback comment claims, and feedback round persistence now live under src/state/.

Watchdog runtime is isolated

runTeamAgentRunnerWatchdog delegates to src/team-agent/watchdog.ts, which plans ready/running/revision-running recovery, respects retry caps, requeues execution candidates, and records failure through explicit Worker ports.

Queue contracts stay stable

team-agent-run and team-agent-execution message shapes did not change. Revision execution candidates are created by src/team-agent/execution-candidates.ts using the same idempotency keys and correlation format.

Runtime traces explain stuck work

team_agent_run_steps records compact, sanitized phases such as execution lease, Asana refresh, skill execution, technical SEO Browser Run crawl, artifact registration, Asana write-back, and watchdog recovery.

Compatibility tests stay broad

The existing index.test.ts remains the Worker-shell behavior backstop, while module tests cover lease acquisition, duplicate rejection, feedback claiming, revision lookup, watchdog recovery, run-step traces, issue dedupe, and retry-cap failure.

AI Gateway path is live

A central integration adapter calls the current Cloudflare AI Gateway REST API using provider-prefixed OpenAI models, disables payload logging by default, records compact runtime traces, and falls back to deterministic output when model calls fail.

Agents SDK prototype is isolated

Cloudflare Agents SDK is now integrated as an isolated TeamAgentTaskAgent prototype and D1 trace bridge, but it is not wired into deployed Jessie, Asana webhooks, or live execution. The next decision is whether it handles duplicate events, resumable work, and write-back better than the current Worker/D1/Queue runtime.

Current Module Map

packages/integrations/src/cloudflare-ai-gateway.ts: central live AI Gateway adapter for safe model-call execution and diagnostics.
src/team-agent/types.ts: shared Team Agent runtime types.
src/team-agent/observability.ts: runtime trace/status types and diagnostic sanitization.
src/team-agent/observability-api.ts: internal operator trace, stuck-run, and platform-issue endpoints.
src/team-agent/agents-sdk-runtime.ts: pure Agents SDK observability bridge that maps SDK events into Agency OS run-step traces.
src/team-agent/agents-sdk-task-agent.ts: isolated TeamAgentTaskAgent class extending Cloudflare Agents SDK for prototype use only.
src/team-agent/platform-issue-policy.ts: deterministic failure classification and platform issue dedupe planning.
src/team-agent/execution-candidates.ts: ready and revision execution queue candidate factories.
src/team-agent/watchdog.ts: stale run recovery orchestration and watchdog planning.
src/state/team-agent-runs.ts: Team Agent run state, lifecycle, lease, and watchdog SQL.
src/state/team-agent-run-events.ts: append-only run event SQL.
src/state/team-agent-run-steps.ts: compact runtime step trace SQL.
src/state/platform-issues.ts: local deduped platform issue SQL for runner/tool/integration defects.
src/state/feedback-rounds.ts: processed comment claiming and feedback/revision round SQL.
src/index.ts: deployed Worker shell plus remaining orchestration for feedback handling, skill execution, Asana write-back, artifact registration, and HTTP/admin routes.

Still To Extract

Post-review feedback/revision orchestration.
Asana comment rendering.
Per-skill hosted execution dispatch.
Technical SEO hosted execution runtime.
Queue dispatch after run/execution modules have smaller interfaces.

Cloudflare Agents SDK Position

Investigated 23 May 2026

Current production stance

Jessie still runs on the extracted Worker shell, D1 run state, Queues, watchdog recovery, Browser Run, R2 artifacts, and Asana adapters. No deployed Jessie path depends on Cloudflare Agents SDK yet.

Current package integration

The repo now pins agents@0.13.2 and includes an isolated TeamAgentTaskAgent prototype plus a pure observability bridge that emits Agency OS-style D1 run-step inputs. This is a code spike, not a live runner migration.

Relevant platform capabilities

Agents SDK provides Durable Object-backed TypeScript agents, built-in SQL/state storage, RPC/callable methods, schedule and queue helpers, durable execution, Workflows integration, sub-agents, tool/MCP support, and observability hooks.

Best-fit Agency OS use

The promising shape remains a TeamAgentTaskAgent per Asana task or run: one durable coordination point for task state, follow-up comments, long-running tool resume, platform issue correlation, and artifact handoff.

Migration guardrail

Do not replace the working Worker/D1/Queue runtime in one move. First spike a narrow adapter that mirrors the existing run ledger, emits the same D1 run-step traces, and proves it handles duplicate webhooks, leases, resumes, and Asana write-back better than the current shell.

Package safety policy

The repo keeps npm min-release-age=7 as the default supply-chain guard. Reviewed Cloudflare agent packages can use the trusted exact-version helper for spikes, not broad latest installs.

Architecture Decision

Adopt now: isolated prototype only. The deployed Jessie runtime remains Worker plus D1/Queues.
Evaluate next: run the TeamAgentTaskAgent prototype against synthetic Asana task events, write existing D1 traces, and demonstrate durable resume without duplicate comments.
Keep unchanged: Asana remains the consultant work thread, D1 remains the compact operational ledger, and platform issues remain deduped/sanitized tasks in the Platform Development project.
Use carefully: Agents SDK observability should feed Agency OS run-step traces and issue policy; it should not become an isolated second source of truth.
Not in scope: client publishing, email sending, account/site/tracking/budget changes, or credential mutations.

Trusted Package Helper

Default: npm still waits seven days before installing newly published packages.
Reviewed bypass: exact allowlisted Cloudflare agent packages can be packed or installed with npm:trusted-pack or npm:trusted-install.
Why: this lets Agency OS evaluate urgent Cloudflare runtime updates without disabling the repository-wide release-age guard for every dependency.

Client-Generic Team Agent Runtime

Next runtime slice

Admin Registry is authoritative

Client Groups, Business Units, Source Assets, context bindings, team assignments, dashboard surfaces, and report history already live in the existing admin/dashboard surfaces. Do not build a second client config system.

Aliases fill the routing gap

Business Unit Intake Aliases add staff-approved shorthand such as Oswald, WACB, Step 1, or Rural so plain-language Asana tasks resolve to configured Business Units without domain hardcoding.

Resolver returns one Business Unit or ambiguity

A Team Agent Business Unit Resolver reads task text, non-intake Asana project bindings, Business Unit names/slugs, and aliases. Multiple confident matches ask for clarification instead of guessing.

Execution context feeds skills

A Team Agent Execution Context loads Business Unit identity, Source Assets, context readiness, active channels, artifact summaries, caveats, and skill readiness before hosted execution.

Generic builders replace Plunkett paths

Technical SEO, SEO, GA4, Google Ads, Meta, and Integrated Performance Report builders should consume the execution context instead of Plunkett-specific defaults, URLs, property IDs, or account helpers.

Registry reuse stays lifecycle-safe

Integrated reports use accepted/current same-period artifacts only when registry lifecycle, evidence capsules, freshness, Business Unit, channel, and unresolved-feedback checks pass.

Runtime Boundary

Setup UI: extend existing Business Unit setup with Intake Aliases, Test Jessie inference, and Test skill readiness.
Stable IDs: Team Agent Runs and Report Artifacts should carry Business Unit and Client Group IDs, not only display names.
Binding config: source IDs and public website URLs live on Source Assets. Credentials stay in Cloudflare Secrets or Workers Secrets.
Prompt context: use task text, compact context slices, and evidence capsules before fetching deeper JSON/CSV files. Do not load full old reports by default.
Fallback policy: missing source setup produces blockers or caveats. It must not silently fall back to Plunkett configuration.
Reference doc: docs/runbooks/team-agent-client-generic-runtime.md records the implementation phases and smoke expectations.

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 the shared artifact contract

The control-plane Worker writes report_artifacts, report_artifact_files, report_channel_provenance, and report_revision_rounds rows with lifecycle status, visibility, evidence capsule JSON, reusable state, and supersedes/superseded-by links.

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 evidence workspaces

The staff-only /reports/ view remains the global Evidence Library. Business Unit dashboards add an internal Report History tab for that client, including lifecycle, reuse, evidence capsule, files, provenance, Asana task, and revision timeline.

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.
Server-side visibility: client/external viewers only receive future client-visible/published records; V2 artifacts remain staff-only by default.
Lifecycle-safe reuse: dismissed, superseded, blocked, stale, wrong-period, wrong-channel, and unresolved-feedback artifacts are excluded from reusable artifact queries.
Context control: prompts should start from compact evidence capsules and fetch deeper JSON/CSV only when a specific section needs it.
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

Team Agent Runtime extraction slice

Run state SQL, run event SQL, feedback round SQL, execution candidate factories, and watchdog recovery moved out of index.ts into focused src/state and src/team-agent modules. The Worker shell and queue contracts remain behavior-compatible.

Team Agent Runtime observability slice

D1 now stores sanitized run-step traces and deduped platform issue records. Internal endpoints expose run traces, stuck active runs, and platform issues without raw provider payloads or secrets.

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, incomplete-crawl findings, and phase-level traces 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, Search Console, and optional Accuranker Source Assets, R2 Raw Source Snapshots, D1 curation runs, current facts, fact versions, comparison-period movement, freshness warnings, and dashboard fact retrieval.

Client-generic runtime plan

The documented next slice uses existing Admin Registry setup, adds Business Unit Intake Aliases, resolves stable Business Unit IDs, loads a compact Team Agent Execution Context, and replaces Plunkett-specific skill builders.

Live AI Gateway model-call adapter

Jessie now has a central Cloudflare AI Gateway integration for bounded model calls. Integrated Performance Report narrative drafting can use OpenAI/gpt-5.5 through the current AI Gateway REST API with payload logging disabled and deterministic fallback output.

Trusted Cloudflare agent package bypass

The repository keeps npm min-release-age=7, but adds a narrow exact-version helper for reviewed Cloudflare agent packages such as agents when a new SDK release needs investigation before the age window expires.

Agents SDK prototype integration

agents@0.13.2 is pinned and the codebase now has an isolated TeamAgentTaskAgent class plus a pure SDK observability bridge that maps SDK events into Agency OS D1 run-step traces. It is not wired into live Jessie or Asana execution.

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, Google Search Console, and optional Accuranker 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

Runtime binding

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.

Pages secrets

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.

Worker service token

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.

No data leakage

Fact and artifact policy

Secrets must not be written into D1 records, R2 objects, Asana comments, generated reports, dashboard HTML, or logs.

Future access

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 manual SEO refresh now fills the dashboard with stored GA4, Search Console, and optional Accuranker tracked-keyword 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 and internal Report History tabs, dashboard registry, staff-only global 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, extracted Team Agent state/watchdog/observability modules, internal Team Agent runtime trace endpoints, Admin Registry, Report Artifact Registry, dashboard surface provisioning, manual SEO 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.
AI Gateway: live central model-call adapter routes bounded Integrated Performance Report narrative drafting through Cloudflare AI Gateway REST API to OpenAI/gpt-5.5, with payload logging disabled and D1 traces storing compact metadata only.
Agents SDK: agents@0.13.2 is pinned for an isolated TeamAgentTaskAgent prototype. The prototype maps SDK observability events into Jessie D1 run-step traces, but is not deployed into live Asana execution.
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, Search Console, and Accuranker ingestion.
Queues: Platform Build and Team Agent queues are configured to keep webhook intake fast and processing retryable.

Near-Term Roadmap

Next build slices

Client-generic Team Agent Runtime: add Business Unit Intake Aliases, a deterministic resolver, execution context loader, and generic skill input builders that consume Admin Registry/Source Asset setup.
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 SEO refresh path into scheduled/daily refreshes, then add Asana, Google Ads, Meta, HubSpot analytics, and Harvest reconciliation.
Agents SDK spike: exercise the isolated TeamAgentTaskAgent Durable Object prototype against synthetic Asana task/run events, while writing the existing D1 run-step traces and platform issue records.
Cloudflare Workflows and Containers: target path for longer-running builder execution and build/check automation after branch creation, with Agents SDK plus Workflows evaluated for durable Team Agent orchestration.
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 indexed

Where 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 23 May 2026

2026-05-21 AI Gateway REST API: Jessie now uses the current Cloudflare AI Gateway REST API for bounded model calls through a central adapter. D1 run-step traces remain the operational source of truth.
2026-05-13 Agents SDK v0.12.4 and npm agents@0.13.2 on 2026-05-21: Cloudflare Agents is a promising Durable Object-backed agent runtime with Workflows, durable execution, MCP, sub-agents, and observability. Agency OS has pinned the SDK for an isolated TeamAgentTaskAgent prototype before any live runner migration.
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 0009: Team Agent Runtime Extraction docs/adr/0009-team-agent-runtime-extraction.md ADR 0009: Team Agent Runtime Extraction Date: 2026-05-22 Status: Accepted Context The Cloudflare control-plane Worker has become the always-on runtime for Agency OS. It owns Asana webhook intake, queue consumers, Team Agent state transitions, execution leases,
ADR 0004: Hosted Team Agent Execution MVP docs/adr/0004-hosted-team-agent-execution.md ADR 0004: Hosted Team Agent Execution MVP Date: 2026-05-18 Status: Accepted Context Hosted Team Agent intake can now notice Jessie Intake tasks, verify Jessie assignment, create a D1 Team Agent Run, assess readiness, and post a Delegation Confirmation. That pr
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 model

Platform 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 boundary

Architecture 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 interface

Skill Inventory

View skills

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