walid@portfolio:~/lab/social-media-agent-team$
cd../lab
01ideaOct 2026

An AI-native social media agent team

One orchestrator, eight departments, eight interrupts and one owner who approves: the full board, how the loop runs and the Claude Code project behind it, as published, with the board as pictures and all eight files the page shows, checked against Claude Code’s docs and each tool maker’s own

A one-screen design for running a company’s social media with AI agents, and the Claude Code project behind it: one orchestrator, eight departments, eight events that interrupt the loop, and one owner who approves. Here it is as published, with the board as pictures and all eight files the page shows. The checks found a design and a starter template, not a running system. As published it connects to no tools and nothing runs on its own; the page shows 8 of the project’s 55 files; its approval rules contradict each other; and three tool claims are wrong: Metricool doesn’t rotate ads, Midjourney has no official API, and Grammarly’s APIs return no corrections.

Claude CodeSubagentsSocial mediaOrchestratorMarketing opsClaude Code subagents ↗Claude Code slash commands and skills ↗Claude Code memory (CLAUDE.md) ↗Claude Code permissions ↗Claude Code hooks ↗
i
What this is

A design for a social media team made of AI agents, and a Claude Code project to start it from: one orchestrator that every event goes through, eight department agents, eight events that break into the loop as slash commands, a shared folder of brand files, and one owner who sets the voice, the budget and the approval bar. It’s republished as it was published: the board as pictures, then How it works, the interrupts table and the project with its eight files, word for word. Only the creator’s credit is removed. The checks are added in their own notes and columns: the Checked column beside each table row, the box under How it works, and the note just above each command block and file. The page’s own text is unchanged, and where it gets something wrong the note at that spot says so.

Checked, not copied

What held up, on 22 October 2026

Checked against the page and its eight files, Anthropic’s Claude Code docs, the agent and command files run through Claude Code 2.1.308’s own validator, and each tool maker’s docs and pricing pages.

ClaimWhat the sources say
“A Claude Code project that automatically runs the complete social media of a company”Not as published. Its own README says the tool connections are not configured, and the project has no MCP servers, hooks or schedule of its own. Out of the box Claude has its built-in tools (files, shell, web) plus any MCP servers or claude.ai connectors you’ve already added for all your projects, and it acts only when you start a session and type. Claude Code 2.1.283 and later start in auto mode, where a classifier, not you, approves most actions, MCP and connector tool calls included; start it with claude --permission-mode manual to be asked first.
“Eight events it handles the moment they happen”Each event is a slash command you type, with a description of what happened. Nothing in the project listens for Semrush, Brand24, Google Business Profile, Meta or ManyChat.
“A ready Claude Code project”The tree lists 55 files and the page shows 8 of them. Seven agents, seven commands, all 28 Brand OS files, the budget cap, TOOLS.md and the rest are names only, and there’s no download.
“open board/index.html”There’s no board/ folder in the project tree, and the page doesn’t provide one: the board is the page itself, the pictures below. open is also a Mac command.
“/agents lists the orchestrator and the eight department agents”Only up to Claude Code v2.1.197. Now /agents prints a reminder to ask Claude or look in .claude/agents/. Type @ to see the agents, or ask Claude to list them.
“Nothing publishes on its own”, and the safety railThe files contradict each other. CLAUDE.md and orchestrator.md (“Routine content ships end to end”) and approval-bar.md (“Ships on its own”) let routine content go out without the owner; the safety rail at the end of CLAUDE.md says nothing goes out without an approved item in the owner’s queue. Claude Code treats CLAUDE.md as context, not enforced settings, and when two instructions conflict it may follow either. Pick one rule and enforce it with permission rules or a hook.
The orchestrator hands each department its workWorks in current Claude Code: a subagent can start its own subagents, up to three levels below the main conversation (the default since v2.1.219). Neither agent file the page shows lists its tools, so both inherit all of them, Bash and any connected MCP server included; the other seven agent files aren’t on the page.
“LangGraph runs the agents, Postgres remembers”That’s the board’s reference stack, not the project. The project runs its agents as Claude Code subagents and keeps a plain log in logs/; its own CLAUDE.md says so.
“Metricool rotates the ads”Wrong as an agent step. In its app a person can switch Meta, Google and TikTok campaigns, ad groups and single ads on and off and change budgets, but Metricool documents no automatic rotation, and its MCP server can’t manage ads at all. For an agent, rotating ad creative takes the Meta Marketing API or the Google Ads API.
Midjourney and Grammarly as agent toolsWrong for both. Midjourney has no official API, and its guidelines say accounts that automate access may be blocked. Grammarly’s developer APIs return scores, not corrections. Images need a person or a model with an API; Claude does the edit pass.
The other tools on the boardReal, and most are within an agent’s reach through official MCP servers (Semrush, Canva, Metricool, Frase, SparkToro, Similarweb, HubSpot, Ahrefs) or APIs. Many need a paid plan or approval: Brand24’s API, Google Business Profile, LinkedIn, Figma layouts, and TikTok, where posts stay private until TikTok audits your app. Google Alerts has no API, and OpenAI’s whisper-1 shuts down on 26 February 2027.
The board itselfA static picture: the page’s live view is switched off, and clicking an interrupt card does nothing. Two zones are numbered 03 (the files use 03 for the Orchestrator), and the department numbers follow the list, not their places on the board.
The board

