One platform layer
Agency OS owns connections, permissions, context, capabilities, evidence, visibility, and audit rather than duplicating them in each interface.
Working product and operating vision
Future State Architecture.
The intended Agency OS destination: governed access to agency platforms, role-specific workspaces, safe human delivery, and a resilient production operating model.
North Star
Agency OS is the agency's governed operating layer. It centrally connects platforms, client and prospect context, intelligence, work, evidence, permissions, and audit. Consultants and their agents use those capabilities within bounded authority; clients, sales, management, and administrators receive purpose-built views over the same controlled system.
Several role-specific experiences
Each user sees the decisions and workflows needed for their role without inheriting another role's access or internal detail.
Human-supervised delivery
AI prepares analysis and recommendations; accepted delivery work moves into Asana for accountable human execution.
Google Ads + GA4
Meta + HubSpot
Box + Asana
Harvest + specialist tools
Agency OS governed operating layer
Identity + permissions
Client + prospect context
Capabilities + approvals
Evidence + audit
Agent gatewayBounded delegate access
ConsultantClient operations
ClientApproved visibility
SalesProspect pipeline
ManagementHealth + capacity
AdminControl + governance
Future state This page records intended direction and requirements. It does not claim these interfaces, permissions, backups, or recovery procedures are live today.
Product Surfaces
| Surface | Primary job | Intended scope |
|---|---|---|
| Consultant agent gateway | Let a consultant use their preferred AI agent with Agency OS capabilities. | Short-lived, consultant-scoped authority limited by assigned clients, allowed platforms, action class, risk, cost, and approval policy. |
| Consultant workspace | Operate a portfolio and drill into each client. | Client health, connected data, strategy, reports, recommendations, work requests, review, visibility decisions, and conversion of accepted recommendations into Asana delivery. |
| Client dashboard | Create confidence, alignment, and useful service visibility. | Only consultant-approved reports, performance views, strategy, completed work, priorities, caveats, and next steps. No raw agent activity or internal commentary. |
| Sales workspace | Research prospects and progress opportunities. | Prospect intelligence, reports, call lists, pipeline, pitch preparation, follow-up, and controlled conversion from prospect to onboarding. |
| Management workspace | See agency delivery, commercial, capacity, and client risk. | Hours against retainers, over/under-servicing, client performance, delivery progress, workload, retention risk, exceptions, and explainable intervention signals. |
| Admin workspace | Control the system rather than deliver client work. | Identities, assignments, connections, permissions, capabilities, approval policy, costs, data health, audit, incidents, offboarding, and recovery controls. |
Governed Platform And Agent Access
Agency OS owns the connection boundary
- Agency OS connects to Google Ads, GA4, Meta, HubSpot, Box, Asana, Harvest, and other approved platforms.
- Consultants and their agents do not receive the underlying platform credentials.
- Every request resolves the human identity, assigned clients, capability, data scope, action class, and approval requirement server-side.
- Permissions can mature from read-only to draft and later to tightly controlled execution as evidence and governance improve.
Agents are bounded delegates
- Treat every local or hosted AI agent as an untrusted requester acting for an authenticated human.
- Issue short-lived Agency OS authority rather than durable provider credentials.
- Prefer narrow tools such as get_campaign_performance over arbitrary provider API access.
- Record the human, agent, client, tool, purpose, result, cost, approval, and resulting artifact for each material operation.
Example: a consultant may read Google Ads performance for assigned clients while campaign, budget, targeting, deletion, and publishing actions remain unavailable.
Analysis To Human Delivery
1
Request
From resolved client context
2
Authorise
Identity, scope, risk, cost
3
Analyse
Evidence + versioned artifact
4
Review
Accept, edit, reject, share
5
Deliver
Commit human work to Asana
6
Learn
Hours, completion, outcomes
Request from client context
The consultant requests work from a client workspace, such as a GA4 report and prioritised recommendations.
Resolve authority and readiness
Agency OS checks identity, client assignment, available sources, permissions, cost, risk, and required approvals.
Produce governed evidence
The selected agent or workflow gathers data, preserves provenance, and creates a versioned report or recommendation artifact.
Consultant review
The consultant accepts, edits, rejects, supersedes, or approves selected material for client visibility.
Commit human delivery
Accepted recommendations requiring human work become structured Asana tasks with evidence, ownership, timing, and traceability.
Close the loop
Agency OS tracks completion, resulting performance, hours consumed, and what should be visible to the client and management.
Development And Production Environments
Production was intentionally used during discovery so real client data could validate the domain shape. Before routine staff use, development must move to isolated resources.
Build
Local + CI
Fixtures and deterministic tests
Prove
Isolated staging
Synthetic data and separate resources
Operate
Production
Real clients and monitored releases
ImmediatePITR + rollback + quarantine
ProtectedLocked D1 exports in R2
CatastrophicEncrypted off-account recovery
| Environment | Data | Permitted use |
|---|---|---|
| Local and CI | Fixtures and mocks only. | Fast development, unit/contract tests, migration replay, security checks, and deterministic failure cases. |
| Staging | Synthetic or approved anonymised data in separate Workers, D1, R2, Queues, Workflows, Durable Objects, and secrets. | End-to-end testing, migration verification, permission tests, recovery drills, and candidate acceptance. |
| Production | Real client and prospect data with production-only credentials. | Human-approved releases from the exact accepted main commit, production-safe canaries, and monitored operation. |
- No preview, branch, staging, or local deployment may bind the live D1 database, R2 buckets, queues, provider credentials, or client destinations.
- Use backward-compatible expand/backfill/switch/contract migrations so the current and previous application versions can coexist during release and rollback.
- A Worker rollback restores code and bindings, not D1, R2, Durable Object, Queue, or external-provider state; release and data-recovery procedures remain separate.
Backup, Recovery, And Redundancy
Immediate recovery
Use D1 and SQLite Durable Object point-in-time recovery, release bookmarks, kill switches, write quarantine, and compatible Worker rollback.
Immutable operational backups
Export D1 to a dedicated R2 backup bucket with unique keys, manifests, checksums, retention policy, and bucket locks against overwrite or deletion.
Catastrophic recovery
Keep encrypted critical backups and infrastructure manifests outside the production account, with separately controlled credentials and a tested rebuild path.
| State class | Recovery expectation | Design rule |
|---|---|---|
| Source and configuration | Rebuild from accepted Git history and a versioned infrastructure manifest. | Production must not depend on one laptop or undocumented dashboard configuration. |
| D1 control-plane data | Point-in-time recovery plus scheduled exports retained beyond the platform PITR window. | Restore is destructive and human-gated; quarantine writes and preserve the pre-restore bookmark. |
| R2 evidence and artifacts | Content-addressed objects, retention policy, bucket locks, integrity manifests, and protected backup copies. | Provider durability does not protect against authorised deletion or account compromise. |
| In-flight agents and workflows | Reconcile from durable D1/R2 intent, result, and outbox records. | Queues, sessions, and workflow execution are never the only system of record for committed work. |
| Secrets and provider access | Recreate from the approved secret manager and rotate after compromise. | Secret values do not belong in database exports, source, docs, logs, or generated artifacts. |
Initial recovery objective: no more than one hour of data loss and service restoration within four hours, proven by a restore drill rather than assumed from documentation.
Requirements To Lock Before Broad Use
Identity, security, and visibility
- Named staff identity, SSO, MFA, and no shared human accounts.
- Cloudflare Access replaces staff Basic Auth before broad rollout.
- Server-side tenant, client, capability, action, and artifact-visibility enforcement.
- Separate staging and production secrets, provider accounts, and service principals.
- Least-privilege deploy, migration, restore, backup, security-admin, and read-only operator roles.
- Client visibility is an explicit versioned decision on each artifact or record, not a frontend-only hidden section.
Operations and continuity
- Release manifest binds commit, Worker versions, migrations, configuration, skills, and live verification.
- Feature flags and kill switches stop risky capabilities without requiring an emergency code edit.
- Backup freshness, queue age, cron heartbeat, delivery lag, provider health, access anomalies, and restore readiness are monitored.
- Monthly backup integrity checks and quarterly isolated restore drills.
- A second trained operator can deploy, diagnose, revoke access, roll back, restore, and communicate an incident.
- Recovery documentation includes bad deploy, bad migration, destructive write, R2 deletion, credential compromise, account loss, and provider outage scenarios.
Phased Transition
Harden the foundation
Create isolated staging, remove live preview bindings, replace Basic Auth, automate protected backups, and prove the first restore.
Consultant workspace and agent gateway
Expose assigned clients, read-only capabilities, structured requests, report history, recommendations, and review decisions.
Agency OS to Asana delivery
Create human delivery tasks only from accepted recommendations, preserving client, source, artifact, scope, capacity, and approval lineage.
Client, sales, and management lenses
Add curated client visibility, prospect workflows, pipeline and call lists, hours, client health, performance, capacity, and intervention views.
Increase authority carefully
Expand selected users and capabilities from read to draft and controlled execution only after measured quality, audit, recovery, and approval evidence.
Source References
- docs/architecture/future-state-architecture.md
- docs/superpowers/plans/2026-07-12-jessie-value-roadmap.md
- docs/adr/0016-single-live-production-client-environment.md
- docs/adr/0031-staff-portfolio-health-and-client-detail.md
- https://developers.cloudflare.com/workers/versions-and-deployments/
- https://developers.cloudflare.com/d1/reference/time-travel/
- https://developers.cloudflare.com/r2/buckets/bucket-locks/
- https://developers.cloudflare.com/workflows/examples/backup-d1/