cargo-cdk

Cargo CDK — declarative workspace-as-code

Use this skill to define a Cargo workspace in TypeScript (define* builders from @cargo-ai/cdk) and reconcile it to live infrastructure with cargo-ai cdk deploy. It is the declarative counterpart to the imperative capability skills: instead of running one CLI command per resource, you write the whole graph once and deploy it repeatably, with a committed cargo.state.json linking your code to what Cargo created.

1) What this skill governs

• Authoring every Cargo resource with a define* builder that returns a

handle; wiring resources by passing handles to each other (the dependency graph is your variable graph).

• Deploying the graph: plan (offline diff) → deploy (create/update, write

state) → destroy (tear down). Plus drift (refresh), adoption (import), and recovery (rollback).

• Typing the config against your workspace's real integration schemas

(cargo-ai cdk types).

The CDK spans every resource kind — so it overlaps every imperative capability skill (cargo-connection, cargo-storage, cargo-ai, cargo-orchestration, cargo-content, cargo-hosting, …). Which to reach for is the first decision:

2) CDK or the CLI? — the routing decision

Declarative (this skill) vs imperative (a capability skill).

Use the CDK when the user is managing resources as an artifact:

• "Set up / stand up / bootstrap a whole workspace (as code / from a template)."
• "Make this reproducible / version-controlled / in git / repeatable across

environments (dev → prod)."

• "Deploy these connectors + models + agents together" (a multi-resource graph

wired by dependency).

• Anything that should be re-runnable and diffable, where losing the definition

would be a problem.

Use the matching capability skill (imperative cargo-ai <domain>) when the user is doing a one-off operation or exploring:

• "Create one connector", "add a column to this model", "list connectors",

"run this workflow", "query storage", "read this agent's memory."

• Any read, ad-hoc query, or single mutation that doesn't need to live in code.

When unsure, ask whether the result should be committed and re-deployable. If yes → CDK. If it's a quick action or a read → the capability skill (see the cargo router to pick the right domain).

3) The lifecycle

cargo-ai cdk init <dir>     scaffold a project from a template (blank | full)
        │
cargo-ai cdk types          generate per-workspace types for typed config (optional)
        │
   (author define* files)   importing a .ts file IS registration — no manifest
        │
cargo-ai cdk plan           offline: compile the graph, diff against cargo.state.json
        │
cargo-ai cdk deploy         create/update resources in dependency order, write state
        │
cargo-ai cdk destroy        tear down resources recorded in state

Side branches: cargo-ai cdk refresh (read-only drift report) · deploy --refresh (re-apply code over out-of-band edits) · deploy --prune (delete resources removed from code) · cargo-ai cdk import <id> <uuid> (bind an existing live resource into state) · cargo-ai cdk rollback (restore the pre-deploy state snapshot).

4) Documentation hierarchy

• Level 1 — SKILL.md (this file): the decision model, lifecycle, critical

rules, and routing.

• Level 2 — Guides:

guides/authoring-resources.md, guides/deploy-and-state.md, guides/typed-config.md.

• Level 2.5 — Recipes: recipes/*.md — step-by-step playbooks to

follow as your execution plan.

• References — references/resources.md (the full

builder catalog), references/commands.md (every cargo-ai cdk subcommand + flags), references/troubleshooting.md, and references/examples/full-workspace.md.

5) Read behavior — match the task to a doc and READ IT

Recipes — follow step-by-step when one matches

6) Critical rules

• Commit cargo.state.json. It is the link from your code to the resources

Cargo created — and the only handle on a deployed play or agent (they have no slug). Lose it and those resources orphan; recover a link with cargo-ai cdk import. It records only {hash, uuid, outputs} — never secret values. Git-ignore the working files (cdk init scaffolds this):

  .cargo-ai/
  cargo.state.lock
  cargo.state.bak.json
  cargo.state.audit.jsonl

• Secrets: wire credentials with secret("ENV_VAR") (often

secret("HUBSPOT_API_KEY")). The value is read from the environment at deploy time, kept out of the content hash and out of state, so rotating a token doesn't read as drift. Export the env var before deploying — a missing one fails the deploy with an unresolved ${ENV_VAR} placeholder.

• Wire by handle, never by .uuid. Pass a define* handle directly

(dataset: hubspot, tools: [enrich]), or xxRef("uuid") for a resource you didn't define in code (connectorRef, modelRef, folderRef, toolRef, agentRef, …). Where a reference needs per-call options, wrap it as { ref, …options } (e.g. models: [{ ref: contacts, readOnly: true }]).

• Run cargo-ai cdk types after workspace integrations change — it

regenerates .cargo-ai/ so defineConnector/defineModel config (and integrations.* in workflow bodies) type-check against the real schemas. Typing is a bonus, never a gate: deploy works without it.

• Run cdk commands from the project root. npx/cargo-ai resolve from the

nearest package.json; run elsewhere and .cargo-ai/ and cargo.state.json land in the wrong directory. Use --dir <path> to be explicit.

• --yes in CI. deploy and destroy prompt for confirmation; non-interactive

runs must pass --yes.

Prerequisites

Standard Cargo CLI setup (install, login, output conventions) is shared across all skills — see ../cargo/references/prerequisites.md.

Two CDK-specific extras:

• The project needs @cargo-ai/cdk as a dependency (for the define*

builders you import). cargo-ai cdk init scaffolds a package.json with it — then run npm install.

• The cargo-ai cdk domain ships with the CLI. Confirm with

cargo-ai cdk --help; an unknown command means the CLI is too old — npm install -g @cargo-ai/cli@latest.

Help

• cargo-ai cdk --help and cargo-ai cdk <subcommand> --help for the live flag

surface.

• When a documented command/flag/response doesn't match what you observe, file a

report: cargo-ai workspaceManagement report create (see ../cargo-workspace-management/SKILL.md).