Document collection discovery in the PromptKit adoption roadmap

This commit is contained in:
2026-11-18 18:39:10 +00:00
parent 95a94249f1
commit a0134ea49a

View File

@@ -15,7 +15,8 @@ The [definition boundary](../adr/0004-definition-boundary.md) and
The existing CLI and HTTP surfaces should be able to use valid definitions for The existing CLI and HTTP surfaces should be able to use valid definitions for
the selected PromptKit release without copying its schema or maintaining a the selected PromptKit release without copying its schema or maintaining a
narrower application-specific subset. This roadmap covers the changes to narrower application-specific subset. This roadmap covers the changes to
existing surfaces needed for the migration. New CLI capabilities, including existing surfaces needed for the migration and the collection-discovery model
below. New CLI capabilities, including
[Narratio's requirements inspection](narratio-feature-request.md), concrete [Narratio's requirements inspection](narratio-feature-request.md), concrete
request validation, inventory, backend inspection, configuration diffs, and request validation, inventory, backend inspection, configuration diffs, and
smoke diagnostics, are deferred to a separate roadmap. It does not add HTTP smoke diagnostics, are deferred to a separate roadmap. It does not add HTTP
@@ -74,6 +75,34 @@ composition. Scriptorium does not recreate the former catalogs, maintained
profile aliases, or a local implicit profile selection. Bundle availability profile aliases, or a local implicit profile selection. Bundle availability
is not a readiness check or a promise of a fixed provider model. is not a readiness check or a promise of a fixed provider model.
### Independently Maintained Collections
Scriptorium provides a neutral application interface over PromptKit, including
CLI subprocess execution for consumers with limited prompting needs. One
installation may load dozens of collections, each maintained in a separate
Git repository with its own maintainer and update cadence. Operators can place
those checkouts beneath a selected directory and make their prompts available
through the same Scriptorium invocation model.
Use ConfigKit imports in a selected framework source to discover collection
entry files. Establish `collection.yml` and `collection.yaml` as equivalent
Scriptorium conventions for the collection-root entry file, and select both
spellings through the installation's import declarations. Each entry file
declares its own namespace under PromptKit's native `collections` mapping and
uses relative imports to assemble its profiles, prompts, and other definition
files. The checkout directory name does not determine the namespace; callers
select resources by their exact qualified IDs.
The application selects the discovery source through its existing framework
source selection. ConfigKit owns entry-file discovery, relative imports, and
composition; PromptKit owns the resulting collection and resource semantics.
Load the repository entry files rather than treating every YAML file in each
checkout as an independent framework input. PromptKit's `DirectoryInputs`
remains useful for curated configuration trees where all YAML files are
intended contributions. Adding another checkout with a matching entry file
must make that collection available on the next CLI invocation without adding
a per-collection source registration or changing the discovery configuration.
### Existing Commands And Execution ### Existing Commands And Execution
Execution, rendering, and prompt inspection select a prompt by exact ID, Execution, rendering, and prompt inspection select a prompt by exact ID,
@@ -141,6 +170,16 @@ serve the application independently of wire compatibility.
existing application discovery, overlays, and path semantics where still existing application discovery, overlays, and path semantics where still
appropriate; they do not need to change solely to make an old file fail. appropriate; they do not need to change solely to make an old file fail.
Review maintained examples and real-engine test fixtures together. Review maintained examples and real-engine test fixtures together.
- **Demonstrate collection discovery and composition.** Add complete,
copyable assets under `examples/` showing application selection of a
framework discovery file, ConfigKit imports matching both collection-root
filename spellings, and multiple independently namespaced collection
directories. Include a representative collection with multiple profile and
prompt definitions in separate files, relative entry-file imports,
sibling profile inheritance, and qualified prompt-to-profile references.
Supply synthetic input fixtures and offline CLI rendering examples that
exercise the discovery-to-selection flow. Keep the example collections in
the repository so validation does not require cloning external repositories.
- **Adapt the existing interfaces.** Update CLI argument mapping, - **Adapt the existing interfaces.** Update CLI argument mapping,
formatters, captured framework source records and list-index explanation formatters, captured framework source records and list-index explanation
paths, HTTP DTOs, and terminal report projections. Keep explicit zero paths, HTTP DTOs, and terminal report projections. Keep explicit zero
@@ -154,6 +193,13 @@ serve the application independently of wire compatibility.
[consumer migration guide](../consumers/upgrading-promptkit.md) with [consumer migration guide](../consumers/upgrading-promptkit.md) with
before-and-after application and framework examples, directions for old before-and-after application and framework examples, directions for old
prompt versions and catalog references, and the changed CLI contract. prompt versions and catalog references, and the changed CLI contract.
Document the collection entry-file convention and discovery configuration
in the [configuration reference](../config.md), with links to the maintained
examples. Explain the checkout layout and independently managed updates in
[operations](../operations.md), and demonstrate qualified prompt/profile
selection and offline rendering in the [CLI reference](../cli.md).
Distinguish collection-owned namespaces from checkout directory names and
explain how entry-file imports select the collection's internal resources.
Explain semantic changes that can survive a syntactic conversion, Explain semantic changes that can survive a syntactic conversion,
particularly replacement, null fallback, and schema particularly replacement, null fallback, and schema
resolution. Document the new HTTP contract directly in the resolution. Document the new HTTP contract directly in the
@@ -170,7 +216,12 @@ serve the application independently of wire compatibility.
and real-engine adapter tests. Exercise native source composition, and real-engine adapter tests. Exercise native source composition,
qualified selection, source-local resources, captured inspection, qualified selection, source-local resources, captured inspection,
render and execution, and representative failures for obsolete formats render and execution, and representative failures for obsolete formats
and selectors. Protect behavior likely to regress in this cutover: and selectors. Verify both collection entry-file spellings, multiple loaded
collections, relative imports, and discovery of an added collection without
editing the installation's source configuration. Include unrelated YAML
outside the authored import selections to verify that entry-file discovery
does not treat an entire repository as framework configuration.
Protect behavior likely to regress in this cutover:
explicit zero overrides, shared backend admission, timeout attribution, explicit zero overrides, shared backend admission, timeout attribution,
safe output, and unchanged HTTP artifact policy. No live inference is safe output, and unchanged HTTP artifact policy. No live inference is
needed to validate the migration. needed to validate the migration.