16 KiB
PromptKit v0.23.2 Adoption
Status And Scope
Accepted direction; not yet implemented. Upgrade the existing Scriptorium product in one native cutover. Use the released PromptKit and ConfigKit APIs for framework and configuration mechanisms that they already own. Provide migration guidance for configuration, definitions, and CLI usage, not a second application schema, a legacy definition reader, or compatibility aliases. Refactor the early-beta HTTP API directly, without an HTTP migration or backward-compatibility requirement.
The definition boundary and configuration boundary remain in effect. 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 and the collection-discovery model below. New CLI capabilities, including Narratio's requirements inspection, concrete request validation, inventory, backend inspection, configuration diffs, and smoke diagnostics, are deferred to a separate roadmap. It does not add HTTP operations for those capabilities or introduce continuation, coordination, prepared-handle workflows, or prepared-content capture.
CommandKit adoption (go.maximumdirect.net/commandkit), including the
ckconfig and ckprompt integrations, is planned after this migration and
belongs to a separate roadmap. Its standardized operator interfaces are
expected to replace Scriptorium's current inspection interfaces. This roadmap
keeps those existing commands in maintenance-only scope and adds no
CommandKit dependencies or advance integration scaffolding.
Baseline And Target
The reviewed Scriptorium baseline is
1b1d967fc78e9c514a478b27debf1fadbc772283. It uses
gitea.maximumdirect.net/eric/promptkit v0.12.0. Application configuration
already uses native ConfigKit v1.2.0, but framework inputs, inspection
records, and diagnostics still use old-path ConfigKit v0.5.0. The old
PromptKit module also selects two external catalog modules and go-yaml
v4.0.0-rc.6. Prompt versions are selectors in both executable interfaces and
appear in prepared, inspection, and execution output. The completed
v0.12.0 roadmap records the prior migration.
The target is go.maximumdirect.net/promptkit v0.23.2, commit
382ccfb14b9630fd8f48c8364dbe2b6159637d71, and
go.maximumdirect.net/configkit v1.2.1, commit
51ef3144158db1a09fabdbd1c7ae59908c84923b, with stable go-yaml v4.0.0.
The existing Go 1.27.0 consumer minimum and Go 1.27.4 release toolchain
already satisfy this selection.
- PromptKit release notes
- PromptKit migration guide
- PromptKit framework formats
- PromptKit consumer API guide
- ConfigKit v1.2.1 release notes
Targeted End State
One Configuration Mechanism, Separate Schemas
ConfigKit resolves the application document; Scriptorium owns its schema, defaults, domain rules, source selection, and override mapping. The app uses one native schema and decoder. Existing fields can remain where they still express the right application setting, without a separate legacy mode. PromptKit loads its framework sources separately using the same released ConfigKit types. Application-only configuration inspection still does not construct a PromptKit engine or require framework resources.
Scriptorium selects ordered framework files and directories and supplies them through PromptKit's supported public APIs. The application config file is not itself a framework source. Preserve the application selectors, explicit override behavior, and source grouping where they already map directly to upstream inputs. PromptKit and ConfigKit determine how those inputs compose and how relative framework resources resolve. Scriptorium does not infer namespaces, rewrite IDs, flatten source origins, or supply a second merge policy.
Adopt PromptKit's default OpenRouter bundle as its lowest-priority underlay. Caller definitions remain able to replace bundled records by ordinary 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. When using a
separate glob for each spelling, leave each glob optional (omit
required: true) so either spelling can have zero matches. An installation
using only one spelling still discovers its collections. 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, including a qualified collection ID where appropriate. Remove the CLI version selector and the corresponding version members from the CLI and HTTP request, response, inspection, and report contracts where they exist. Do not accept a legacy version selector and then ignore it.
Keep the existing config and inspect commands functional and accurate
against the selected upstream APIs. Limit inspection work to required import,
API, type, selector, and semantic adaptations. Do not expand capabilities,
redesign command syntax or report presentation, or build reusable inspection
abstractions for the later CommandKit adoption. Necessary output changes should
be the smallest accurate adaptation, with proportionate test and documentation
updates.
Continue to distinguish framework configuration, resolved resources, and request preparation. Framework configuration inspection reports the upstream captured result, with native provenance, normalization, and redaction where currently used. Profile inspection reports the resolved profile, preserving unset versus explicitly supplied values, rather than reconstructing backend-completed settings. Render shows request-completed settings. Reuse existing native writers and make only required adjustments to local inspection projections. Preserve existing disclosure boundaries; captured prompt messages becoming available upstream is not reason to add them automatically to existing prompt inspection output. Adoption of CommandKit's report formats and disclosure behavior belongs to the later roadmap.
PromptKit owns preparation, provider calls, retries, capacity, validation, and repair. Preserve the configured shared server engine and established backend admission behavior. Use PromptKit's native operation timeout for the existing whole-run budget where it can preserve the execution boundary and support the intended CLI and HTTP outcomes. A provider-attempt timeout is still distinct from the whole-run deadline; caller cancellation still applies. Keep the existing context wrapper if delegation would change those semantics rather than introducing two independent timers. CLI process behavior, HTTP decoding, limits, restricted artifact loading, safe diagnostics, and application-owned execution reports remain adapter responsibilities.
HTTP Contract
Serve one ID-only HTTP execution contract. Choose the route, request and
response shapes, and status mapping that best fit the single-run model.
There is no need to preserve POST /v1/runs or to introduce a successor
route solely to signal incompatibility. No HTTP compatibility routes,
legacy payload adapters, or client migration procedures are needed.
Retain operational boundaries such as configured size limits, restricted
artifact access, credential handling, and shared backend admission; these
serve the application independently of wire compatibility.
Work Needed From The Baseline
- Converge the module graph and engine wiring. Move runtime and test imports to the vanity paths. Replace old ConfigKit input, path, provenance, and diagnostic types at the CLI construction and inspection boundaries. Remove the obsolete diagnostic branches and the legacy module and catalog dependencies. Keep distinctions between application and framework error presentation where they remain useful. Use public typed causes and sentinel categories, including for construction, deadlines, and artifact failures. Reconcile commit-pinned attribution and license notices against the resulting runtime graph under the OSS policy, distinguishing linked dependencies from upstream maintainer tooling.
- Migrate maintained configuration and definitions in place. Convert
version-keyed prompts and other keyed resource maps to explicit-ID lists;
choose one definition per ID or give separately selectable former versions
distinct IDs. Convert framework source controls to
config:, writerequired: truewhere a missing import is an error, and use version 2 only where an optional framework source header is supplied. Use siblingextends: {id: ...}and update exact references when using collections. Review same-ID whole-record replacement, backend fallback from null profile fields, self-contained schemas, and source-local message files. Retain 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. Inspection changes are limited to the maintenance-only adaptations above; inspection formatter cleanup, presentation improvements, and CommandKit command standardization are outside this migration. Keep explicit zero overrides and optional-value presence. Check that the restricted HTTP artifact reader transfers ownership of returned artifacts and bytes under the new public contract without changing Scriptorium's containment policy. Preserve established CLI outcomes outside the intentional cutover changes. Validate the HTTP adapter against its new contract and the application boundaries above, not against old wire shapes.
- Give operators a migration path in documentation. Update the consumer migration guide 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, with links to the maintained examples. Explain the checkout layout and independently managed updates in operations, and demonstrate qualified prompt/profile selection and offline rendering in the CLI reference. 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 API reference and update its maintained examples. Update the canonical configuration, CLI, subprocess, and internal references where their implementation changes. For existing inspection commands, correct documentation affected by required API and semantic changes without expanding their operator workflows or documenting future CommandKit behavior as current. Refresh current contributor and architecture references to the selected upstream release, leaving historical release records intact. Record release impact as an intentional incompatible change under the release policy; this roadmap does not select or publish a release.
- Verify the migrated boundary, not a second upstream test suite. Use the repository's baseline Go checks and representative offline examples 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. Verify collection discovery with either entry-file spelling alone and with both spellings across multiple checkouts. Verify 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. Update affected inspection tests to cover required adaptations, accurate optional-value handling, and preserved disclosure boundaries. Reuse existing coverage and keep new inspection checks focused on migration regressions; do not build a broader report or command suite ahead of CommandKit adoption. 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.