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

When the task involves…	Read this first	What it gives you
Writing define* files, wiring resources, secret()/env(), defineWorkflow bodies (tool/play logic)	guides/authoring-resources.md	The builder catalog, the handle/ref model, secrets, and how workflow bodies compile.
plan / deploy / destroy, the state file, drift, adopting existing resources, CI	guides/deploy-and-state.md	The deploy lifecycle, cargo.state.json semantics, drift/import/rollback, async builds.
Typed config, cargo-ai cdk types, tsconfig wiring, integrations.* in workflow bodies	guides/typed-config.md	What cdk types generates and how to wire it into your project.
A field/spec/output for a specific builder	references/resources.md	Every builder → spec fields → which ref each takes → outputs.
Exact command flags	references/commands.md	Every cargo-ai cdk subcommand and its flags.
A deploy error / footgun	references/troubleshooting.md	The known failure modes and fixes.

Recipes — follow step-by-step when one matches

Recipe	Use when…
recipes/scaffold-a-workspace.md	Standing up a new workspace from scratch (init --template full → types → plan → deploy).
recipes/add-connector-and-model.md	Adding a data source + a model sourced from it, wired by handle.
recipes/build-an-agent.md	Composing a model + tool + agent (with uses / models / tools) and deploying.
recipes/migrate-existing-workspace.md	Bringing an already-live workspace under CDK management via cdk import.
recipes/deploy-from-ci.md	Deploying non-interactively from CI (token auth + committed state).

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).