The Agent OS

The target state is a company where one human (the orchestrator) sets direction and reviews; everything else — engineering, marketing, customer support, ops, planning — is an agent. This document is the architecture for the operating system that makes that possible.

Five layers: command surface (where you give orders), coordination plane (tasks + events + decisions + memory), agents (the workforce), action surface (the external world they touch), and a write loop that flows actions back into memory so the org gets sharper every week.

The architecture's defining property isn't any single component — it's the read-act-write loop. Agents read from the coordination plane, act on the world, and the actions become events that flow back into memory. Without that loop, agents stay frozen at whatever you seeded them with. With it, month two is meaningfully smarter than month one.

              YOU (orchestrator)
                    ↕
            [ COMMAND SURFACE ]    Slack mobile + Claude Code
                    ↕
            [ COORDINATION PLANE ] Tasks + Events + Decisions + Memory
                    ↕
                AGENTS (many)
                    ↕
            [ ACTION SURFACE ]     GitHub + Slack + Email + Calendar
                    ↕
          (events flow back into coordination plane → memory grows)

From the MemGPT taxonomy (UC Berkeley, now standard). Treating "memory" as one thing is the failure mode that makes most agent systems get worse over time, not better.

• Working — current task RAM. Vanishes after the task. Lives in process memory and conversation context.
• Episodic — what happened. Append-only. Lives in the events table, git history, Slack logs, and (today) data/overnight-logs/*.jsonl.
• Semantic — what's true. Curated, slow-changing. Lives in BRAND.md, AGENTS.md, and the future decisions/ directory.
• Procedural — how to do things. Lives in .claude/skills/ as agent definitions and templates that agents execute directly.

Conversations, code, Slack messages, emails, run logs all feed an ingestion layer. The ingestion layer fans out into a vector DB (semantic search), a knowledge graph (relationships), and structured tables (queryable facts). A retrieval layer — exposed as MCP / SDK / REST — sits on top. Agents call it before they act.

Today the read path is shallow: agents read state.json, BRAND.md, and their own SKILL.md. Phase 1 widens it to the tasks/events/decisions tables in Supabase. Phase 2 layers Mem0 on top for semantic retrieval.

Every meaningful agent action produces an event: PR opened, decision made, customer replied, build failed. Events go through the same ingestion layer in reverse — they become the new memory the next agent reads. The system gets sharper without a single line of code change.

Three properties matter: persistent (survives across sessions), phone-accessible (orders from anywhere), async (you write, agents act, you check back). Slack hits all three. Free tier. Phone/web/desktop. Built-in conversation history. Each agent gets a Slack bot user.

Claude Code stays as the interactive interface for code-heavy work — what you're reading right now is part of that loop. Slack becomes the always-on operations layer for everything else.

Channels mirror functions, not departments. #planning is where you give orders. #engineering is where Bob and friends report. #ops is where the broadcaster posts decisions and the digest agent drops weekly summaries. #review is the 30-minute approval window for medium-trust actions. #firehose is muted-by-default; everything goes there for debug. #humans-only is your private notes — no agent reads it.

A workflow is a chain of agent invocations with state, conditions, and rollbacks. The overnight-builder is one (Steph → Kai → Bob → Lace → Simon → Ben → merge or fix-loop). Future workflows: customer onboarding, monthly strategic review, marketing launch, incident response, refund processing.

They're stored the same way agents are — as markdown files with YAML frontmatter — under .claude/workflows/<name>/SKILL.md. The frontmatter declares the step graph; the body explains intent. A small runner reads the frontmatter and dispatches via the existing agent CLI.

---
name: overnight-builder
trigger: cron, slack-mention, manual
steps:
  - { agent: steph, on_first_run_only: true }
  - { agent: kai, when: "needsSpec == true" }
  - { agent: bob }
  - { agent: lace }
  - { agent: simon }
  - { wait_for: cf-preview }
  - { agent: ben }
  - { action: merge, when: "ben_verdict == PASS" }
  - { action: fix_loop, max_attempts: 2, when: "ben_verdict == FAIL" }
state_table: tasks
---

Triggers fan in from many sources — a Slack message (@router run weekly-digest), a cron firing, a GitHub PR webhook, a customer email arriving. The workflow runner is agnostic to where the trigger came from; it just needs the workflow name and an initial context payload.

Three Supabase tables form the substrate. tasks tracks anything an agent (or human) is working on, with statuses, owners, and parent links for sub-tasks. events is the append-only audit log — every significant action lands here, including the orchestrator's own state transitions. decisions mirrors a decisions/ directory in the repo so ADRs are searchable from the same plane.

Decisions follow the decision-as-event pattern: each decision is a markdown file with frontmatter declaring who it applies to and where to broadcast it. Committing the file fires a webhook; the broadcaster fans out to Slack, the weekly digest, email, and any agent skill files affected.

---
id: 2026-05-08-torque-converters-common-values
applies-to: [bob, lace]
broadcast: [slack-engineering, weekly-digest, email-daniel]
---
From now on, all torque converters require a "common values" reference table.

Memory is repo-first today: BRAND.md, AGENTS.md, .claude/skills/, data/specs/. Phase 2 layers Mem0 on top via MCP — agents query for "what do we know about X" and get semantically-relevant prior decisions back.

Each agent is a small, focused skill — a markdown file in .claude/skills/<name>/SKILL.md describing its job, its refusal rules, and its archetype-template references. Agents compose: the overnight-builder orchestrator drives the engineering pipeline by calling Steph → Kai → Bob → Lace → Simon → Ben in sequence.

• Steph — research scout. Pulls Ahrefs + GSC + competitor diff to find high-volume / low-difficulty tool ideas.
• Kai — spec writer. For non-trivial tools, studies the SERP and writes a spec to data/specs/<slug>.md.
• Bob — tool builder. Generates the React widget, seeds Supabase, runs the gate, opens the PR.
• Lace — SEO writer. 1500–2500 word long-form article published to tool_metadata.seo_article.
• Simon — translator. Translates metadata + article into the locales Kai's spec marked.
• Ben — QA. Tests the live preview against the spec; posts PASS/FAIL on the PR.
• Overnight-Builder — the orchestrator that drives the whole sequence.

Phase 3 adds external-facing agents: Marketing (drafts launch posts), Customer Support (Gmail + Slack DMs), Calendar (scheduling), Finance (Stripe + reconciliation). Each gets its own GitHub service account, Slack bot user, and email signature so external interactions are clearly attributed.

Functional bots get used. Lovable characters get followed. Companies are proving this now: Replika built a billion-dollar business on agent-as-companion; Character.AI runs on millions of user-created personalities; Klarna's customer-service AI has a name, a face, and a consistent voice; Microsoft's Clippy was the OG. The cultural priors exist (Wall-E, Baymax, R2-D2, Severance's work-personas). Audiences love characters. Most agent products haven't figured this out — that's the edge.

In this architecture, every agent has both a skill (what it does) and a character (who it is). Personality is a separate file, loaded BEFORE the skill on every invocation. Function flows through, flavored.

What every character bible holds

Architecture additions

The skill directory grows from one file to a small bundle:

.claude/skills/bob/
├── SKILL.md         (what Bob does)
├── CHARACTER.md     (who Bob is — voice, motivation, banned words)
├── STORY.md         (notable moments, growth, arcs — appended over time)
├── avatar.svg       (visual identity)
└── voice-samples/   (prior outputs to stay consistent with)

Where each piece lives long-term

Treating the bundle as all-markdown is a Phase-1 simplification. Long-term, different files want different homes — the same split as the broader memory architecture: procedural in the repo, episodic in the database, binary assets on a CDN.

But don't migrate now. Repo-as-truth scales 6+ months at solo scale. Move STORY.md to Supabase when entries cross ~50 per agent (querying breaks down before that). Move voice-samples/ to pgvector when the voice gate genuinely needs semantic search (it doesn't yet). Move avatars to R2 when public agent profiles launch. The agents table is the only one that should start in Supabase day one — the router needs to look up "who is Bob?" the moment Phase 1 ships.

A voice gate runs on every outbound message: "does this sound like Bob?" If no, regenerate. Slow at first, fast once tuned. Same shape as Ben's QA gate but on tone instead of correctness.

Five integration surfaces: GitHub (code + PRs), Slack (chat), Email (Gmail MCP for read; Resend for send), Calendar (Google Calendar MCP), and Customers (eventually the public-facing tools themselves). Each surface has typed wrappers so agents don't reinvent connectors.

Phase 1 (weeks 1–4) — MVP

Slack workspace + bot identities. tasks / events / decisions tables in Supabase. decisions/ directory in repo with ADR template. Broadcaster Worker (fans new decisions out to Slack + email + skill PRs). Router bot (parses your Slack messages, dispatches to agents). Webhook receivers on Cloudflare Workers (GitHub PR events, Slack events, cron). Migrate the overnight-builder onto the new substrate. Cost: ~$5/mo.

Phase 2 (months 2–3) — Memory + observability

Layer Mem0 on top of repo memory once the decision pool crosses ~50 entries. Weekly digest agent (cron). Editor agent for memory hygiene (proposes consolidations as draft PRs you approve in the morning). Trust gradient enforcement (auto / notify-then-execute / require-approval). Rollback lever: @router rollback last 6h.

Phase 3 (months 4–6) — External-facing agents

Marketing agent drafts launch posts when tools merge. Customer support agent reads inbound email + Slack DMs from external users; drafts replies, applies trust level, sends. Calendar agent negotiates meeting times via email. Finance agent reads Stripe + bank, reconciles against tasks, drafts monthly summaries.

Phase 4 (months 12+) — Full org

Multi-project Mem0 (cross-project shared memory). Customer-facing agents promoted to auto trust where track record warrants. Self-improvement loop: editor agent proposes skill edits weekly based on observed failure patterns; you approve or reject the diff.

Cloudflare Workers (paid plan, $5/mo) hosts the always-on bits: webhook receivers, the Slack router bot, the broadcaster, scheduled jobs. Supabase (existing, free tier covers Phase 1) holds tasks/events/decisions. Slack free tier is enough for solo + small team. Resend covers 10k emails/mo free. Total Phase 1: ~$5/mo.

Companies running on agents fail on trust before they fail on infrastructure. Three tiers, with a rollback lever as a safety net.

Plus: @router rollback last 6h reverts (where possible) opened PRs, deleted branches, posted retractions. Some actions are irreversible (sent emails, customer replies) — those are flagged for manual cleanup. Every event captures a "how to undo" hint when it's written, so the rollback can replay reverse-order.

Three interaction patterns drop naturally onto the same Slack-plus-memory substrate. Each is a different access shape on the same coordination plane.

1. DM — one-on-one, ad hoc

Slack DM with any agent bot. You: "@bob how's the queue?" Bob queries the tasks table, replies with in-flight + queued + blocked. No meeting, just a quick question. Phase 1 supports this on day one — every agent gets its own bot user, every DM lands in the same coordination plane.

2. Daily standup — scheduled, multi-agent

A cron-fired @digest agent runs at 8 AM. Reads the last 24h of events, queries open tasks per agent, generates a unified post in #ops: yesterday's shipped work, today's queue, blockers. Each agent can thread-reply with detail. Phase 2 work — same shape as the weekly-digest pattern, just a shorter cadence.

3. Strategic meeting — long-running, decision-producing

You open a thread in #planning: "Q3 priorities discussion." The router tags it meeting:q3-strategy. Each agent reads its corner — Bob looks at the backlog, Steph at SERP opportunities, Ben at recurring failure patterns — and posts their input as a thread reply. You ask questions, agents respond. At the end you say "@router log decisions" and a meeting-summary agent extracts the decisions, writes ADRs to decisions/, and the broadcaster fans them out.

The first two patterns work today on the architecture's MVP. The third is a stretch — worth piloting only after a few months of muscle memory with the simpler patterns. Most solo founders running this haven't formalized strategic meetings yet; they treat decisions as Slack threads where they tag in agents one at a time, not as structured meetings.

Done (shipped + working)

• Seven agent skills: Steph, Kai, Bob, Lace, Simon, Ben, Overnight-Builder
• Overnight-builder pipeline (state machine + scheduled wakeups)
• Procedural memory: .claude/skills/
• Semantic memory: BRAND.md, AGENTS.md, data/specs/
• Episodic logs: data/overnight-logs/*.jsonl
• Build pipeline: Astro SSG + Cloudflare Pages + Supabase

Coming (Phase 1)

• Slack workspace + router bot + agent identities
• tasks / events / decisions tables
• Decision-as-event broadcaster (Cloudflare Worker)
• Webhook receivers (GitHub, Slack, cron)
• Migration of overnight-builder onto the new substrate
• .claude/workflows/ directory + workflow runner
• CHARACTER.md + STORY.md per agent (skeleton — content fills in over time)

Future (Phases 2–4)

• Mem0 semantic memory layer
• Weekly digest + editor agents
• Trust gradient + rollback
• Voice gate (per-agent tone consistency)
• External-facing agents (marketing, support, calendar, finance)
• Per-agent public surfaces (X account, newsletter, merch)
• Self-improvement loop (skill edits proposed by agents)
• Strategic-meeting chair agent + multi-agent coordination protocol

The point is the operating philosophy. The infrastructure is well-trodden — Slack + Cloudflare Workers + Supabase + MCP integrations is a solved stack. What's not well-trodden is your operating discipline: what gets agent-handled vs human-only, what trust gradient feels right, how often you review.

Build the smallest version. Run it for a month. Redesign. Don't try to design the final state on day one.