gtmos-onboarding

GTM OS per-org setup runbook (the agent executes this)

The console's setup wizard and this runbook drive the SAME operations: whatever you save here, the user sees in the console (Setup), and the other way round. Before this skill, the workspace must be connected to an instance (.claude/gtmos-instance.json has an apiUrl, /mcp shows the gtmos server). If not, run the gtmos-setup skill first.

Step 0 -- probe the instance first

Before the first screen, and again at the start of a new session:

1. Call harness.status with gtm_query {"name":"harness.status"}. Compare operationsHash with referenceOpsHash in .claude/gtmos-instance.json, and expectedSkillsTag with the skills tag you were installed from. A difference means the instance changed since gtm init: tell the user and suggest gtm init --refresh.
2. Call gtm_describe with no argument for the catalog of this instance, and again with a name for every operation a screen needs, just before you use it.
3. If the instance does not know an operation, skip that part of the screen and say why in the same reply ("this instance has no <operation>"). Add an Open item. Never call a different operation in its place and never invent one.
4. If harness.status itself is unknown, the instance is older than GTM OS 0.2.6: carry on with the catalog from gtm_describe alone.

Rules (all of them, every time)

1. Read the schema before every call. gtm_describe {"name":"<operation>"} returns the exact input schema; docs/gtmos/reference/operations.md has the same entries. Never guess a field or a value of an enum. Reads go through gtm_query {"name":"<op>","input":{...}}, writes through gtm_act {"name":"<op>","input":{...}}.
2. Never invent a value. A value you save comes from one of: the user's own words in this conversation, an evidence entry of a drafted card, a reasons[].fact of onboarding.suggest, the crawled site (research.workspace_profile.get), an uploaded setup document, or a connected source's real counts. If none of these has it, leave the field empty and open a numbered ask (asks.create, or onboarding.request_access / onboarding.request_docs) with an owner. "I don't know yet" is a valid answer; a plausible guess is not.
3. Cite the evidence. When you show a draft, show where each value comes from: quote the card's evidence item (or the suggestion's { fact, source }) next to the value, e.g. "ICP country DE, weight 30 -- evidence: 14 of 22 closed-won accounts are in DE (closed-won deals)". A value with no evidence is shown as "no evidence -- please confirm or leave empty".
4. The model drafts, the human owns. Present drafts; save a value only after the user confirms it (onboarding.card.edit / onboarding.update). Never approve a card the user has not seen.
5. Human-only operations. Agent keys are refused on some operations (the tables say human only; the full list and what you do instead is in "Human-only: what you do instead" below). The refusal reads FORBIDDEN: Operation "<name>" can only be performed by a human. Over MCP every call counts as an agent call, even when the MCP bearer is a human's own session token: roles.assign, onboarding.launch and the rest are refused there too, so the human does them in the console. Never retry, never route around it (another key, the user's session, a raw API call): propose what you can, prepare the draft, then ask the human to finish it in the console and tell them where to click.
6. The ARR band is private. profile.arrBand is set and read by human owners / admins only; agents get FORBIDDEN ("the ARR band is private: only a human owner or admin can set it") and see it redacted. Never ask the user to paste it to you: tell them to set it themselves in Setup > Welcome (or leave it empty, which keeps it private). Never write it to a file or the memory.
7. Four-eyes. An operation that proposes (blueprint.apply, env.promote, stage_map.set, the ICP / pilot / customer-type / suppression ChangeSets, the journeys, what a build step proposes) is approved by a DIFFERENT human: not the proposer and not the person you act for. You never approve, never ask for the approver's password, and never use their session. Report the approval id and <console>/org/<org id>/approvals, then continue.
8. Optimistic concurrency. Every write takes expectedVersion from the last onboarding.get. A CONFLICT means someone else (often the user in the console) changed the session: re-read, show what changed, and ask before you redo the write.
9. Never silent. A refusal (FORBIDDEN, NOT_CONFIGURED, VALIDATION_FAILED, CONFLICT) or a proposal is told to the user in the same reply: the operation, the error, the fix and who owns it. Record it as an Open item in .claude/memory/setup-status.md.
10. Only what exists. Use the operations listed below; if gtm_describe does not know one, see "On an older instance".
11. Say why. A gtm_act that proposes an effect takes an optional justification (the MCP argument of gtm_act; over REST the x-gtmos-justification header): why now, in your own words, for the person who approves. In GTM OS 0.2.6 it is optional. An agent proposal at tier T2 or above without one is still recorded, and the approver sees "No reason given by the agent". From GTM OS 0.2.7 (GTMOS_JUSTIFICATION_ENFORCE on by default) it is required for agent proposals at T2 or above: at least 10 characters that are not spaces, or the call is refused with VALIDATION_FAILED and nothing is written. Always send one now. A good reason names the evidence and the effect: "14 of 22 closed-won accounts are in DE, so this saves the ICP card with country DE". A bad one repeats the operation name or says "as requested". It is a statement, not a proof: never write a reason you cannot back with a number or a source. A person may leave it out. At tier T3 and above a named person other than you approves, whatever the reason says.

