Prompt versioning and rollout

Migrating an existing prompt

Start with one prompt, not all of them.

npx cloudmind prompts create support-summary --from ./prompts/support-summary.txt

Then declare its variables so a missing field fails loudly:

const prompt = await cloudmind.prompts.get("support-summary", {
  label: "production",
  requires: ["ticket", "tone"],
});

If the production revision does not declare both variables, this throws at startup rather than silently rendering a broken prompt.

Labels and environments

Labels are pointers to revisions. The usual set:

Label	Points at	Who can move it
development	Latest revision	Anyone
staging	Candidate	Anyone
production	Live	Requires approval

Deploying a prompt means moving the production label. There is no code change and no deploy.

Review gates

Under Settings → Prompts, require approval for the production label. A named reviewer must approve before the label can move, and the approval is recorded in the audit log.

This is what makes it safe to give prompt access to people who cannot ship code.

Gradual rollout

Split traffic between the current and candidate revisions:

const prompt = await cloudmind.prompts.get("support-summary", {
  label: "production",
  splitKey: session.id,
});

splitKey keeps a given user on one arm for the duration of the rollout. Without it, a user can flip between revisions mid-conversation, which reads as incoherent.

Set the percentage in the prompt editor, watch the eval score per arm, then ramp or revert.

Rollback

npx cloudmind prompts rollback support-summary --to v13

Takes effect within the SDK cache TTL, which defaults to 60 seconds. No deploy.

Handling breaking changes

When a prompt change requires a code change, do it in two steps:

1. Pin the code to an explicit revision: cloudmind.prompts.get("x", { revision: 14 }). Ship it.
2. Move the production label to revision 14. Remove the pin on the next deploy.

This keeps the prompt and code changes atomic without giving up the registry.