canned-prompts/SCOPE.md

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

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/

Generated work-record index

This repository opts into staged-source WORK-RECORDS.md generation through .generated-work-records.json and the isolated .generated-work-records.mk recipe. make generated-work-records reuses the State Hub renderer through the Custodian adapter; make generated-work-records-check verifies byte-exact agreement with staged Markdown. The pre-commit hook uses the isolated recipe, preserves unstaged index edits by refusing them, and retains the generated-only commit guard. It does not contact the hub, alter workplan statuses, or grant deployment authority. This consumes shared tooling; it does not make this repository the provider of the generator capability.

Local orientation brief policy — 2026-10-21

.custodian-brief.md is a local, ignored State Hub orientation snapshot. Refreshing it does not require a Git commit. Authored workplans and the generated WORK-RECORDS index keep their existing source and staged-generation contracts.