Agent Contracts Spec

Purpose

Each agent has a versioned input and output schema. All agents consume a shared artifact (Evidence Layer or prior reports); no agent re-scrapes or re-interprets raw HTML. No cross-agent duplication of reasoning.

Contract Version

AGENT_CONTRACT_VERSION: "1" (in core/agents/types.ts). Bump when any agent I/O schema changes.

CMO

Role: Positioning, distribution, narrative.
Input (v1): Evidence Layer (and optionally legacy pageEvidence/enrichedData for the current pipeline steps). Defined as CmoAgentInputV1.
Output (v1): Canonical: Report 1 (Report1Result) from runReportFromCrawl + buildCmoReportFromDiscovery. Alternative: CmoAgentResult from runCmoAgent (3-prompt path); not used by any route in v1.
Source of truth: Report 1 is the canonical CMO output; stage and recommendation come from discoveryVerdict.verdict.
No re-crawl: When run from roles flow, CMO uses stored crawl only. runCmoAgent without preCrawled runs interns internally; that path is not used by the roles API.

CDO

Role: Visual, UX, brand signal.
Input (v1): Evidence Layer + ui_captures (CaptureResult[]). Defined as CdoAgentInputV1.
Output (v1): CdoAgentResult from runCdoAgent (UX blockers, design system audit, UI rewrite plan). Schemas in core/schemas/cdo-output.ts.
No re-crawl: When preCrawled is provided, no interns run.

BD

Role: Market landscape, competitive positioning.
Input (v1): Report 1 only. Defined as BdAgentInputV1.
Output (v1): Report2Result (distribution relevance, expert quotes, cases, companies like you). Type in lib/types.ts.
No crawl: BD is prompt-only on Report 1.

COO

Role: Operational feasibility, execution risk.
Input (v1): Report 1 + Report 2. Defined as CooAgentInputV1.
Output (v1): Report3Result (what to change, strategies, small wins, next actions, one thing this week). Type in lib/types.ts.
No crawl: COO is prompt-only on Report 1 and Report 2.

Shared Artifact Registry

Artifact	Produced by	Consumed by
Crawl (company_crawls)	Shared crawl pipeline	Evidence normalizer, CMO path, CDO path
Evidence Layer	`normalizeFromCrawl()`	CMO (conceptually), CDO (conceptually), orchestration
Report 1	CMO path (`runReportFromCrawl` + assemble)	BD, COO, UI, save
Report 2	BD	COO, UI, save
Report 3	COO	UI, save

Rules

No agent re-scrapes or re-interprets raw HTML. All consume Evidence Layer or prior reports.
No agent produces conflicting judgments on the same dimension. Stage/recommendation are owned by CMO (Report 1).
Input/output schemas are versioned; changes require contract version bump and doc update.

Stage authority

In v1, stage authority is the CMO agent (Report 1). Orchestration and all downstream consumers use the stage from Report 1 only. Future versions may introduce weighted cross-agent scoring; for v1 there is no ambiguity.