AI Native Social Media Agent Team

The whole system on one screen. Open it to read the tiles; the four close-ups below are the same board in sections, and the tables after them give its text.

Signals, system of record, owner input and the brain.
The orchestrator and the knowledge layer.
The eight departments.
Engage, the interrupts, data and the legend.
The board, zone by zone

What each zone says

The board’s text, for reading on a phone or in print. Tools in brackets are the logos on tiles that don’t name them; the emoji icons are left out. The Checked column is not on the page.

ZoneOn the boardChecked
01 SignalsOn the board“where every market and brand signal comes from” · GSC search queries · GA4 sessions · Semrush rankings · GBP reviews · FB & IG insights · LinkedIn analytics · YouTube analytics · Web mentions (Brand24)CheckedEight sources; TikTok, X, Pinterest and the ad platforms aren’t among them. Only GBP (new-review notifications), Brand24 (alerts), Semrush (ranking-change emails) and GA4 (custom-insight emails) alert you when something changes. Search Console can email owners a monthly summary, but to catch a change as it happens, it and the rest have to be asked on a schedule.
02 System of recordOn the board“the customer spine, one unified profile” · HubSpot CRM · Content calendar (Airtable) · Brand asset drive (Google Drive) · Brand wiki (Notion) · Segment CDP · Unified store (Supabase) · Publish calendar (Google Calendar)CheckedSeven separate tools, and nothing on the page joins them into one profile; Segment’s Unify can, on its Business tier. Of the seven, the eight files on the page name only HubSpot and Airtable.
Owner inputOn the board“what the one human sets” · HUMAN-LED · NOT COUNTED · Brand Voice · Budget cap · Approval bar · PositioningCheckedThe project’s owner/ folder: four files, two of them shown below.
03 The brainOn the board“the labour” · Claude reasoning · Agent runner (LangGraph) · Memory store (PostgreSQL) · Midjourney visuals · Voice-over (ElevenLabs) · Transcribe (Whisper, shown as “Wh”) · “Claude reasons and writes, LangGraph runs multi-step agents, pgvector remembers every topic and customer, Midjourney and ElevenLabs produce visuals and voice.”CheckedNumbered 03, like the Orchestrator; the project’s files use 03 for the Orchestrator. The project uses none of LangGraph, Postgres or pgvector. Midjourney has no official API. OpenAI’s whisper-1 shuts down on 26 February 2027; its replacement is gpt-transcribe.
03 OrchestratorOn the board“every event enters here first, nothing publishes on its own” · Collects every signal · Scores what matters now · Briefs the right department · Drafts in your voice · Schedules every channel · Approves or calls the owner · “Routine content ships end to end. Only budget changes and edge cases reach the owner.” · Claude AI · LangGraph · “reasons against the playbook, remembers with pgvector”CheckedThe board’s own wires go around the orchestrator: interrupts go straight to departments, replies straight to Reviews & Reputation, and escalations from Reviews and Leads straight to the owner. The tile says the orchestrator drafts; CLAUDE.md says the department does.
04 Knowledge layer + accessOn the board“the brand brain, one shared workspace · Brand OS file system” · /brand-brain 4 files · voice-guide.md · /signals-seo 4 files · keyword-map.md · /content 4 files · content-calendar.md · /creative 3 files · visual-specs.md · /social 3 files · channel-playbooks.md · /reputation 3 files · gbp-response.md · /conversation 3 files · faq-library.md · /reporting 3 files · kpi-model.md · Owner dashboard · Approval queue · Activity log · Permissions · Alerts · Kill switchCheckedThe folders and file counts match the project tree. The project has the approval queue and the log; the dashboard, permissions, alerts and kill switch have no counterpart in it. In Claude Code the real stops are interrupting the session, permission rules and hooks.
05 DepartmentsOn the board“eight departments an owner recognizes · the orchestrator hands each one its work”CheckedThe cards and their tiles are in the next table.
06 EngageOn the board“approved content goes back out from one brain” · Metricool scheduler · WordPress posts · GBP posts · Chat replies (ManyChat) · Audience · followers, customers, reviewersChecked“Approved” mostly means approved by the orchestrator: on the board only budget changes and edge cases reach the owner. Nothing receives replies, reviews or DMs until tools are connected.
07 Data & observabilityOn the board“the numbers behind every card” · Airbyte · dbt · BigQuery · Looker · Vercel · Sentry · Flags (LaunchDarkly)CheckedAirbyte, dbt, Vercel, Sentry and LaunchDarkly appear in none of the eight files on the page; Looker and BigQuery appear only in CLAUDE.md’s table, as Results & ROI tools. Vercel, Sentry and Flags are engineering tools (hosting, error tracking, feature flags), not marketing numbers, and the static board shows no numbers.
What interrupts the loopOn the board“things that used to need a marketer at a desk · handled as they happen” · Search demand spikes · Competitor drops a promo · One-star review lands · Content calendar looks thin · A post goes viral · Ranking drops a page · Ad creative fatigues · DM / lead at 11pmCheckedEach card shows the tools that handle it, as icons; the interrupts table below spells them out. Clicking a card does nothing.
Wires and legendOn the boardreads the playbook · replies come back · escalates to the owner · results feed Signals again · Legend: buyer journey · feedback loop · human control · background data · safety netCheckedThe “buyer journey” wires trace the content pipeline, not a customer’s path. The only escalation wires run from Reviews and from Leads, none from the Orchestrator or for budget.
05 Departments

