Agent Spec Template — Governed Revenue Architecture

substrate

Control plane primitives

Four primitives every agent must use. Without these, nothing else is real.

Identity

Canonical account/contact/opportunity IDs. Lead→account mapping rules. Dedupe policy.

Permissions

Tool access by role + data domain + environment. Read vs write separation.

Provenance

Every decision logs inputs, weights, model version, tool calls, and output.

Approvals

Explicit human gates for high-impact actions. Campaign send, CRM write, budget realloc.

build order

The sequence

Each layer depends on the prior. Read-only first. Bounded writes earned, not assumed.

Start with “read-only agents.” They produce plans, not actions. They output structured JSON with rationale + confidence + evidence. Only then add bounded-action agents—smallest permissions, smallest surface area, smallest blast radius.

phase a weeks 1–2

Identity & Hygiene Provenance & Audit

phase b weeks 2–4

Signal & Scoring Routing & SLA

phase c weeks 4–6

P&L / Unit Economics Forecast / Stage Ledger

phase d weeks 6–10

Motion Orchestration Content / Positioning

phase e post-trust

Experimentation Security / Governance

the template

Agent spec structure

Every agent uses this template. No exceptions. This is how you prevent the agent layer from turning into folklore.

agent 01 Identity & Hygiene Agent phase a — foundation read-only → limited write

purpose

Normalize the identity substrate. Ensure every object in the CRM has a canonical ID, correct parent mapping, and no duplicate pollution. Without this, nothing downstream is trustworthy.

inputs

CRM lead/contact/account/opportunity objects
Email domain → account mapping table
Third-party enrichment signals (Clearbit, ZoomInfo)
Historical merge/dedupe logs

tools

crm.read — query objects across all entities
crm.write.merge — merge confirmed duplicates (gated)
enrichment.lookup — domain/firmographic resolution
audit.log — provenance write for every action

outputs

Identity graph: canonical IDs + parent mappings
Hygiene backlog: flagged duplicates, orphaned leads, unmapped accounts
Structured JSON: {entity_id, action, confidence, evidence[]}
Weekly hygiene drift report

guardrails

Confidence threshold for auto-merge: ≥ 0.95
Max batch size per run: 200 objects
Enrichment rate limit: 500 calls/hour
No deletes. Ever. Only merges and flags.

never list

Delete any CRM record
Change account ownership
Modify opportunity amounts or stages
Merge below confidence threshold without human approval
Override manual territory assignments

human gates

Any merge with confidence < 0.95 → queue for ops review
Any lead→account mapping that conflicts with existing territory → RevOps approval
First 50 auto-merges → 100% human audit (trust calibration)

provenance schema

field

type

description

agent_id

string

identity-hygiene-v1

action

enum

flag | merge | map | enrich

entity_ids

string[]

Canonical IDs of affected objects

confidence

float

0.0 – 1.0, model-assigned

evidence

object[]

Matching signals: domain, name, email patterns

model_version

string

Semantic version of decision logic

tool_calls

object[]

Every external call: tool, params, response_code

approval_state

enum

auto | pending_review | approved | rejected

timestamp

ISO 8601

UTC execution time

test cases

scenario

input

expected output

pass

Exact domain match

Two leads, same domain, same company name

Merge recommended, confidence ≥ 0.95

—

Ambiguous match

Similar names, different domains

Flag for review, confidence 0.6–0.94

—

Territory conflict

Lead maps to account owned by different rep

Route to RevOps, no auto-merge

—

Orphan detection

Contact with no parent account

Flag + enrichment lookup + suggested mapping

—

Batch limit

Queue of 500 pending merges

Process 200, defer rest, log deferral

—

registry

Agent registry

Every agent has an entry. Name, purpose, owner, tools, permissions, data domains, escalation path, version.

agent

purpose

mode

phase

Identity & Hygiene

Normalize objects, detect duplicates, map lead→account

read → write

A

Provenance & Audit

Log decisions, generate traces, detect policy violations

read-only

A

Signal & Scoring

Classify readiness vs motion, detect staleness, compute probability deltas

read-only

B

Routing & SLA

Assign ownership, enforce SLAs, manage queues

recommend → write

B

P&L / Unit Economics

Compute CAC, payback, LTV:CAC by segment/motion

read-only

C

Forecast / Stage Ledger

Separate ledger truth from forecast, detect stage inflation

read-only

C

Motion Orchestration

Choose motion lane, pick next best action, trigger sequences

recommend → write

D

Content / Positioning

Translate segment economics into messaging + proof points

read-only

D

Experimentation

Propose tests, estimate impact, enforce stopping rules

recommend

E

Security / Governance

Permission drift, anomaly detection, prompt-injection checks

always-on

E

non-negotiable

Build alongside agents

Agent Registry

Name, purpose, owner, tools, permissions, data domains, escalation path, versioning. If it’s not in the registry, it doesn’t exist.

Policy-as-Code

Simple rules first: “no CRM writes without human approval,” “no campaign send without preview + confirm.” Enforced, not suggested.

Evaluation Harness

Offline test set: historical deals + known outcomes. Metrics: precision/recall for “ready,” time-to-action, error rate, false positives by segment.

Kill Switch

Per-agent and global. No heroics. If something goes wrong, you need to stop it in seconds, not hours.

first milestone

Read-only control plane

Identity is normalized. Signals are interpreted into probability deltas. Routing recommendations are produced. Every output has provenance. Nothing writes without approval.

That’s when it stops being a concept and starts being infrastructure.

back to doctrine explore spine