Build and customize GTM OS by talking to Claude

The model in one minute

Goal: know what happens between "you ask" and "it is live", so you can predict what Claude will do and where it will stop.

1. You say what you want in plain words.
2. Claude looks up the exact operation (with the gtm_describe tool) and calls it with its own agent key. The key acts for you but is never you.
3. Reads and internal changes run at once. A change that goes live, or anything aimed at a customer (a send, a CRM write, a merge, a page change, an ad budget change), becomes a proposal.
4. A different person with the owner or admin role approves the proposal in the console (Approvals), then executes it. Needs a human
5. GTM OS writes down who proposed, who approved and what ran. You can read that trail in Settings > Audit log.

Claude never approves anything, and neither can you for what your own agent proposed. This rule is called four-eyes. It is the reason you need a second approver from day one (see Approvals and four-eyes).

The pieces you will touch

The five operation classes

Goal: read the class letter of an operation and know what a call will do.

The 0.2.5 catalog has 671 operations: 294 Q, 255 D, 5 T, 30 E and 87 M. You do not memorize them. Claude lists them with gtm_describe, and your project holds the full generated list at docs/gtmos/reference/operations.md after gtm init.

What ships in 0.2.5, and what does not

Goal: know which engines exist today, so you never ask Claude to configure something that is not there.

Seven engines ship as packages. Each runs on your signed definitions and falls back to a built-in default when you have none.

Around the engines sit things that are not packaged engines but have their own pages and operations: plays (Engines > Plays), routing (Engines > Routing), the research agent (CRM > Research), CRM sync, source mappings, the adapter builder (CRM > Adapters) and AI chat.

Four safety rules that explain most of what you will see

• Four-eyes. Whoever proposes a change can never approve it. For an agent's proposal, the person the agent acts for cannot approve it either. A second owner or admin must.
• Dev first, then prod. Every organization has dev, staging and prod. prod is the default: a call that names no environment runs in prod. Definitions cannot be published straight into prod. They are written in dev, signed by a person, then promoted. Customer-facing effects in dev and staging are recorded but not sent.
• Dry first, then live. Dry Mode (Settings > Safety) turns every customer-facing action into a draft across the whole organization. Each engine also has its own mode, dry or live, and in a new organization every engine starts dry until a person flips it.
• Never fake data. A value with no source is shown as unverified. Fixture data in a demo instance is marked as fixture. Claude must tell you when a check is not green.

The working loop

Goal: one loop you repeat for every change, whatever the engine.

1. Describe. Claude reads the operation or definition kind it is about to use.
2. Change in dev. Claude writes the change to dev and says so.
3. Propose. Claude reports the approval id and stops. Needs a human
4. Approve and sign. A second person approves, then signs the definition. Needs a human
5. Promote. One approval promotes everything from dev to prod (CRM > Environments, the Go live card). Needs a human
6. Verify. Claude reads the result back and shows you the proof, for example a record, a score reason or a readiness line.

The build chapters go through each step in detail. For now, remember the sentence Claude should end with after any definition change: "I wrote X in dev. It is not live until it is signed and promoted."

Where to look in the console

Console paths are written as Group > Page. Every page lives under /org/<orgId>/.

First prompt to try

Call agent.whoami, policy.get_dry_mode and instance.readiness. Then tell me in plain words: who you are acting as, which scopes your key has, whether Dry Mode is on, which providers are live, and what you cannot do without a person.

Untested. This prompt was not run against a live instance. Operation names were checked against the 0.2.5 catalog.

Check the prerequisites

Goal: a machine that can run the stack and a working gtm command.

• Docker Desktop, installed and running.
• 10 GB or more of free disk (images plus database).
• 4 GB or more of free RAM for the stack (Postgres, API, worker, MCP, console). On Windows, Docker runs in WSL 2. If containers are killed, raise the memory limit in %UserProfile%\.wslconfig and restart Docker.
• Node 22 or newer.
• Claude Code.
• The gtm CLI from npm:

npm i -g @gtmos/cli

docker info --format '{{.ServerVersion}}'
node -v
gtm version --offline

Make a workspace and run gtm init

Goal: an empty folder that Claude Code can work in, loaded with GTM OS skills, slash commands and the MCP entry.

1. Make a folder and start Claude Code in it:

   mkdir my-gtm && cd my-gtm
   claude

2. Inside Claude Code, the ! prefix runs a shell command. Run:

   ! gtm init

3. Quit Claude Code and start it again in the same folder. Claude reads new slash commands and skills only at startup.

With no instance yet, gtm init never fails. It scaffolds offline and tells you what to do next. If an instance already answers on this machine at http://127.0.0.1:3001, it says so.

Let Claude install the instance: /setup-gtmos

Goal: a running instance, an owner, a second approver and a connected agent key, with Claude doing the typing.

/setup-gtmos

Claude checks the prerequisites, then asks you one grouped question: use an instance already running here or install a new one; organization name; owner email (you); approver email (a different person); version (stable or a local image tag); ports; and which provider keys you have ready.

Prefer to see every step yourself? The next section does the same by hand.

The same thing by hand

Goal: install an instance and connect a workspace without /setup-gtmos. Commands are for bash. On PowerShell, write $env:NAME = "value" instead of export NAME=value.

1. Install into its own folder. The owner and approver passwords are generated into its .env:

   gtm setup gtm-instance --org "Acme" --email you@acme.example --approver-email cofounder@acme.example

   Port busy? Add --console-port, --api-port, --mcp-port or --postgres-port. Local images only? Add --version <tag> --no-pull.
2. Sign in as the owner. It asks for the password, or reads GTMOS_PASSWORD. Your org id is ORGANIZATION_ID in gtm-instance/.env:

   export GTMOS_API_URL=http://127.0.0.1:3001 GTMOS_ORG=<org id>
   gtm login --email you@acme.example --console-url http://localhost:3000

   Run the export GTMOS_TOKEN=... line it prints. This is your owner session. It is not the agent key.
3. Create the agent key. It is shown once:

   gtm token create --name claude-code --client claude-code --preset full-gtm-engineer --expires-days 90

4. Put the key in your environment (next section).
5. Connect the workspace and check it:

   gtm init --url http://127.0.0.1:3001 --key <agent key> --yes
   gtm doctor

6. Start claude in the workspace and run /mcp.

