Agent Hierarchy & Org Structure

Design Principle: One Agent, One Function

Each agent does exactly one thing:

• One type of input
• One type of output
• One system prompt that fits on a single page
• One test that fully verifies its job

This makes agents easier to build, easier to test in isolation, and easier to diagnose when they fail. The Activity Planner chains them into pipelines — the agents themselves stay dumb and single-purpose.

Full Agent Roster

SETUP CHAIN (once per tenant, run in sequence on registration)
─────────────────────────────────────────────────────────────
 Client Researcher ──┐
                     ├──► Context File Writer ──► Context File
 Competitor Researcher ──┘

STRATEGY CHAIN (once, after context approved — or on refresh)
─────────────────────────────────────────────────────────────
 Context File ──► Strategy Writer ──► Deliverable Planner
                                              │
                                     Goals + Monthly Deliverable Plan

ORCHESTRATION (each deliverable period)
─────────────────────────────────────────────────────────────
 Deliverable Plan ──► Activity Planner ──► dispatches tasks to workers below

WORKER AGENTS (dispatched by Activity Planner)
─────────────────────────────────────────────────────────────

 SEO Chain:
   Keyword Researcher ──► Content Brief Writer
   Site Auditor
   Backlink Researcher ──► Backlink Outreach Writer

 Content Chain:
   Blog Writer
   GBP Post Writer
   Social Post Writer
   Email Writer
   Landing Page Writer
   Google Ads Writer
   Meta Ads Writer

 Planning:
   Social Calendar Planner

 Ads Analysis:
   Ads Analyst

 Reporting:
   Report Writer
   Anomaly Detector

 Research (Ollama/local):
   Topic Researcher ──► Research Note Writer

REACTIVE AGENTS (triggered by external events, not Activity Planner)
─────────────────────────────────────────────────────────────
 Review Response Writer  (new review on GBP/Facebook → draft response)

SYSTEM AGENTS (live background automation)
─────────────────────────────────────────────────────────────
 Blog AI Agent  [Live]
 Billing Agent  [Live]

Pipeline Examples

Blog Post Pipeline

Topic Researcher → [HITL: approve topic list]
     ↓ approved topic
Content Brief Writer → [HITL: approve brief]
     ↓ approved brief
Blog Writer → [HITL: approve draft]
     ↓ approved
Published to WordPress

Social Media Pipeline

Social Calendar Planner → [HITL: approve calendar]
     ↓ for each approved calendar item
Social Post Writer → [HITL: approve post]
     ↓ approved
Published to connected social channel

Backlink Pipeline

Backlink Researcher → [HITL: approve prospect list]
     ↓ for each approved prospect
Backlink Outreach Writer → [HITL: approve email]
     ↓ approved
Sent via connected email channel

Paid Ads Pipeline

Google Ads Writer → [HITL: approve copy]   Meta Ads Writer → [HITL: approve copy]
     ↓ approved                                  ↓ approved
Pushed to Google Ads                       Pushed to Meta Ads Manager
     ↓ (next month)
Ads Analyst → [HITL: review recommendations]

Monthly Report Pipeline

Report Writer (pulls GA4 + Ads + channel data) → [HITL: review report]
     ↓ approved
Sent to tenant via email
     ↑ also feeds
Anomaly Detector (runs same data) → alerts to DM Portal if anomalies found

Agent Role Definitions

Setup Chain

Client Researcher

Queue: agent__client-researcher Input: Tenant domain URL + any seed info (industry, products, services) Output: Structured research doc — company overview, products/services, brand tone, target audience, existing content Model: Claude Sonnet 4.6 Tools: web_search, web_fetch (client’s site only) Doc: docs/agents/client-researcher.md

Competitor Researcher

Queue: agent__competitor-researcher Input: Client industry + top competitor domains (from seed or Onboarding) Output: Competitor analysis — positioning, content topics, keyword overlap, gaps Model: Claude Sonnet 4.6 Tools: web_search, web_fetch, semrush_competitor_overview Doc: docs/agents/competitor-researcher.md

Context File Writer

Queue: agent__context-file-writer Input: Client Researcher output + Competitor Researcher output Output: Client Context File — the single Markdown skill doc injected into all future agents for this tenant Model: Claude Sonnet 4.6 Tools: none (synthesis only) Doc: docs/agents/context-file-writer.md

Strategy Chain

Strategy Writer

Queue: agent__strategy-writer Input: Approved Client Context File Output: Marketing strategy document — goals, recommended channels, content focus, rationale Model: Claude Sonnet 4.6 Tools: none (reasoning from context) Doc: docs/agents/strategy-writer.md

