canned-prompts/CannedPromptFormat-v0.1.md

# Canned Prompt Format v0.1

**Status:** Seed specification / experimental  
**Project:** `canned-prompts`  
**Purpose:** Portable packaging of reusable prompts and prompt templates.

## 1. Goals

The Canned Prompt Format (CPF) defines the smallest practical contract for a reusable prompt artifact.

A conforming package should be:

- human-readable;
- filesystem-portable;
- provider-neutral;
- inspectable before use;
- parameterizable where useful;
- versionable;
- extensible with examples, evals, dependencies, and provenance.

CPF v0.1 specifies the **artifact format**. It intentionally does not specify model execution, agent orchestration, dependency resolution, registry transport, or evaluation engines.

## 2. Package layout

The minimum valid package is:

```text
my-prompt/
├── prompt.yaml
└── prompt.md
```

A richer package may contain:

```text
my-prompt/
├── prompt.yaml
├── prompt.md
├── README.md
├── examples/
│   ├── basic.yaml
│   └── edge-case.yaml
├── evals/
│   └── quality.yaml
└── assets/
    └── rubric.md
```

### Reserved paths

| Path | Meaning |
|---|---|
| `prompt.yaml` | Required package manifest |
| `prompt.md` | Default prompt template unless overridden by `template` |
| `README.md` | Optional human documentation |
| `examples/` | Optional examples/fixtures |
| `evals/` | Optional evaluation specifications |
| `assets/` | Optional supporting text/data artifacts |

Tools MUST ignore unknown non-reserved files unless a manifest field explicitly references them.

## 3. Manifest

The canonical manifest is UTF-8 YAML named `prompt.yaml`.

### 3.1 Minimal manifest

```yaml
format: canned-prompt/v0.1
id: review/code-review
name: Code Review
version: 1.0.0
summary: Review a change for correctness and maintainability.
template: prompt.md
```

Required fields are:

- `format`
- `id`
- `name`
- `version`
- `summary`
- `template`

### 3.2 Package identity

#### `format`

MUST be exactly:

```yaml
format: canned-prompt/v0.1
```

for this specification.

#### `id`

A stable, registry-independent logical identifier.

Recommended syntax:

```text
<namespace>/<name>
```

Examples:

```text
review/code-review
engineering/architecture-review
practice/pqrst-estimate
```

Rules for v0.1:

- lowercase ASCII is RECOMMENDED;
- `/`, `-`, `_`, and `.` MAY be used;
- whitespace MUST NOT be used;
- the ID MUST NOT contain `..` path traversal segments;
- `:` MUST NOT be used, so that it remains available as the registry separator
  in a qualified reference (below);
- registry implementations MUST treat the ID as logical metadata rather than an unchecked filesystem path.

##### Identity is registry-scoped

An `id` names a package **within a registry**, the way a path names a file
within a repository. CPF v0.1 does **not** claim that an id is globally unique:
`practice/pqrst-estimate` obtained from two different registries may be two
different packages, and a consumer that draws on more than one registry MUST
keep track of which registry each package came from.

This follows from what the format actually guarantees. A local-first format
with no signing, no federation and no central authority (all explicit
non-goals) cannot enforce global uniqueness, and a guarantee that cannot be
enforced is worse than none — it invites consumers to conflate two packages
that merely share a name.

Where a consumer must distinguish them, a **qualified reference** names the
registry:

```text
<registry>:<id>
```

For example:

```text
house:practice/pqrst-estimate
upstream:practice/pqrst-estimate
```

An unqualified id is acceptable wherever it is unambiguous for that consumer.
A tool that finds the same id in more than one registry MUST report the
ambiguity rather than choosing for the caller.

#### `name`

Human-readable display name.

#### `version`

A package version. Semantic Versioning (`MAJOR.MINOR.PATCH`) is RECOMMENDED and used by the reference implementation.

Behavior-changing edits SHOULD create a new version rather than overwrite a published package.

#### `summary`

A short description of the intended purpose. A consumer SHOULD be able to decide whether a package is potentially relevant from `name` + `summary` alone.

#### `template`

Relative path to the primary prompt template inside the package. The path MUST remain within the package directory.

## 4. Complete v0.1 manifest surface

