Skip to content

Versions and Diagnostics

@meta.syntax declares language syntax, not package, policy, registry, or organization version.

Syntax Versions

VersionAdded capability
1.0.0Core instruction and composition blocks
1.1.0Agents and workflows
1.2.0Few-shot examples
1.3.0Direct regular field replacement with field!
1.4.0Hooks, MCP servers, and plugins
1.5.0Contextual section headers, atomic @override, declaration-order operations, unquoted ${VAR} values
1.6.0Prompt definitions: validated @prompts entries with typed inputs and runtime slots; coding agent targets skip them, bundle and prompt-text compile them

Use the minimum required version for reusable published fragments. Use current syntax for new project entry files.

Operation semantics follow the complete reachable composition graph. An inherited, imported, inline-composed, or extension-carried source declaring 1.5.0 enables declaration order for the graph even when the entry file declares an older version. Inline @use declarations inside @extend bodies are included. PS018 reports that mixed-version requirement; it does not reject the composition.

Upgrade Commands

Terminal window
# Preview all .prs version changes.
prs upgrade --dry-run
# Upgrade syntax declarations using per-file atomic replacement.
prs upgrade
# Find compatibility and shape problems.
prs validate --strict
# Preview generated output and hook migration.
prs compile --dry-run

prs upgrade parses every discovered file before writing, so an initial parse failure aborts the complete plan. Each file then uses atomic replacement and preserves permissions. Multi-file upgrade is not transactional: a write-time failure in a later file does not roll back files already replaced. Symlinks are skipped. Run upgrades on a clean version-control branch.

Prompt Definitions

@prompts entries need syntax 1.6.0. A file that declares an older version and has entries gets a PS018 warning, and prs validate --fix raises the version. PS042 to PS046 check the entries and their {{input.name}} slots, see @prompts. The parser rejects a __proto__ field name in every block, and PS042 rejects the other prototype names. PS045 only runs from 1.6.0, because from that version a {{name}} that nothing bound is reported instead of being printed silently. Fenced code blocks, inline code spans and escaped \{{ are skipped, so documentation of template syntax stays quiet. No target emits prompt definitions.

Policies in promptscript.yaml act on the entries through PS030, located at the entry: a missing governance field, a risk below a risk-floor, a model outside a model-allowlist, or a content check or denied phrase of content-rules. A policies value that is not a list, a policy definition with an unknown kind or key, an unknown role, environment or model, a data class outside governance.dataClasses, or an approval count above 1 is a PS030 error too. With a governance section, PS047 warns on owners and reviewers that are not a Git host identity and on data classes outside governance.dataClasses. See the Policy Engine guide.

PS048 is an error for a second block with the same name in one file, because formatters read only the first block of a name. Same-name blocks from @inherit and @use are merged by name and are not reported. At syntax 1.5.0 and later, @shortcuts followed by @commands in one file is reported; before 1.5.0 the two are merged as aliases.

Model Versions

@meta.syntax does not track AI models. Agent and skill model values resolve against the model catalog configured under models. Floating aliases such as sonnet follow the newest release in the catalog, and the Model Catalog lists every built-in model. PS041 reports pinned models that are deprecated or retired, together with their replacement, models outside models.supported, and inconsistent models.profiles entries. It also reads the model.ref of @prompts entries.

Key Diagnostics

DiagnosticMeaningAction
PS018Used feature requires newer syntaxRun prs validate --fix or prs upgrade
PS019Unknown built-in block nameCorrect typo or confirm custom block intent
PS030Policy from promptscript.yaml not metFix the prompt, skill or policy it names
PS034Invalid hook executable or optionFix command, script, or target override
PS037Invalid contextual section headerFix owner, key, title, or duplicate
PS038Unsupported or risky built-in block shapeConvert to canonical shape
PS041Unsupported model or invalid model profileSwitch model or update models config
PS042Invalid @prompts entry or governance valueFix the entry as the message describes
PS043Undeclared or malformed runtime slotDeclare the input or fix the slot
PS044Declared prompt input is never usedUse the input or remove it
PS045{{name}} left in text (syntax 1.6.0+)Bind it with a parameter or remove it
PS046Runtime slot in the system messageMove the slot to the user message
PS047Owner, reviewer or data class off the configUse a Git host identity or a listed class
PS048Second block with the same name in one fileMerge the blocks into one
PS049Declared skill has no SKILL.md and no contentAdd the SKILL.md next to the declaring project or set content
PS4002Target cannot preserve requested capabilityUse documented target fallback
PS4004Target cannot run or write the modelPick another model or set a target name
PS5001releases missing or invalidAdd releases.environments
PS5002Environment not in releases.environmentsUse a configured environment
PS5003Release bundle or prompt missingRun prs release build or restore the file
PS5004Release file does not verifyRestore it from Git, or run the build
PS5005Promotion skips the previous environmentPromote to the previous environment first
PS5006Git history, base file or ref is not usableCommit the label, fetch base, use a full ref
PS5007Another release command holds the lockWait, then run the command again
PS5008Compile output inside the release directoryPoint the target output elsewhere
PS5009Invalid split, or a split in the first environmentFix the arms, or split in a later environment
PS5010Promote on an entry with a running experimentEnd it with prs release split --end
PS5011Labelled prompt runs a retired or retiring modelMove it to a current model, build and promote
PS5101governance missing or invalid, or no roleFix the section or add the role
PS5102Approval reference, prompt id or hash filter malformedUse <id>@sha256-<64 hex>, a hash filter takes 4+ hex digits
PS5103Approved hash is not built or releasedApprove the hash prs approve --list shows
PS5104Approver is not a user handleUse your handle, like @jane
PS5105Approval record existsDelete it in a commit to withdraw it
PS5106CODEOWNERS not managed by this projectAdd the marker line the message names
PS5107CODEOWNERS owner or path refusedUse Git host identities and plain paths
PS5108Git missing, no repository, shallow history, Git failed or history that does not explain HEADRun it in a full Git checkout with git on PATH, see the releases guide
PS5109Approval record invalid or misplacedFix, move or delete it in a commit
PS5110Invalid --max-weight, or --max-weight without --env or with --all-environmentsGive a percent like 5 or 2.5 with --env and no --all-environments

PS5109 is a warning when prs approve --list reads such a record, or a modified one (its bytes are not the ones Git has) or one with a role that is not in governance.roles. It is an error, with exit code 1, when the path prs approve writes to has a symbolic link, a file where a directory goes, or a name that differs only in case from an existing one.

Release Gate

Terminal window
prs validate --strict
prs compile --dry-run
prs diff --all

Commit syntax upgrades, lockfile changes, source changes, and reviewed generated outputs together according to repository policy.

See Upgrade 1.15 to 1.16 for release-specific migration steps.