Agent Architecture

How AI actually gets used in this portal, and — more importantly — where it deliberately doesn't.

Read ARCHITECTURE.md first. This document assumes the cost model in it.

The correction to the standard picture

The usual "centralised orchestration" diagram puts a master AI agent at the top, dispatching to worker agents. In production that master is usually the part you delete.

An LLM deciding what to do next earns its cost only when the plan genuinely can't be predicted. Our pipelines are known in advance. A model routing a fixed pipeline adds latency, cost, and non-determinism in exchange for nothing.

        WHAT THE DIAGRAM SHOWS              WHAT WE BUILD
     ┌──────────────────────┐          ┌──────────────────────┐
     │   Master AI Agent    │          │  Orchestrator (CODE) │
     │  decides the plan    │          │  the plan is known   │
     └──────────┬───────────┘          └──────────┬───────────┘
                │ $$$ + non-determinism           │ $0 + deterministic
        ┌───────┼───────┐                  ┌──────┼──────┐
      Worker  Worker  Worker             Worker Worker Worker
                                          (judgment lives here)

Deterministic orchestration, smart workers. LLM-as-orchestrator is reserved for genuinely unpredictable work — which, so far, we don't have.

The rule that decides everything

Agents where volume is low and judgment is high. Code where volume is high and the path is fixed.

	Volume	Judgment	Implementation
Strategy: research, positioning, angles, critique	~1× per client per quarter	Very high	Agents
Copy variants per angle	~1× per angle	Medium	One batched agent call
Creative generation	Constant, thousands	Zero	Pure code — no LLM in the hot path

This is the same insight as hybrid rendering: pay for intelligence once, reuse it many times. It's also what makes the portal affordable at the volume you're planning.

The strategy pipeline (agentic)

Runs rarely. Produces the approved message angles that everything downstream is constrained to.

Orchestrator — deterministic code, not a model
  │
  ├─ research      → industry brief          (web search, competitor scan)
  ├─ profile       → client profile          (site, contract, brand kit)
  │        ↓ both feed the next stage
  ├─ strategy      → positioning + pillars
  ├─ angles ×N     → message angles          ← parallel, one worker per pillar
  └─ critic        → scores angles, flags the weak ones
             ↓
     ┌───────────────────────────────────┐
     │  HUMAN GATE — strategist approves │   ← the guardrail. Nothing downstream
     └───────────────────────────────────┘      exists without this.
             ↓
     copy worker  → ~20 headline/CTA variants per angle, ONE batched call

The human gate is both your business requirement and correct agentic design: put the human at the high-stakes decision, automate everything around it.

The generation pipeline (no agents at all)

approved angle + approved copy + cached scene + layout → composite → done

No LLM in the hot path. Marginal cost per creative after the scene is bought: effectively zero.

Practices this codebase holds to

Deterministic scaffolding over model-driven control flow. Code the loop; let the model do the judgment step inside it.
Structured output at every boundary. Every worker declares a schema and is validated against it. Free-text handoffs between agents are where these systems rot.
Right-size the model per worker. Classification and extraction don't need the top tier. The model is a per-worker declaration, not a global constant.
Prompt-cache the stable prefix. A client's brand kit, industry brief, and strategy are identical across every call for that client — cached reads cost ~10% of fresh input. Volatile content goes last; nothing dynamic above the cache breakpoint.
Batch instead of looping. One call returning 20 headline variants, not 20 calls.
Every run is durable and idempotent. Runs persist to jobs and resume; a retry never double-charges.
Every run logs what it spent. Without per-worker cost visibility you cannot control spend, and every other rule here becomes unverifiable.
A budget ceiling per run. Enforced by the orchestrator before a worker is dispatched, not discovered on the invoice.

Rough cost shape

Illustrative, for one client campaign — verify against real runs before trusting the numbers.

	This architecture	Naive "agent per creative"
Strategy pipeline	~$2–5, once per quarter	—
Copy variants	~$0.04 per angle (cached prefix)	—
Scenes bought	3–5	~150
LLM calls in generation	0	~150
Marginal cost per creative	~$0	image + LLM, every time

The gap is roughly two orders of magnitude, and it comes almost entirely from refusing to put a model in the high-volume path.

Roadmap note — MCP

Your original complaint was that MCP servers aren't shared across the team. The portal solves that for non-technical staff by removing the CLI entirely. Later, the same server-side tools can be exposed as an MCP server, so you and your dev can drive the portal from Claude Code while the team uses the UI — one set of credentials, two interfaces. Worth doing once the tools are stable; not before.

Brand Intelligence subsystem

A separate area of the portal from Creative Studio, with a different cadence and a different audience. Its job is keeping a client's knowledge base coherent so information doesn't degrade as it passes between strategist, scriptwriter, editor and media buyer.

That degradation is the actual problem. A founder says "15 years". A strategist writes "over a decade and a half". A scriptwriter compresses to "nearly two decades". A caption rounds to "20 years of trusted service". Nobody lied at any step, and the brand is now making a false claim.

The pipeline

content in  →  extract  →  reconcile  →  ┬→ auto-merge (audit trail only)
(script,       (facts,     (vs the       │
 transcript,    angles,     existing     └→ escalate → human deconflicts → canonical KB
 call, page)    voice)      KB)                                                  │
                                                                                 ▼
                                          validate ← every outbound script, caption, ad

Worker	Job	Status
`extract-features`	Facts, angles and voice out of raw content	Built
`reconcile`	What each fact means against the existing base	Built
`validate-claims`	Check outbound content against approved facts	Not built — see below

Escalation discipline is the whole design

Most differences between two sources are not conflicts. A queue that flags them all is ignored within a fortnight, and then the system is worse than nothing because there is now a queue nobody reads.

So reconcile classifies first. Duplicates, more precise restatements and figures that legitimately grew are merged and recorded; only contradictions, scope changes, unsupported restatements and backward drift reach a person. The full taxonomy is in skills/reconcile-knowledge-base/SKILL.md.

The distinction that does the most work: could both statements have been true when each was made? If yes it is drift, and drift is an update with history, not an alert.

The category that causes the most damage is scope_change — the claim looks the same and its boundaries moved. "Lifetime warranty on hardware" becoming "lifetime warranty". "From $19,000" becoming "for $19,000". Each reads as a rewording and behaves as a new promise.

The missing half — validating outbound content

Ingest keeps the knowledge base true. It does not stop a script drifting from it.

validate-claims is the other direction: before a script, caption or ad ships, check every factual claim in it against the approved knowledge base. A script claiming "20 years" against a base holding "15+ years" fails. A caption saying "lifetime warranty on carpentry" against a base holding "on carpentry hardware" fails.

This is what actually closes the broken-telephone loop, and it is the highest-value thing not yet built. It also makes the knowledge base self-justifying: the moment it blocks one wrong claim from reaching a paid ad, it has paid for itself.

Why this is backend-shaped

The work here is maintenance — irregular, judgment-heavy, done by strategists rather than the delivery team. It belongs behind its own area with its own queue, not mixed into the tool the delivery team opens every day.

This is NOT the Next.js you know

This version has breaking changes — APIs, conventions, and file structure may all differ from your training data. Read the relevant guide in node_modules/next/dist/docs/ (resolved from this file's directory; in monorepos the next package may not be visible from the repo root) before writing any code. Heed deprecation notices.

This block is written and re-added by next dev — verify at node_modules/next/dist/server/lib/generate-agent-files.js. Removing it from a diff only re-creates the uncommitted change; committing it with your work keeps the tree clean.