```yaml
format: canned-prompt/v0.1
id: review/code-review
name: Code Review
version: 1.2.0
summary: >
  Review a change for correctness, maintainability,
  security and test coverage.

type: template
template: prompt.md

inputs:
  - name: change
    type: content
    required: true
    description: The code, diff, or change to review.

  - name: repository_context
    type: content
    required: false
    description: Optional surrounding repository context.
    default:
      derive: context/repository-summary
      value: "(no repository context provided)"

parameters:
  depth:
    type: enum
    values: [quick, normal, thorough]
    default: normal
    description: Desired review depth.

  include_security:
    type: boolean
    default: true

output:
  format: markdown
  description: A structured review with findings and recommendations.

compatibility:
  capabilities:
    - code-analysis
  models: []
  providers: []

dependencies:
  prompts:
    - id: context/repository-summary
      version: 1.0.0
      requirement: generate
  context: []
  capabilities: []

examples:
  - examples/basic.yaml

evals:
  - evals/review-quality.yaml

license: CC-BY-4.0

tags:
  - code-review
  - engineering

provenance:
  author: Example Author
  source: https://example.invalid/original
  derived_from: []

extensions: {}
```

All fields other than the required fields in section 3.1 are optional.

## 5. Prompt template syntax

CPF v0.1 uses deliberately small placeholder semantics:

```text
{{ variable_name }}
```

A placeholder name MUST correspond to either:

- a declared `input`, or
- a declared `parameter`.

Whitespace immediately inside `{{` and `}}` is insignificant.

Examples:

```markdown
Review the following change at {{ depth }} depth.

{{ change }}
```

### 5.1 Resolution and rendering

Producing a final prompt is two steps:

1. **Resolve** — determine a value for every declared input and parameter.
2. **Render** — substitute those values into the template as text.

The steps are separate because only the first may be non-deterministic.
**Rendering is deterministic:** the same resolved values and the same template
always produce the same output. A consumer that satisfies a derived default
(§ 6.1) does so during resolution, never during rendering.

**Resolution rules:**

1. Call-supplied values override defaults.
2. A declared parameter default is used when no call value is supplied.
3. A declared static input default is used when no call value is supplied.
4. A required input without a value is an error.
5. A derived input default is satisfied only by a consumer that is able and
   permitted to derive it. A consumer that does not derive uses the default's
   static fallback `value` when one is declared, and otherwise leaves the
   input unresolved.
6. Resolution MUST report which values were derived, so that a caller can see
   what was added on its behalf before the prompt is used.

**Rendering rules:**

7. Values are substituted as text in v0.1.
8. A placeholder with no resolved value is an error.
9. Template evaluation MUST NOT execute arbitrary code.
10. Rendering MUST NOT derive values. A tool offering derivation MUST perform
    it as a distinct resolve step whose results are visible to the caller
    before rendering.

A minimal implementation may implement resolution for supplied values and
static defaults only. Such a tool is conforming: it reports an input with an
unsatisfied derived default and no static fallback as unresolved, which
rule 8 makes an error.

CPF v0.1 does not define conditionals, loops, filters, or functions. Implementations MAY offer richer rendering modes only when explicitly declared by an extension; they MUST NOT silently reinterpret a v0.1 template as executable code.

## 6. Inputs

`inputs` is an optional ordered list.

```yaml
inputs:
  - name: document
    type: content
    required: true
    description: Document to summarize.
```

Fields:

| Field | Required | Meaning |
|---|---:|---|
| `name` | yes | Placeholder/input identifier |
| `type` | no | Suggested semantic type; defaults to `content` |
| `required` | no | Whether a caller must supply it; defaults to `false` |
| `description` | no | Human-readable explanation |
| `default` | no | Value used when the caller supplies none; see § 6.1 |

Recommended v0.1 input types are:

- `content`
- `text`
- `url`
- `path`
- `json`

These are descriptive hints in v0.1. A runtime MAY use them for validation or adapters.

### 6.1 Input defaults

An input MAY declare a `default`, used when the caller supplies no value.

`default` MUST NOT be combined with `required: true`: a required input is always
supplied by the caller, so a default could never apply.

Without this field an optional input is close to unusable. Rendering rule 8
makes an unresolved placeholder an error, so an input marked `required: false`
and referenced from the template would fail every render in which the caller
omitted it.

A default takes one of two forms.

#### Static default

A literal value, used as-is:

```yaml
inputs:
  - name: repository_context
    type: content
    required: false
    default: "(no repository context provided)"
```

Every conforming implementation supports static defaults.

#### Derived default

A declaration that the value **may** be produced from available context by a
consumer able to do so. It is a request to the consumer, not an instruction the
package executes.

