Prompt Versioning and Management

Pathrule2 Rules • 2 Memories • 2 Skills

Production prompts are executable behavior, not anonymous strings hidden in handlers or provider dashboards. This bundle gives each prompt an immutable version, typed variables, model and tool contract, ownership, change history, evaluation evidence, staged release, and rollback path. Unlike LLM Evaluations and Testing, it governs the prompt artifact and its deployment lifecycle; evals are one required input to that lifecycle.

Suggested path map

Pathrule places each piece on the matching path, so your assistant only sees it where it belongs. This is the scoping you get on import; you can adjust it in your workspace.

/ workspace root

src/

ai/

prompts/

Published prompt versions are immutable complete artifacts

Prompt compatibility includes callers, tools, and outputs

publish-prompt-version

runtime/

Every generation pins an approved release version

Prompt identity participates in cache and trace identity

rollback-prompt-release

Rules

Published prompt versions are immutable complete artifacts/src/ai/promptshighstrictOne version captures messages, typed variables, model intent, tools, output contract, safety policy, defaults, ownership, and provenance.

1	A prompt is more than its instruction text. Publish an immutable artifact that includes ordered messages or template sections, typed variable definitions, required and optional inputs, model or capability intent, sampling and length settings, tool definitions, output schema, safety and data-handling policy, owner, source revision, and change reason. Never edit a version after it has produced traffic.
2
3	- Validate unknown, missing, empty, oversized, and incorrectly typed variables before provider submission.
4	- Escape or delimit untrusted values according to the prompt's threat model rather than interpolating raw content casually.
5	- Give semantically identical artifacts one stable content identity and semantically different artifacts distinct versions.
6	- Store provider-managed prompt ids as deployment references, not as the only source of the reviewed artifact.
7
8	Verification: Reconstruct an old request from its recorded artifact and inputs; confirm it resolves the same messages, tools, schema, and configuration without consulting mutable latest state.

Every generation pins an approved release version/src/ai/runtimehighstrictRuntime resolves a named release to one immutable prompt artifact and records that version through evaluation, rollout, observation, and rollback.

1	Never let production traffic follow an unversioned latest prompt. A release record points to one immutable prompt version, compatible model and fallback policy, tool implementation versions, output parser, evaluation result, approver, rollout allocation, start time, and rollback target. Runtime resolves the release once per generation and records the chosen identity.
2
3	- Gate promotion on the required offline evals, contract tests, safety checks, and representative manual review.
4	- Roll out by a stable assignment key when comparison or canary traffic requires consistent user experience.
5	- Keep a known-good release immediately restorable without rebuilding or editing the artifact.
6	- Stop or roll back on predefined quality, safety, latency, error, and cost signals rather than waiting for anecdotal reports.
7
8	Verification: Promote, canary, retry, fail over, and roll back a version while traffic is active; confirm every generation maps to exactly one complete approved release.

Memories

Prompt compatibility includes callers, tools, and outputs/src/ai/promptsA text edit can change input assumptions, tool selection, structured output, moderation, localization, caching, or downstream business behavior.

1	Treat prompt compatibility as an interface contract. Identify application callers and their variable shapes, the tool names and argument schemas the model may invoke, output formats and parsers, fallback models, safety filters, localization variants, retrieval context, and downstream effects. A change is breaking when any consumer must change or when the same input can now trigger a materially different side effect.
2
3	Version tool and output contracts explicitly and test prompt-model combinations that production can select. Use migration or dual-read paths when old sessions, cached inputs, queued jobs, or persisted tool calls outlive a release. See /src/ai/runtime for release pinning and /tests/evals for behavioral evidence.

Prompt identity participates in cache and trace identity/src/ai/runtimeSemantic caches, response reuse, traces, costs, feedback, and incidents include the immutable prompt release and relevant runtime configuration.

1	A cache entry created under one prompt can be wrong under the next even when user input is identical. Include the prompt artifact or release identity, model and material settings, tool and output schema versions, retrieval corpus version, safety policy version, and normalized input contract in cache identity according to the feature's semantics.
2
3	Attach the same identities to traces, token and cost records, user feedback, evaluation samples, incident cases, and support views. Preserve privacy by logging references and approved hashes rather than raw sensitive prompt content. This makes regressions attributable and rollback measurable. See the LLM Observability and Tracing pattern for telemetry boundaries.

Skills

publish-prompt-version/src/ai/promptsCreate, validate, evaluate, approve, and stage an immutable prompt artifact with complete compatibility and rollback evidence.

1	---
2	name: publish-prompt-version
3	description: Publish an immutable prompt version with contract, evaluation, approval, rollout, and rollback evidence.
4	---
5
6	# Publish Prompt Version
7
8	1. Diff messages, variables, model intent, settings, tools, output schema, safety policy, retrieval inputs, owner, and affected callers against the active version.
9	2. Classify compatibility and update contract tests, persisted-session handling, caches, parsers, tool implementations, and fallbacks where required.
10	3. Run the required representative, adversarial, safety, deterministic, cost, latency, and model-compatibility evaluations; retain dataset and rubric versions.
11	4. Create the immutable artifact and release record with reviewer, change reason, rollout key, monitoring thresholds, and known-good rollback target.
12	5. Canary the version, compare predefined signals, promote or roll back, and link production evidence to the exact release.
13
14	Do not publish from an editable draft or a passing average that hides a critical regression slice.

rollback-prompt-release/src/ai/runtimeContain a prompt regression, restore a complete known-good release, and preserve evidence for diagnosis and corrected rollout.

1	---
2	name: rollback-prompt-release
3	description: Roll back a prompt release as a complete runtime artifact while preserving incident evidence.
4	---
5
6	# Roll Back Prompt Release
7
8	1. Freeze the affected release ids, assignment keys, time window, models, tools, schemas, retrieval versions, safety policy, metrics, feedback, and representative failing traces.
9	2. Stop further promotion and route new generations to the recorded known-good release without editing either artifact.
10	3. Confirm caches, queued jobs, persisted sessions, fallbacks, and retries cannot continue selecting the bad or an incompatible mixed configuration.
11	4. Verify quality, safety, error, latency, and cost signals recover, then classify affected outputs and any downstream side effects.
12	5. Add the failure to eval and contract coverage, create a new corrected version, and use the normal staged release path.
13
14	Rollback is complete only when every generation can be attributed and mixed-version behavior is excluded.

Why this pattern

Agents edit prompt text in place, forget coupled tools and output schemas, and cannot identify or restore the exact behavior that produced a bad generation.

Built for Teams operating LLM features whose prompts, tools, models, schemas, or policies change independently of application releases.

Keeps your assistant from:

A production output with no identifiable prompt and configuration version
Prompt edits breaking variables, tools, parsers, caches, or fallback models
Rollback restoring text while leaving incompatible model or tool settings active

View as markdown

License: Apache-2.0
Version: 1.0.0
Updated: 2026-08-25