# SCOPE

## One-liner

Portable package format, spec and reference CLI for reusable prompt artifacts
(Canned Prompt Format v0.1).

## Core Idea

The valuable unit is not prompt text but a **reusable prompt contract**: a
filesystem-portable, provider-neutral package (`prompt.yaml` + `prompt.md`) that
declares its purpose, inputs, parameters, output, compatibility, provenance and
evidence, and is inspectable before use. See `INTENT.md`.

## In Scope

- `CannedPromptFormat.md` — the package-format specification (revision v0.2).
- `reference/` — a deliberately small Python CLI (`add`, `search`, `show`,
  `render`, `install`, `publish`) over a filesystem catalog and registry.
- `examples/` — real packages that exercise the format and the implementation.
- Format evolution: manifest surface, rendering rules, validation rules,
  registry semantics, provenance and eval hooks.

## Out of Scope

Per `INTENT.md` § Deliberate boundary — canned-prompts standardizes reusable
prompt artifacts, **not agent execution**:

- model execution, routing, billing, or authentication;
- agent runtimes, workflow/orchestration engines, memory systems;
- hosted or federated registries and network transport (v0.1 is filesystem-only);
- dependency resolution, semver range resolution, package signing;
- trust/reputation scoring and social features.

Thin execution adapters are permitted; a general runtime is not.

## Current State

- **Experimental, revision v0.2.** The five open questions promoted from v0.1
  are resolved and specified (`CANP-WP-0002`); what remains deferred is listed
  in § 23. Packages declaring `canned-prompt/v0.1` remain valid.
- The reference CLI implements the full local lifecycle across eight verbs and
  its 81 tests pass. Two example packages (`practice/pqrst-estimate` and the
  `practice/house-style` fragment it composes) round-trip add → search → show →
  resolve → render → eval → publish → install.

## Developer Workflow

```bash
cd reference
python3 -m venv .venv && . .venv/bin/activate
pip install -r requirements-dev.txt

python3 -m pytest -q                        # 81 tests
CANNED_PROMPTS_HOME=/tmp/cp \
  python3 canned_prompts.py add ../examples/pqrst-estimate   # smoke
```

There is no lint or build step yet; `pyproject.toml` declares the
`canned-prompts` console script but the module is normally run directly.

## Getting Oriented

- Intent and principles: `INTENT.md`
- Format specification: `CannedPromptFormat.md`
- Agent instructions: `AGENTS.md`
- Workplans: `workplans/`