tegwick
d528e75539
The generated index had drifted from the workplan files. The opt-in lets the pre-commit hook rebuild WORK-RECORDS.md in the same commit as the workplan it indexes. Assistant: grok Assistant-Session: 01a17f9d-fe9d-7d72-9a22-6304f1a2a790
85 lines
3.5 KiB
Markdown
85 lines
3.5 KiB
Markdown
# 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/`
|
|
|
|
## 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.
|