Reference Architecture · Slack Agent Fleet
A fleet of autonomous Slack agents,
operated like employees
Two doer agents and one orchestrator that wake on a schedule, load their behavior from a cloud "brain," and act inside your team's Slack. This is the architecture pattern, end to end: how the agents are wired, how they ship, and how you operate them.
- Vercel cron runtime
- Brain / body split
- Self-healing
- Single alerting layer
- Git-driven deploys
The big idea
The repo is the body. Google Drive is the brain.
A GitHub repository holds the runtime — scheduling, authentication, the agent loop, and the API clients for Slack, Google Drive, the CRM, and the community. A Google Drive folder (the "Company Brain") holds behavior — everything the agents say and decide lives in skill files there.
Each scheduled job fetches its skill file from Drive at runtime. Editing a skill changes behavior on the very next run, with no redeploy. That single decision is what makes the fleet easy to operate: behavior is content you edit, not code you ship.
Change behavior
Edit a skill file on Google Drive. Live on the next run, no deploy.
Change code
Push to the main branch on GitHub. Vercel auto-builds and
promotes to production.
Git is how the body ships. The main branch is the source of
truth for runtime code and the deploy trigger: a push to main makes Vercel
auto-build and promote to production — no manual deploy, no CLI, no
dashboard click. Feature branches build as Vercel previews but never run
the schedule.
Roster
The fleet: two doers, one operator
The PM Agent and the Chief of Staff are the doers. The Orchestration Director is the operator. All three are autonomous — they take initiative and run consequential moves by their owner for a green light.
Doer
PM Agent
home: the PM channel
Project intelligence — action items, open loops, decisions, blockers, daily standups, and the structured Tracker (a Slack List).
Doer
Chief of Staff
home: the CoF channel
Knowledge work — transcripts into Company Brain docs, member profiles, use cases, channel intel, weekly digests, and CRM + community data.
Operator
Orchestration Director
home: the Director channel
Operates the fleet — health monitoring and the single alerting layer, a conversational front door, cross-agent hand-off, deploys, and cross-session memory.
Interaction model
How you talk to the agents
The agents are not Slack users — you cannot @mention them. They act on what their scans read in the channels they watch. There are five ways to reach them.
- 1
Reply in thread
Standup threads and captured-item threads are read by every scan.
- 2
Drop a keyword in a watched channel
A short trigger word routes to the right agent; the hourly scans pick it up.
- 3
Use a slash command
A direct, interactive session with a specific agent from Claude Code or Claude chat.
- 4
Reply to the end-of-day check-in
Direct-message replies to the 5 PM check-in are processed automatically.
- 5
React with an emoji
Add the agent's emoji to any message and it processes that item immediately via a real-time Slack Events webhook — no waiting for a scan, nothing running on your machine. The agent replies in-thread.
Surface map
Channel model
Each agent has a home channel and clear read/write rules so they never duplicate noise. One external client channel is write-locked: the agents read context but never post.
| Channel | PM Agent | Chief of Staff |
|---|---|---|
| PM channel | home — standups, scans, check-ins, Tracker mechanics | reads signals; posts only hand-off signals |
| CoF channel | — | home — intel sweeps, transcript/recap artifacts, community briefs |
| Team channel | reads; thread acks only | reads; posts the weekly digests here |
| External / client channel | — | read-only, write-locked — never posts |
Architecture at a glance
Three views of the system
The system (what talks to what), the brain/body split (the most important idea), and a single scheduled run from trigger to heartbeat.
1 · System — what talks to what
The Brain · Company Brain (Google Drive)
The Body · GitHub Repo → Vercel Runtime
The Surface
The repo is the body (scheduling, auth, the agent loop, the clients). Google Drive is the brain. Slack is the surface; a Slack List is the structured Tracker; external data is pulled only by the jobs that need it.
2 · Brain / body split — pointers and siblings
Siblings inside each agent's Drive folder
Pointer · interactive
Slash command = a tiny stub: read full instructions from Drive. Never goes stale — it carries no behavior.
File-ID · automated
Each cron job maps to a Drive file ID and reads it at run time.
One Vercel Runtime
Two sources of truth, two update paths. A skill is authored once as plain markdown; an interactive pointer stub and an automated file-ID lookup both consume it at run time.
3 · One scheduled run, end to end
- Vercel cron fires
- Bearer auth valid? no → Reject
- Time-zone guard
- Fetch skill from Drive
- Agent loop preamble + skill, prompt-cached
- Act in Slack / Tracker
- Write heartbeat on success or error
Every run authenticates, lands at the correct local hour year-round, loads its skill from Drive, runs the cached agent loop, acts, and records a heartbeat. A crashed job is never silent: the error heartbeat is the signal the Director reads.
Inside a run
How a scheduled job actually executes
The shared handler turns a job name into identity, auth, a skill, and a heartbeat. AI jobs run the agent loop; deterministic jobs (like the Skool sync) skip the model entirely.
- 1
The Vercel cron fires
A scheduled trigger calls the job's route at its configured time.
- 2
Auth check
The shared handler rejects anything without the correct bearer token, so endpoints can't be triggered by a random request.
- 3
Daylight-saving guard
The trigger fires at both standard- and daylight-time candidates; the job only proceeds at the correct local hour, so it lands at the right time year-round.
- 4
Fetch the skill from Drive
The handler maps the job to a Google Drive file ID and reads its behavior markdown live.
- 5
Run the agent loop
A runtime preamble injects identity, voice, structured-store rules, and formatting; the Drive skill is appended. The preamble overrides the skill where they conflict. The system prompt and tool set are prompt-cached, so every round after the first reads that prefix at a fraction of the input price.
- 6
Act, then record a heartbeat
The agent acts in Slack and the Tracker, then writes a per-job heartbeat to Drive — durable proof the job ran. On error it records the failure instead of paging anyone directly; the Director's health job is the single alerting layer.
The operating layer
The Director: operate the fleet, don't do its work
The Orchestration Director is a Vercel runtime agent with its own cron jobs. Its job is to operate the two doers across four functions.
Observability
The heartbeat ledger
Every job, on success or error, writes a tiny per-job file to Google Drive recording status, duration, summary, and timestamp. Best-effort: a heartbeat write can never break a run. This is the durable record of whether the fleet actually ran.
Health + alerting
One synthesized digest
Twice a day the Director reads the whole ledger, compares it to the expected schedule, and computes per-job health — with cold-start suppression and a due-grace window to avoid false alarms. For every red it produces a root cause and remedy, then posts one digest and alerts the owner only when something is actually actionable.
Work hand-off
The broker
Agents hand work to each other through a Drive-backed queue (enqueue / list / resolve), exposed to the agent loop as hand-off tools. The Director drains and routes the queue. This is how the doers coordinate as peers without one bossing the other.
Front door + memory
Conversational, persistent
Hourly through the workday the Director reads its channel, replies in-channel, enforces lane ownership, and keeps its living fleet-state memory current. It also owns deploys and change management via the Vercel token.
Cadence
The schedule
All AI jobs fire at both standard- and daylight-time candidates; the local-hour guard picks the right one. Intended Eastern times below.
| Job | Agent | Time & purpose |
|---|---|---|
monday-cleanup | PM | Mon 9:00 AM — mechanical cleanup (archive, reset, stale flags) |
standup | PM | 10:00 AM Mon–Fri |
standup-watchdog | PM | 10:05 AM Mon–Fri |
standup-scan | PM | 10:30 AM Mon–Fri — early standup-thread replies |
hourly-scan | PM | 11 AM–5 PM hourly Mon–Fri |
checkin-5pm | PM | 5:00 PM Mon–Fri — per-person DMs + thread summaries |
watchdog-5pm | PM | 5:15 PM Mon–Fri |
transcript-monitor | CoF | 10 AM, 1 PM, 5 PM Mon–Fri |
channel-monitor | CoF | 10 AM, 1 PM, 5 PM Mon–Fri — one EOD digest at 5 PM |
weekly-digest | CoF | Mon 10:05 AM (Week Ahead) & Fri 5 PM (Week in Review) |
skool-sync | CoF | 9 AM Mon–Fri — diff Skool members vs snapshot; silent; feeds Friday digest |
cost-monitor | CoF | 5 PM Mon–Fri — daily Anthropic spend, MTD, 7-day trend; alerts on a spike |
director-scan | Dir | 10 AM–6 PM hourly Mon–Fri — front door, drains hand-off queue, updates memory |
fleet-health | Dir | 11 AM + 5:30 PM Mon–Fri — reads ledger, one health digest, alerts only on actionable red |
External data
Data integrations
Three external systems feed the agents, plus an internal prompt-caching ledger that measures its own savings.
Skool
Pulls live member and post data from the private Skool community, parsing the server-rendered Next.js pages. Skool sits behind AWS WAF bot protection, which is the whole story: the cookie bundles a long-lived auth token plus a short-lived WAF token that ages out in days.
The fetch chain tries a cheap plain HTTP request first; if AWS WAF blocks it, it falls back to a headless Chromium browser that runs the challenge itself, mints a fresh token, and scrapes the page — self-healing, in-stack, no third party, no manual cookie grab. The cookie is read from a Google Drive file first (so it can be rotated with no redeploy), then from an environment variable as fallback. A Skool Zapier webhook can also receive new-paid-member and membership-question events into a Drive log.
GoHighLevel
Pulls leads, pipeline stages, revenue, and conversion rates via GoHighLevel's Private Integration API. Injected into the Friday weekly digest as a live snapshot, and available on demand through a read-only endpoint.
Anthropic API spend
Pulls month-to-date model spend from Anthropic's Admin cost endpoint. Because that API is rate-limited and a full pull fans out to many paged calls, spend is cached to Google Drive once a day by the cost-monitor job — the only live caller. Every other reader serves from cache, which is why repeated reads can never re-trip the rate limit. On any upstream change the fetch degrades gracefully and posts a soft warning rather than hard-failing.
Stand it up
Install & setup
From an empty project to a running fleet. The wiring is GitHub-to-Vercel plus a set of secrets; behavior arrives separately, from Google Drive.
- 1
Connect GitHub to Vercel
Install the Vercel GitHub App on your code organization and link it to a Vercel project. This wires Git to the host: a push to main builds and promotes automatically.
- 2
Create the Company Brain on Google Drive
Author each agent's skill files — skill.md, personality.md, and the per-job cron/*.md — in Drive. This is where all behavior lives; the repo holds none of it.
- 3
Set the environment secrets in Vercel
Add the Anthropic API key and Admin key, the Slack user token and signing secret, the Google service account, the per-job skill file IDs, the cron bearer secret, the Director channel ID, the GoHighLevel token and location, the Skool cookie, and the Skool snapshot folder/file IDs. Secrets live only in Vercel env vars, never in the repo.
- 4
Register the schedule in vercel.json
Declare every job and its timing there. On each production deploy, Vercel reads that file and registers the schedule. The Git folder path maps one-to-one to the cron route.
- 5
Push to main to deploy
The GitHub App notifies Vercel, which builds and promotes to production. Crons only fire on the production deployment — previews never run the schedule.
- 6
Seed the snapshot IDs
After the first Skool-sync run, capture the members and posts snapshot file IDs back into Vercel env so future diffs have a baseline.
- 7
Verify
Confirm the newest deployment is ready and matches your commit, then watch the heartbeat ledger fill in as jobs run. Health is visible the moment the Director's first health pass runs.
House rules
Operating principles
- Drive is the source of truth for behavior. Edit skills on Google Drive, not in the repo. The repo is the runtime body.
- All infrastructure in one project. Runtime, crons, and every capability live together — not scattered across personal repos.
- Nothing on local disk. Artifacts the agents create go to the Company Brain; temp files are cleaned up.
- Skills belong in their agent's folder. Each agent's capabilities live under its own skill folder, never scattered in the Drive root.
- Autonomous, reporting to one owner. Propose and do; surface consequential moves for a green light; don't wait to be micromanaged.
- Voice is centralized per agent. Personality lives in one file per agent, so a voice change lands everywhere at once.
Ship & roll back
Hosting & deployment (Vercel ↔ GitHub)
Git is the source of truth for the body; Vercel is the only place it runs. The two are wired by the Vercel GitHub App.
Push to main → production
The GitHub App notifies Vercel, which builds and promotes to production automatically. No manual deploy, no CLI, no dashboard click.
Any other branch → preview
Vercel builds a preview deployment with its own URL. Previews are testable, but crons only fire on production — a preview never runs the schedule.
Schedule comes from vercel.json
On each production deploy, Vercel reads the cron declarations and re-registers the schedule. Add or remove a job there and it takes effect on the next production deploy.
Auth between cron and code
Vercel calls each route with a bearer token; the handler rejects anything else.
Keep it current
Maintenance SOP
This document is the canonical architecture doc — keep it current in the same change as the system. The trigger for each update:
- Add, remove, or rename a job. Update the layout, the schedule, vercel.json, and the job-to-skill map. Caching and the savings ledger are automatic — nothing to wire per job.
- Add a data integration. Update the integrations section, the layout, and the environment variables.
- Change where an agent posts or reads. Update the channel model.
- Change identity, ownership, or principles. Update the relevant section so the roster stays accurate.
- Add or rename an agent, or change how skills are sourced. Update the architecture diagrams and the source-of-truth section.
- Change the deploy pipeline. Update the hosting and deployment section.
The body ships through Git. The brain lives on Google Drive.