canned-prompts/INTENT.md

# canned-prompts — INTENT

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

## Mission

`canned-prompts` exists to make prompts that are worth using more than once easy to package, understand, find, reuse, version, evaluate, and share.

The project treats a reusable prompt as a small software-like artifact with an explicit contract rather than as an anonymous block of copied text.

A canned prompt can therefore carry not only prompt text, but also its purpose, inputs, parameters, expected output, examples, compatibility information, provenance, and quality evidence.

## Core proposition

> **The valuable unit is not prompt text. It is a reusable prompt contract.**

A copied prompt is easy to produce but hard to govern. A reusable prompt should be independently understandable and usable by another human, tool, or agent without requiring hidden knowledge from its author.

## Primary user loop

```text
write
  ↓
package
  ↓
publish
  ↓
discover
  ↓
configure
  ↓
render / invoke
  ↓
observe
  ↓
improve
  ↓
publish a new revision
```

The first implementation should make this loop cheap enough that packaging a useful prompt feels easier than leaving it in an arbitrary notes file.

## Scope

`canned-prompts` owns the **artifact and ecosystem around reusable prompts**.

It should establish:

1. a portable package format for prompts and prompt templates;
2. a catalog/registry model for discovery and distribution;
3. explicit parameters and context requirements;
4. versioning and provenance;
5. examples and evaluation hooks;
6. compatibility metadata for models, tools, agents, or required capabilities;
7. composition metadata for prompts that depend on other reusable prompt/context artifacts;
8. lightweight tooling to add, inspect, search, install, render, and publish packages.

## Deliberate boundary

> **canned-prompts standardizes reusable prompt artifacts, not agent execution.**

The project may provide thin execution adapters for convenience, but it should not become a general agent runtime, workflow engine, model router, memory system, or orchestration framework.

Execution systems should be able to consume canned prompt packages without being forced to adopt a particular agent architecture.

A useful conceptual separation is:

```text
canned-prompts
    |
    | discover / retrieve
    v
PromptPackage / PromptTemplate
    |
    v
resolver / compiler / agent runtime
    |
    v
CompiledPrompt
    |
    v
PromptRun
    |
    v
result + run evidence
```

## Design principles

### 1. Text first

A package should remain readable and editable with ordinary text tools. Markdown plus a small machine-readable manifest is the preferred baseline.

### 2. Portable by default

The package format must not depend on one model provider, IDE, agent framework, or hosted registry.

### 3. Explicit over magical

Inputs, parameters, dependencies, and expectations should be declared where practical. Hidden context is the enemy of reuse.

### 4. Useful before sophisticated

A prompt consisting only of `prompt.yaml` and `prompt.md` should already be a valid package. Examples, evals, dependencies, and richer metadata are progressive enhancements.

### 5. Version prompt behavior

Changes that materially alter intended behavior should create a new package version. Consumers should be able to pin versions when reproducibility matters.

### 6. Preserve provenance

Authorship, source, derivation, and lineage should be representable. Forking and adaptation are expected rather than treated as exceptional.

### 7. Quality should become evidence-backed

Popularity is not the same as quality. The ecosystem should make room for evals, run evidence, model/context compatibility, and adoption signals without requiring them in the minimum package.

### 8. Safe to inspect

Prompt packages must never require embedded secrets or credentials. Consumers should be able to inspect the complete artifact before execution.

### 9. Composition without capture

Packages may declare dependencies on prompts, context generators, policies, or information spaces, but the format should describe those requirements without dictating one resolver implementation.

### 10. Local-first, registry-ready

The first useful implementation should work entirely on a filesystem. Hosted or federated registries can be layered on later without changing the core package semantics.

## Canonical concepts

### PromptPackage

The distributable directory containing a manifest, template text, and optional supporting artifacts.

### PromptTemplate

The reusable prompt text plus its declared substitution/context contract.

### Input

Content supplied by a caller for a specific use, such as source code, a document, or a question.

### Parameter

A named configuration choice that modifies how the prompt behaves, preferably with type, allowed values, and defaults.

### Dependency

Another named artifact or capability that a package expects to be available. Dependency resolution is outside the core package format.

### Example

A small reproducible usage fixture showing representative inputs and/or rendered output.

### Eval

A machine- or human-readable specification for assessing whether the prompt behaves as intended.

### Provenance

Metadata describing origin, authorship, source, derivation, and lineage.

### RunEvidence

Optional external evidence produced by use of a prompt version. Run evidence is not embedded into the immutable package by default, but may be linked to it by registries or evaluation systems.

## Initial capability surface

A minimal reference tool should support:

```text
canned-prompts add <package-path>
canned-prompts search <query>
canned-prompts show <id>
canned-prompts render <id> --set name=value
canned-prompts install <id>
canned-prompts publish <package-path>
```

The reference implementation may use a filesystem-backed local catalog and filesystem-backed registry. Network services are explicitly unnecessary for v0.1.

## Non-goals for v0.1

The first version does **not** need to solve:

- hosted social features;
- model execution or billing;
- autonomous dependency generation;
- semantic version range resolution;
- trust/reputation scoring;
- cryptographic package signing;
- cross-registry federation;
- secrets management;
- universal prompt evaluation;
- a universal agent or workflow specification.

These may become separate modules or later layers if usage demonstrates the need.

## Success criteria for the first practical release

The project is useful when a user can:

1. take a prompt worth keeping and package it in a few minutes;
2. understand an unfamiliar package without reading external documentation;
3. search a local catalog and discover a suitable prompt;
4. render a parameterized prompt deterministically;
5. publish a version to a registry and install it elsewhere;
6. keep multiple versions without destructive overwrite;
7. attach examples or eval specifications without changing the core format;
8. use the package from another tool without importing the reference runtime.

## Evolution hypothesis

If the simple package loop proves useful, `canned-prompts` can evolve from a prompt library into a package ecosystem for reusable cognitive procedures.

A mature feedback loop could be:

```text
PromptPackage
   ↓
Use
   ↓
Run evidence
   ↓
Evaluation
   ↓
Improved package
   ↓
New version
   ↓
Adoption / comparison
```

That later ecosystem should be able to answer questions such as:

- Which prompt versions perform better for a defined task?
- Under which models, contexts, or capabilities?
- Which forks outperform their ancestors?
- Which dependencies reliably improve outcomes?
- When has a prompt's behavior drifted enough to require a new version?

These are long-term opportunities, not reasons to complicate the initial format.

## Working motto

> **Package what is worth prompting twice.**