canned-prompts seed

Collect, reuse and share prompts and prompt templates.

This bundle contains a first project seed for canned-prompts:

• INTENT.md — project mission, boundaries, principles, and success criteria.
• CannedPromptFormat-v0.1.md — experimental package-format specification.
• reference/ — deliberately small Python CLI implementing the basic lifecycle.
• examples/pqrst-estimate/ — a real package that can be used to exercise the implementation.

Try the reference implementation

cd reference
python -m venv .venv
. .venv/bin/activate            # Windows: .venv\Scripts\activate
pip install -r requirements.txt

# add the included example to your local catalog
python canned_prompts.py add ../examples/pqrst-estimate

# find and inspect it
python canned_prompts.py search pqrst
python canned_prompts.py show practice/pqrst-estimate

# see how each input and parameter resolves, and where the value came from
python canned_prompts.py resolve practice/pqrst-estimate \
  --set session_summary="Implemented feature X, read unfamiliar code, added tests."

# render it
python canned_prompts.py render practice/pqrst-estimate \
  --set session_summary="Implemented feature X, read unfamiliar code, added tests."

# publish it to the local filesystem registry
python canned_prompts.py publish ../examples/pqrst-estimate

# remove the local catalog if you want to simulate another machine, then install
python canned_prompts.py install practice/pqrst-estimate --version 0.1.0

Packages added from a path are filed under the registry name local; packages installed from a registry are filed under that registry's name. search prints qualified references:

house:practice/pqrst-estimate@0.1.0  PQRST Estimate
local:practice/pqrst-estimate@0.1.0  PQRST Estimate

By default the reference tool uses:

~/.canned-prompts/catalog
~/.canned-prompts/registry

Override them with:

CANNED_PROMPTS_HOME=/some/path

or command-level --catalog / --registry options.

Resolution vs rendering

The format separates the two steps (CannedPromptFormat-v0.1.md § 5.1). Resolution decides a value for every input and parameter and may be non-deterministic; rendering substitutes those values and always is. An input may declare a default that is either a static value or a derived one — a prompt that a capable consumer may run to produce the value, declared without naming any resolver or model.

This reference tool never calls a model, so it resolves supplied values and static defaults only, and reports anything it cannot derive instead of rendering a prompt with a silent hole in it.

Registries and identity

An id names a package within a registry (CannedPromptFormat-v0.1.md § 3.2). The same id obtained from two registries may be two different packages, so the catalog keeps them apart and a bare id that matches more than one is reported as ambiguous rather than guessed. Qualify it when you need to:

python canned_prompts.py render house:practice/pqrst-estimate --set ...

A registry may describe itself with an optional registry.yaml naming it and recording which namespaces are claimed and under what policy. Those claims are descriptive: a filesystem registry cannot authenticate a publisher, and signing and trust scoring are explicit non-goals. Ownership lives with the registry rather than in the package, so no package carries an unverifiable assertion of authority.

Deliberate limitations

This seed has no hosted registry, model execution, authentication, network access, dependency resolver, or social features. publish and install operate on a filesystem registry so that the package semantics can be tested before infrastructure is built around them.