Deliverable Planner

Queue: agent__deliverable-planner Input: Approved strategy document Output: Structured deliverable plan — list of deliverable types, monthly volumes, platforms, priority order Model: Claude Sonnet 4.6 Tools: none (reasoning from strategy) Doc: docs/agents/deliverable-planner/index.md

Orchestration

Activity Planner

Queue: agent__activity-planner Input: Deliverable plan for the current period Output: Ordered list of activity tasks with agent assignments and dependencies Model: Claude Sonnet 4.6 Role: Orchestrator only — does NOT generate content. Reads the plan, decides the pipeline sequence, creates Activity records, enqueues tasks to worker queues. Doc: docs/agents/activity-planner/index.md

SEO Chain

Keyword Researcher

Queue: agent__keyword-researcher Input: Client domain + target topics from context file Output: Keyword clusters — primary keyword, secondary keywords, search intent, monthly volume, difficulty Model: Claude Sonnet 4.6 Tools: semrush_keyword_overview, semrush_keyword_magic, google_search_console (read) Doc: docs/agents/keyword-researcher.md

Content Brief Writer

Queue: agent__content-brief-writer Input: Single keyword cluster from Keyword Researcher Output: SEO content brief — recommended title, H2 structure, target word count, target keywords, angle/hook, competing articles to beat Model: Claude Sonnet 4.6 Tools: web_search (SERP analysis for target keyword) Doc: docs/agents/content-brief-writer.md

Site Auditor

Queue: agent__site-auditor Input: Client domain URL Output: Technical SEO audit report — crawl issues, meta tag problems, page speed flags, internal linking gaps, structured data issues Model: Claude Sonnet 4.6 Tools: semrush_site_audit, web_fetch (spot-check pages), google_search_console (crawl errors) Doc: docs/agents/site-auditor.md

Backlink Researcher

Queue: agent__backlink-researcher Input: Client niche + existing backlink profile Output: Backlink prospect list — target domains, DR score, relevance reason, contact page URL Model: Claude Sonnet 4.6 Tools: semrush_backlink_analytics, ahrefs_site_explorer, web_search Doc: docs/agents/backlink-researcher.md

Backlink Outreach Writer

Queue: agent__backlink-outreach-writer Input: Single approved prospect (domain, contact, their content focus) Output: One personalized outreach email — subject line + body Model: Claude Sonnet 4.6 Tools: none (writing only) Doc: docs/agents/backlink-outreach-writer.md

Content Writing Chain

Blog Writer

Queue: agent__blog-writer Input: Approved SEO content brief + Client Context File (skills) Output: Full blog post — title, introduction, H2 sections, conclusion, internal link suggestions, meta description Model: Claude Sonnet 4.6 (long context, high quality) Tools: none (writing only; research done by Research Note Writer upstream if needed) Doc: docs/agents/blog-writer.md

GBP Post Writer

Queue: agent__gbp-post-writer Input: Business info + month/topic/offer + Client Context File (skills) Output: Single GBP post — body text (1,500 chars max) + call-to-action button type Model: Claude Sonnet 4.6 Tools: none Doc: docs/agents/gbp-post-writer.md

Social Post Writer

Queue: agent__social-post-writer Input: Platform (Instagram/LinkedIn/Facebook/X/TikTok) + content brief + approved calendar item Output: Single post copy — body text, hashtags, emoji use, platform-specific formatting Model: Claude Sonnet 4.6 Tools: none Doc: docs/agents/social-post-writer.md

Email Writer

Queue: agent__email-writer Input: Campaign brief (goal, offer, audience) + optional performance data to reference Output: Email newsletter — subject line, preview text, header, body sections, CTA Model: Claude Sonnet 4.6 Tools: none Doc: docs/agents/email-writer.md

Landing Page Writer

Queue: agent__landing-page-writer Input: Product/service brief + target audience + primary CTA Output: Landing page copy — hero headline, sub-headline, features/benefits sections, social proof placeholder, CTA copy Model: Claude Sonnet 4.6 Tools: none Doc: docs/agents/landing-page-writer.md

Google Ads Writer

Queue: agent__google-ads-writer Input: Campaign brief + keyword list + landing page URL Output: RSA copy set — 15 headlines (30 chars each) + 4 descriptions (90 chars each), with pinning recommendations Model: Claude Sonnet 4.6 Tools: none (formatting constraints enforced via Zod validator post-generation) Doc: docs/agents/google-ads-writer.md