The preferred form references a package already declared in
`dependencies.prompts` with `requirement: generate` (§ 10):

```yaml
dependencies:
  prompts:
    - id: context/repository-summary
      version: 1.0.0
      requirement: generate

inputs:
  - name: repository_context
    type: content
    required: false
    default:
      derive: context/repository-summary
      value: "(no repository context provided)"
```

A derivation prompt MAY instead be written inline:

```yaml
inputs:
  - name: repository_context
    type: content
    required: false
    default:
      derive:
        prompt: |
          Summarize the repository this prompt is being run against,
          in under 200 words.
      value: "(no repository context provided)"
```

`derive` is therefore either a string naming a declared prompt dependency, or a
mapping carrying an inline `prompt`. A single default MUST NOT use both.

Prefer the reference form wherever the derivation is worth keeping. An inline
prompt is anonymous: it has no version, provenance, examples or evals, and
cannot be reused, evaluated or improved independently of its host package —
the situation this format exists to replace. Validators SHOULD warn when a
**published** package derives inline. Inline derivation is intended for local
and draft packages.

`value` inside a derived default is an optional **static fallback**. Its
meaning is defined by resolution rule 5: a consumer that does not derive uses
it, and an input with neither a derived value nor a fallback stays unresolved,
which rule 8 makes an error. Derivation never silently yields empty content.

Declaring a derived default does not oblige any consumer to derive anything,
and does not make the package depend on a particular resolver, model or
runtime. Resolution belongs to the consumer; the package only declares what it
would like resolved.

## 7. Parameters

`parameters` is an optional mapping keyed by parameter name.

Supported descriptive parameter types:

- `string`
- `integer`
- `number`
- `boolean`
- `enum`

Example:

```yaml
parameters:
  tone:
    type: enum
    values: [neutral, friendly, formal]
    default: neutral

  max_items:
    type: integer
    default: 10
```

A tool SHOULD validate enum values. Other type validation is RECOMMENDED but not mandatory for a minimal implementation.

## 8. Output contract

`output` describes the intended result, not an execution protocol.

```yaml
output:
  format: markdown
  description: Concise structured findings.
```

Suggested `format` values include:

- `text`
- `markdown`
- `json`
- `yaml`
- `xml`
- `code`

Registries MAY index output format for discovery.

## 9. Compatibility

`compatibility` records known requirements or observations without binding the package to one runtime.

```yaml
compatibility:
  capabilities:
    - code-analysis
    - long-context
  models:
    - example/model-family
  providers: []
```

Semantics:

- `capabilities`: abstract capabilities expected from the execution environment;
- `models`: model identifiers known to be compatible or evaluated;
- `providers`: provider identifiers when provider-specific behavior matters.

An empty list means "not constrained/unspecified", not "compatible with nothing".

## 10. Dependencies

Dependencies describe external artifacts or capabilities expected by the prompt.

```yaml
dependencies:
  prompts:
    - id: context/repository-summary
      version: 1.0.0
      requirement: optional

  context:
    - id: policy/security
      requirement: required

  capabilities:
    - web-search
```

Recommended requirement values:

- `required`
- `optional`
- `generate`

`generate` means that a resolver MAY satisfy a missing dependency by invoking an appropriate generation process. **CPF v0.1 does not define how generation or dependency resolution works.**

This allows richer systems to integrate prompt resolution without forcing simple tools to implement an agent runtime.

A prompt dependency declared `requirement: generate` is the mechanism behind a
referenced derived default (§ 6.1): the input's `default.derive` names the
dependency, and a consumer able to generate satisfies both at once. Declaring
the dependency records *what* may be generated and at which version; the input
default records *where the result lands*. Neither states how generation works.

## 11. Examples

`examples` is a list of relative paths.

An example file is not normative but SHOULD make intended usage obvious.

Suggested YAML shape:

```yaml
name: basic review
values:
  change: |
    def add(a, b):
        return a + b
  depth: quick
```

Tools MAY render examples directly.

## 12. Evals

`evals` is a list of relative paths to evaluation specifications.

CPF v0.1 deliberately does not standardize a universal evaluation language. Eval files SHOULD therefore declare their own evaluator or schema.

Example:

```yaml
schema: canned-prompts/eval-rubric/v0.1
name: code-review-quality
criteria:
  - identifies correctness risks
  - distinguishes blocking from advisory findings
  - avoids inventing repository facts
```

A registry may associate externally collected run/eval evidence with `<id>@<version>` without mutating the package.

