deploy-cookbook

Deploy a cookbook

This is the procedure every cookbook shares. Each cookbook's own SKILL.md carries what makes it different: the outcome, the questions, the acceptance test, the bill. It does not restate anything below, so read this once and then read the cookbook.

What a cookbook is

A folder of define* CDK resources that combine into one outcome, sitting on a shared base-gtm foundation so two cookbooks stack instead of colliding. Installing one is four moves: scaffold, fit, deploy, verify. The middle move is the one that matters, and it is the reason this is a skill and not a git clone.

Setup

npm install -g @cargo-ai/cli
cargo-ai login --email you@company.com          # sends a code, then exits
cargo-ai login --email you@company.com --code 123456
cargo-ai whoami                                  # already signed in? this confirms it

Confirm which workspace you are pointed at before anything else. A cookbook deployed into the wrong workspace looks like a success and is silently wrong.

1. Scaffold

cargo-ai cdk init <dir> --from getcargohq/cargo-cookbooks/<slug>
cd <dir> && npm install

--from reads cargo.scaffold.json and pulls the cookbook plus its required siblings, transitively, keeping the folder layout so cross-folder imports resolve. base-gtm always comes along. Never hand-copy a folder: you will miss a dependency and the imports will not resolve.

Adding a cookbook to a project that already has one? Scaffold into a temp directory and copy the new folder across. The shared root files and base-gtm are already there.

2. Fit it to the company

Read <slug>/cookbook.json. Its inputs array is the entire list of things that must be answered before this cookbook can deploy. Work it in this order:

Derive before you ask. Every input carrying a derive is a lookup, not a question. Run the lookup first and ask only if it comes back empty or ambiguous. The reason this is a skill rather than a form is that it can go and look: which connector is already authenticated, which models exist, how many closed-won rows there are, what the CRM schema actually contains. If you are asking more than about four questions, you have skipped lookups you should have run.

Then, by kind:

`kind`	What you do
`value`	Patch the answer into the named `file` at `path`. Edit that one value; leave the surrounding code alone.
`generated`	Write the whole `file` from the answers. These are the files whose content is the configuration, like an ICP.
`env`	Tell the operator to set the variable in `.env`. Never read, print, echo or commit the value.
`manual`	Something that must be true outside the repo: a CRM property, an OAuth connection. Check it and report. You cannot write it, and deploying without it produces a run that looks successful and lands nowhere.

Every input carries a why. When the operator pushes back on a question, that is the answer to give them: what breaks if this is wrong. Every input with a validate gets checked before you move on, not after the deploy.

Ask the questions in one pass, not one at a time across several turns. Read the cookbook's README first: it explains why the design is the way it is, and that context is what makes a good answer possible.

3. Plan, then stop

npm run typecheck      # needs `cargo-ai login` then `npm run types` first
cargo-ai cdk plan

Show the plan and stop there. Review it the way you would review a terraform plan: it is the last point at which nothing has happened yet. Deploy only on an explicit yes from the person whose workspace it is.

cargo-ai cdk deploy

Never deploy to production on your own judgement, and never deploy a plan the operator has not seen.

4. Verify

Walk doneWhen from cookbook.json, one line at a time, and report each as pass or fail with the evidence. This is the acceptance test, not a formality: a cookbook that deployed cleanly and produces nothing is the normal failure, because CDK resources reconcile happily whether or not the data behind them is right.

If every check passes on a fresh workspace, say so explicitly. That is half the approval evidence a cookbook needs, and it is recorded in cookbook.json under approval.demoWorkspace by a human, not by you.

5. Record the install

grep -q '"cargo@gtm"' ~/.claude/plugins/installed_plugins.json 2>/dev/null ||
  cargo-ai workspaceManagement session upsert \
    --session-id "${SESSION_ID:-$(date +%s)}" \
    --title "<slug>" \
    --summary "[cookbook: <slug>] Installed via deploy-cookbook."

Installs per cookbook is one of the two numbers the cookbook programme is measured on. The guard skips the stamp when the Cargo GTM plugin is installed, because its session hooks already record the same session and two rows would double-count.

What this skill will not do

Deploy without showing the plan.
Mark a cookbook approved. Approval needs a fresh-workspace test and two customer or partner implementations, and it is recorded by a person.
Claim an outcome for a cookbook whose state is to-be-approved. Every cookbook is to-be-approved until the evidence is in cookbook.json, and most are.
Invent an input that is not in cookbook.json. If the cookbook needs something the file does not list, that is a bug in the cookbook: say so, and add it in a PR rather than papering over it in the session.