From a0134ea49a6b2de542746a5ff1eb9ed10466a8b3 Mon Sep 17 00:00:00 2001 From: Eric Rakestraw Date: Wed, 18 Nov 2026 18:39:10 +0000 Subject: [PATCH] Document collection discovery in the PromptKit adoption roadmap --- docs/roadmap/promptkit-v0.23.2-adoption.md | 55 +++++++++++++++++++++- 1 file changed, 53 insertions(+), 2 deletions(-) diff --git a/docs/roadmap/promptkit-v0.23.2-adoption.md b/docs/roadmap/promptkit-v0.23.2-adoption.md index 51235aa..b6f4eeb 100644 --- a/docs/roadmap/promptkit-v0.23.2-adoption.md +++ b/docs/roadmap/promptkit-v0.23.2-adoption.md @@ -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.