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

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:

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:

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:

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.