The eight departments and their tiles

On the board the cards sit in wiring order, not by number: 02 then 01 on the top row, 06 then 05 on the third. Tools in brackets are the logos on tiles that don’t name them. The Checked column is not on the page.

DepartmentTilesChecked
01 Search visibilityTilesGSC queries · Semrush ranks · GA4 sessions · Ahrefs backlinks · Site crawl (Screaming Frog)CheckedAll reachable. Search Console’s API has had hourly data for the last 10 days since April 2025; its own screens show only the last 24 hours. Screaming Frog runs from its command line on your own computer; it has no cloud API.
02 Market radarTilesSemrush rivals · Brand24 mentions · Audience research (SparkToro) · Traffic intel (Similarweb) · Alerts watch (Google Alerts)CheckedGoogle Alerts has no API: an agent can only read the alert emails or an RSS feed. Brand24’s API is a paid add-on or comes with Enterprise. Similarweb needs a plan with API access. SparkToro has had an MCP server since June 2026.
03 Content engineTilesClaude drafts · Surfer briefs · Frase research · Grammarly · Content calendar (Airtable)CheckedGrammarly has no API that returns corrections, so Claude does the edit pass. Frase has an MCP server on every plan. Surfer’s API returns a Content Score and the terms to add; use its V2 endpoints.
04 Creative studioTilesCanva graphics · Midjourney · Remotion video · Figma layouts · Voice-over (ElevenLabs)CheckedMidjourney has no official API. Figma layouts need Figma’s MCP server, in beta, on a Professional, Education, Organization or Enterprise plan; its REST API can’t draw them. Canva’s MCP server edits designs on every plan; autofill from brand templates needs Pro or above. Remotion is free for individuals, non-profits and companies of up to three people; bigger for-profit companies need a paid company licence.
05 Publishing & socialTilesMetricool · WordPress · GBP posts · Facebook · Instagram · LinkedIn · TikTokCheckedMetricool’s MCP server schedules posts on every plan, including Free. The GBP API needs an approved application; LinkedIn’s is vetted; posts from your own TikTok app stay private until TikTok audits it, so post TikTok through Metricool. Instagram needs a professional account.
06 Reviews & reputationTilesGBP reviews · Podium · NiceJob · Claude reply · Mentions watch (Brand24)CheckedGBP review replies work once API access is approved. Podium has an OAuth API. NiceJob’s API needs developer credentials from its support team, and its review endpoints aren’t public.
07 Leads & conversationsTilesManyChat · HubSpot · Twilio SMS · Calendly · Front inboxCheckedManyChat replies inside Meta’s 24-hour messaging window; its Notify Admins alerts go by email, and its phone app can send push notifications. Texts from a Twilio local (10DLC) number to US phones need A2P 10DLC registration; toll-free numbers and short codes have their own approval. Use Calendly’s API v2; v1 is gone.
08 Results & ROITilesLooker · BigQuery · Metabase · Margin watchCheckedLooker is Google’s enterprise BI, not the free Looker Studio. “Margin watch” is a gauge that names no tool.
How it works