## 13. Provenance and lineage

```yaml
provenance:
  author: Ada Example
  source: https://example.invalid/source
  derived_from:
    - id: review/code-review
      version: 1.1.0
```

The field is descriptive in v0.1. Registries SHOULD preserve provenance when publishing or mirroring packages.

## 14. Licensing

A package MAY declare an SPDX license identifier or other clear license expression:

```yaml
license: CC-BY-4.0
```

Absence of a license MUST NOT be interpreted as permission to redistribute or modify the package.

Tools SHOULD surface licensing metadata during publishing and installation.

## 15. Tags

```yaml
tags:
  - architecture
  - review
  - agentic-coding
```

Tags are free-form discovery hints. Registries MAY normalize or enrich tags while preserving package metadata.

## 16. Extensions

`extensions` is the designated escape hatch for experimental or implementation-specific metadata.

```yaml
extensions:
  org.example.canned-prompts:
    maturity: experimental
```

Extension keys SHOULD be namespaced to avoid collisions.

A consumer MUST ignore unknown extension entries unless it explicitly claims support for them.

## 17. Immutability and versioning

Published `<id>@<version>` pairs SHOULD be immutable.

A registry SHOULD reject publication of a package when the same ID/version already exists with different contents unless an explicit administrative override mechanism exists.

Immutability is scoped to a registry, because identity is (§ 3.2). The same
`<id>@<version>` held by two registries is two packages, and a consumer holding
both is not in a conflict — it is holding two things whose names happen to
coincide. Only a repeat publication *within one registry* violates
immutability.

Suggested versioning guidance:

- PATCH: wording/metadata correction with intended behavior unchanged;
- MINOR: backward-compatible behavior or parameter additions;
- MAJOR: changed contract, renamed/removed inputs, or materially different intended behavior.

This guidance is intentionally advisory because prompt behavior is probabilistic and cannot be versioned as mechanically as an API.

## 18. Package validation

A v0.1 validator SHOULD verify at least:

1. `prompt.yaml` exists and parses as YAML;
2. required manifest fields exist;
3. `format == canned-prompt/v0.1`;
4. `id` is non-empty and contains no path traversal;
5. `version` is non-empty;
6. `template` resolves to a regular file inside the package;
7. referenced example/eval paths do not escape the package;
8. required inputs and parameter names are unique;
9. every template placeholder resolves to a declared input or parameter;
10. no required value is silently omitted during rendering;
11. no input declares both `default` and `required: true`;
12. a derived default declares either a `derive` reference or an inline
    `derive.prompt`, never both;
13. a `derive` reference names a package declared in `dependencies.prompts`.

A validator SHOULD additionally warn when a package intended for publication
declares an inline derivation prompt (§ 6.1).

A validator that is given a **registry** rather than a package SHOULD verify,
when `registry.yaml` is present, that `format` is
`canned-prompt-registry/v0.1`, that `name` is a non-empty string usable in a
qualified reference, and that each `namespaces` entry declares a `policy` of
`open` or `closed`.

## 19. Security requirements

Prompt packages are content, not trusted code.

Implementations MUST NOT:

- execute code merely because it appears in a package;
- treat template expressions as arbitrary code;
- treat a derived default's prompt text as instructions addressed to the
  consuming tool itself; it is content to be resolved on the package's behalf,
  and it carries no more authority than any other package text;
- derive an input default without the caller being able to see that it
  happened (§ 5.1 rule 6);
- interpolate environment variables or credentials implicitly;
- follow paths outside the package without explicit user action;
- embed or require secrets in published package metadata.

Implementations SHOULD:

- inspect all referenced paths for traversal;
- make package contents visible before execution;
- surface provenance and license metadata;
- treat remote content referenced by a package as untrusted input;
- separate package installation from model/tool authorization.

## 20. Registry model

CPF v0.1 does not mandate registry transport.

A valid registry may be:

- a filesystem directory;
- a Git repository;
- an object store;
- an HTTP service;
- a federated catalog.

Conceptually, a registry stores immutable package versions keyed by:

```text
<id>@<version>
```

### 20.1 Registry identity and namespace ownership

A registry MAY declare itself with a `registry.yaml` at its root:

```yaml
format: canned-prompt-registry/v0.1
name: house
description: Internal prompt registry.

namespaces:
  practice:
    owner: Ada Example
    policy: closed
  scratch:
    policy: open
```

Fields:

