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;
- registry implementations MUST treat the ID as logical metadata rather than an unchecked filesystem path.

#### `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.

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: []
  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 Rendering rules

1. Call-supplied values override defaults.
2. A declared parameter default is used when no call value is supplied.
3. A required input without a value is an error.
4. A placeholder with no resolved value is an error.
5. Values are substituted as text in v0.1.
6. Template evaluation MUST NOT execute arbitrary code.

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 |

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.

## 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.

## 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.

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.

## 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;
- 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>
```

The reference implementation uses the filesystem layout:

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

For example:

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

## 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
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
```

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.