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

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.

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