One loop that runs the complete social media of a company

1

Signals come in

Search Console, GA4, Semrush, GBP, Meta, LinkedIn, YouTube and Brand24 watch search demand and mentions all day.

2

System of record and owner input

HubSpot, Airtable, Drive, Notion, Segment and Supabase hold every customer and asset. The owner sets voice, budget cap, approval bar and positioning once.

3

The brain

Claude reasons and writes, LangGraph runs the agents, Postgres remembers, Midjourney and ElevenLabs make visuals and voice.

4

Everything enters the orchestrator

Collects, Scores, Briefs, Drafts, Schedules, Approves. Every event enters here first and nothing publishes on its own.

5

Knowledge layer

Every department reads the Brand OS files (voice guide, keyword map, hook bank and the rest) before it writes.

6

Eight departments do the work

Search Visibility, Market Radar, Content Engine, Creative Studio, Publishing & Social, Reviews & Reputation, Leads & Conversations, Results & ROI.

7

ENGAGE sends it out

Metricool, WordPress, GBP and chat replies reach the audience. Replies, reviews and DMs come back through Reviews & Reputation.

8

The loop closes

Data & Observability feeds Results & ROI, and the results feed Signals again.

!
How much of the loop is real

As published, none of it runs by itself. Signals: “all day” means asking most sources on a schedule (GBP, Brand24, Semrush and GA4 can send alerts, but nothing in the project receives them), and the project has no schedule. The brain: the project runs its agents as Claude Code subagents and keeps a plain Markdown log; LangGraph and Postgres are the board’s reference stack, and Midjourney has no official API, so a person or a model with an API has to make those images. The orchestrator: “nothing publishes on its own” means nothing goes past it, not that the owner signs off on each post. Knowledge layer: it’s an instruction, and only the Content Engine file is shown following it. ENGAGE: nothing receives replies, reviews or DMs until tools are connected. The loop closes only as a line written to logs/results.md after something is published, and someone running Claude again. Not on the page.

What interrupts the loop

Eight events it handles the moment they happen

As published, with a Checked column added (not on the page). None of these fires on its own: in the project each one is a slash command you type with a description of the event.

WhenWhat happensCommand in the projectChecked
Search demand spikesWhat happensSemrush flags the spike, Claude drafts the contentCommand in the project/search-demand-spikesCheckedSemrush has no demand-spike alert: its Position Tracking alerts are for your own rankings, by email. Claude has to pull Semrush data through its official MCP server, or Search Console’s hourly data, and spot the jump itself.
Competitor drops a promoWhat happensBrand24 flags it, Claude re-briefs the plan, Canva refreshes the creativeCommand in the project/competitor-drops-a-promoCheckedBrand24 alerts on spikes in mentions of keywords you add, so add the competitor’s name; Claude decides whether it’s a promo. Canva’s MCP server edits designs. The project’s own approval bar says a reply to a competitor’s promo waits for the owner; this row leaves that step out.
One-star review landsWhat happensGBP alerts, Claude drafts the reply, the owner approvesCommand in the project/one-star-review-landsCheckedWorks: Google sends new-review notifications, and replies post through the Business Profile API, once your access application is approved (you have to manage a Business Profile that’s been verified and active for 60 days or more).
Content calendar looks thinWhat happensClaude fills the calendar, Metricool schedules the postsCommand in the project/content-calendar-looks-thinCheckedWorks through Metricool’s MCP server. The page names four calendars (Airtable, Google Calendar, content-calendar.md and Metricool) without saying which one is the real one.
A post goes viralWhat happensClaude repurposes it, Meta boosts itCommand in the project/a-post-goes-viralCheckedPossible with Meta’s Marketing API, which turns a post into a paid ad. That spends money and needs an ad account; no ads tool is part of the project, and its own safety rail needs the owner’s OK before any spend.
Ranking drops a pageWhat happensSemrush alerts, Surfer refreshes the contentCommand in the project/ranking-drops-a-pageCheckedSemrush’s ranking alerts arrive by email only; to react, Claude reads Position Tracking through the Semrush MCP server. Surfer scores the page and lists the terms to add; its app’s Auto-Optimize can work them in, but its API has no endpoint for that, so for an agent Claude does the rewrite.
Ad creative fatiguesWhat happensCanva rebuilds the creative, Metricool rotates the adsCommand in the project/ad-creative-fatiguesCheckedWrong as an agent step: Metricool has no automatic rotation (in its app a person can switch single ads on and off), and its MCP server can’t manage ad campaigns at all. Rotate creative through the Meta Marketing API or the Google Ads API, with the owner’s OK, since live ads spend money.
DM / lead at 11pmWhat happensManyChat auto-replies and wakes the owner only if it is realCommand in the project/dm-lead-at-11pmCheckedManyChat auto-replies. “Only if it is real” is logic you build into the flow. ManyChat alerts you by email or with a push from its phone app; a Twilio text is another way to wake the owner. An automatic reply also breaks the project’s own rule that nothing is sent without approval.
Claude Code project

