Register with Custodian State Hub and seed format open-questions workplan

Register canned-prompts under agents / practice (topic c1d199b6-55ee-4db6-b49e-257a9f0f15ac, workplan prefix CANP-WP) via `statehub register`, then replace the generated placeholders with repo-specific facts. - SCOPE.md: real boundaries drawn from INTENT.md's deliberate boundary, current state (spec v0.1 + reference CLI, 3/3 tests pass, example round-trips), and the developer workflow. - AGENTS.md: drop the unresolved {CREDENTIAL_ROUTING} template token left by the generator. - CANP-WP-0001: bootstrap tasks closed. - CANP-WP-0002: new workplan carrying the five § 23 open questions promoted from "experience will decide" to "decide for v0.2" — optional-input defaults (static or derived), registry namespaces/ownership, prompt composition, canonical eval schemas, typed context/dependency contracts — plus two reference-implementation conformance defects found in review (prerelease versions sort as newest; copy_immutable packages the whole source directory). Also lands the previously untracked seed: INTENT.md, the CPF v0.1 spec, the reference CLI, and examples/pqrst-estimate. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Bjefh8NUiEiahN4JLwoSKM Assistant: claude-code Assistant-Model: opus Assistant-Process: 388925@bnt-lap001 Assistant-Session: 3507023f-e0fd-4a1e-9d90-a0d4217d1502
2026-09-06 00:45:23 +02:00 · 2026-09-06 00:45:23 +02:00 · dc615ef530
commit dc615ef530
parent 985b41dc87
19 changed files with 2130 additions and 2 deletions
--- a/CannedPromptFormat-v0.1.md
+++ b/CannedPromptFormat-v0.1.md
@ -0,0 +1,640 @@
+# Canned Prompt Format v0.1
+
+**Status:** Seed specification / experimental  
+**Project:** `canned-prompts`  
+**Purpose:** Portable packaging of reusable prompts and prompt templates.
+
+## 1. Goals
+
+The Canned Prompt Format (CPF) defines the smallest practical contract for a reusable prompt artifact.
+
+A conforming package should be:
+
+- human-readable;
+- filesystem-portable;
+- provider-neutral;
+- inspectable before use;
+- parameterizable where useful;
+- versionable;
+- extensible with examples, evals, dependencies, and provenance.
+
+CPF v0.1 specifies the **artifact format**. It intentionally does not specify model execution, agent orchestration, dependency resolution, registry transport, or evaluation engines.
+
+## 2. Package layout
+
+The minimum valid package is:
+
+```text
+my-prompt/
+├── prompt.yaml
+└── prompt.md
+```
+
+A richer package may contain:
+
+```text
+my-prompt/
+├── prompt.yaml
+├── prompt.md
+├── README.md
+├── examples/
+│   ├── basic.yaml
+│   └── edge-case.yaml
+├── evals/
+│   └── quality.yaml
+└── assets/
+    └── rubric.md
+```
+
+### Reserved paths
+
+| Path | Meaning |
+|---|---|
+| `prompt.yaml` | Required package manifest |
+| `prompt.md` | Default prompt template unless overridden by `template` |
+| `README.md` | Optional human documentation |
+| `examples/` | Optional examples/fixtures |
+| `evals/` | Optional evaluation specifications |
+| `assets/` | Optional supporting text/data artifacts |
+
+Tools MUST ignore unknown non-reserved files unless a manifest field explicitly references them.
+
+## 3. Manifest
+
+The canonical manifest is UTF-8 YAML named `prompt.yaml`.
+
+### 3.1 Minimal manifest
+
+```yaml
+format: canned-prompt/v0.1
+id: review/code-review
+name: Code Review
+version: 1.0.0
+summary: Review a change for correctness and maintainability.
+template: prompt.md
+```
+
+Required fields are:
+
+- `format`
+- `id`
+- `name`
+- `version`
+- `summary`
+- `template`
+
+### 3.2 Package identity
+
+#### `format`
+
+MUST be exactly:
+
+```yaml
+format: canned-prompt/v0.1
+```
+
+for this specification.
+
+#### `id`
+
+A stable, registry-independent logical identifier.
+
+Recommended syntax:
+
+```text
+<namespace>/<name>
+```
+
+Examples:
+
+```text
+review/code-review
+engineering/architecture-review
+practice/pqrst-estimate
+```
+
+Rules for v0.1:
+
+- lowercase ASCII is RECOMMENDED;
+- `/`, `-`, `_`, and `.` MAY be used;
+- whitespace MUST NOT be used;
+- the ID MUST NOT contain `..` path traversal segments;
+- registry implementations MUST treat the ID as logical metadata rather than an unchecked filesystem path.
+
+#### `name`
+
+Human-readable display name.
+
+#### `version`
+
+A package version. Semantic Versioning (`MAJOR.MINOR.PATCH`) is RECOMMENDED and used by the reference implementation.
+
+Behavior-changing edits SHOULD create a new version rather than overwrite a published package.
+
+#### `summary`
+
+A short description of the intended purpose. A consumer SHOULD be able to decide whether a package is potentially relevant from `name` + `summary` alone.
+
+#### `template`
+
+Relative path to the primary prompt template inside the package. The path MUST remain within the package directory.
+
+## 4. Complete v0.1 manifest surface
+
+```yaml
+format: canned-prompt/v0.1
+id: review/code-review
+name: Code Review
+version: 1.2.0
+summary: >
+  Review a change for correctness, maintainability,
+  security and test coverage.
+
+type: template
+template: prompt.md
+
+inputs:
+  - name: change
+    type: content
+    required: true
+    description: The code, diff, or change to review.
+
+  - name: repository_context
+    type: content
+    required: false
+    description: Optional surrounding repository context.
+
+parameters:
+  depth:
+    type: enum
+    values: [quick, normal, thorough]
+    default: normal
+    description: Desired review depth.
+
+  include_security:
+    type: boolean
+    default: true
+
+output:
+  format: markdown
+  description: A structured review with findings and recommendations.
+
+compatibility:
+  capabilities:
+    - code-analysis
+  models: []
+  providers: []
+
+dependencies:
+  prompts: []
+  context: []
+  capabilities: []
+
+examples:
+  - examples/basic.yaml
+
+evals:
+  - evals/review-quality.yaml
+
+license: CC-BY-4.0
+
+tags:
+  - code-review
+  - engineering
+
+provenance:
+  author: Example Author
+  source: https://example.invalid/original
+  derived_from: []
+
+extensions: {}
+```
+
+All fields other than the required fields in section 3.1 are optional.
+
+## 5. Prompt template syntax
+
+CPF v0.1 uses deliberately small placeholder semantics:
+
+```text
+{{ variable_name }}
+```
+
+A placeholder name MUST correspond to either:
+
+- a declared `input`, or
+- a declared `parameter`.
+
+Whitespace immediately inside `{{` and `}}` is insignificant.
+
+Examples:
+
+```markdown
+Review the following change at {{ depth }} depth.
+
+{{ change }}
+```
+
+### 5.1 Rendering rules
+
+1. Call-supplied values override defaults.
+2. A declared parameter default is used when no call value is supplied.
+3. A required input without a value is an error.
+4. A placeholder with no resolved value is an error.
+5. Values are substituted as text in v0.1.
+6. Template evaluation MUST NOT execute arbitrary code.
+
+CPF v0.1 does not define conditionals, loops, filters, or functions. Implementations MAY offer richer rendering modes only when explicitly declared by an extension; they MUST NOT silently reinterpret a v0.1 template as executable code.
+
+## 6. Inputs
+
+`inputs` is an optional ordered list.
+
+```yaml
+inputs:
+  - name: document
+    type: content
+    required: true
+    description: Document to summarize.
+```
+
+Fields:
+
+| Field | Required | Meaning |
+|---|---:|---|
+| `name` | yes | Placeholder/input identifier |
+| `type` | no | Suggested semantic type; defaults to `content` |
+| `required` | no | Whether a caller must supply it; defaults to `false` |
+| `description` | no | Human-readable explanation |
+
+Recommended v0.1 input types are:
+
+- `content`
+- `text`
+- `url`
+- `path`
+- `json`
+
+These are descriptive hints in v0.1. A runtime MAY use them for validation or adapters.
+
+## 7. Parameters
+
+`parameters` is an optional mapping keyed by parameter name.
+
+Supported descriptive parameter types:
+
+- `string`
+- `integer`
+- `number`
+- `boolean`
+- `enum`
+
+Example:
+
+```yaml
+parameters:
+  tone:
+    type: enum
+    values: [neutral, friendly, formal]
+    default: neutral
+
+  max_items:
+    type: integer
+    default: 10
+```
+
+A tool SHOULD validate enum values. Other type validation is RECOMMENDED but not mandatory for a minimal implementation.
+
+## 8. Output contract
+
+`output` describes the intended result, not an execution protocol.
+
+```yaml
+output:
+  format: markdown
+  description: Concise structured findings.
+```
+
+Suggested `format` values include:
+
+- `text`
+- `markdown`
+- `json`
+- `yaml`
+- `xml`
+- `code`
+
+Registries MAY index output format for discovery.
+
+## 9. Compatibility
+
+`compatibility` records known requirements or observations without binding the package to one runtime.
+
+```yaml
+compatibility:
+  capabilities:
+    - code-analysis
+    - long-context
+  models:
+    - example/model-family
+  providers: []
+```
+
+Semantics:
+
+- `capabilities`: abstract capabilities expected from the execution environment;
+- `models`: model identifiers known to be compatible or evaluated;
+- `providers`: provider identifiers when provider-specific behavior matters.
+
+An empty list means "not constrained/unspecified", not "compatible with nothing".
+
+## 10. Dependencies
+
+Dependencies describe external artifacts or capabilities expected by the prompt.
+
+```yaml
+dependencies:
+  prompts:
+    - id: context/repository-summary
+      version: 1.0.0
+      requirement: optional
+
+  context:
+    - id: policy/security
+      requirement: required
+
+  capabilities:
+    - web-search
+```
+
+Recommended requirement values:
+
+- `required`
+- `optional`
+- `generate`
+
+`generate` means that a resolver MAY satisfy a missing dependency by invoking an appropriate generation process. **CPF v0.1 does not define how generation or dependency resolution works.**
+
+This allows richer systems to integrate prompt resolution without forcing simple tools to implement an agent runtime.
+
+## 11. Examples
+
+`examples` is a list of relative paths.
+
+An example file is not normative but SHOULD make intended usage obvious.
+
+Suggested YAML shape:
+
+```yaml
+name: basic review
+values:
+  change: |
+    def add(a, b):
+        return a + b
+  depth: quick
+```
+
+Tools MAY render examples directly.
+
+## 12. Evals
+
+`evals` is a list of relative paths to evaluation specifications.
+
+CPF v0.1 deliberately does not standardize a universal evaluation language. Eval files SHOULD therefore declare their own evaluator or schema.
+
+Example:
+
+```yaml
+schema: canned-prompts/eval-rubric/v0.1
+name: code-review-quality
+criteria:
+  - identifies correctness risks
+  - distinguishes blocking from advisory findings
+  - avoids inventing repository facts
+```
+
+A registry may associate externally collected run/eval evidence with `<id>@<version>` without mutating the package.
+
+## 13. Provenance and lineage
+
+```yaml
+provenance:
+  author: Ada Example
+  source: https://example.invalid/source
+  derived_from:
+    - id: review/code-review
+      version: 1.1.0
+```
+
+The field is descriptive in v0.1. Registries SHOULD preserve provenance when publishing or mirroring packages.
+
+## 14. Licensing
+
+A package MAY declare an SPDX license identifier or other clear license expression:
+
+```yaml
+license: CC-BY-4.0
+```
+
+Absence of a license MUST NOT be interpreted as permission to redistribute or modify the package.
+
+Tools SHOULD surface licensing metadata during publishing and installation.
+
+## 15. Tags
+
+```yaml
+tags:
+  - architecture
+  - review
+  - agentic-coding
+```
+
+Tags are free-form discovery hints. Registries MAY normalize or enrich tags while preserving package metadata.
+
+## 16. Extensions
+
+`extensions` is the designated escape hatch for experimental or implementation-specific metadata.
+
+```yaml
+extensions:
+  org.example.canned-prompts:
+    maturity: experimental
+```
+
+Extension keys SHOULD be namespaced to avoid collisions.
+
+A consumer MUST ignore unknown extension entries unless it explicitly claims support for them.
+
+## 17. Immutability and versioning
+
+Published `<id>@<version>` pairs SHOULD be immutable.
+
+A registry SHOULD reject publication of a package when the same ID/version already exists with different contents unless an explicit administrative override mechanism exists.
+
+Suggested versioning guidance:
+
+- PATCH: wording/metadata correction with intended behavior unchanged;
+- MINOR: backward-compatible behavior or parameter additions;
+- MAJOR: changed contract, renamed/removed inputs, or materially different intended behavior.
+
+This guidance is intentionally advisory because prompt behavior is probabilistic and cannot be versioned as mechanically as an API.
+
+## 18. Package validation
+
+A v0.1 validator SHOULD verify at least:
+
+1. `prompt.yaml` exists and parses as YAML;
+2. required manifest fields exist;
+3. `format == canned-prompt/v0.1`;
+4. `id` is non-empty and contains no path traversal;
+5. `version` is non-empty;
+6. `template` resolves to a regular file inside the package;
+7. referenced example/eval paths do not escape the package;
+8. required inputs and parameter names are unique;
+9. every template placeholder resolves to a declared input or parameter;
+10. no required value is silently omitted during rendering.
+
+## 19. Security requirements
+
+Prompt packages are content, not trusted code.
+
+Implementations MUST NOT:
+
+- execute code merely because it appears in a package;
+- treat template expressions as arbitrary code;
+- interpolate environment variables or credentials implicitly;
+- follow paths outside the package without explicit user action;
+- embed or require secrets in published package metadata.
+
+Implementations SHOULD:
+
+- inspect all referenced paths for traversal;
+- make package contents visible before execution;
+- surface provenance and license metadata;
+- treat remote content referenced by a package as untrusted input;
+- separate package installation from model/tool authorization.
+
+## 20. Registry model
+
+CPF v0.1 does not mandate registry transport.
+
+A valid registry may be:
+
+- a filesystem directory;
+- a Git repository;
+- an object store;
+- an HTTP service;
+- a federated catalog.
+
+Conceptually, a registry stores immutable package versions keyed by:
+
+```text
+<id>@<version>
+```
+
+The reference implementation uses the filesystem layout:
+
+```text
+registry/
+└── <id path>/
+    └── <version>/
+        ├── prompt.yaml
+        └── ...
+```
+
+For example:
+
+```text
+registry/
+└── practice/
+    └── pqrst-estimate/
+        └── 0.1.0/
+            ├── prompt.yaml
+            └── prompt.md
+```
+
+## 21. Reference CLI semantics
+
+The v0.1 reference tool uses two stores:
+
+- **catalog** — packages locally available for search/show/render;
+- **registry** — packages available for publish/install.
+
+Commands:
+
+```text
+add PATH       validate and copy a package into the local catalog
+search QUERY   search locally installed package metadata
+show ID        display one installed package manifest
+render ID      render an installed prompt with supplied values
+publish PATH   validate and copy a package into a filesystem registry
+install ID     copy a package version from the registry into the catalog
+```
+
+These semantics are illustrative, not mandatory for other implementations.
+
+## 22. Worked example
+
+`prompt.yaml`:
+
+```yaml
+format: canned-prompt/v0.1
+id: practice/pqrst-estimate
+name: PQRST Estimate
+version: 0.1.0
+summary: Estimate how session effort was distributed across PQRST categories.
+template: prompt.md
+
+inputs:
+  - name: session_summary
+    type: content
+    required: true
+
+parameters:
+  include_rationale:
+    type: boolean
+    default: true
+
+output:
+  format: markdown
+
+tags: [retrospective, agentic-coding, pqrst]
+```
+
+`prompt.md`:
+
+```markdown
+Review the following coding-session summary and estimate the distribution of
+session effort across PQRST. Percentages must sum to 100%.
+
+P = main problem
+Q = quality and tests
+R = research and context clarification
+S = security and credentials
+T = task organization
+
+Session:
+
+{{ session_summary }}
+
+Include rationale: {{ include_rationale }}
+```
+
+## 23. Open questions for v0.2+
+
+Experience should determine whether later revisions standardize:
+
+- typed context/dependency contracts;
+- content macros;
+- prompt composition and inheritance;
+- registry namespaces and ownership;
+- cryptographic integrity/signing;
+- canonical evaluation schemas;
+- model capability vocabularies;
+- run manifests and evidence formats;
+- deterministic compilation manifests;
+- trust/reputation signals;
+- federated discovery;
+- richer template syntax.
+
+Until practical usage forces these decisions, v0.1 should remain intentionally small.