| Field | Required | Meaning |
|---|---:|---|
| `format` | yes | MUST be `canned-prompt-registry/v0.1` |
| `name` | yes | Short registry name, used in qualified references (§ 3.2) |
| `description` | no | Human-readable explanation |
| `namespaces` | no | Mapping of namespace to its claim |

Within `namespaces`, `owner` is a human-readable claim and `policy` is
`closed` (only the owner publishes) or `open` (anyone may). Both are
descriptive: a filesystem registry has no way to authenticate a publisher, and
authentication, signing and trust scoring are all explicit non-goals.

The file is **optional**. A bare directory remains a valid registry; a consumer
that finds no manifest SHOULD take the registry's name from how it was
addressed — for the reference implementation, the registry directory's
basename.

**Ownership is a property of the registry, not of the package.** A package
never declares who owns its namespace. This keeps the claim where it can
actually be acted on — the registry decides what it admits — and keeps
packages free of unverifiable assertions of authority, consistent with § 19's
position that a package is content rather than a trusted actor. It also means
package semantics do not change when a filesystem registry is later replaced
by a hosted one.

A registry SHOULD refuse to publish into a `closed` namespace it does not
consider the publisher to own. How it decides is registry policy and is
outside this specification.

### 20.2 Consumer-side layout

A consumer drawing on more than one registry MUST keep packages from different
registries distinct, because identity is registry-scoped (§ 3.2). Installing
the same `<id>@<version>` from two registries is not an error and MUST NOT
overwrite: both are retained and addressed by qualified reference.

The reference implementation stores its catalog as:

```text
catalog/
└── <registry name>/
    └── <id path>/
        └── <version>/
```

The reference implementation uses the filesystem layout:

```text
registry/
└── <id path>/
    └── <version>/
        ├── prompt.yaml
        └── ...
```

For example:

```text
registry/
├── registry.yaml
└── practice/
    └── pqrst-estimate/
        └── 0.1.0/
            ├── prompt.yaml
            └── prompt.md
```

A registry's own layout is not namespaced by registry name: within one
registry, an id is unambiguous by definition.

## 21. Reference CLI semantics

The v0.1 reference tool uses two stores:

- **catalog** — packages locally available for search/show/render;
- **registry** — packages available for publish/install.

Commands:

```text
add PATH       validate and copy a package into the local catalog
search QUERY   search locally installed package metadata
show ID        display one installed package manifest
resolve ID     report the resolved value of every input and parameter
render ID      render an installed prompt with supplied values
publish PATH   validate and copy a package into a filesystem registry
install ID     copy a package version from the registry into the catalog
```

Every command that takes an `ID` accepts either a bare id or a qualified
`<registry>:<id>` reference (§ 3.2). A bare id that matches packages installed
from more than one registry is reported as ambiguous, listing the candidates,
rather than resolved by guessing.

`add` takes a package from a path rather than from a registry, so it files the
package under the reserved registry name `local`.

The reference tool never calls a model, so its `resolve` handles supplied
values and static defaults only and reports any input whose derived default it
cannot satisfy. `render` performs the same resolution and then substitutes;
per § 5.1 rule 10 it never derives.

These semantics are illustrative, not mandatory for other implementations.

## 22. Worked example

`prompt.yaml`:

```yaml
format: canned-prompt/v0.1
id: practice/pqrst-estimate
name: PQRST Estimate
version: 0.1.0
summary: Estimate how session effort was distributed across PQRST categories.
template: prompt.md

inputs:
  - name: session_summary
    type: content
    required: true

parameters:
  include_rationale:
    type: boolean
    default: true

output:
  format: markdown

tags: [retrospective, agentic-coding, pqrst]
```

`prompt.md`:

```markdown
Review the following coding-session summary and estimate the distribution of
session effort across PQRST. Percentages must sum to 100%.

P = main problem
Q = quality and tests
R = research and context clarification
S = security and credentials
T = task organization

Session:

{{ session_summary }}

Include rationale: {{ include_rationale }}
```

## 23. Open questions for v0.2+

Experience should determine whether later revisions standardize:

- typed context/dependency contracts;
- content macros;
- prompt composition and inheritance;
- registry namespaces and ownership;
- cryptographic integrity/signing;
- canonical evaluation schemas;
- model capability vocabularies;
- run manifests and evidence formats;
- deterministic compilation manifests;
- trust/reputation signals;
- federated discovery;
- richer template syntax.

Until practical usage forces these decisions, v0.1 should remain intentionally small.