Run it yourself

A ready Claude Code project: the orchestrator rules, nine agents, the eight interrupts as slash commands, the Brand OS tree and the owner's four levers. Fill the templates with your brand, connect your tools, and run it.

!
Before you run it

Out of the box this is a scaffold. The page shows 8 of its 55 files: two of the four owner files and none of the 28 Brand OS files, so you write the rest, along with the seven missing agents and seven missing commands. To make it act, connect your tools as MCP servers, give each agent a tools: list so that only Publishing & Social can post (the orchestrator’s list needs Agent, so it can still hand out work), and enforce one approval rule with Claude Code permission rules or a PreToolUse hook. The project itself connects to nothing, but Claude Code also loads any MCP servers you’ve added for all your projects and, if you sign in with a Claude account, your claude.ai connectors, which agents with no tools: list inherit. When claude starts, type /mcp before you ask it for anything, to see what’s connected. And Claude Code 2.1.283 and later start in auto mode, where a classifier approves most actions without asking you, MCP and connector tool calls included; start it with claude --permission-mode manual to be asked before most edits, shell commands and network calls. Not on the page.

(There’s no download, so the first line works only once you’ve made the folder and saved the files below into it under the paths shown; otherwise claude starts in whatever folder you’re in. The page’s second line fails either way: there’s no board/ folder in the project tree, and the page doesn’t provide one. The “board” is the page itself, the pictures above. open is also Mac-only: on Windows it’s start, on Linux xdg-open.)

terminal3 lines
cd ai-native-social-media-agent-team
open board/index.html
claude

The project tree, 55 files. The page shows the contents of the eight below; the other 47 are names only, and there’s no download. Not on the page.

ai-native-social-media-agent-team/71 lines
ai-native-social-media-agent-team/
├── .claude/
│   ├── agents/
│   │   ├── content-engine.md
│   │   ├── creative-studio.md
│   │   ├── leads-conversations.md
│   │   ├── market-radar.md
│   │   ├── orchestrator.md
│   │   ├── publishing-social.md
│   │   ├── results-roi.md
│   │   ├── reviews-reputation.md
│   │   └── search-visibility.md
│   └── commands/
│       ├── a-post-goes-viral.md
│       ├── ad-creative-fatigues.md
│       ├── competitor-drops-a-promo.md
│       ├── content-calendar-looks-thin.md
│       ├── dm-lead-at-11pm.md
│       ├── one-star-review-lands.md
│       ├── ranking-drops-a-page.md
│       └── search-demand-spikes.md
├── brand-os/
│   ├── brand-brain/
│   │   ├── messaging-bank.md
│   │   ├── positioning.md
│   │   ├── tone-rules.md
│   │   └── voice-guide.md
│   ├── content/
│   │   ├── brief-templates.md
│   │   ├── content-calendar.md
│   │   ├── hook-bank.md
│   │   └── seo-checklist.md
│   ├── conversation/
│   │   ├── auto-reply-scripts.md
│   │   ├── faq-library.md
│   │   └── routing-rules.md
│   ├── creative/
│   │   ├── asset-library.md
│   │   ├── video-scripts.md
│   │   └── visual-specs.md
│   ├── reporting/
│   │   ├── attribution.md
│   │   ├── kpi-model.md
│   │   └── margin-rules.md
│   ├── reputation/
│   │   ├── gbp-response.md
│   │   ├── mentions-rules.md
│   │   └── review-flow.md
│   ├── signals-seo/
│   │   ├── keyword-map.md
│   │   ├── ranking-targets.md
│   │   ├── serp-rules.md
│   │   └── tracking-setup.md
│   ├── social/
│   │   ├── channel-playbooks.md
│   │   ├── hashtag-rules.md
│   │   └── posting-schedule.md
│   └── README.md
├── logs/
│   └── results.md
├── owner/
│   ├── approval-bar.md
│   ├── brand-voice.md
│   ├── budget-cap.md
│   └── positioning.md
├── queue/
│   ├── held-for-voice-review.md
│   └── needs-your-ok.md
├── CLAUDE.md
├── README.md
└── TOOLS.md
The files

