Document collection discovery in the PromptKit adoption roadmap
This commit is contained in:
@@ -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 selected PromptKit release without copying its schema or maintaining a
|
||||
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
|
||||
request validation, inventory, backend inspection, configuration diffs, and
|
||||
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
|
||||
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
|
||||
|
||||
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
|
||||
appropriate; they do not need to change solely to make an old file fail.
|
||||
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,
|
||||
formatters, captured framework source records and list-index explanation
|
||||
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
|
||||
before-and-after application and framework examples, directions for old
|
||||
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,
|
||||
particularly replacement, null fallback, and schema
|
||||
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,
|
||||
qualified selection, source-local resources, captured inspection,
|
||||
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,
|
||||
safe output, and unchanged HTTP artifact policy. No live inference is
|
||||
needed to validate the migration.
|
||||
|
||||
Reference in New Issue
Block a user