Exit codes of gtm init: 0 done, 1 usage or file error, 2 instance or key problem, 3 refused key. It refuses a credential that can approve (a person's session), because a coding agent must only propose.

Put the key in your environment

Goal: Claude Code finds the key through GTMOS_AGENT_TOKEN and the key never lands in a file you might commit.

Windows PowerShell (persistent, then open a new terminal):

[Environment]::SetEnvironmentVariable('GTMOS_AGENT_TOKEN', '<agent key>', 'User')

macOS or Linux: add this line to ~/.zshrc or ~/.bashrc, then open a new terminal:

export GTMOS_AGENT_TOKEN='<agent key>'

The MCP address defaults to http://localhost:3004/mcp. To point at another address, set GTMOS_MCP_URL. .mcp.json reads it as ${GTMOS_MCP_URL:-http://localhost:3004/mcp}.

Connect Claude Code

Goal: the gtmos MCP server shows as connected, with all nine tools.

1. In Settings > Developer, the Connect Claude Code / Codex card creates the same key as gtm token create. Choose the coding agent, an agent name and the preset, then Create agent key. Copy the key now. The page also shows your org id, the MCP address and copy-ready snippets. Needs a human
2. Set GTMOS_AGENT_TOKEN as above, then in the workspace folder run gtm init --url <api url> --key <agent key> --yes.
3. Restart Claude Code in the folder and run /mcp.

The .mcp.json that gtm init writes has this shape (the URL is your instance's MCP address):

{
  "mcpServers": {
    "gtmos": {
      "type": "http",
      "url": "${GTMOS_MCP_URL:-http://localhost:3004/mcp}",
      "headers": { "Authorization": "Bearer ${GTMOS_AGENT_TOKEN}" }
    }
  }
}

To make every MCP call in this project default to dev, run gtm init --env dev. It adds an x-gtmos-environment header to that entry. Without it, calls that name no environment run in prod.

Quick check that the key works, outside Claude (bash):

curl -s -X POST "http://localhost:3004/mcp" \
  -H "Authorization: Bearer $GTMOS_AGENT_TOKEN" \
  -H "Content-Type: application/json" -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Keep the project current after you upgrade the CLI or the instance. Files you edited are kept:

gtm init --refresh --yes

Connect Claude Desktop

Goal: ask questions of your instance from Claude Desktop. Know first what you give up.

GTM OS speaks streamable HTTP and wants an Authorization: Bearer header. Claude Desktop starts local programs from its config file. To bridge the two you run a small helper in between. The steps below use mcp-remote.

Untested path. The bridge steps below were not run against a GTM OS instance, and the mcp-remote flags may differ in its current release. Whether a Claude Desktop custom connector (Settings > Connectors) can reach a GTM OS MCP server is not confirmed. If the bridge does not connect, use Claude Code.

1. Create a key for it in Settings > Developer. Choose Other MCP client, give it its own name (for example claude-desktop-anna), and pick the read-only preset unless you need more. Use a short expiry. Needs a human
2. In Claude Desktop open the Claude menu, then Settings, then Developer, then Edit Config. This opens claude_desktop_config.json. Its usual location is %APPDATA%\Claude\claude_desktop_config.json on Windows and ~/Library/Application Support/Claude/claude_desktop_config.json on macOS.
3. Add the server. Node must be installed, because npx runs the bridge:

   {
     "mcpServers": {
       "gtmos": {
         "command": "npx",
         "args": ["-y", "mcp-remote", "http://127.0.0.1:3004/mcp", "--header", "Authorization:${GTMOS_AUTH}"],
         "env": { "GTMOS_AUTH": "Bearer <agent key>" }
       }
     }
   }

4. Quit Claude Desktop completely and start it again.
5. In a new chat open the Add files, connectors, and more menu, then Connectors, and check that gtmos is listed.

The cost of this setup: the agent key is written into the config file. Treat that file like a password. Never commit it, never share it, use a read-only or short-lived key, and revoke the key in Settings > Developer when you stop using Desktop. .mcp.json avoids this for Claude Code because it only references an environment variable.

Prompts for this chapter

/setup-gtmos

Check that the gtmos MCP connection works. Call agent.whoami and show me my agent name, my scopes and whether I can approve. Then run gtm doctor and summarize anything that is not LIVE. Do not change anything.

Untested. This prompt was not run against a live instance. Operation names were checked against the 0.2.5 catalog.

The nine tools at a glance

Every call goes through the same path as the console and the REST API. Claude has no side door. Everything the console does is an operation, so what you can click, Claude can do, minus the things only a person may do (see What only a person can do).

gtm_describe: look before you call

Goal: get an operation's exact input shape so no field name is guessed.

Arguments: name (an operation name, optional) and class (Q, D, T, E or M, optional).

gtm_describe {}                                   the whole catalog
gtm_describe { "class": "E" }                     only customer-facing effects
gtm_describe { "name": "records.search" }         one operation in full

With no name you get one row per operation: name, class, method, summary, required scopes, error codes. With a name you also get the version, whether it is idempotent, whether it supports a dry run, and the input and output as JSON Schema.

When a guide and the live answer from gtm_describe disagree, the live answer wins.

gtm_query: run a read

Arguments: name (required), input (an object, optional), environment (optional). It refuses write operations and tells Claude to use gtm_act.

gtm_query { "name": "agent.whoami" }
gtm_query { "name": "policy.get_dry_mode" }
gtm_query { "name": "instance.readiness", "input": { "status": "not_configured" } }
gtm_query { "name": "runtime.list_approvals", "input": { "state": "proposed", "limit": 20 } }

gtm_get, gtm_search and search_records: find records

gtm_search { "objectType": "gtm.account", "limit": 10 }
gtm_get    { "objectType": "gtm.account", "id": "<account id>" }
search_records { "query": "fintech accounts that hired a head of sales", "objectType": "gtm.account", "limit": 5 }

Record visibility applies. A private or team record is returned only to its owner, its creator and the organization's owners and admins. An agent sees what the person it acts for sees.

gtm_act: change something

Arguments: name (required), input, environment. It refuses read operations and tells Claude to use gtm_query.

gtm_act { "name": "score.score_account", "input": { "accountId": "<account id>" } }

score.score_account is a D operation. It runs now and writes a new qualification with its reasons.

gtm_act { "name": "outreach.send_message", "input": { "messageId": "<message id>" } }

outreach.send_message is an E operation. This call proposes the send. Nothing is sent. The result carries the approval, and a different person must approve and execute it. A send that has no lane fails with lane_required. While Dry Mode is on, E operations return drafts and create no approval at all.

gtm_approvals and gtm_lineage: follow a proposal

Engine keys you can filter by: outreach, meetings, perf_ads, seo_geo, routing, crm_writeback, enrichment and identity_dq. The states are proposed, approved, rejected, expired, revoked, withdrawn, executing, executed and failed. A proposal expires after 7 days.

gtm_lineage_trace: where did this value come from

gtm_lineage_trace { "recordId": "<account id>", "objectType": "gtm.account", "property": "employee_count" }

For each property you get the winning value, the rule that chose it, a confidence, and the observations that fed it with their sources. A record with no provenance is labeled unverified, never invented. In 0.2.5, lineage for derived values and metrics is not filled in yet and comes back empty.

Which environment does a call use

gtm_query, gtm_get, gtm_search and gtm_act take an optional environment (dev, staging, prod or a named one). If you leave it out, the call uses the x-gtmos-environment header from .mcp.json when there is one, and otherwise prod. An unknown environment is refused with VALIDATION_FAILED. It never silently falls back to prod.

Read the error, then the remediation

Errors come back as a normal tool result flagged as an error, with this shape:

{ "error": { "code": "FORBIDDEN", "message": "...", "remediation": "...", "details": { } } }

The remediation text usually names the exact fix. Tell Claude to read it before it retries.

Claude must tell you at once when a call returns FORBIDDEN, NOT_CONFIGURED or VALIDATION_FAILED: the operation, the error, and the fix. This is built into the project's CLAUDE.md.

Rate limits apply per signed-in session or key, per anonymous address and per IP address. They are set in the instance .env with GTMOS_RATE_LIMIT_API_PER_MIN, GTMOS_RATE_LIMIT_API_ANON_PER_MIN and GTMOS_RATE_LIMIT_API_IP_PER_MIN (see the config keys). Read the shipped values in the .env.example of your release.

Prompts for this chapter

Use gtm_describe on score.score_account and show me its input. Then pick one account from gtm_search on gtm.account, score it with gtm_act, and show me the reasons it gave. Tell me which environment you used.

Use gtm_approvals with count true, then list everything in state proposed. For each one tell me what it will do, who proposed it, which engine owns it and who can approve it. Do not try to approve anything.

For the account <account id>, use gtm_lineage_trace and explain in plain words where its employee count came from and which rule picked it.

Who Claude is when it calls GTM OS

Goal: understand the identity behind every MCP call, so the audit log and the approval rules make sense.

• An agent key belongs to a named agent in your organization. The agent acts on behalf of the person who created the key.
• Every action is attributed to the agent and the key in the audit log, not to you.
• An agent can propose. It can never approve, reject or execute an approval, and a key can never be granted the right to approve.
• Keys follow the person's current role. Demote or remove the person and their agents narrow or stop at once.

Scopes and presets

action.approve is a scope too, but it can never be put on a key. The command refuses it, and so does the database.

In the generated operation reference, each operation lists who can call it. operate means record.read for reads and record.write for writes. build means engine.configure, and the person behind the key must be an owner, an admin or a builder. admin means the right to approve, and an agent never has it.

Effective authority: three things must agree

What the agent can do = the key's scopes, intersected with the agent's scopes, intersected with the current role of the person who made the key. It is checked on every call.

Create, list and revoke a key

Goal: a key with the scopes you chose, shown once, that you can revoke. Needs a human Claude cannot create keys. Key management needs a signed-in person.

1. Console: Settings > Developer, Connect Claude Code / Codex. Choose the client, name, preset and expiry, then Create agent key. Copy the key now.
2. Terminal: sign in first, then create (your owner or admin session, not an agent key):

   gtm login --email you@acme.example
   gtm token create --name claude-code-anna --client claude-code --scopes record.write,engine.configure --expires-days 90

   --client is claude-code, codex or other. Use --preset full-gtm-engineer|read-write|read-only or --scopes, not both. --expires-days is 1 to 365 or never, and the default is 90.
3. List keys (it never shows key material) and revoke one:

   gtm token list
   gtm token revoke <key-id>

What only a person can do

Goal: know in advance which requests Claude must hand back to you.

Claude gets FORBIDDEN "Operation ... can only be performed by a human" on these, whatever its scopes.

Claude also cannot switch on research auto-apply, because that removes the human review of research suggestions.

What Claude can do with the Full GTM engineer preset, acting for an owner or admin: records, custom fields, pipelines, definitions (as proposals), research profile and settings, CRM settings, workflow flags, connections and keys you give it, MCP servers, syncs, scans, blueprints and proposals. High-impact changes come back as proposals.

The full list of operations that refuse an agent key is in the reference.

Approvals and four-eyes

Goal: know who can approve what Claude proposes, and what to do when nobody can.

• Only owner and admin can approve, reject or revoke.
• The proposer cannot approve. For an agent's proposal, the person the agent acts for cannot approve either. A second owner or admin must.
• Executing is human-only and four-eyes too: not the proposer, and not the person whose agent proposed it. The approver, or another member, can execute.
• A proposal expires after 7 days. Propose again if it does.
• The console hides Approve only from the person who proposed. On an agent's proposal the creating person still sees the button, and the server refuses it with "An action proposed by your own agent must be approved by a different person". That is expected.

Approve something Claude proposed

1. The approver opens Approvals (or Operate > Needs a human) and clicks the item. Needs a human
2. Read what it will do. For a config change, the impact preview is shown.
3. Click Approve, then Execute.

You have no second approver

With one owner or admin, nothing can go live. Add a second one in Settings > Members, or from a terminal:

gtm member add --email approver@acme.example --password '<password>' --role admin --org <orgId>

Autonomy: how much Claude may do alone

The default is that every customer-facing effect needs approval. A person can widen this for one scope (the organization, a play or a lane) and can set budgets and time limits with envelopes. Claude can propose such a change. It can never grant it. The autonomy scale in the code runs from A0 Observe, through A1 Suggest and A2 Propose (the default), to A3 Act within policy and A4 Mission autonomy.

Stop an agent now

1. One key: Settings > Developer, revoke it, or gtm token revoke <key-id>. It stops working at once.
2. The whole agent, everywhere: Settings > Agents, Kill. Every key of that agent is refused at every checkpoint. Needs a human
3. Bring it back: Settings > Agents, revive. Only a person can.

Prompts for this chapter

Call agent.whoami. List my effective scopes. Then tell me which of these I can do and which need a person: create a definition, approve a send, change Dry Mode, create a key, connect HubSpot. For each one that needs a person, say who and where in the console.

List every approval in state proposed with gtm_approvals. For each, name what it will do, who proposed it, and who is allowed to approve it, given that I created your key and cannot approve your proposals.

Untested. This prompt was not run against a live instance. Operation names were checked against the 0.2.5 catalog.

What a definition is

Goal: know what you are asking Claude to write, and why nothing changes until a person signs it.

A definition has four parts:

Three rules hold for every definition:

• Engines read only the signed version in the environment of the call. A draft or a proposed version is ignored. Where an engine ships a built-in default (scoring does), it runs that default until you sign your own.
• The proposer never approves or signs. If Claude proposes it, a different human approves it and a different human signs it.
• Production only accepts signed definitions that were promoted from a lower environment. You cannot write straight into prod.

The config store inside your instance is the source of truth. A git repository is an optional mirror, not a requirement (gtm mirror export writes the store out to a repo).

Every definition kind

Goal: find the kind that holds the logic you want to change. 0.2.5 has 31 definition kinds, plus four other config kinds (ontology.field, ontology.object, ontology.relationship and package.manifest). Claude reads the exact field list from the bundled definition-kinds reference in your project, so you never need to memorize it.

Some things you might expect to be a definition are not:

• Routing and territories. There is no routing definition kind. Territories are records, set with territory.upsert, and member capacity is set with routing.member_settings.set (see Routing).
• Workflow automation. The qualified-account handoff and the signal reaction are feature flags (qualification.handoff, signals.reaction), set with flags.set.
• The autonomy level and Dry Mode. These are policy settings, not definitions (see Governance).

Only definition.data_monitor is sign-exempt: it is active the moment it is published. Every other kind needs a signature before an engine uses it in production.

A few kinds also have a dedicated "set" operation that publishes and signs in one step, as the person who calls it: brand.set, money.settings.set, deal_type.set, reply_labels.set and buying_roles.set. Agents cannot call them. Over MCP every call counts as an agent call, even when your own login is behind it. So you use the console screen (the Setup cards or the Settings pages), or Claude proposes the same change as a normal change set and a person signs it. stage_map.set is different: an agent may call it, and the call becomes an approval proposal. territory.upsert is human-only.

The change set: how a definition travels

Goal: understand the four calls Claude makes to carry a definition from an idea to a draft in dev.

A ChangeSet is a bundle of one or more definitions (it can mix kinds). Over MCP, each one is an envelope:

apiVersion: gtmos/v1
kind: definition.segment
metadata: { kind: definition.segment, key: mid-market-saas, organizationId: <orgId>, env: dev }
spec:
  label: Mid-market SaaS accounts
  objectType: gtm.account
  criteria:
    expression: "employeeCount >= 200 && employeeCount <= 2000"
    variables: { employeeCount: int }

Conditions use CEL, a small expression language. Every expression comes with a variables map that names the type of each field it reads (int, uint, double, bool, string, bytes, list or map). Claude writes both; validation catches a mismatch.

Blueprint files and the git mirror use a flat form (kind, key, spec). The envelope form above is what the MCP operations take.

The full life of one definition

Goal: follow one change, "qualify accounts at 65 instead of 60", from your prompt to production. Every definition follows these same steps.

You need at least two humans with the owner or admin role. With only one, everything Claude proposes sits waiting. Add a second with Settings > Members.

Status values for a version: draft, proposed, signed, and deprecated at the end of its life (definition.deprecate, terminal, optionally with a sunset date and a notice window).

The same steps in the console

• Approvals and Operate > Needs a human: approve the change set, with its impact preview.
• CRM > Environments, Go live card: Review & sign all proposed (N) (step 5), then Promote dev to prod (step 6). Until it is done, Home, Apps and the engine pages show "N definitions are in dev, not live".

Where it goes wrong

The same path from a terminal

Goal: know the commands a person runs for the human steps, or when scripting. gtm plan, gtm apply and the others act in the environment you name with --env. Without it they use the instance default (prod), except that a blueprint of sign-gated definitions seeds dev. Always pass --env.

The sign commands need a person's own session (gtm login), not an agent key. An agent key is refused.

History, rollback and ownership

Goal: undo a bad change safely, and keep an audit trail of who owns each definition.

Prompts for this chapter

Goal: copy, adjust and paste. These prompts stop at proposals. Nothing here sends mail or spends money.

Show me what is different between dev and prod. List every definition that is in dev but not live, which ones still need a signature, and who is allowed to sign each one.

Raise the qualified threshold of the default scoring model from 60 to 65. Work in dev only. Show me the diff, validate it, and tell me exactly who has to approve, who has to sign, and what I click. Do not promote anything yet.

Everything I approved is now in dev. Propose it for signing, then preview the promotion to prod and show me the plan. Stop before you propose the promotion.

The new scoring threshold is too strict. Roll definition.scoring_model default back to the version before the last one, in prod. Show me both versions first.

Prompts in this guide are untested drafts. Run each once on a dry-mode instance before you rely on it.

Which entry point to use

Goal: pick the right starting prompt.

All of them use the same operations as the console. What one saves, the others see.

/setup-gtmos: install and connect

Goal: go from an empty folder to a connected instance. The step-by-step version is in the Quickstart. This is what it means for you as an engineer.

• Claude runs each step itself and stops only where a person must act. It does not invent commands.
• It installs the instance into ./instance, writes the owner and approver passwords into instance/.env, and never prints them.
• It mints its own agent key (preset Full GTM engineer), runs gtm init and gtm doctor, and tells you to set GTMOS_AGENT_TOKEN and restart.
• It stores and tests connection keys you give it, links your Composio apps, and prints the SPF, DKIM and DMARC records for your sending domain.

Needs a human You sign in as owner and, in a second browser profile, as the approver. You click every OAuth consent. You add the DNS records.

The setup wizard

Goal: turn answers, your website, connected data and your documents into the definitions the engines run on, with no invented values. Console: Setup. Over MCP: say "set up GTM OS for my company". The agent then follows the gtmos-onboarding skill, resumes at session.currentStep, and shows every draft with its evidence.

Three rules hold on every screen:

• No invented values. Every suggestion lists the facts it rests on. A value nobody knows stays empty and becomes a numbered open ask with an owner.
• Every saved answer changes engine behaviour. A card is published through the operation that owns that definition, with the same permissions, approvals and audit as anywhere else.
• The proposer never approves. Change sets, journeys, stage mappings, blueprints and promotions are approved by a different human. Definitions are signed by someone other than their proposer.

The six screens and the operations behind them

Every write takes the expectedVersion from the last onboarding.get. A CONFLICT means someone else changed the session: read again, then redo the write.

What each card becomes

Approving a card publishes real definitions or settings. Here is where each one lands:

When an agent drafts the cards, it prepares each one and a human finishes the human-only ones in Setup. The agent never retries through another key. See Governance for what the autonomy card really does.

The build and Launch

• The build (onboarding.build.start) queues a worker job that runs as you: it settles approved cards, adapts and proposes the chosen blueprint, suggests stage values, checks completeness, rescores, and writes the brief. Each step is logged with real results (onboarding.build.get). A failed step does not stop the others. A retry re-runs only failed or unfinished steps.
• Adapting a blueprint. With adaptToOnboarding, blueprint.apply substitutes your approved card values into the blueprint first (ICP weights, pilot segment, journeys, customer types, suppression rules, and the daily cap of email lanes from the trust card). onboarding.blueprint_adaptations previews exactly what it will take.
• Launch (onboarding.launch, human only) signs and promotes every setup definition from the seed environment to the live one, and turns engines live only where the approved autonomy card says so. onboarding.launch.preview shows that without writing anything. Signing is four-eyes. Each promotion is approved by a teammate in Approvals.

/build-gtm-system: engine by engine

Goal: a full, customized setup from one conversation. Optionally give a goal: /build-gtm-system B2B SaaS sales-led, outbound plus SEO.

1. Interview. Claude reads the live state first (instance.readiness, blueprint.list, packages.list, config.list), then asks in batches: business and offer, ICP and tiers, personas, markets and compliance, channels, CRM and tools, data volumes, team and approver. It does not ask what the instance already knows.
2. Recommend. Claude picks the closest general blueprint and says why. You confirm.
3. Seed. Claude applies it in dev as a proposal.
4. Engine by engine. Order: data first (CRM sync or import, Identity and data quality, Enrichment, Signals), then Score, then routing and plays, then Outreach, SEO and GEO, Ads. For each engine Claude explains it in two sentences, shows the defaults it would run today, asks only about the knobs that matter, writes the definitions, sends you to the console for any credential, and verifies live. Not green means not done.
5. Go live. You approve the proposals, then sign and promote (see The full life of one definition).

Claude keeps two notes in your project. .claude/memory/decision-records.md holds each decision with its reason. .claude/memory/setup-status.md holds what a human still has to do.

Smaller commands for one job each:

Blueprints and motions

Goal: start from the closest ready-made motion, then customize. A blueprint seeds a whole motion (personas, segments, scoring, suppression, bindings, lanes, plays, metrics) in one change set. They are general templates. Do not ask Claude to create one per customer. Apply the closest, then customize it through the normal path (Chapter 5).

Every blueprint also lists the connections it needs (a model provider, an email sender, looot, a CRM, an ad platform). Applying one makes those connections required in readiness. Claude reads the exact list with blueprint.get. Only seo and full-gtm require Search Console.

Apply one

1. Claude lists and reads: blueprint.list, then blueprint.get with the id.
2. Claude applies it with blueprint.apply: id, env (default dev), senderPhysicalAddress (stamped on every email lane that has none), parameters, gscProperty (required for a search blueprint on a live instance), and optionally adaptToOnboarding. It first runs a validator. It drafts a change set of only the resources that differ, then proposes config.apply. Applying the same input again while that proposal waits returns the same proposal.
3. Needs a human A different admin approves. The definitions land in dev, unsigned. They go live after sign and promote.

Other entry points: gtm init --org <id> --blueprint <file>, gtm onboard, and gtm setup ... --blueprint <id>. To pick up a newer version of a blueprint you already applied, gtm blueprint upgrade shows a diff first and applies through the approval gate only with --yes.

Customize after applying

1. Read what was seeded (config.list, config.get).
2. Change only what your interview requires: ICP criteria, weights, thresholds, lane caps, brand voice, play steps. Keep keys stable (default scoring model, lane keys) so plays and engines still resolve them.
3. Propose, approve, sign, promote (Chapter 5). Chapter 7 gives the prompt for each kind of logic.
4. Record the blueprint and every deviation in decision-records.md.

Prompts for this chapter

Goal: the first prompts to run, in order. None of them sends mail or spends money.

Set up GTM OS for my company. Start by reading where setup stands. Use my website to draft what you can, show me the evidence for every value, and only save what I confirm. Turn every gap into a numbered open ask.

We sell to about 200 named accounts with five-person buying committees. Recommend the closest blueprint and explain why. Preview what it seeds with its connections, then apply it in dev as a proposal. Then list what you would change for us. Do not promote anything.

/build-gtm-system B2B SaaS, sales-led, selling to mid-market in the DACH region. Work in dev. Go engine by engine, data first. For each engine show me today's defaults before you change anything, and stop at every proposal that needs a person.

What is my next step to get live? Check engine readiness, my first-win progress, and everything waiting on a person. Tell me who has to do each thing.

Prompts in this guide are untested drafts. Run each once on a dry-mode instance before you rely on it.

Where each kind of logic lives

Goal: find the right section fast.

Untested. This prompt was not run against a live instance. Operation names were checked against the 0.2.5 catalog.

ICP and scoring models

Goal: the Score engine ranks accounts the way you would. Three models work together: icp_fit (firmographics), default (intent signals) and signals (signal strength).

Ask Claude to use: definition.scoring_model (keys default, icp_fit, signals), definition.segment, definition.persona. For example, an ICP fit model for the DACH region looks like this when Claude proposes it:

kind: definition.scoring_model
key: icp_fit
spec:
  scoreScaleId: icp.fit.0-100
  qualifiedThreshold: 70
  needsReviewThreshold: 30
  rules:
    - id: region
      statement: Headquartered in DACH
      matchesKind: [firmographic]
      weight: 40
      condition: { expression: 'countryCode in ["DE", "AT", "CH"]', variables: { countryCode: string } }
    - id: size
      statement: 200 to 5,000 employees
      matchesKind: [firmographic]
      weight: 40
      condition: { expression: "employeeCount >= 200 && employeeCount <= 5000", variables: { employeeCount: int } }

Our ICP: B2B software companies in Germany, Austria and Switzerland with 200 to 5,000 employees. Hiring for sales roles is a strong sign. Competitors must never score. Read our current icp_fit and default scoring models in dev, show me the changes side by side, run a rescan preview, and propose the change set. Work in dev. Do not rescan the organization.

Qualification and buying committees

Goal: decide what "qualified" means for you, who must be on the buying committee, and what happens the moment an account qualifies.

The qualification.handoff flag is on by default. Its value is strict: any key not listed here is refused.

When an account qualifies, route it only among these people: <names or ids>. Make the follow-up task due in 1 day and enrol at most 2 contacts. Keep every other setting of the qualification.handoff flag as it is. Read the flag first and show me the old and new values before you save. Do not enrol or send anything.

Our deals need an economic buyer, a champion, a technical evaluator and a legal contact. The champion must be mandatory. A role counts as covered if someone in it was touched in the last 45 days. Propose the committee model in dev.

Routing, territories and round robin

Goal: every account, contact and deal gets the right owner, fairly, with a record of why.

There is no routing definition kind. Territories are records and capacity is a per-member setting. Both are saved by a person (human-only: agent keys are refused). Claude can preview any change before you save it, and can run assignments itself.

How a winner is chosen: named-account territories always win. Then the lowest priority number, then the most matching criteria, then the name. Round robin skips anyone who is inactive, out of office or at their cap.

Design territories for us. DACH accounts with 1,000 or more employees go to the enterprise team (rotate between <two names>). Everything else in DACH goes to the mid-market team. Our top 20 named accounts (I will paste the domains) always go to their account owner. Show me every territory with its match rules, priority and rotation, then preview three real accounts with territory.match. Do not save anything. Tell me the exact values I need to enter in Engines > Routing.

Plays, sequences and cadences

Goal: automate the motion: what triggers, what it does, in what order, how fast, and how it stops.

Plays

Scheduled plays can aim at a built-in audience: deal.stage_stuck, deal.closed_lost, subscription.renewal_due, contact.champion_moved, meeting.ended, content.refresh_due. A play can start on any of 15 events, such as gtm.signal.observed, gtm.record.created, gtm.meeting.booked, gtm.reply.received and gtm.transcript.ingested. The full list with filter fields is in the reference. Event plays skip events from bulk writers (imports, CRM sync) unless the play sets includeBulkSources. Step inputs can read the trigger and earlier steps with {{ trigger.subject.id }} and {{ steps.<id>.output.<path> }}.

Sequences and cadences

A sequence with no signed definition.sequence keeps the classic cadence: one step every 3 days. Bind a signed step plan with sequence.update. Cadence timing runs through outreach.rescan_cadences (drafts the next step for anyone due) and outreach.advance_cadence (forces one step for one person).

Lanes: the sending rules

definition.lane sets a channel's limits: dailyCap, recentTouchWindowHours, openDealPolicy (block or allow), enforcedChecks, envelopeBudgetEur over windowDays, bounceRatePauseThreshold, complaintRatePauseThreshold, sendingDomain, senderPhysicalAddress, and for LinkedIn the seat and its daily and weekly caps. Every send needs an active lane. lane.activate proposes activation. A different human approves it. In a production environment it is refused unless SPF, DKIM and DMARC pass for the sending domain. The console has no activate button.

Create a play called stuck-deal-nudge. Every weekday at 08:00 Europe/Berlin it looks at deals that have sat in a stage for more than twice that stage's median time, at most 20 per run, and creates a follow-up task for the deal owner. No emails. Propose it in dev, then simulate it over the last 30 days and show me what it would have done. Do not trigger it.

Write a 4-step email sequence called signal_follow_up_v2. Step 1 at once, then +3, +5 and +7 business days. Send only 08:30 to 11:30 recipient time, Monday to Thursday. Test two subject lines on step 1, 50/50. Steps use a brief, and claims must come from approved proof only. Exit on reply, unsubscribe, bounce, or a booked meeting. Propose it in dev. Do not create, enrol or send anything.

Propose a lane called primary-email: email, at most 80 sends a day, no contact touched in the last 7 days, block anyone with an open deal, enforce suppression, consent, daily cap, recent touch and open deal checks. Pause it at a 4 percent bounce rate or 0.1 percent complaint rate. Sending domain mail.example.com. Do not activate it.

Suppression and compliance

Goal: the system never contacts who it must not, and follows the rules of each region.

A suppression rule from a shipped blueprint looks like this:

kind: definition.suppression_rule
key: opted-out
spec:
  label: Opted-out contacts
  reason: Contact requested no further outreach
  criteria:
    expression: 'has(consent.status) && consent.status in ["withdrawn", "denied", "expired", "opted_out"]'
    variables:
      consent: map

We start prospecting in Germany and France. Seed the standard compliance policies into dev. Add a suppression rule for our competitors and our current customers (I will paste the domains). Then show me how our email lane would treat a German contact with no recorded consent. Propose changes only, send nothing.

Claims, voice and proof

Goal: every message and page sounds like you and claims only what you can prove.

Brand voice by change set works for Claude. brand.set publishes and signs in one step, but only a person can call it. Where to click: Settings > Brand & compliance (voice and forbidden claims), Settings > Proof library (proof, and the Claims check tab for the policy).

Our voice: plain, direct, no hype. Avoid: "revolutionary", "best-in-class", "synergy". Never claim: "guaranteed results" or "number one". I am attaching a customer case study PDF. Extract draft proof and claims from it and show me each claim next to the sentence it came from. Propose the brand voice in dev. Do not activate any proof, and do not draft any message.

Identity resolution and merge rules

Goal: decide when two records are the same company or person, which source wins each field, and what a merge keeps.

There are two layers. Both read the same signed definition.identity_rule per object type (gtm.account, gtm.contact).

The easy way to change merge rules: identity_dq.merge_rules.get reads the effective rules, and identity_dq.merge_rules.propose drafts a new definition.identity_rule version as a change set in dev. Nothing changes until it is approved, signed and promoted.

When two company records disagree on the company name, the CRM must win over any other source. For employee count, take the highest-confidence value. Show me the effective merge rules today, then propose the change in dev. Then scan accounts for duplicates and preview three merges with identity_dq.preview_merge. Do not merge anything.

Metrics, KPIs and money

Goal: the numbers on your dashboards mean what your team means, and revenue is counted the way finance counts it.

money.settings.set publishes and signs definition.money in one step, and only a person can call it. Claude can propose the same change by change set. Settings page: Settings > Money.

Define a metric called qualified-dach-accounts: the count of accounts in DACH that are qualified. Define a second, qualified-dach-enterprise, as a slice of the first for companies with 1,000 or more employees. Propose both in dev, then check that the slice rolls up to the whole.

Show me where our revenue truth comes from today, the attribution model and window, and the FX convention. Then reconcile revenue truth against the CRM's won-deal amounts for the last 6 months and tell me where they differ. Change nothing.

Stage machines and journeys

Goal: your lifecycle words and stage rules replace the generic ones, and CRM stage values map onto them.

Propose a journey with journey.propose. It builds and validates the change set (unique stage keys, at least one open stage, valid links, one default journey per object type). journey.apply submits it for approval. After that comes sign and promote.

Our deal lifecycle is: discovery, evaluation, proposal, negotiation, won, lost. Propose it as a journey for deals in dev, with a stage machine that does not allow skipping from discovery to won. Then list every stage value in our CRM that is not mapped yet, suggest a mapping for each with the reason, and do not save any of them.

What ships, and what does not

Goal: know exactly which engines exist in release 0.2.5, so you never promise a client something that is only on the roadmap.

Signals has no engine page and no mode switch. It records and scores evidence and sends nothing out. Its one paid action, the daily signal scan, is stopped by the organization-wide Dry Mode.

Next to the seven engines sit surfaces that are not engines but that you configure the same way: Plays (Engines > Plays), Routing (Engines > Routing), the research agent (CRM > Research), CRM sync and source mappings, the adapter builder (CRM > Adapters) and AI chat. Chapter 7 covers routing and plays; chapter 10 covers data in.

The chain, from raw record to a reply

Goal: predict what a change in one engine does downstream.

1. Data in. Import, CRM sync or a source mapping creates companies and contacts. These writes are marked bulk, so event plays and agent triggers skip them unless they opt in.
2. Data Quality. identity_dq.normalize_records cleans domains, emails and casing. The duplicate scan proposes merges that follow your identity rule.
3. Enrichment. Fills empty fields (employee count, industry, country, email, phone). Fit scoring reads employeeCount, countryCode and industry, so enrichment quality sets the ceiling for fit.
4. Signals. Signals arrive from the daily scan, intent ingest, your own site and mailbox, or signals.record. The verification gate decides which ones count. Each new signal emits gtm.signal.observed.
5. Score. Composite of fit (40 percent) and intent (60 percent) by default. A new qualification emits gtm.scores.computed.
6. Handoff. When an account moves into qualified, the handoff routes an unowned account, creates a task and enrols a contact. The signal reaction can do the same on one strong signal.
7. Outreach. The sequence cadence drafts the next step. A person approves it. The lane gate, the claims gate and the guardrails check it again at send time.
8. Feedback. Replies are labelled. Unsubscribes, objections and hard bounces lower the account's intent score. Positive replies, meetings and won deals feed score.learn, which proposes new weights.

SEO & GEO and Performance Ads run beside this chain. They share the same plumbing: the proof library and claims gate, your brand voice, the money definition (revenue truth and attribution), the guardrails and the approval gate.

What starts each engine

Events you can build on

Goal: start a play or an agent when something happens, instead of on a timer.

Plays (definition.play, trigger kind event) and agent event triggers can start on these events. Each carries the fields you can filter on.

Events from bulk writers (import, CRM sync, enrichment, the projector) carry sourceCategory: "bulk". Plays and agent triggers skip them unless they set includeBulkSources. That is why a 10,000-row import does not start 10,000 plays.

The engines also write their own audit rows, called ledger action types. You read them in Operate > Actions and with actions.list. Examples: outreach.message_drafted, outreach.message_sent, perf_ads.campaign_changed, seo_geo.page_published, identity_dq.records_merged, enrichment.field_overwritten, crm.outcome_written. The reference lists the rest, and four more events (a mission step, a connection created, a connection tested, a sync finished).

Rules every engine shares

Goal: know the guardrails before you tune an engine, so a tuned engine cannot hurt a client.

Dry and live, per engine

• A new organization starts with every engine dry. A dry engine watches, scores and drafts, but sends and writes nothing outside. Each draft is a drafted row in Operate > Actions with its reason.
• Organizations that existed before 0.2.5 keep their old behavior: an engine with no row of its own follows the organization-wide Dry Mode.
• The organization-wide Dry Mode is the master. An engine runs in the stricter of the two.
• Needs a human An owner or admin takes an engine live in Settings > Safety, or with policy.engine_modes.set, which agent keys cannot call. Read the state with policy.engine_modes.get.

Guardrails across all engines

Set with policy.guardrails.set (human only; pass the complete spec and the expectedVersion from policy.guardrails.get). A reached cap or quiet hours hold the action. It is never dropped, and it runs by itself later.

Rules no setting turns off

• Net-new rule. A first message, or a meeting invite, to a contact nobody has ever written to is never auto-sent. It always waits for a human, at every autonomy level.
• Claims gate. A stat, a result or a named customer in outbound copy must be backed by active proof in Settings > Proof library. It runs when the action is proposed and again right before it runs. It covers outreach, SEO page publishes and meeting invites.
• Four-eyes. The person who proposed an action cannot approve it. An agent never approves.
• Only signed definitions run in prod. An engine reads the signed version in the call's environment, and falls back to its built-in default when there is none.

Where each kind of knob lives

Goal: when a client asks "can we change X", know which route changes it and who has to sign.

The change loop is the same for every definition: ask Claude, let it validate (config.validate_changeset), have a different person approve, sign (gtm definition sign or Environments > Go live), promote to prod (config.promote), then verify. Chapter 5 walks through it and its failure modes.

Prompts for this chapter

Show me the state of every engine: mode (dry or live), what is waiting for approval, and the last thing each one did. Read-only. Tell me which engines are still dry.

Take the account acme.example. Show me its fit and intent scores and why, the signals behind them, whether it was handed off, and where its contacts sit in any sequence.

Nothing is going out from outreach. Check, in order: engine mode, organization Dry Mode, guardrails and today's headroom, lane activation, sequence status and signed step plan. Report the first thing that blocks it.

Score

Goal: a scoring model that matches the client's ideal customer and buying signals, with a reason on every verdict.

What it does

Score gives each account a number from 0 to 100, a verdict (Qualified, Needs review, Not qualified) and a priority tier. The default is a composite of two parts:

• Fit (40 percent): firmographic match from the signed icp_fit model.
• Intent (60 percent): the signals on the account. Each signal carries the weight of the rule that matches its kind. That weight fades with the signal's age, is multiplied by who observed it (your own systems count 1.5 times), and is lowered by negative replies and hard bounces. A hard disqualifier can cap the whole score.

Score also hosts CRM write-back, source sync and the learning loop. A new qualified account triggers the handoff: owner, follow-up task, sequence enrolment.

Where to find it

What you can customize

Two scoring models do the work. definition.scoring_model key default is the intent model. Key icp_fit is the firmographic fit model.

Here is an icp_fit model for a client that sells to software companies with 50 to 500 staff in Germany, Austria and Switzerland:

kind: definition.scoring_model
key: icp_fit
spec:
  scoreScaleId: icp.fit.0-100
  qualifiedThreshold: 70
  needsReviewThreshold: 30
  rules:
    - id: icp.size
      statement: 50 to 500 employees
      matchesKind: [firmographic]
      weight: 50
      condition:
        expression: employeeCount >= 50 && employeeCount <= 500
        variables:
          employeeCount: int
    - id: icp.region
      statement: Germany, Austria or Switzerland
      matchesKind: [firmographic]
      weight: 30
      condition:
        expression: countryCode in ["DE", "AT", "CH"]
        variables:
          countryCode: string
    - id: icp.industry
      statement: Software
      matchesKind: [firmographic]
      weight: 20
      condition:
        expression: industry in ["Software", "SaaS"]
        variables:
          industry: string

Operations

score.score_account (D), score.score_contact (D), score.explain_subject (Q), score.explain_qualification (D), score.list_ranked (Q), score.account_tiers (Q), score.committee_coverage (Q), score.rescan_organization (D), score.rescan_preview (Q), score.kpis (Q), score.feedback (D), score.learn (D, proposes only), score.learning_report (Q), score.learning_settings.get (Q), score.learning_settings.set (M, human only), score.ingest_market_signals (D). The engine also hosts crm.write_outcome and crm.update_record (E, undoable), crm.sync and the source.* operations.

KPIs it publishes

score.kpis: accounts scored, tier distribution, hot now (top tier), next-move acceptance with its weekly trend, and score against deal outcome. Mission Control shows qualified_coverage. score.learning_report adds Brier score, reliability by tier and lift per signed version.

Events and ledger rows

• Emits gtm.scores.computed for a new qualification. Start a play on it.
• On a move into qualified it queues score.qualified_handoff, once per qualified episode.
• Reads gtm.signal.observed and gtm.signal.verification_changed through the signal reaction (see Signals).
• Ledger rows for write-back: crm.outcome_written and crm.record_updated, each with an undo.

Dry Mode and guardrails

• Scoring is an internal write, so it runs in Dry Mode. Only write-back to your CRM (engine crm_writeback) is held as a draft.
• After a model change that alters the fingerprint, the first rescore never hands off. Nobody is routed, tasked or enrolled because of an upgrade rescore.
• Every handoff step runs through the normal gates: Dry Mode, approvals, the lane gate. A first message to a net-new contact still waits for a person.
• The signal verification gate decides which signals count. In Strict, unverified third-party signals never score.

How to extend it

• New signal kind. Record it with signals.record (or a source mapping that targets signals), then add an intent rule whose matchesKind names it.
• Another field in fit. Fit rules read four fields. To score on anything else (technology, funding stage), score it as an intent rule on a signal, or use the segmented account_field feature.
• Account-based tiers. Add a committee_model and the segmented committee_coverage signal for enterprise accounts.
• Compile a client rule. The /compile-rule slash command turns a written scoring rule into definitions.

Prompts to give Claude

Our client sells to software companies with 50 to 500 employees in Germany, Austria and Switzerland. Rewrite the icp_fit scoring model for that: size 50 points, region 30, industry 20. Keep the thresholds at 70 and 30. Validate it, then tell me what to approve.

Our sales cycle is short. Make web and topic intent fade with a 7-day half-life, buying triggers 30 days, and count our own website and mailbox signals 2 times. Show me a rescan preview before anything is signed.

Never qualify accounts whose country is RU or BY, and cap anything with a risk signal in the last 30 days at 20. Add these as disqualifiers to the default scoring model.

Raise the unsubscribe penalty to 50 and the hard bounce penalty to 25. Keep the 180-day window.

Run score learning in report-only mode for the outcome "meeting" with 21 day windows. Show me what it would change and the evidence. Do not propose yet.

How to verify the change took effect

Outreach

Goal: sequences that send the right message on the right channel at the right time, and stop when they should, with a person approving every send.

What it does

Outreach drafts messages in your brand voice, runs sequences, and sends email and LinkedIn steps through activated lanes. Every send is a proposal (class E). A different person approves it, and every check runs again at execute time. It also labels replies, proposes next actions, and reports deliverability and what is working.

Where to find it

What you can customize

A three-step plan with an A/B test on the opener and an exit when a deal moves on:

kind: definition.sequence
key: cold_saas_v1
spec:
  label: Cold outreach to SaaS founders
  steps:
    - key: opener
      channel: email
      wait: { amount: 0, unit: days }
      personalisation: auto
      variants:
        - key: pain
          weight: 50
          template:
            subject: "{{company|your team}} and onboarding time"
            body: "Hi {{firstName|there}}, teams like {{company|yours}} tell us onboarding is the slow part. Worth a short call?"
        - key: question
          weight: 50
          template:
            subject: "Quick question, {{firstName|there}}"
            body: "Hi {{firstName|there}}, how do you handle onboarding at {{company|your company}} today?"
    - key: follow_up
      channel: email
      wait: { amount: 3, unit: business_days }
      sendWindow: { start: "08:30", end: "11:30", days: [1, 2, 3, 4] }
      brief: Add one approved proof point and repeat the small ask.
    - key: close
      channel: email
      wait: { amount: 5, unit: business_days }
      template:
        body: "Hi {{firstName|there}}, I will leave it here. If timing changes, a reply is all it takes."
  exits:
    reply: true
    unsubscribe: true
    bounce: true
    manualStop: true
    meetingBooked: true
    stageChange:
      objects: [deal]

Operations

Drafting and sending: outreach.draft_message (D), outreach.draft_personalized_message (D, spends model credits), outreach.send_message (E), outreach.undo_send_message (D, writes a retraction note; a sent email cannot be un-sent), outreach.sending_mailboxes (Q), outreach.advance_cadence (D), outreach.rescan_cadences (D), outreach.signal_enroll (D). Sequences: sequence.create, sequence.update, sequence.enroll (up to 500), sequence.set_member_status, sequence.message.resolve_uncertain (D); sequence.list, sequence.get, sequence.members, sequence.messages, sequence.replies (Q). Lanes: lane.activate (T, proposes), lane.list (Q). Replies: replies.ingest, replies.classify, replies.link, replies.next_action (D, proposes); replies.list, replies.get, replies.next_actions (Q); outreach.bounce_undo (D, human only). Reports: outreach.kpis, outreach.step_stats, outreach.learning_report, outreach.deliverability, outreach.linkedin_seats (Q). Activate a lane from a terminal with gtm lane activate <laneKey> --env <envId>.

KPIs it publishes

• outreach.kpis: sends per week, human-approved share, reply rate by channel, bounces and complaints, meetings booked, cold against warm lanes, guardrail usage, and a funnel (sent, delivered, opened, replied, positive, meeting). Funnel rates stay empty under 20 sends. Opens are always flagged unreliable.
• outreach.step_stats: per sequence, step and A/B variant. Rates appear from 30 sends.
• outreach.learning_report: reply, positive-reply and meeting rate by angle, proof, persona, subject style, step and variant. A group needs 30 sends.
• Mission Control: reply_rate.

Events and ledger rows

• Consumes gtm.signal.observed (signal plays), gtm.reply.received, gtm.meeting.booked.
• Ledger rows: outreach.message_drafted, outreach.message_sent. A reply with a confident label proposes outreach.reply_next_action (book a meeting, snooze, referral). Unsubscribe and bounce propose nothing, because suppression already ran.

Dry Mode and guardrails

• Engine keys outreach and meetings start dry on a new organization. Dry drafts appear in Operate > Actions and emit gtm.dry_draft.produced. The Safety page shows how many dry-drafted contacts later replied.
• Checks at propose time and again right before execute: Dry Mode, engine mode, claims gate, brand safety, suppression, consent, reply stop, quiet hours and the step's send window, guardrail caps, the lane gate, sequence exits and freshness.
• The first message to a net-new contact always needs a person.
• A cap, quiet hours or a LinkedIn limit holds the send. It returns to draft with the reason and is proposed again.
• A send whose outcome is uncertain is never retried. A person resolves it with sequence.message.resolve_uncertain.

How to extend it

• A new cadence per motion. One signed definition.sequence per motion, one sequence per lane.
• Signal plays. The outbound, full-gtm, sales-led and enterprise-abm blueprints ship three plays on gtm.signal.observed (funding, hiring, intent). Copy one with /create-play for a new signal kind.
• New reply behavior. Add a label with its effects in definition.reply_labels.
• Other rails. outreach.sending_mailboxes lists connected Google and Microsoft mailboxes, Gmail and Outlook through Composio, and outbound rails. Bind a sequence to the lane and mailbox you want.

Prompts to give Claude

Create a 4-step email cadence for our outbound motion: day 0 opener, 3 business days later a proof follow-up (mornings Monday to Thursday only), 5 business days later a soft close, and 7 business days later a break-up note. A/B test two subject lines on the opener, 50/50. Exit on reply, unsubscribe, bounce, a booked meeting, or if the deal moves to any stage. Bind a new sequence to lane "outbound-email". Do not enrol anyone.

Create an email lane called "outbound-email" for sending domain mail.example.com: daily cap 50, block contacts with an open deal, pause the lane at a 3 percent bounce rate or 0.1 percent complaints, cold temperature, and our postal address in the footer. Then propose activating it.

Limit outreach to 150 emails a day across all engines, 40 new accounts a week, and only Tuesday to Thursday between 09:00 and 16:00 in the recipient's time. Show me today's headroom afterwards.

Update our brand voice: direct and warm, no exclamation marks, prefer "teams" over "users", avoid "revolutionary", "synergy" and "game-changing". Forbid the claim "guaranteed results". Add the two voice samples I paste below.

Add a reply label "budget_next_quarter" with neutral sentiment, recognized by the phrases "next quarter", "after the budget cycle" and "revisit in". Effect: stop the sequence for that person and open a task for the owner due in 60 days titled "Follow up on budget".

How to verify the change took effect

Performance Ads

Goal: ad spend that follows the client's unit economics, with budget moves proposed on real customers and approved by a person.

What it does

Performance Ads syncs spend and results from Google Ads and Meta Ads, paces each campaign against its schedule, and judges it on real CAC and real ROAS: customers and revenue from your own revenue truth, not the platform's conversion count. Every night an allocator proposes small, budget-neutral moves from campaigns that cost too much per customer to ones that cost less. Every change is a real-money proposal (class E).

The engine does nothing on its own until you set a target. Without targetCac, targetRoas or maxPaybackMonths, pacing follows the schedule only and the allocator runs but proposes nothing, and says why.

Where to find it

What you can customize

Example target for a client that can pay at most 250 EUR to win a customer:

kind: definition.unit_economics
key: default
spec:
  label: Client unit economics
  currency: EUR
  grossMargin: 0.7
  targetCac: 250
  ltv: 2400

Set one basis: targetCac, or targetRoas, or maxPaybackMonths with its two companions.

If you set more than one, the engine steers on CAC: an explicit targetCac, otherwise the CAC a payback limit implies. It uses targetRoas only when no CAC target exists.

Operations

perf_ads.sync_performance (D), perf_ads.get_pacing_recommendation (Q), perf_ads.get_campaign_performance (Q), perf_ads.scan_campaign (D), perf_ads.scan_all_campaigns (D), perf_ads.update_campaign (E), perf_ads.undo_campaign_change (E), perf_ads.reallocate (D, queues the allocator), perf_ads.reallocation_plan (Q, previews, proposes nothing), perf_ads.allocator_runs (Q), perf_ads.kpis (Q).

KPIs it publishes

perf_ads.kpis: spend, conversions, CPA, ROAS on real customers, real CAC, platform against real, MER, aMER (new-customer revenue over spend), ACoS, payback against your economics, and the open moves. Metric definitions perf_ads_spend_total, perf_ads_conversions_total, perf_ads_campaign_count, perf_ads_outcome_freshness. Mission Control shows spend_total. Only live synced rows count. Demo data and fixture rows never do.

Events and ledger rows

• Ledger row perf_ads.campaign_changed, with perf_ads.undo_campaign_change as its undo.
• The allocator is a nightly job at 02:00 UTC. Each of its moves is its own approval ("Reallocate ad budget (decrease / increase)") with the real CAC, platform CPA, customers, target and paired campaign.
• No domain event is emitted. Start plays from a schedule or from gtm.deal.stage_changed.

Dry Mode and guardrails

• Engine key perf_ads. In Dry Mode the allocator drafts its plan and proposes nothing.
• Allocator bounds: at most 20 percent per campaign per run, budget-neutral within one currency, never a paused campaign, a demo-data campaign, a campaign with a change already pending, or a campaign read only through Composio (no native write path; the recommendation is reported, not proposed).
• A campaign is not judged before it is as old as your attribution window, and never called worse on zero customers.
• After an executed change the campaign is left alone for 7 days.
• "Run now" works once per hour. A repeat returns the same run.
• An approved move is refused at execution if the campaign's budget changed after the proposal.
• Approving a decrease without its paired increase lowers total spend. Approving an increase alone raises it. The approval shows what each choice does.

How to extend it

• Another platform. The engine runs on Google Ads and Meta Ads. A platform your connectors reach only through Composio is read-only here.
• Tag your ads. A paid visit is credited to the campaign named in utm_campaign: the platform campaign id or the exact campaign name. Untagged traffic leaves real CAC empty, with the reason.
• A play on a schedule. Run perf_ads.scan_all_campaigns from a play so campaigns are scanned and proposals appear without anyone clicking.
• Use /tune-economics. The slash command walks through the economics with the client's numbers.

Prompts to give Claude

The client can pay at most 250 EUR to acquire a customer. Gross margin is 70 percent. Set the unit economics target to a CAC of 250 EUR and show me what the allocator would do right now, without proposing anything.

The client's total ad budget must never exceed 400 EUR a day. Give me the exact guardrail spec to set, and tell me what the allocator does if we are already above it.

Our customers take about 45 days from first ad click to purchase. Set the attribution window to 45 days with a position-based model (40 percent first touch, 40 percent last touch). Tell me how real CAC will change.

Show me the last allocator run: each move with its evidence, which campaigns it left alone and why, and any approval still waiting.

How to verify the change took effect

SEO & GEO Search Console required

Goal: know how the client shows up in Google and in AI answers, and run a content loop from topic to published page.

What it does

The engine audits tracked pages (technical SEO, GEO readiness, Google's index status), tracks the prompts you care about on AI answer engines and the keywords you care about on Google, groups demand into topic clusters, runs a content factory (brief, draft, QA gate, approval) and publishes an approved draft to a CMS. Every publish is a proposal that a different person approves. Google Search Console is required. An organization that does not use SEO does not need it.

Where to find it

What you can customize

Operations

The engine has 44 operations. Pages and audits: seo_geo.create_tracked_page, seo_geo.run_audit, seo_geo.audit_page, seo_geo.scan_all_pages (D); seo_geo.get_recommendation, seo_geo.get_readiness_view, seo_geo.get_page_performance, seo_geo.fix_queue (Q). Site and AI visibility: seo_geo.run_visibility, seo_geo.create_tracked_prompt, seo_geo.update_tracked_prompt, seo_geo.delete_tracked_prompt, seo_geo.update_visibility_settings (D); seo_geo.get_visibility, seo_geo.list_tracked_prompts, seo_geo.get_visibility_settings, seo_geo.list_visibility_alerts, seo_geo.gsc_properties, seo_geo.kpis (Q). Keywords: seo_geo.keyword_opportunities (Q), seo_geo.refresh_keyword_data (D). Clusters and factory: seo_geo.build_clusters, seo_geo.add_content_idea, seo_geo.create_brief, seo_geo.draft_page, seo_geo.update_draft, seo_geo.qa_draft, seo_geo.approve_draft (human only, not the author), seo_geo.move_content, seo_geo.mark_refresh_due (D); seo_geo.clusters, seo_geo.get_cluster, seo_geo.cluster_sources, seo_geo.content_item, seo_geo.factory, seo_geo.refresh_candidates, seo_geo.refresh_calendar (Q). Publishing: seo_geo.publish_content_change, seo_geo.undo_content_change, seo_geo.publish_to_cms, seo_geo.unpublish_from_cms (E); seo_geo.publish_queue, seo_geo.publish_preview, seo_geo.cms_targets (Q).

KPIs it publishes

seo_geo.kpis: pages tracked and live, indexed share, organic clicks and impressions, AI referral visits (GA4), AI citation share per answer engine, each with its previous value and trend, plus publishing KPIs (time to publish, time to index, citation gain after publish). Metric definitions: search_organic_traffic, search_avg_rank, search_geo_readiness, search_tracked_pages, search_ai_share_of_voice, search_ai_citation_rate, search_ai_mention_rate, search_serp_avg_rank, search_ai_referral_sessions, search_outcome_freshness. Visits from AI assistants (ChatGPT, Perplexity, Gemini, Copilot, Claude and others) are credited to SEO & GEO.

Events and ledger rows

• Ledger rows seo_geo.page_published (undo: seo_geo.undo_content_change) and seo_geo.page_published_to_cms (undo: seo_geo.unpublish_from_cms).
• Search alerts for keyword rank drops and AI-visibility drops, read with seo_geo.list_visibility_alerts.
• Content lifecycle states: idea, brief, draft, qa_passed, approved, published, refresh_due.

Dry Mode and guardrails

• Engine key seo_geo. A dry engine audits and drafts but publishes nothing.
• The copy published is the approved draft, bound to its hash. An edited draft is refused. A retry never creates a second page.
• The claims gate and brand safety run at propose and again at execute. A different person than the author approves the draft, and a different person approves the publish.
• Every tracked acquisition goes through the metered capability broker with a per-run cap. A cluster build with embeddings is estimated first, refused over its cap and reserved on your org budget.
• Without a connected CMS the answer is "not connected". There is never a fake publish.

How to extend it

• New CMS. Use the signed webhook target to reach any CMS you can write an endpoint for.
• New markets. Add tracked prompts per country and language.
• Plays. Schedule seo_geo.scan_all_pages and seo_geo.mark_refresh_due from a play so fixes and refreshes queue themselves.
• Competitor tracking. Name competitors on each tracked prompt so share of voice counts them.

Prompts to give Claude

Track these prompts on ChatGPT, Perplexity and Google AI Overviews for brand "Acme", also written "Acme Corp": "best CRM for small agencies", "how to automate lead scoring", "Acme alternatives". Competitors: Globex and Initech. Our domain is example.com. Country US, English. Do not turn on the schedule yet.

Turn on scheduled visibility tracking every 168 hours. Alert me if any keyword loses 5 positions or an engine's share of voice falls by 20 percent. Stop a run at 3 dollars.

List the Search Console properties our connection can read, then select the one for example.com.

Show me what a cluster build would read and what embeddings would cost. Then build clusters from the last 28 days without embeddings, and give me the top 5 clusters that are a gap or cannibalised, with a brief for the best one.

Preview publishing the approved draft "crm-for-agencies" to Webflow. Show me exactly what would be sent and every reason it cannot go yet. If it can, propose it.

How to verify the change took effect

Data Quality (identity and merges)

Goal: one record per real company and person, with clean fields, and a clear rule for which value wins when two records merge.

What it does

The engine validates records, normalizes domains, emails, casing and whitespace, scans for duplicates by your identity keys, and merges duplicates through an approval, with unmerge. A daily scan records quality as monitor runs and alerts the owner when a threshold is breached. It surfaces problems and proposes. It never merges on its own.

Where to find it

What you can customize

Example: accounts match on domain, and a person picks the industry when two records disagree:

kind: definition.identity_rule
key: gtm.account
spec:
  objectType: gtm.account
  rules:
    - { key: domain, role: authoritative }
    - { key: name, role: corroborating }
    - { key: phone, role: corroborating }
    - { key: linkedinUrl, role: corroborating }
  survivorship:
    default:
      strategy: most_recent
    mergeDefault:
      strategy: keep_survivor
    mergePerProperty:
      industry:
        strategy: manual
      employeeCount:
        strategy: highest_confidence
  matching:
    minConfidence: 0.7
    nameSimilarity: 0.9

Operations

identity_dq.scan_duplicates (Q), identity_dq.preview_merge (Q), identity_dq.validate_records (Q), identity_dq.quality_report (Q), identity_dq.merge_rules.get (Q), identity_dq.merge_rules.propose (D, builds a ChangeSet), identity_dq.flag_invalid_records (D), identity_dq.normalize_records (D, reversible), identity_dq.undo_normalization (D), identity_dq.backfill_domains (D, free, from contacts' work emails), identity_dq.enrich_accounts (D), identity_dq.scan (D, on-demand scan), identity_dq.merge_records (E), identity_dq.revise_merge (E, people only), identity_dq.unmerge_records (E).

KPIs it publishes

identity_dq.quality_report: fill rate per field, duplicate rate, staleness and mean quality score. The daily scan stores one monitor run per object type (identity_dq.scan:gtm.account, identity_dq.scan:gtm.contact) with the change since the last run, so Operate > Monitors shows the trend.

Events and ledger rows

• Ledger rows identity_dq.records_merged (undo: unmerge), identity_dq.records_unmerged, identity_dq.records_normalized (undo: identity_dq.undo_normalization).
• A threshold breach sends the owner a dq_alert notification, once per object type per day.
• Writes from the merge are recorded in field history. A value a person picked is recorded as the approver's edit, so a later CRM sync does not overwrite it.

Dry Mode and guardrails

• Engine key identity_dq. A merge is a proposal in every mode. A different person approves it. A pick on the approval card is re-proposed as a new approval, and a third person approves it.
• If the survivor changed after the proposal, the merge refuses and changes nothing.
• Undo restores the survivor's earlier values and the duplicate, except for fields edited after the merge. The result lists what was restored and what was kept, and why.
• Normalization is an internal write. It is not behind an approval. It is idempotent and reversible.

How to extend it

• New object type. Identity rules cover accounts and contacts for the duplicate scan. Deals can be merged by hand with identity_dq.merge_records.
• More monitors. Add definition.data_monitor instances per lane (bounce rate, complaint rate) or per property (fill rate on industry).
• Run it after every import. A play on gtm.sync.completed can run the scan and the quality report.

Prompts to give Claude

We just imported 4,000 companies. Run the quality report for accounts, normalize the records, backfill missing domains from contact emails, scan for duplicates, and show me the top 20 duplicate pairs with their match reasons. Do not merge anything.

Our duplicates are mostly the same company under different names. Match accounts on domain first, then LinkedIn URL, then name. Use a name similarity of 0.9 and ignore pairs with confidence under 0.7. When two records disagree on industry, make a person choose. For employee count, keep the value with the highest confidence.

Preview merging acme-inc.example into acme.example. Show every field that conflicts, how each one would be decided and why. If it looks right, propose the merge.

Alert the owner when more than 3 percent of companies are in a duplicate pair, or when the mean quality score falls below 0.6. Also add a monitor for the fill rate of industry on accounts, warning at 70 percent and breaching at 50 percent, checked daily.

A fill_rate monitor is a floor. It warns when the fill rate is at or below warnThreshold and breaches at or below breachThreshold, so set warn above breach (for example warn 0.7, breach 0.5).

How to verify the change took effect

Enrichment

Goal: fill the empty fields the other engines need, at a price the client agreed to, and keep them fresh.

What it does

Enrichment fills empty fields on companies and contacts through a waterfall: for each field it tries the capabilities that can fill it, in order, and stops at the first good value. Each value is stamped with when it was verified, how long it stays fresh and a confidence. A stale value that enrichment wrote is re-checked later. A newer enriched value replaces an existing one only through an approval, with undo. Spend is real, so always estimate first.

Where to find it

What you can customize

Operations

enrichment.enrich_accounts (D), enrichment.enrich_contacts (D), enrichment.refresh_stale (D), enrichment.overwrite_preview (Q), enrichment.overwrite_field (E), enrichment.undo_overwrite_field (E), enrichment.policy.get (Q), enrichment.policy.set (D, human only), enrichment.budget.get (Q), enrichment.coverage_report (Q), enrichment.freshness (Q), enrichment.record_freshness (Q), enrichment.kpis (Q), enrichment.list_runs (Q).

KPIs it publishes

enrichment.coverage_report (fill rate per field), enrichment.kpis (provider win rate, fill rate, spend, cost per filled field, cache-hit rate), enrichment.freshness (share within its window, average confidence, stale count per field), enrichment.budget.get (cap, month to date, what is left, when it resets). Confidence shows as high (0.8 and up), medium (0.5 and up) or low.

Events and ledger rows

• Ledger rows enrichment.field_overwritten (undo: enrichment.undo_overwrite_field) and enrichment.field_overwrite_undone.
• Every lookup is a line on the cost ledger (Operate > Cost). Each value carries custom.enrichment[field] with verifiedAt, ttlDays, confidence, provider.
• enrichment.policy.set emits gtm.definition.signed. Enrichment writes count as bulk events, so plays skip them unless they opt in.

Dry Mode and guardrails

• Engine key enrichment. In Dry Mode (workspace or engine) a run returns its estimate marked dryMode: true and attempts no lookup. If Dry Mode turns on during a run, held lookups are counted in heldByDryMode, not as approvals.
• Empty-only and idempotent: a field is never overwritten by a run.
• A paid-once cache means a field is never paid for twice inside its freshness window.
• The monthly cap is checked by the broker on every enrichment lookup, including agents' own. Past the cap a lookup waits for an approval.
• When money is limited, records are worked in score-band order: hot, then warm, then cold, then by score. Unscored records come last.
• If a provider is down, enrichment moves on to the next one in the binding.

How to extend it

• Another provider. Add a fallbacks[] entry to the capability's binding, or point the binding at an MCP server you registered. Composio is never used to buy data.
• Refresh on a schedule. A play that calls enrichment.refresh_stale with maxUsd and requireMonthlyCap: true.
• Enrich on create. A play on gtm.record.created that calls enrich_accounts with requireMonthlyCap: true. Opt in to bulk sources only if you mean it.

Prompts to give Claude

Estimate the cost of enriching the 200 companies with the highest score that are missing employee count or industry. Show the expected and worst-case cost and which providers would be used. Do not run it.

Cap enrichment at 150 dollars a month. Re-check emails after 60 days instead of 90, keep phones at 180 days.

Enrich the 25 oldest incomplete companies, but stop at 2 dollars. Then show me the fill rate before and after and what it cost.

For finding emails, use looot job people.email.find first, capped at 4 cents a lookup, and fall back to our own MCP server "emails" capped at 2 cents. Require verification before an email is written.

Show me how many enriched values are stale and what refreshing them would cost. If it is under 20 dollars, propose the refresh capped at that.

The email fallback prompt assumes an MCP server named emails is already registered (chapter 10).

How to verify the change took effect

Signals

Goal: the right signals count, from the right sources, with the right weight, and a person has verified the ones that need it.

What it does

Signals records typed evidence about accounts and contacts (funding, hiring, a pricing page visit, a reply), weights it by kind with recency decay, and reports intent surges by topic. A verification gate decides which signals count toward scores and reach sellers. The daily signal scan, run by the Score package, gathers new signals from looot research.

Where to find it

What you can customize

Signing a signals model replaces the default model, it does not add to it. List every kind you care about, including the negative ones. Any kind you leave out scores defaultWeight, and a risk signal would then count as a small plus. Ask Claude to start from the default's 24 rules and change only what you name. A model without a signalStrength block is ignored.

Two words are used for grouping. A category (buying, intent, engagement, product, lifecycle, negative, record) drives decay and the reaction. A class (buying, growth, risk, other) drives the feed filter and classes.

Example: let signals from your intent provider verify on their own, and make pricing visits count more:

kind: definition.scoring_model
key: signals
spec:
  scoreScaleId: signals.strength.0-100
  qualifiedThreshold: 60
  needsReviewThreshold: 30
  signalStrength:
    defaultWeight: 5
    halfLifeDays: 30
    disputedMultiplier: 0.5
    floor: 0
    ceil: 100
    autoVerify:
      - { id: first_party, partyTiers: [first] }
      - { id: intent_vendor, providers: [looot], kinds: [intent_surge] }
  rules:
    - id: signals.pricing
      statement: Visited pricing pages
      matchesKind: [website_visit_pricing]
      weight: 20
    # ...the other 22 default rules, unchanged, including the negative ones (shortened for this page)
    - id: signals.risk
      statement: Risk (layoffs, breach, lawsuit)
      matchesKind: [risk]
      weight: -40

Check the provider string stored on a real looot signal before you rely on the auto-verify rule above.

Operations

Record and read: signals.record (D, up to 1,000 per call, idempotent by dedupeKey), signals.list (Q, seller view by default), signals.feed (Q), signals.review_queue (Q), signals.score (Q), signals.surge_report (Q). Review: signals.verify (D, human only, up to 500), signals.retract_signals (D, reversible), signals.undo_retraction (D). Gate: signals.settings.get (Q), signals.settings.set (D, human only). Intake: signals.ingest_intent (D), signals.scan_now (D), signals.scan_status (Q). Market feed: score.ingest_market_signals (D).

KPIs it publishes

signals.surge_report (surging topics with z-score, mean and standard deviation over a window), the Hot and Warm account counts, the review queue length, and signals.scan_status (signals created and spend against the cap per run).

Events and ledger rows

• Emits gtm.signal.observed for every new signal and gtm.signal.verification_changed on every verify, dispute, retract and restore. The account is re-scored on each.
• A signal the gate held back is released once, when first verified. Its routing, enrolment, alert and plays run then.
• The scan records its runs as the monitor score.signal_scan.

Dry Mode and guardrails

• Signals has no engine mode. Recording a signal is an internal write and works in Dry Mode.
• The scan spends real looot credits, so Scan for signals now is disabled, and nothing is queued, while the organization-wide Dry Mode is on or while signals.scan.enabled is false. The page says which one applies.
• The scan stops at perRunCapUsd through the broker's ledger (never above 1 USD on demand).
• Retracting never deletes. Turning the gate off does not replay held signals. They release when someone verifies them.

How to extend it

• First-party signals. Send your product events, form fills and bookings in through the connectors or signals.record with partyTier: "first". Third-party sources: set partyTier to third.
• Source mapping. Map any connected app's rows to signals with the source mapping flow (chapter 10), for example demo requests from a form tool.
• New kinds. A new kind scores defaultWeight in this engine. Give it a rule here, and in the Score intent model if it should move the account score.
• Evidence. Add evidence {sourceUrl, matchedText, confidence, provider} so a reviewer can decide fast.

Prompts to give Claude

Show me the current signal verification mode and which signals are waiting in the review queue. Explain what changes if we move from strict to seller_surfaces. Do not change anything.

Auto-verify hiring and funding signals from looot, but keep everything else third-party in the review queue. Keep first-party auto-verification. Start from the default signals model so the weights and the negative kinds stay as they are.

For this client, pricing page visits are the strongest signal: weight 35. Funding stays at 30. Make signals fade with a 14-day half-life. Leave every other weight alone.

Scan 50 target accounts a day, only prospects, look back 60 days, cap a run at 5 dollars, and skip social posts and reviews. Then show me the scan status.

Record a "demo_requested" signal for contact jane@example.com on account acme.example with the summary "Requested a demo from the pricing page" and a link to the form submission. Treat it as first party. Then tell me how it scores.

demo_requested is not a built-in signal kind. The closest built-in kinds are form_submitted and discovery_call_booked.

How to verify the change took effect

The picture in one minute

Goal: know which door a piece of data uses, and who is allowed to open it.

Two rules hold everywhere. Secrets are sealed on save and never shown again, so a person pastes them in the console. Any write that leaves GTM OS (a CRM field, a webhook subscription) is a proposal that someone other than the proposer approves.

Native, Composio, looot or your own MCP server?

Goal: pick the right connection path before you build on it.

Rule of thumb. Is it data you buy? looot. Is it your own SaaS account? Composio. Is it a Google, Microsoft, Slack, email or ads account that has a card? Native. Is it your own internal service? An MCP server. An org connection always beats the instance environment credential.

On the Connections page each tile says Native or Via Composio. Tools with no native card yet (Instantly, lemlist, Smartlead, Gong, Mixpanel, Amplitude) connect through Composio.

Check what is connected before anything else

Goal: see which seams are live, unverified, failed or still fixture data.

Check readiness. List every connection seam as live, stored but not verified, failed or missing, and say which engines each one blocks. Do not change anything.

A stored key that was never tested reads "stored, not verified". Click Test on it, or ask Claude to run connections.test (a probe of the provider, so it counts as an effect and is recorded).

Composio: connect your apps and pick the CRM of record Needs a human

Goal: your apps show ACTIVE and one CRM is the CRM of record.

1. Needs a human On Integrations > Connections, Composio card, click Connect Composio and sign in. Or open Advanced and paste a Connect key ck_... or a project key ak_.... A uak_ user key is refused.
2. Ask Claude to link your apps (prompt below). In Connect mode, apps you already connected in your Composio account become ACTIVE at once.
3. Needs a human A new app needs the hosted sign-in. Claude gives you the link. It lasts about 10 minutes.
4. Ask Claude to set the CRM of record.

Check the Composio connection, link every app I already connected there, then set HubSpot as the CRM of record and run one sync. Report the counts and anything truncated.

looot: bought data, always priced first

Goal: enrichment and research pull from looot inside a spend cap.

looot has no operations of its own. GTM OS reaches it through capabilities, resolved by a definition.binding with backend: looot. A binding looks like this:

kind: definition.binding
key: enrich.find_email
spec:
  capability: enrich.find_email
  backend: looot
  opId: job:people.email.find
  maxUnitCostUsd: 0.05

1. Needs a human Add the looot connection in Integrations > Connections (Add a connection), then run Test.
2. Ask Claude to find candidate provider endpoints and price them before it pins one.
3. Claude proposes the binding. A person signs it and promotes it.

Quote what it would cost to find work emails for the 200 accounts in the segment target-accounts. Do not buy anything. Show the unit price, the total and the cap that applies.

Never ask Claude to run a paid enrichment without a quote. capability.acquire is a metered effect and runs through the approval gate.

Your own MCP server as a data source Needs a human

Goal: an internal tool becomes a capability or a source of records. This is the opposite direction from the MCP you use to talk to GTM OS.

1. Claude registers the server and tests it. You can paste the auth value yourself in the MCP servers card if you want it kept out of chat.
2. Needs a human You mark each tool Read or Write (approval). An unmarked tool cannot be used. Agents cannot do this step.
3. Claude binds a capability to a tool, or builds a source mapping over a read tool (see Any other app).

Add our internal API as an MCP server named acme-tools at https://tools.acme.example/mcp. Test it, show me its tools, and propose a binding that uses its company lookup tool for the capability enrich.company.

CSV import: the wizard and its rules

Goal: companies, contacts or deals in GTM OS, matched to what you already hold, with every row previewed first.

The console wizard

1. CRM > Import. What are you importing? Companies, contacts or deals.
2. Choose the file or paste CSV. The first row is read as headers. Comma, semicolon and tab all work.
3. Map your columns. Each CSV column goes to a field, to Do not import, or to a new custom field. Map at least one column to continue.
4. Preview. Every row reads Create, Update, Held for review, or an error. Nothing is written.
5. Commit. Owner or admin by default.

The rules that decide what happens

I will paste a CSV of contacts. Map the columns to canon fields, link each contact to its company by website, run a preview only, and show me the counts for create, update, held and error, plus the unmatched companies. Do not commit.

Any other app: source mappings

Goal: a list tool of any Composio app (or your MCP server) feeds an ontology object on a schedule.

A source mapping is a definition.source_mapping. Only a signed version runs. These are the fields that matter:

Map our Typeform demo-request responses to signals, every hour, matched to contacts by email. Preview the live data first and show me the proposed field mapping before you propose it.

For a messy source, or when you want a reviewable trail, use the adapter builder next.

The adapter builder Needs a human

Goal: turn a connected source into a signed mapping with a confidence on every line, numbered questions for the unclear parts, and a mapping document. No code is generated.

Console: CRM > Adapters. Every step is also an operation.

Start an adapter for HubSpot contacts into gtm.contact using the list tool HUBSPOT_LIST_CONTACTS. Run the completeness audit, propose the mapping, and give me every numbered question with your recommended answer. Do not publish yet.

Incremental syncs: set the changed-since argument and the cursor field on the adapter, then publish a new version. Automatic incremental runs skip while the CRM write-back engine is in Dry Mode. Sync now always works. If you stop, adapter.abandon drops the session's open asks. A signed mapping keeps running until you deprecate it (definition.deprecate) or set it to manual. Mirrored rows stay.

CRM mirror and sync health

Goal: know your mirror is complete and current, not just "synced".

• Supported CRMs: hubspot, salesforce, pipedrive, attio, zoho, all through Composio. The setting is crm.settings.set {crmOfRecord}. There is no separate "of record" operation.
• Synced records are keyed on custom.crm = {toolkit, object, recordId}, so a re-sync updates, never duplicates. One sync runs per org at a time.
• Stage and lifecycle values are meaningful only through a definition.stage_map for that system. An unmapped value is held for review, never defaulted (see Definitions as code).
• Binding modes (binding.set_mode): replicate, soft_merge, federate, in_zone, sheet. The modes in_zone, soft_merge and federate never write back.

Audit my data sources. For each mirrored source and object show the source row count against what GTM OS holds, the ratio, and anything below the flag threshold. Then sample 20 records per object and show field-level differences against live. Read only.

Write-back to the CRM or to a source app Needs a human

Goal: GTM OS changes a field in your CRM, with a different person approving and a one-step undo.

Rules: the record must carry the sync marker (it was mirrored by crm.sync or by that mapping). Only fields in the CRM's schema, or in writeBack.fieldMap, are accepted. Binding modes in_zone, soft_merge and federate refuse. Prior values are saved when the CRM or the mapping's get tool can read them, which is what makes undo possible. A different person approves and executes. In Dry Mode the effect ends at the proposal.

Propose moving the HubSpot deal for Acme Logistics to the stage Contract sent. Show me the exact field and value you will write and who needs to approve. Do not execute.

Webhooks: in and out

Goal: events arrive from outside, and GTM OS events leave to your own endpoint, both signed.

Inbound

The API URL is the apiUrl that agent.connect_info returns. Replace <orgId> with your org id. The signature is the authentication. With no secret configured the endpoint answers 503, and with a bad signature 401. Nothing is written in either case.

Outbound

1. Ask Claude to register a subscription: webhooks.create {url, eventTypes[], secret}. The secret must be at least 16 characters. Generate it yourself and keep it. It is sealed and never returned.
2. Needs a human A different person approves the subscription. This is a proposal like a package install, because it opens a stream of your events to an outside URL.
3. Your endpoint verifies the HMAC-SHA256 signature from the webhook-id, webhook-timestamp and webhook-signature headers and answers with a 2xx status.

Propose a webhook subscription to https://hooks.acme.example/gtmos for the event types gtm.reply.received and gtm.meeting.booked. Generate a random secret of at least 16 characters, use it in the call, and print it to me once so I can set it in my receiver. Do not write it to any file. Then list subscriptions.

Event types are matched exactly against the event names GTM OS writes to its outbox. The agent and play events are gtm.meeting.booked, gtm.reply.received, gtm.record.created and gtm.transcript.ingested. The target URL is checked against a private-network guard when you create it and again at delivery, so localhost and private addresses are refused.

Only the event names in the reference are confirmed. The full set of event types that webhooks.create accepts is not published, so test a new subscription before you rely on it.

Enrichment inputs and other feeds

Goal: know what feeds enrichment and the other data engines, and what caps the spend. The engine itself is in Engines.

Spend controls: the per-call cap on a binding, the per-run maxUsd, and a monthly cap (UTC calendar month) in definition.enrichment_policy.monthlyCapUsd. Freshness windows are ttlDays per field in the same definition. enrichment.policy.set publishes and signs it in one step, and it is humans only. Read the month's spend and what is left with enrichment.budget.get. Enrichment only fills empty fields. It never replaces a value a person set, unless a person approves an enrichment.overwrite_field proposal.

Show source coverage, enrichment freshness, the monthly enrichment cap and month-to-date spend. Then list which feeds I have not connected yet. Read only.

Verify and pitfalls

Goal: a short check after every data change, and the mistakes that cost time.

1. gtm doctor --strict exits 0, or instance.readiness shows the seam as live.
2. crm.sync_status or source.sync_status shows counts, truncated: false and no errors.
3. CRM > Data health has no object flagged below the threshold.
4. Open one record and check where its values came from with gtm_lineage_trace (the receipts behind a record's values).

• Do not put keys in instance/.env after install. Org connections are live at once. Env changes need a restart.
• An unsigned mapping never runs. Signing and promotion need a person other than the proposer.
• Signals sources must use mode: append.
• A mapped source never creates a contact's company for you. Unresolved rows mean the parent is missing.
• Do not use Composio to buy data and do not use looot to read your own CRM.
• CRM writes use the CRM's own field names, not GTM OS names.

What is what

Goal: pick the right layer for the job.

The rule that never changes: an agent proposes and a different person approves. No agent can approve, sign, or widen its own authority.

The predefined agents Needs a human

Goal: turn on ready-made agents and know what each one is allowed to do.

Sixteen agents ship in six signed packs. They are not on by default. Turning a pack on is a request that a second admin approves, in Settings > Agents, Agent packs.

Enable stdlib/pack.core-skills before stdlib/pack.core-agents. The core agents use its skills.

List every agent pack with its install state. For each agent show its scopes, skills, bounds and trigger. Then propose enabling stdlib/pack.ops-agents in my default environment.

What happens to your edits: an agent you re-bound (Update to new version) or whose spec you edited is left alone on update. A trigger you edited, paused or deleted is never overwritten or re-created. Disabling the pack in its last environment, or uninstalling it, switches its agents and triggers off. agent.revive refuses a pack agent while its pack is off.

Agent bounds, scopes and authority

Goal: know every limit on an organization agent and which one wins.

An agent's limits live in its definition.agent spec:

kind: definition.agent
key: <agent id>            # the id agent.register returned
spec:
  agentSpecVersion: 1
  authorityScopes: [record.read, record.write]
  skillRefs: [acme-pipeline-reader]
  bounds:
    maxSteps: 15            # loop length
    maxCostUsd: 1.0         # accumulated ledger spend
    deadlineMs: 300000      # wall-clock lifetime of a run
  goal: Review stalled deals and propose one next step each.   # optional default goal
  systemPrompt: ...                                             # optional

Skills and allowlists

Goal: give an agent exactly the operations it needs and nothing else.

A skill for an organization agent is a definition.skill:

kind: definition.skill
key: acme-pipeline-reader
spec:
  skillSpecVersion: 1
  packageRef: acme/sales-pack
  operations: [records.search, records.get, task.create]
  unmaskPaths: []
  costCeilingUsd: 0.1
  systemPrompt: Read deals, never write them. Create one task per stalled deal.

Skills for your coding agent are a different thing. gtm init installs them from a pinned, checksum-verified release (with a bundled offline copy), plus 11 role subagents (gtm-operator, revops-analyst, deal-reviewer, sales-researcher, content-strategist, seo-refresher, customer-success-manager, competitive-analyst, ads-analyst, data-steward, eval-reviewer). After upgrading the CLI, run gtm init --refresh in each project. Files you edited are kept.

Create and register your own agent Needs a human

Goal: a custom organization agent with its own scopes, skills, bounds and a trigger.

Claude can draft all of it. A person must do the steps that grant authority. An agent key cannot call agent.register, agent.bump_version, agent.kill, agent.revive or agent.create_key.

Path A: ship it as a declarative pack (recommended)

This is the same path the sixteen shipped agents use. Enabling the pack registers each agent, publishes its skills, and provisions its triggers in one approved step.

1. Claude scaffolds a declarative package (gtm pkg scaffold acme/sales-pack --tier declarative) with contributes entries for skills, agents and triggers, and permissions.operations as the union of the skills' operations.
2. Claude validates and tests it: gtm pkg validate, gtm pkg test (checks the declared eval files exist), gtm pkg build.
3. Needs a human You install and enable it: gtm pkg install, then gtm pkg enable acme/sales-pack --env <default env>. Each is a proposal a different person approves.

Path B: register directly

1. Needs a human An owner, admin or builder registers the agent: agent.register {name, specRef, scopes}. The caller becomes its owner.
2. Claude proposes the definition.skill and definition.agent resources (key = the agent id). They go through config.propose_changeset, config.validate_changeset, config.apply.
3. Needs a human A different person signs both (definition.sign). In prod, only a signed version is read. Promote with env.promote.
4. Claude registers a trigger (next section).

Untested: the specRef value for an agent that is not shipped by a package was not confirmed. Prefer Path A.

Design a read-mostly agent that reviews deals stalled for more than 21 days every Monday and creates one task per deal with the reason. It may read records and create tasks only. Bounds: 12 steps, 50 cents, 3 minutes. Package it as a declarative pack named acme/sales-pack with its skill, agent and a schedule trigger. Validate and build it, then show me what the approval will list. Do not install anything.

Triggers and starting a run

Goal: an agent starts on a schedule, on an event, or when you say so.

Common fields: enabled, goal and successCriteria (override the run's goal), maxFiresPerHour (1 to 10000), includeBulkSources. A triggered run knows why it started: it carries the event type and record ids, or the UTC day, time and cron of the occurrence.

No event storms. Events written by bulk writers (imports, the CRM mirror and sync, the projector, enrichment, first mailbox sync, canon.edit_many) start nothing unless includeBulkSources is true. Each trigger fires at most maxFiresPerHour runs per hour, and the instance default cap is 60 (GTMOS_AGENT_TRIGGER_MAX_FIRES_PER_HOUR). A fire over the cap is skipped and recorded on the trigger. A package cannot loosen these guards. Only a person can, with agent.trigger.update.

For the agent follow-up-agent, add an event trigger on transcript ingested with a cap of 10 runs per hour. Then fire it manually once and show me the run.

Pause, resume or edit a trigger with agent.trigger.update. Remove one with agent.trigger.delete (soft delete: it stops firing at once, and past runs keep their attribution).

Run history, KPIs and the kill switch

Goal: see what an agent did, what it cost, and stop it.

A rate shows as "n/a" with the reason until there are 5 finished runs, 3 decided approvals or 3 evaluated runs. Runs answered by the demo model are excluded and counted.

Show the KPIs for pipeline-review-agent over the last 30 days. List its last 10 runs with status and cost, and open the most expensive one. Tell me whether any run stopped on a bound.

Run history for agents is read through these operations. The Operate > Runs page shows durable flow runs (plays), not agent runs.

Missions: a plan a person approves, then a bounded run

Goal: hand an agent a bigger job with one human approval and a hard envelope.

A mission moves through these states: intake, clarify, plan, approve, execute, adapt, then done, failed or cancelled. There is no mission screen in the console in 0.2.5. You drive missions through MCP or the API. Do not confuse them with Mission Control, which is the console home page.

The mission bounds

On approval, the mission's bounds are pinned onto the run, and the agent's own bounds still apply. The lowest value wins. A mission-scope cost budget with your maxCostUsd as its cap is created too.

The lifecycle

1. mission.start creates it in intake. It does not execute.
2. mission.clarify records questions and answers. An optional ask opens a numbered open ask for a person. Answering it feeds the answer back.
3. mission.plan records the plan. mission.submit_for_approval proposes it.
4. Needs a human mission.approve. This is the single human moment. A different person approves, and an agent is refused. Execution begins.
5. mission.step advances by one durable step. It checks the budget first. At a cap it halts and waits for approval, with no further spend. Re-calling after a crash continues without double spend. The result says whether it is done, failed, halted on budget, or still executing.
6. If the plan must change, mission.adapt replans inside the envelope, then mission.resume continues. Anything outside the envelope escalates to a person.
7. mission.cancel stops it from any non-terminal state. mission.get and mission.list read it.

A play with a mission_step trigger starts when a mission runs a step of that kind. The kind is the approved plan's steps[i].kind, execute when the plan lists no steps, and * matches any.

Start a mission for pipeline-review-agent: "Find the 10 stalled deals with the highest value and draft one next step each". Bounds: 20 steps, 2 dollars, 10 minutes. Success criteria: every draft cites a deal record. Gate on the eval safety.cites-records at minScore 1. Clarify anything unclear with me first, write the plan, and submit it for approval. Do not execute until I approve.

Evals: prove an agent behaves before you widen it

Goal: a run that breaks a safety rule is marked failed, not completed.

A run or mission can declare evalName and minScore. At completion the scorer runs. A score below minScore fails the run. With no evalName or no minScore the gate is skipped, and that is an honest no-op, not a pass. The safety gate uses minScore: 1, so any single breach fails it.