The eight files the page shows

The creator’s credit line is removed. (The README says /agents lists the agents; in current Claude Code it prints a reminder instead, so type @ or ask Claude. board/index.html isn’t in the project, and “automatically runs” overstates it: by the README’s own table no tools are connected. The “+340%” is an example. Two of the README’s bash lines end in # comments, which zsh on a Mac passes on as extra words; copy the terminal block above instead.)

README.md26 lines
# AI Native Social Media Agent Team

A Claude Code project that automatically runs the complete social media of a company: one orchestrator, eight departments,
eight interrupt playbooks, a shared Brand OS, and one owner who only approves.

## Open it

```bash
cd ai-native-social-media-agent-team
open board/index.html      # the full system: live view, how it runs, this project
claude                     # start Claude Code in this project
```

Inside Claude Code:

- `/agents` lists the orchestrator and the eight department agents.
- `/search-demand-spikes "glass skin routine +340%"` runs one interrupt playbook.
- Ask "run the orchestrator on today's signals" to walk the pipeline: Collects → Scores → Briefs → Drafts → Schedules → Approves.

## What you fill in

| Part | Status |
|---|---|
| Orchestrator rules (`CLAUDE.md`), agents, slash commands, Brand OS tree | Ready |
| File contents in `brand-os/` and `owner/` | Templates. Write them for your brand |
| Tool connections (Semrush, Brand24, Metricool, HubSpot and the rest) | Not configured. See `TOOLS.md` |

Loads by itself when you start claude in the folder, and the project’s agents read it too. Its rules contradict each other: lines 8, 25 and 33 let routine content go out without the owner, while the safety rail at the end says nothing goes out without an approved item in queue/needs-your-ok.md. CLAUDE.md is context, not enforced settings, and Claude may follow either rule, so decide on one and enforce it before the first run, since MCP servers and claude.ai connectors you already have count too. The pipeline also schedules before it runs the gates, so a post scheduled live in Metricool goes out even if a later gate fails: schedule into Metricool’s review stage instead. And nothing can text the owner until a messaging tool such as Twilio is connected. Not on the page.

CLAUDE.md80 lines
# Social Media Team: orchestrator rules

This project runs a social-media operation as one orchestrator, eight departments and one owner.
Open `board/index.html` to see the full system.

## How it works

> "Every post goes through it first. It checks the voice, checks the budget, and sends it out.
> If something's off, it stops and calls the owner. It doesn't do the work itself, it just decides who does.
> The owner still owns the voice, the budget, and anything that reads like a promise. Everything else runs."

## The one rule

**Every event enters the orchestrator first. Nothing publishes on its own.**

## The pipeline (03 · Orchestrator)

Collects → Scores → Briefs → Drafts → Schedules → Approves

1. **Collects**: read new signals (01 SIGNALS) and the system of record (02).
2. **Scores**: decide whether the event is worth acting on.
3. **Briefs**: write a brief and hand it to the department that owns the work.
4. **Drafts**: the department drafts. The orchestrator never does the work itself. It decides who does.
5. **Schedules**: Publishing & Social places the item on the calendar.
6. **Approves**: run the two gates below, then send it out.

## The two gates on every item

- **Checks the voice.** Compare the draft with `owner/brand-voice.md` and `brand-os/brand-brain/`.
  If it does not sound like the brand, it does not go out. Log it in `queue/held-for-voice-review.md`.
- **Checks the budget.** Compare spend with `owner/budget-cap.md`. At the cap, hold and ask.

"Routine content ships end to end. Only budget changes and edge cases reach the owner."

## When something is off

Stop and call the owner. Add the item to `queue/needs-your-ok.md` with **Hold / Approve**
and send the owner a short text (see the example thread in that file). Do not guess.

## What the owner still owns

The voice, the budget, and anything that reads like a promise. Everything else runs.
The owner's four levers live in `owner/` and are **human-led, not counted** as agents.

## Who does what

| Department | Agent | Board tools |
|---|---|---|
| Search Visibility | `search-visibility` | GSC, Semrush, GA4, Ahrefs, Screaming Frog |
| Market Radar | `market-radar` | Semrush, Brand24, audience research tile, Similarweb, Google Alerts |
| Content Engine | `content-engine` | Claude, Surfer, Frase, Grammarly, Airtable |
| Creative Studio | `creative-studio` | Canva, Midjourney, Remotion, Figma, ElevenLabs |
| Publishing & Social | `publishing-social` | Metricool, WordPress, GBP, FB & IG, LinkedIn, TikTok |
| Reviews & Reputation | `reviews-reputation` | GBP, Podium, NiceJob, Claude, Brand24 |
| Leads & Conversations | `leads-conversations` | chat tile (Messenger, IG, WA), HubSpot, Twilio, Calendly, Front |
| Results & ROI | `results-roi` | Looker, BigQuery, Metabase, margin watch |

## Memory and playbook

"Reasons against the playbook, remembers with pgvector."
The playbook is `brand-os/`. Read the relevant folder before any draft. Memory is a vector store
(pgvector on Postgres in the board's stack); this scaffold keeps a plain log in `logs/` until one is connected.

## Closing the loop

Every published item writes a line to `logs/results.md`
("Result logs to record → Results & ROI reads it"). Results & ROI reads that log and feeds
01 SIGNALS again. That return edge is what makes the system a loop.

## Interrupts

Eight events break into the loop. Each one is a slash command in `.claude/commands/`:
`/search-demand-spikes`, `/competitor-drops-a-promo`, `/one-star-review-lands`,
`/content-calendar-looks-thin`, `/a-post-goes-viral`, `/ranking-drops-a-page`,
`/ad-creative-fatigues`, `/dm-lead-at-11pm`.

## Safety rails for this scaffold

- Never publish, post, send, or spend from this project without an approved item in `queue/needs-your-ok.md`.
- Tool connections are not configured here. `TOOLS.md` lists what each board tile is for.

A valid Claude Code subagent. With no tools: line it inherits every tool, Bash, Write and any connected MCP server included, so add an allowlist before the first run, since MCP servers and claude.ai connectors you already have count too. Keep Agent in that list, or it can no longer hand work to the department agents. To be sure Claude uses it, write @agent-orchestrator rather than naming it in plain words. Subagents can’t stop to ask you a question, so “calls the owner” means a row in queue/needs-your-ok.md. Not on the page.

.claude/agents/orchestrator.md16 lines
---
name: orchestrator
description: Every event enters here first. Runs Collects → Scores → Briefs → Drafts → Schedules → Approves, checks voice and budget, delegates to departments, and stops to ask the owner when something is off.
---

You are the orchestrator of a one-owner social media team. Follow `CLAUDE.md` exactly.

- Nothing publishes on its own. Every event comes through you first.
- You do not do the work yourself. You decide which department does it and hand over a brief.
- Before anything goes out, check the voice (`owner/brand-voice.md`, `brand-os/brand-brain/`)
  and the budget (`owner/budget-cap.md`).
- Routine content ships end to end. Budget changes, edge cases and anything that reads like a
  promise go to `queue/needs-your-ok.md` with Hold / Approve, plus a one-line text to the owner.
- After an item is published, append a line to `logs/results.md`.

Output for each event: what came in, its score, who you briefed, the gates' results, and the next step.

Loads in Claude Code, but its description isn’t strict YAML (the colon after “department”); put it in quotes so other tools can read the file. Grammarly has no API that returns corrections, so Claude does that pass. Surfer scores content against what ranks (its own study puts the correlation at 0.28); it can’t make a page rank, and until Surfer is connected any “SEO score” is Claude’s estimate. “Can’t post in a voice that isn’t yours” is an instruction: only a tools list or a hook would stop a post. Not on the page.

.claude/agents/content-engine.md11 lines
---
name: content-engine
description: Content Engine department: Brief → Draft → SEO pass → Hook. Claude writes, Surfer makes it rank, Grammarly cleans it. Holds anything off-brand.
---

Board tools: Claude (drafts copy), Surfer (briefs), Frase (research), Grammarly (editing), Airtable (content calendar).
What it does: "It reads what people are searching and the voice you set once. Then it builds the piece,
Brief, Draft, SEO Pass, Hook. Claude writes, Surfer makes it rank, Grammarly cleans it, and it can't post
in a voice that isn't yours. If it doesn't sound like the brand, it doesn't go out."
Read `brand-os/content/` and `brand-os/brand-brain/`. Return the draft with its SEO score and the fixes made.
Off-brand drafts go to `queue/held-for-voice-review.md`, not out.

Works as a slash command: the file name becomes /search-demand-spikes, and $ARGUMENTS is whatever you type after it. .claude/commands still works, though skills (.claude/skills) are now the preferred format. What runs is a prompt: with no Semrush connected, step 1 doesn’t happen, and Claude works from the words you type. The other seven command files aren’t on the page. Not on the page.

.claude/commands/search-demand-spikes.md16 lines
---
description: Interrupt · Search Demand Spikes (Semrush, Claude)
argument-hint: <a search term or topic and its jump>
---

Interrupt from "What Interrupts The Loop": **Search Demand Spikes**.

Event: $ARGUMENTS

Send this event to the orchestrator agent first. Nothing publishes on its own.

What the board's card says happens:
1. **Semrush**: SEO flags spike
2. **Claude**: Drafts content

Run the voice and budget gates from CLAUDE.md before anything goes out.

A template with a sample brand, a skincare studio: replace it before running, or every draft is judged against that voice. Its approved example, “two openings left this week”, is an availability promise, which approval-bar.md says waits for the owner. Not on the page.

owner/brand-voice.md34 lines
# Brand Voice

_Set once, checked on every draft._  
OWNER INPUT · human-led · not counted as an agent.

## Voice in one paragraph
_Example (a skincare studio):_
> Warm, confident, a little playful. Talks like a knowledgeable friend, never a lecture.
> Short sentences. No hard-sell language. Every claim has to be something we can actually back up.

## Do
- Friendly
- Specific claims
- Real before/after
- Emoji, sparingly

## Never
- ALL CAPS hype
- Fear-based hooks
- Medical claims

## Dials (0–100)
| Warmth | Confidence | Playfulness | Formality |
|---|---|---|---|
| 92 | 84 | 61 | 28 |

## Examples
- ✗ "LIMITED SPOTS!! Book NOW before it's too late!!" (rejected: hype + urgency)
- ✓ "We've got two openings left this week if you've been meaning to come in." (approved)

## Sample caption on file
> Your skin doesn't need 12 steps. It needs the right 3, done consistently. Here's what we'd actually put on your shelf.

_Replace the example with your own brand. Last edited by the owner: (date)._

“Ships on its own” agrees with CLAUDE.md’s pipeline and contradicts its safety rail; here “on its own” means without the owner, while on the board “nothing publishes on its own” means without the orchestrator. Replies to one-star reviews, which the interrupts table sends to the owner, aren’t on this list. Not on the page.

owner/approval-bar.md13 lines
# Approval bar

_What ships without the owner and what waits for a yes._  
OWNER INPUT · human-led · not counted as an agent.

## Ships on its own
- Routine content that passes the voice check and stays inside the budget.

## Waits for the owner (goes to `queue/needs-your-ok.md`)
- Budget changes
- Edge cases
- Anything that reads like a promise (prices, guarantees, results, availability)
- A reply to a competitor's promo

Example rows and an example thread; the file says to clear them. No ads tool is part of the project, so nothing in it can pause or spend on TikTok ads, and nothing sends the owner a text. The files name two queues for off-brand drafts: this one (its second row) and held-for-voice-review.md, which isn’t on the page. Not on the page.

queue/needs-your-ok.md18 lines
# Needs your OK

_Items wait here when the orchestrator stops. Everything else published itself._
The owner answers with **Hold** or **Approve**.

| Item | Why it stopped | Status |
|---|---|---|
| Budget cap reached | TikTok ads spend hit 90% of monthly cap, needs sign-off before more spend | (example) |
| Post flagged: off-brand voice | A promo draft used hype language that doesn't match the saved voice profile | (example) |
| Competitor response ready to send | Drafted reply to a rival's promo, ready to publish before lunch | (example) |

## How the owner gets pulled in: a text thread, not a meeting

> **Social media agent:** Post held: TikTok ad spend is at 90% of this month's cap. Want me to raise the cap or pause new ads?
> **Owner (9:43 AM):** Pause for now, resume next month
> **Social media agent:** Done. New TikTok ads paused. Everything else keeps running.

_The three rows and the thread are examples. Clear them before use._