The six screens

1. Welcome (screen welcome; steps company, motion)
2. Connect your data (screen connect; steps connections)
3. Your definitions (screen definitions; steps definitions)
4. Rules and who approves what (screen rules; steps rules, team)
5. The build (screen build; steps build)
6. First motion and 90 days (screen first_motion; steps plan, launch)

Start every session with gtm_query {"name":"onboarding.get"}: it starts the session on first read and returns session.currentStep, completedSteps, version, the cards and the progress. Resume at currentStep; never redo a completed step unless the user asks (onboarding.update with reopenStep). After each screen, mark its steps done with onboarding.update {"completeStep":"<step>","expectedVersion":<v>} (one step per call, in order).

Operations for every screen:

Screen 1 -- Welcome (company, motion)

1. Ask the user, in one grouped question: company name, website, industry, team size, markets, deal sizes, sales cycles, motions, maturity, the tools in their stack, up to 3 pains, who runs it and the hours a week they give it, and the five free answers (what you sell, who buys, a great next quarter, what has not worked, what the OS must never do). Use the enum values of onboarding.update (gtm_describe); map the user's words to them and show the mapping. Unanswered = left empty. The stack decides which sources are selected by default and which access asks open; the hours size the 90-day plan.
2. With a website, run research.workspace_profile.refresh, then read research.workspace_profile.get: offer facts from it (with the page it came from) for the user to confirm; never copy them in unconfirmed.
3. Save the confirmed answers with onboarding.update (profile, pains, team, stakeholders). The ARR band: rule 6.
4. Read onboarding.suggest. Show the engines and blueprints with their reasons (and against). The user picks the engines (onboarding.update {"engines":[...]}, or null = take the suggestion) and, optionally, a blueprint (blueprint.get shows what it installs). Save the pick with onboarding.update {"blueprint":"<id>"}: the build (Screen 5) applies it adapted to the approved cards. Apply it now (blueprint.apply, it proposes: rule 7) only when the user asks, and then save {"seed":{"changeSetId":"...","approvalId":"..."}} too. Applying the same input again while its proposal still waits (and its base versions are current) returns that proposal with reused: true, not a duplicate.
5. completeStep company, then motion.

Screen 2 -- Connect your data (connections)

1. Read onboarding.signal_coverage: per category, what is connected, real record counts, the most accounts one source covers (never a sum), stackMissing, and catalog (each connector: how it connects, where its data lands, the operations that pull it, what it still needs). Report only these numbers; no percentage or score that the operation did not return.
2. Read onboarding.get runbook: per source, what to ask for, who grants it, lead time, and whether it is EARLY. Connecting a source follows the gtmos-setup skill (Step 6: Connections): provider keys as connections, Composio apps through composio.sync_connections; a new OAuth sign-in is clicked by a human in the console.
3. A connected source the catalog says still needs a setting (a project id, an event map): ask the user for the value and save it with connections.set_provider_setting. Never guess an id.
4. Pull now, once a source is connected, so the next screens draft from real data: product_analytics.sync (PostHog, Mixpanel, Amplitude), transcripts.sync (Fireflies, Gong, Zoom, Fathom), outbound_rails.sync_replies (Smartlead, Instantly, lemlist). NOT_CONFIGURED means that tool is not connected: say so. outbound_rails.list shows which rail senders / campaigns a lane can bind; every send through a rail still goes through the approval-gated outreach.send_message.
5. For the grants the user cannot give now, run onboarding.request_access (optionally grantors = the emails the user names) and hand the user the numbered list it returns to forward.
6. completeStep connections (missing sources stay as numbered open asks; that is fine).

Imports (GTM OS 0.2.6): a file import goes through a review gate. import.review.list shows the batches and each row's gate result; rows the gate blocked are held back from the CRM. You may fix or skip a row with import.review.decide and show the user the reasons. You never override the gate: that needs a reason of 10 or more characters from the person, and a legal block (suppression, consent, do-not-contact) cannot be overridden at all.

