<aside> 💡 Use case: write the rules once, in one file, and every agent in the project follows them. This is where the kill switch, the owner gates and the "never invent numbers" rule live.
</aside>
<aside>
📜 CLAUDE.md is a Markdown file in the root of the project folder. Claude Code reads it automatically at the start of every session in that folder, so you never paste the rules in by hand. If an agent file or a brief ever disagrees with it, CLAUDE.md wins.
</aside>
<aside>
🛑 Rule zero: the kill switch. Before every action, every agent checks for a file called owner/STOP. If it is there, nothing is written, scheduled, sent or spent. Only you create or delete it.
</aside>
<aside> 🗂️ Folder map. Where everything lives: the agents, the playbooks, the brand templates, the owner files, the two queues, the drafts and the log. Agents use it to find files without guessing.
</aside>
<aside>
🧑💼 The owner gates. Agents read your four owner files before acting, never edit them, and stop if any [FILL IN: ...] prompt is left. Nothing publishes or spends unless your approval bar allows it. The budget cap is never passed. Five kinds of work always wait for you, whatever the bar says.
</aside>
<aside> 🔁 The 6 moves. Collects, Scores, Briefs, Drafts, Schedules, Approves. Every piece of work follows them in order.
</aside>
<aside> 🤝 How departments hand off. Departments never brief each other. The orchestrator writes a brief, the main Claude Code session hands it to the department named in it, and the orchestrator runs again to decide the next step.
</aside>
<aside>
🔐 Who writes where. A small table of which agent may write to which folder. This is the Permissions control in plain text. Each agent's tools: line is the other half.
</aside>
<aside>
📝 Drafts and queue conventions. One naming pattern for every draft, front matter on every draft, no overwrites. New queue items go at the bottom, only you tick a box, decided items move to ## Done.
</aside>
<aside>
📒 Logging convention. One line per action in logs/activity.md, always in the same four-part format, append only.
</aside>
<aside> 🚫 Facts and numbers. No invented numbers, prices, quotes, reviews, customer names or results. Anything unsourced is marked [VERIFY], and an item with a [VERIFY] mark always waits for you.
</aside>
<aside> 🔌 Tool connections. Start with weekly exports in the right folder. Add an API or MCP connection later and nothing else changes.
</aside>
<aside> ▶️ How to start a session. The seven steps every session follows, from the kill switch check to the end-of-session report.
</aside>
<aside>
📋 Copy this into CLAUDE.md in the root of your project folder.
</aside>
# AI Social Media Team: project rules
This project is an AI social media team that runs inside Claude Code. One orchestrator agent reads
every signal, decides what matters this week and briefs eight department agents. The departments
draft, design, schedule, answer and report. One human, the owner, sets the voice, the budget, the
approval bar and the positioning, and approves anything above that bar.
Every agent and every session in this folder follows the rules below. If a rule here conflicts with
an agent file or a brief, this file wins.
## Rule zero: the kill switch
Before every action, check whether the file `owner/STOP` exists.
If it exists: stop. Do not write, schedule, send or spend anything. Append one line to
`logs/activity.md` with the action `stopped: owner/STOP present` and tell the owner the system is
paused. Only the owner removes `owner/STOP`. No agent creates, edits or deletes it.
## Folder map
- `CLAUDE.md`: this file. The rules.
- `README.md`: what the project is and how to start.
- `.claude/agents/`: `orchestrator.md` plus the 8 department agents:
search-visibility, market-radar, content-engine, creative-studio, publishing-social,
reviews-reputation, leads-conversations, results-roi.
- `.claude/commands/`: the 8 playbooks, run as slash commands (for example `/one-star-review-lands`).
- `brand-os/`: 27 brand templates in 8 folders. Signal exports land in `brand-os/signals-seo/`.
- `owner/`: brand-voice.md, budget-cap.md, approval-bar.md, positioning.md. Read-only for agents.
- `queue/needs-your-ok.md`: items waiting for an owner decision.
- `queue/held-for-voice-review.md`: drafts that failed the voice check.
- `drafts/`: everything a department produces. Briefs from the orchestrator go in `drafts/briefs/`.
- `logs/activity.md`: one line for every action any agent takes.
## The owner gates
1. Read all four `owner/*.md` files before any action that writes, schedules, sends or spends.
2. `owner/` is read-only. Never edit, rename or delete a file in it. If an owner file is empty or
still has `[FILL IN: ...]` prompts, do not guess: stop and ask the owner to fill it.
3. Nothing publishes and nothing spends unless `owner/approval-bar.md` says it may auto-ship.
Everything else goes to `queue/needs-your-ok.md` and waits for a ticked box.
4. Never pass the budget in `owner/budget-cap.md`. A spend that would pass it is not queued as a
normal item: it is queued with the words `OVER CAP` in the title, and it never auto-ships.
5. These always wait for the owner, whatever the approval bar says: any paid spend or budget
change, any reply to a negative review, anything that names a real person or customer,
anything that mentions a price or an offer, and anything with an unresolved [VERIFY] mark.
## The 6 moves
Every piece of work moves through these six steps, in this order:
1. Collects: read the newest signals in `brand-os/` and the open items in `queue/`.
2. Scores: the orchestrator ranks what matters this week.
3. Briefs: the orchestrator writes one brief per job to `drafts/briefs/`.
4. Drafts: the named department does the job, in the owner's voice.
5. Schedules: Publishing & social puts approved work on the publish calendar.
6. Approves: work inside the approval bar ships; everything else waits in the queue.
## How departments hand off
- Departments never brief each other. All work goes through the orchestrator.
- The orchestrator writes briefs. The main Claude Code session then hands each brief to the
department named in it, for example: "Use the content-engine agent on drafts/briefs/<file>".
- A department returns three things: the file it wrote, its check results, and anything it
could not finish. The orchestrator is then run again to decide the next step.
- When a playbook fires, its event goes to the orchestrator first. Playbook events are handled
before the weekly plan.
## Who writes where
| Agent | May write to | Never |
|---|---|---|
| orchestrator | drafts/briefs/, queue/, logs/ | publish, schedule, spend |
| departments | drafts/, queue/held-for-voice-review.md, logs/ | edit owner/, brief another department |
| publishing-social | drafts/, logs/, the publish calendar (approved items only) | schedule an unapproved item |
| everyone | logs/activity.md (append only) | edit or delete an existing log line |
## Drafts convention
- Save every draft as `drafts/YYYY-MM-DD-<channel>-<slug>.md`.
- `<channel>` is one of: linkedin, instagram, facebook, tiktok, youtube, blog, gbp, email, chat.
- `<slug>` is 3 to 6 lowercase words joined with hyphens.
- Start each draft with front matter: channel, brief, voice_check, sources.
- Never overwrite a draft. A new version gets `-v2`, `-v3` on the end of the slug.
## Queue convention
- `queue/needs-your-ok.md`: new items go at the bottom, in the format shown at the top of that
file. The owner ticks `- [x] Approve` or `- [x] Reject`. Agents never tick a box.
- `queue/held-for-voice-review.md`: a draft that fails the voice check goes here with the rule it
broke. Do not quietly fix a voice failure and send it on.
- When an item is decided, the orchestrator moves it to the `## Done` section at the end of the
same file and logs the decision.
## Logging convention
Append one line per action to `logs/activity.md`, in this exact format:
YYYY-MM-DD HH:MM | <agent> | <action> | <file>
Use the agent's file name without `.md`. Use `-` when no file was touched. Log reads only when they
change a decision. Log every write, every queue item, every hand-off and every stop.
## Facts and numbers
- Never invent numbers, statistics, prices, quotes, reviews, customer names or results.
- Use only facts found in the brief, the `brand-os/` files, the `owner/` files or a signal export.
- Mark anything you could not source as [VERIFY]. An item with a [VERIFY] mark always waits.
- Every draft lists its sources in front matter.
## Tool connections
Start with weekly exports dropped into the right `brand-os/` folder. When a real connection (an API
or an MCP server) is added later, the agents read the same folders, so nothing else changes. If a
connection fails, say so in the log and fall back to the latest export. Never guess the missing data.
## How to start a session
1. Check for `owner/STOP`. If it exists, stop and say so.
2. Read the four `owner/*.md` files.
3. Read the last 20 lines of `logs/activity.md` and every open item in both `queue/` files.
4. Run: "Use the orchestrator agent to run this week's loop."
5. Hand each brief it lists to the department named in it, one at a time.
6. Run the orchestrator again to process returns and ticked approvals.
7. End by telling the owner what shipped, what waits, and what was held.
ai-social-media-team/
├── CLAUDE.md ← here, next to README.md
├── README.md
├── .claude/
├── brand-os/
├── owner/
├── queue/
├── drafts/
└── logs/