stackbone prompts

stackbone prompts targets a running agent installation. With no --agent it runs against the local-dev installation linked to the current project, so stackbone dev must be running. See target resolution. Every verb but list also needs the owner of the prompt, as --owner-kind plus --owner-name. remove, remove-version, publish and unpublish are destructive verbs that refuse to run without --yes. Every verb emits the shared JSON envelope under --json.

Manage the versioned prompt catalog on the targeted installation. Writing and publishing are two steps. Each key holds an append-only chain of immutable versions and exactly one of them is PUBLISHED: the one the agent reads. update writes a version that does not run yet; publish points the prompt at a version that already exists, so going back to v3 makes the prompt read v3 rather than a copy of its text under a new number. You cannot delete a published version, or the prompt holding it, until you unpublish. This is the catalog the agent reads at runtime through stackbone.prompts.

Every prompt has an owner

A prompt belongs to one workflow or one deep agent, never to the workspace at large. The owner plus the key is the prompt's identity, so two owners can hold the same key and they are two prompts, with their own text and their own history. Every verb but list requires both owner flags, and neither has a default: a guessed owner reads or writes a prompt you never named.

Flag	Value
`--owner-kind <kind>`	`workflow` or `agent`. Any other value is refused before the request leaves your machine.
`--owner-name <name>`	Name of the workflow or deep agent that owns the prompt, up to 200 characters.

list is the one read that spans owners, which is why it takes neither flag.

Command	Purpose
`stackbone prompts list`	List every prompt of every owner at its published version (up to 200, ordered by owner, then key).
`stackbone prompts get <key>`	Print a prompt (the published version, or a pinned `--version <n>`).
`stackbone prompts create <key>`	Register a prompt at version 1, published. Content via `--template`, `--file` or stdin; `--name` required.
`stackbone prompts update <key>`	Write a version and/or patch the head. The new version does NOT run until `publish`.
`stackbone prompts publish <key> --version <n>`	Make an existing version the one the agent runs. It points at that version, so nothing is copied. Requires `--yes`.
`stackbone prompts unpublish <key>`	Take the prompt out of service. History stays; nothing runs until you publish again. Requires `--yes`.
`stackbone prompts versions <key>`	List a prompt's version history (newest first, up to 200), marking the published one.
`stackbone prompts remove-version <key> --version <n>`	Delete one version from the history. Refused for the published one. Requires `--yes`.
`stackbone prompts remove <key>`	Soft-delete a prompt. Refused while it publishes a version, so unpublish first. Requires `--yes`.
`stackbone prompts preview <key>`	Server-side compile the prompt against a `--vars <file.json>`; reports a missing `{{var}}` cleanly.

Write, then publish

# Register the first version. It is published straight away.
stackbone prompts create welcome_email \
  --owner-kind workflow --owner-name onboarding \
  --name "Welcome email" --template "Hi {{name}}, welcome aboard."

# Write a second version. The agent still runs v1.
stackbone prompts update welcome_email \
  --owner-kind workflow --owner-name onboarding \
  --file ./prompts/welcome-v2.txt

# Compile it before it goes live.
stackbone prompts preview welcome_email \
  --owner-kind workflow --owner-name onboarding \
  --version 2 --vars ./vars.json

# Point the prompt at v2.
stackbone prompts publish welcome_email \
  --owner-kind workflow --owner-name onboarding \
  --version 2 --yes

JSON payload

// prompts list: every row names its owner, because the list spans owners
{ "schema_version": 1, "items": [
  { "ownerKind": "workflow", "ownerName": "onboarding", "key": "welcome_email",
    "publishedVersion": 3, "latestVersion": 4, "name": "Welcome email",
    "content": "Hi {{name}}, welcome aboard.", "variables": ["name"] }
] }

// prompts preview: a missing variable is a clean result, not an error
{ "schema_version": 1, "ok": true, "version": 3, "output": "Hi Ada", "missingVar": null }

// the same call when {{name}} has no value: ok is false, output is null
{ "schema_version": 1, "ok": false, "version": 3, "output": null, "missingVar": "name" }

// nothing published and no --version pinned: there was no text to compile
{ "schema_version": 1, "ok": false, "version": null, "output": null, "missingVar": null }

publishedVersion is the version that runs and latestVersion is the newest one anyone wrote, so a draft waiting to go live shows up as the two numbers differing. Both are null on a prompt with no versions left. A read resolves content from the published version, or from the one --version pins; it is null when nothing is published, which is a different answer from the prompt not existing.

A prompt key is unique per owner and URL-safe: lowercase, starting with a letter, then letters, digits, _ or -, up to 128 characters (welcome_email, tool-describe-orders). Content is capped at 256 KiB.

--template and --file are mutually exclusive. On update, pass at least one field. create also takes an optional --description and --metadata. Like get, preview accepts a pinned --version <n> and compiles the published version when you omit it.

A template uses the {{var}} Mustache subset only: no conditionals, no loops, no helpers. That is the same engine the agent compiles with through stackbone.prompts.compile, so a preview here matches what the agent renders.

Exit codes: 0 ok · 4 not found (unknown key/version) · 5 permission (remove/remove-version/publish/unpublish without --yes) · 1 generic (a missing or unknown --owner-kind/--owner-name, missing --name/content, bad --metadata JSON, unreadable --file/--vars, non-integer --version). See exit codes.