Screen 3 -- Your definitions

1. Documents first. onboarding.get docs is the checklist (ICP notes, stage definitions, pricing, brand voice, suppression lists, DPA). A document the user hands you (a file in this workspace): onboarding.docs.upload with its docKey (it answers that document's open ask); onboarding.docs.list shows what was extracted. A document they mention but have not shared: onboarding.request_docs with an owner each. Never upload a file the user did not point you at.
2. onboarding.draft_cards drafts every card from the org's own data, answers and documents. With a model configured (mode auto), each value cites evidence ids; an uncited value is dropped and opens a numbered question ask; without a model the card says so (evidence.model). Edited, approved, pending and skipped cards are kept (pass force only when the user asks to redraft one).
3. For each card of this step (onboarding.get cards), show the draft WITH its evidence (rule 3). The user confirms, changes or skips it: onboarding.card.edit (shape per card in the reference) / onboarding.card.skip.
4. Approve with onboarding.card.approve only what the card table lets you; for the rest, tell the user to approve it in Setup > Your definitions (rule 5). The answer's card.status is approved, pending_approval (a different human approves: rule 7) or failed (say why; the card stays editable). A card whose draft is not complete yet is refused with VALIDATION_FAILED and its issues (e.g. an icp card with no rules on an org without closed-won deals): fill it with the user's own criteria (onboarding.card.edit), or skip it. Seen live: with no revenue source connected, the money card opens the numbered ask "Connect a CRM with deals or Stripe" and fails until one is connected; brand_voice needs at least one tone word in the user's words.
5. The cards of this screen:
   • crm_stages: stage_map.unmapped lists the CRM's REAL stage values; stage_map.suggest / stage_map.ai_suggest propose a mapping; the user confirms it on the card (or you save it with stage_map.set, which an agent proposes for the approver).
   • customer_types: compare with customer_type.list (and customer_type.classify for a sample record the user names); approving proposes a ChangeSet.
   • brand_voice: compare with brand.get; brand voice is human-only (brand.set).
   • suppression: built from their suppression documents and words; approving proposes a ChangeSet a different human approves. Suppression lists are RESTRICTED documents: an agent cannot read them, so your draft has the competitors and existing-customer rules but NOT the do-not-contact list. Say so, and ask an owner / admin to redraft that card (onboarding.draft_cards {"force":["suppression"]}, or Redraft in the console) and approve it. Never ask for the addresses in the chat.
6. onboarding.blueprint_adaptations shows what the picked blueprint will take from the approved cards when the build applies it: show it before the build.
7. Definitions you publish land in dev; prod needs signing + promotion (Screen 6).
8. completeStep definitions.

Newer definitions (GTM OS 0.2.6), only when the user asks for them and Step 0 showed the instance has them: a data-quality policy (identity_dq.dq_policy.get, then identity_dq.dq_policy.propose), a funnel (funnel.list, funnel.evaluate), a revenue target (board.target.get, board.target.propose) and the recommendation rules (recommendation.rules.get, recommendation.rules.propose). Each is a definition a person signs. Read before you propose. Quote the coverage block with every funnel rate and say "unavailable" where board.evaluate does. A data steward bundle (identity_dq.steward_plan, then identity_dq.steward_bundle) is shown as a plan first; a different person approves it.

The cards of this screen and who can approve them:

Screen 4 -- Rules and who approves what (rules, team)

1. The cards of this step (below): show the draft and its evidence; the user approves them in the console (their targets are human-only). For autonomy, say plainly that outreach never acts within caps unless the org baseline already grants it, and that engines go live only at Launch.
2. Show the current policy as read (policy.get_dry_mode, policy.guardrails.get, policy.engine_modes.get, policy.get_autonomy_scopes) next to the draft, so the user sees the change.
3. Seats: roles.list shows the profiles and the members. Save the seats the user names (member user ids from roles.list members) with onboarding.seats.set. Its roles.errors for an agent is expected: the binding to a role profile (roles.assign) is human-only -- the user saves the seats again in the console, or assigns the profiles in Settings > Members. Warn before a seat is bound: a profile caps its holder at its base role and removes its denied operations (Operator = member; Exec = admin without config / journey / send operations; Ops lead = admin; Engineer = builder). roles.list returns keepsSetupAuthority per profile and setupStewards (the owners / admins who can still run the build, approve the cards and launch). Never put the sole owner in the Operator or Exec seat: seat them as Ops lead (or leave them unseated). The kernel refuses a change that would narrow, demote or remove the last setup steward with CONFLICT details.reason LAST_OWNER_NARROWING: the fix is another un-narrowed owner or admin first.
4. Custom role profiles (roles.upsert) are human-only: describe what the user wants (base role, denied operations, KPIs, actions) and let them create it in the console. A profile only narrows.
5. completeStep rules, then team.

Before the user decides who approves what, owners and admins can read risk.tier_readiness: it lists the operations that would start needing a named approver when the stricter risk tiers turn on (default on from GTM OS 0.2.7).

Screen 5 -- The build

1. onboarding.engine_readiness: per picked engine, each requirement met / missing / unknown, with the evidence and the remediation. An unknown is reported as unknown, never as met.
2. Tell the user what the build will do (the steps below), then onboarding.build.start. It returns at once (run.status queued); one run at a time per org (a second start returns the running one with alreadyRunning: true).
3. Follow it with onboarding.build.get every few seconds until run.terminal: report each step's status and its real result (ChangeSet, approval, ask and adapter ids). A step you may not run is skipped with the refusal; a failure carries its reason and the run continues. Stop it with onboarding.build.cancel only when the user asks.
4. needsHuman lists what waits for a person: the proposals of this run (a different human approves them in Approvals) and the asks raised. Nothing you do executes an approval. A finished run with failed, partial or cancelled steps: fix the cause with the user, then onboarding.build.start {"retryRunId":"<run id>"} re-runs only the failed, partial, cancelled and unfinished steps. A skipped step is NOT retried that way: once its cause is fixed (a CRM connected, a website given), start a new run, optionally only that step: onboarding.build.start {"steps":["<step key>"]}.
5. Walk the missing readiness requirements with the user: each one maps to an earlier screen, a connection, or an open ask. Do not mark the build done while a required requirement is missing without telling the user it is.
6. completeStep build.

The build steps, in run order:

Screen 6 -- First motion and 90 days (plan, launch)

1. Read the plan in onboarding.get (plan.phases, deferred, overCapacity, sized by the hours a week; each item says why it is there, who owns it and what it waits on). The user shapes it with onboarding.plan.set (keys from plan.phases[].items[].key / plan.deferred[].key, play refs from plays.catalog): add, remove, defer with a reason, undefer, order, phase, hours. A play they want that the catalog does not have: request (it runs studio.request as you); a catalog play not installed yet: add with install: true (it ships only after a different person approves it in Studio).
2. onboarding.brief.refresh (readiness checked live + the model's cited summary), then onboarding.brief: give the user the Markdown, or save it where they ask. A withheld section says why (role, scopes); a summary sentence without evidence is never shown.
3. Going live: onboarding.launch.preview says per definition what Launch would sign / promote and per engine what the approved autonomy card allows. Launch (onboarding.launch) is human-only: show the preview and ask the user to click Launch in Setup > First motion (signing is four-eyes: the signer is never the proposer; each promotion is approved by a teammate). Outside Launch you may propose env.promote (rule 7).
4. completeStep plan, then launch. Then summarise: what is live, what waits for whom (approval ids, ask numbers), and the Open items.

The motion and the recommendation loop (GTM OS 0.2.6, check Step 0 first). motion.assess ranks the motions on real counts; motion.decide and motion.change are the person's, so show the ranking and let them record it. After launch, recommendation.generate reads the funnel and proposes at most one recommendation per finding; recommendation.accept, recommendation.dismiss and recommendation.start_mission are the owner's (agent keys are refused). After an accept you may call recommendation.act (a different person approves it) and, later, recommendation.measure. motion.checkpoint (the +30, +60 and +90 day readings) is the person's too: bring the real numbers.

Human-only: what you do instead

Every operation below refuses an agent key with FORBIDDEN: Operation "<name>" can only be performed by a human (the ARR band with its own FORBIDDEN). That is expected, not an error to work around. For each one: do the part you may do (prepare and edit the draft, propose, read the preview), then ask the human to finish it, naming the screen and the button, and record it as an Open item.

Open asks

Every gap becomes a numbered ask with an owner, never a guess: asks.list shows them (number, kind, owner, status). When the owner answers in the conversation, record it with asks.answer and then save the value through the screen's own operation. You answer only the asks you own: for any other, give the answer to the ask's owner (or a member relays it in the console). Report the open asks in every summary.

On an older instance

The setup operations above ship with GTM OS 0.2.5. If gtm_describe does not know one, the instance is older: say which part needs the update, carry on with what exists, and ask an operator to update the instance (console Settings > Updates, or gtm upgrade). Never imitate a missing operation with other writes.