DOC ARCH-01 SYSTEM ENGINEERDAD MARKETING OS UPDATED 2026-06-17 SHEET 1 / 1

A marketing department,
drawn as a state machine.

The EngineerDad Marketing OS is a closed-loop marketing driver: each cycle it reads live ad-performance signals, reasons about what worked, writes its own briefs, scripts and renders bilingual creatives, designs the next experiment, and ships — with a human approving at every gate and a regulatory compliance scanner on every write. Built on Claude Code subagents, 15 custom MCP servers, and Postgres.

01 · The closed loop

Nine stages. Three human gates. Then it reflects.

One run walks the stages in fixed order, driven by a typed, resumable orchestrator (plan → verify → advance). Cyan stages spawn an agent with genuine decision space; everything else is deterministic code. At each amber gate the loop stops until a human approves in the review webapp.

S1
tracking
Validate the Meta CAPI path — synthetic canary lead
→
S2
analytics
Pull insights; rank creatives, cost-per-angle, decay
→
S3
synthesize
brain — 9-step scaffold → Decision Memo + hypotheses
→
S4
brief
brief-writer — 12 message-based briefs
→
HG1briefs■ STOP
→
S5
content
content-writer — hooks, scripts, authority articles
→
HG2scripts■ STOP
→
S6
produce
creative-director + render workers → creative variants
→
HG3creatives■ STOP
→
S7
schedule
Organic slots + paid flight windows
→
S8
experiment
Factorial design; 70 / 20 / 10 allocation
→
S9
distribute
YouTube unlisted · site drafts · Meta posting pack
↩ then /reflect grades the cycle's hypotheses — Confirmed | Refuted | Inconclusive — and promotes confirmed ones to Learnings, which feed the next run's synthesize stage. The system compounds.
agentic cell (LLM, open decision space) deterministic code human gate — loop stops
02 · Three layers, one direction

Agents decide. Code does everything else.

Dependency flows strictly downward. The conductor talks to exactly two surfaces — the orchestrator MCP and Claude Code's task spawner — and no MCP server ever opens a client to another MCP server.

COMMANDS.claude/commands/

The runtime entry points. /loop is the domain-agnostic conductor; scoped delegators (/brief, /content, /produce, /distribute…) resume a run at a stage. The conductor reasons; it never executes domain logic itself.

▼

AGENTIC CELLS.claude/agents/

Four subagents, each spawned by one stage — brain, brief-writer, content-writer, creative-director. Each has genuine open decision space. Nothing else in the system is an agent.

▼

DETERMINISTIC SUBSTRATEpackages/ + mcp-servers/

Pure typed logic in packages/; thin stdio MCP adapters over it. The orchestrator state machine, the compliance scanner, analytics + bandit math, BM25 corpus search, renderers and platform adapters — all testable without a model in the loop.

The agentic litmus test (ADR-020): a step is an agent only if a verifier could not make its judgement. Everything else is code.
03 · The four agentic cells

Small surface, real judgement.

brain

Runs a 9-step reasoning scaffold over the cycle's analytics → a Decision Memo with falsifiable hypotheses and budget allocation. Also runs the post-cycle Reflect grading.

brief-writer

Turns the Memo's angles into 12 message-based briefs — persona, promise, proof type, funnel stage, budget bucket. Angles, not audiences: creative-as-targeting doctrine.

content-writer

Approved briefs → hook banks (≥30 hooks, 6 emotional registers), scripts with data-bound claims, and AEO/GEO authority articles. Grounded on the BM25 corpus; 80% proof rule enforced.

creative-director

The taste layer — decomposes each script into storyboards, hook rotation, thumbnail briefs and chart selection. Returns a plan; never writes, never renders. Mechanical spec derivation is code.

04 · The MCP fleet

Fifteen custom stdio servers, no mesh.

Each server is a thin adapter over a sibling package library. Cross-server sequencing goes through the orchestrator hub; inside the workspace, library imports beat stdio calls (ADR-023).

Spine
orchestratortyped run-state machine store9 entities · compliance scan at write analyticsinsights · bandit · decay corpusBM25 search · compliance blocks experimentfactorial design + readout
Media production
static-rendererHTML → PNG (Chromium) heygenAI-avatar multi-scene reels asset-storeR2 CDN upload media-providers-geminiimage gen media-providers-kie-aidormant
Distribution — every write fails safe
meta-adshard-wired PAUSED meta-organicschedule-only youtubeunlisted-only distributemanual posting packs engineerdad_sitedraft-branch handoff

Grounding without a vector DB: all generation is grounded on a local, committed BM25 index over the compliance / courses / proof / knowledge corpus. Quantitative claims are bound to vetted datasets at authoring time (ADR-030) and enforced by verifiers — a chart ships only if a source-of-record dataset depicts it.

05 · Storage

One Postgres. Three schemas. One choke point.

postgres://engineerdad — Drizzle ORM, journaled migrations

  • public9 entity tables — briefs → learnings; the content lifecycle
  • orchestratorruns, steps, claim-check step results (JSONB + size audit)
  • analyticsevents audit trail, Meta insights, bandit signals

corpus/ — committed grounding material

  • compliance/SC Malaysia · FIMM · Public Mutual rules + banned phrases
  • courses/ proof/brand doctrine, frameworks, persona-keyed proof
  • data/datasets (source-of-record) → charts (derived, cited)
  • .index/BM25 index — travels with the clone

The compliance scanner fires at the store-package write boundary — one auditable choke point that both MCP writes and webapp server-action writes must pass through. Layer-aware, not transport-aware.

06 · Trust boundary

Autonomy inside, hard rails at the edge.

This system markets a licensed financial-advisory practice. The rails are not optional.

HUMAN-GATED WRITES

Every external write passes a human gate in the review webapp. Ad activation is human-only — the OS never sets a Meta ad to ACTIVE.

FAIL-SAFE ADAPTERS

meta-ads creates PAUSED, youtube uploads unlisted, meta-organic schedules only. Safety is hard-wired into the adapter, not the prompt.

COMPLIANCE SCANNER

SC-Malaysia / FIMM rules from the corpus run against the four content entities at the single write boundary. Non-compliant content cannot persist.

DATA-BOUND CLAIMS

Numbers in creatives must trace to vetted datasets; concept visuals may carry no digits. Verifiers enforce both — refusal is mechanical, not behavioural.

07 · Doctrine

Thirty ADRs carry the why.

The load-bearing ones, if you read only a few: