canned-prompts/README.md

# canned-prompts seed

> **Collect, reuse and share prompts and prompt templates.**

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

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

## Try the reference implementation

```bash
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:

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

By default the reference tool uses:

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

Override them with:

```text
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:

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