Meta Ads Writer

Queue: agent__meta-ads-writer Input: Campaign brief + target audience + visual concept (if available) Output: Ad copy variants — 3–5 primary text variants, 3 headline variants, link description Model: Claude Sonnet 4.6 Tools: none Doc: docs/agents/meta-ads-writer.md

Planning Agent

Social Calendar Planner

Queue: agent__social-calendar-planner Input: Approved strategy + platforms + month + deliverable volume Output: Monthly social content calendar — 30 days of post items, each with platform, content type, topic/hook, format (static/reel/story/carousel) Model: Claude Sonnet 4.6 Tools: none Doc: docs/agents/social-calendar-planner.md

Paid Ads Analysis

Ads Analyst

Queue: agent__ads-analyst Input: Google Ads + Meta Ads performance data (last 30 days) Output: Analysis report — top/bottom performers, wasted spend, recommended changes, bid strategy notes Model: Claude Sonnet 4.6 Tools: google_ads_reports, meta_ads_insights Doc: docs/agents/ads-analyst.md

Reporting

Report Writer

Queue: agent__report-writer Input: GA4 data + Ads data + social metrics + goal progress + review summary Output: Monthly performance report — executive summary, channel-by-channel breakdown, goal progress, next month recommendations Model: Claude Sonnet 4.6 Tools: ga4_reports, google_ads_reports, meta_ads_insights Doc: docs/agents/report-writer.md

Anomaly Detector

Queue: agent__anomaly-detector Input: Current metrics vs prior period (traffic, conversions, ad spend, cost-per-result) Output: Alert list — each anomaly with metric name, % change, likely cause, recommended action Model: Claude Haiku 4.5 (lightweight; just needs to identify deviations and write a short explanation) Tools: none (metric comparison logic handled pre-agent; agent writes the narrative) Doc: docs/agents/anomaly-detector.md

Research Agents (Ollama/local)

Topic Researcher

Queue: agent__topic-researcher Model: gemma3:4b (Ollama — local, cost-free) Input: Client industry + niche + list of recent published topics (to avoid repeats) Output: List of 10–15 blog topic ideas — each with a working title, angle/hook, why it’s relevant now Tools: web_search (SerpAPI or Tavily) Doc: docs/agents/topic-researcher.md

Research Note Writer

Queue: agent__research-note-writer Model: gemma3:4b (Ollama — local, cost-free) Input: Single approved blog topic Output: Research notes — key stats with sources, 3–5 reference articles, competitor angle analysis, suggested examples Tools: web_search, web_fetch Doc: docs/agents/research-note-writer.md

Reactive Agent

Review Response Writer

Queue: agent__review-response-writer Input: Single review — platform, star rating, review text, reviewer name Output: Draft response + classification (sentiment, topics, urgency flag, requiresHITL) Model: Claude Sonnet 4.6 Tools: none Trigger: Polling (every 6h) or webhook from Meta/GBP HITL rule: All 1–3 star reviews → mandatory human sign-off before posting. 4–5 star → bulk-approvable. Doc: docs/agents/review-response-writer.md

System Agents (Background Automation — Live)

These run in response to platform events; not part of the marketing pipeline.

Blog AI Agent

Status: [Live] Trigger: New BlogRequest record created What it does: Picks up the request and generates an initial blog draft. Visible as the “assigned to” principal in the Request Queue (M12/M13). Future: Will be superseded by the Blog Writer + Content Brief Writer pipeline for deliverable-driven blogs. Kept for ad-hoc request queue blogs.

Billing Agent

Status: [Live] Trigger: Billing events (subscription renewal, overage, manual trigger) What it does: Auto-creates invoice records. Appears in invoice audit trail.

Deliverable → Agent Pipeline

Agent Availability by Plan

Setup + Strategy Agents

SEO Agents

Content Agents

Planning + Analysis + Reporting

Research Agents (Ollama/local)

Reactive Agents

System Agents (always on — not plan-gated)

BullMQ Queue Reference

Org Chart in the Dashboard

The /team/org-chart view renders all agents as nodes. Layout:

• Setup chain (Client Researcher → Competitor Researcher → Context File Writer) at the top
• Strategy chain (Strategy Writer → Deliverable Planner) below setup
• Activity Planner as the central orchestrator node
• Worker agents in functional clusters below: SEO, Content, Planning, Analysis, Reporting, Research
• Reactive agents (Review Response Writer) in a side lane
• Human users shown at each HITL gate point

Post-MVP Agents (Not in Current Scope)