23 KiB
CommandKit Adoption
Status And Intent
Implementation and assembled acceptance verification are complete; see the implementation plan for evidence and selected releases. Initial roadmap prepared 2026-11-19. This document owns the target and product intent, incorporating the decisions in the migration notepad. The notepad remains the discussion record. The Narratio proposal supplies consumer acceptance scenarios for requirements discovery. The implementation plan owns the ordered stages and concrete adapter choices.
ADR 0006 records the native-interface adoption and ownership boundaries, complementing ADRs 0004 and 0005.
Make Scriptorium a CommandKit-native executable interface over PromptKit, including ckconfig and ckprompt. Most subprocess consumers should be able to select a stored prompt and consume its resulting artifact directly. Operators and consumers needing inspection or metadata should use native upstream interfaces and reports.
This is a full CLI cutover. Existing command names, flag spellings, parsing, report shapes, and exit conventions are not compatibility constraints. Release migration guidance replaces a compatibility layer. Implementation may proceed in reviewable increments; this does not require shipping both interfaces.
Planning Baseline And Upstream References
Reviewed Scriptorium baseline: 5f32a4f2adb2d382a6cfce3a787ada4576be7705.
At that baseline the module used Go 1.27.0, PromptKit v0.23.3, and ConfigKit
v1.2.1, without CommandKit. The following table records the starting point.
| Baseline implementation | Migration work |
|---|---|
internal/adapter/cli dispatches and parses commands, resolves configuration, builds engines and requests, writes diagnostics, and returns integer statuses. |
Replace dispatch and shared CLI mechanics with CommandKit; retain application loading, request mapping, and effects through its extension points. |
run uses flag-based prompt selection and writes generated content; --execution-report writes an observer-derived Scriptorium report. |
Adopt positional prompt selection, native request flags, and native result reporting. |
render, inspect prompt, and inspect profile use custom presentation in internal/format. |
Replace with native ckprompt operations and remove unused presentation code. |
config and inspect configuration separately expose application and framework configuration. |
Install one ckconfig family with app and promptkit scopes, including comparison. |
internal/config owns application schema, discovery, defaults, and conversion through ConfigKit. |
Adapt its loader and explicit overrides to standard selections and scope capabilities. |
serve constructs a restricted HTTP artifact reader and one shared PromptKit engine. |
Register it as an application command and preserve existing HTTP behavior. |
internal/report also supplies HTTP's optional execution report. |
Remove its superseded CLI use; retain functionality still used by HTTP. |
The current CLI, configuration contract, adapter internals, and subprocess contract now describe the implemented native interface, not the historical starting point or a compatibility layer.
The reviewed upstream combination is CommandKit v0.7.0, ckconfig v0.9.0,
and ckprompt v0.10.0, documented at revision
d330d7637f2e7507eca931a899397222c82bc892:
- Consumer guide: composition, loading, reusable bindings, reporting, and outcomes.
- CLI reference: native command grammar and observable behavior.
The selected released combination retains Scriptorium's adopted PromptKit v0.23.3 fixes and ConfigKit v1.2.1. The reviewed ckprompt release's PromptKit v0.23.2 minimum does not require a downgrade. Supported public APIs and released dependencies remain subject to the existing architecture policy.
No selected-format accessor is required for this migration. The native invocation reporter handles the main result on stdout; the existing writer API handles the separate report with automatic or explicitly selected rendering. The upstream accessor proposal remains optional API work, independent of Scriptorium's adoption.
Target End State
Responsibilities And Scope
CommandKit owns command declarations, dispatch, common parsing, help, reporting, and outcome mechanics. ckconfig and ckprompt supply their standard families. ConfigKit owns configuration policy through the fully resolved handoff, including resolution of PromptKit's configuration using PromptKit's schema and rules. PromptKit owns definition, preparation, execution, validation, and inspection semantics. Scriptorium owns the application domain: it interprets resolved values and uses upstream APIs and results to satisfy user requests. Application commands, process lifecycle, and artifact delivery remain local.
This preserves Scriptorium's request-independent execution model and support for valid definitions under ADR 0004. It adds no workflow, conversation, archive, or resume system. HTTP design review remains separate work before v1.0; migrating its startup command does not redesign the HTTP API or its execution-report representation.
Use shared upstream capabilities where available. A concrete missing shared capability should prompt an upstream discussion before a local substitute. Application-specific loading and effects remain ordinary application work.
Command Surface
| Surface | Target |
|---|---|
| Generation | Application command run PROMPT_ID, with a required positional prompt ID and no duplicate prompt flag. |
| HTTP service | Application command serve. |
| Configuration | Native config family with app and promptkit scopes: scope discovery, validation, effective values, sources, explanations, and diff. |
| Resource inspection | Native prompt, profile, backend, namespace, and collection inventories and applicable named inspection. |
| Dependency discovery | Native promptkit requirements show PROMPT_ID. |
| Concrete validation | Native promptkit requirements validate capability. |
| Prepared preview | Native promptkit show prepared PROMPT_ID, replacing render. |
| Provider diagnostics | Native smoke-test commands, invoked explicitly. |
| Executable support | Native help, version, reporting modes, outcomes, and shell completion. |
Install application commands outside the reserved standard families. Enable
the native convenience aliases consistently. Prefer shorter spellings such as
--profile, --input-file, --input-text, and --var in examples and guidance
where applicable and unambiguous; canonical --llm-* spellings remain available.
Aliases retain upstream semantics: --input supplies literal text, and file
references use --input-file.
Reuse applicable ckprompt resource, input, and execution bindings for run.
Preserve explicit-value presence, including zero and empty values, and native
repeated mapping semantics. Do not carry forward comma splitting or obsolete
aliases merely because the old parser accepted them. Keep application-only
controls, including HTTP settings, reporting, and whole-operation deadlines,
distinct from framework request controls.
Completion initially uses native command, flag, static-value, and path completion, with suitable application hints. Dynamic installed-resource completion is not required. Smoke tests are explicit operator operations; their inclusion does not make provider access a startup or release prerequisite. Preserve native diagnostic findings, including successful invocations whose reports describe unsupported or unsuccessful checks.
Configuration Authority And Native Inspection
The migration implements the ownership decision in ADR 0006 through these two boundaries:
- ConfigKit's completed result is authoritative configuration. Scriptorium supplies its schema, domain defaults, validation, and genuine application configuration-resolution logic through ConfigKit's supported extension points. Those callbacks operate within ConfigKit's lifecycle and evidence model, including recording resolution changes through the supported APIs. Scriptorium consumes the completed result without subsequently revising what effective configuration means. Runtime conversion and request construction may consume resolved values; they do not introduce another configuration merge, defaulting, or normalization pass. This follows the configuration boundary established in ADR 0005.
- Standard inspection exposes that result through native adapters.
Scriptorium selects and acquires the requested configuration and declares
supported capabilities. Use
ckconfig.FromConfigKitfor the application result andckprompt.ConfigScopefor PromptKit's captured configuration inspection within the nativeckconfigfamily. Scriptorium does not assemble a different effective document, reconcile separate explanation trees, or reinterpret upstream path semantics. Effective values, sources, explanations, metadata, and comparisons come from the acquired upstream result through those adapters. CommandKit owns their standard presentation.
Application selection and supported configuration overrides feed the loading
lifecycle before its completed result is exposed. Adapting loaders or supplying
scopes below does not authorize a second configuration-resolution or inspection
model. The app and promptkit scopes retain their respective upstream evidence;
they are not combined into a synthetic effective configuration.
Configuration, Collections, And Request Context
Expose application configuration through app and captured framework
configuration through promptkit. Collections are resources within the
framework configuration, not separate configuration scopes. Application-only
inspection must work without constructing a PromptKit engine.
--config selects Scriptorium application configuration on every applicable
command, including framework inspection. That configuration selects framework
sources. Adopt native --overlay selection and upstream selection presence
semantics. For ConfigKit v1.2.1 the supplied value selects an overlay by name,
not an arbitrary file path. Map selections through the application's ConfigKit
loader rather than retaining the old flag parser as a compatibility layer.
Keep HTTP-related named flags on serve. The config family exposes only
upstream commands and flags: add no application selectors or custom
--against-* flags. Retain native --against-config, --against-overlay, and
--against-set where supported. Remove --promptkit-source and --schema-dir
from all commands. Native resource IDs select loaded prompts and profiles;
installation configuration supplies their definitions and schema source.
For implicit application configuration discovery, adopt ConfigKit's built-in
directory presets and their native filename conventions through SearchConfig.
Replace the legacy two-file search. The selected order is WorkingDirectory,
UserConfigDirectory, HomeDirectory, then UnixSystemDirectories, using each preset's native
filename rules. This implements current-directory, user, then system discovery;
the two user presets cover the platform configuration directory and home layout.
ConfigKit selects one main file, with native optional-search exhaustion and
selected-file error behavior; this is not a merge of all discovered files.
Enable temporary configuration overrides where the loader supports them, passing native override records into loading. ConfigKit owns rejection and diagnostics for duplicate or ancestor/descendant-overlapping records. Do not filter or merge conflicts locally. The reviewed PromptKit scope does not support these overrides; do not emulate them locally. Configuration comparison must support independent selections for both sides in both scopes through native flags alone.
Use an application promptkit settings section containing configuration, the
path to one external framework entry file, and schema_dir, the output-schema
root. Replace the general promptkit_sources file/directory list and top-level
schema_dir. Pass the selected file to PromptKit as its native main input with
ConfigKit imports enabled. Keep the bundled upstream defaults.
Keep the established collection-discovery model: that entry file's ConfigKit
glob imports discover collection.yml and collection.yaml entry points; each independently
maintained collection declares its namespace and imports its own definitions
through relative references. Retain the
discovery example and representative
multi-definition collection documentation, updating the application example to
the new settings. No repeated source flag, separate directory-source mechanism,
Git update manager, or custom collection traversal is part of this migration.
Embedding actual PromptKit definitions under the application's promptkit key
is deferred pending suitable upstream support. The current section contains
application settings for acquiring the separate framework document. Do not
extract, reserialize, or reload a resolved application subtree as a substitute
for a native upstream handoff. This deferred capability does not block adoption.
Use native prompt, profile, and backend namespace selectors independently on
applicable commands. Short caller-supplied IDs use their selected namespace;
qualified IDs remain exact. Selection does not rewrite stored references.
Retain upstream inventory filters and defaults, including --all-namespaces.
Do not add a configurable default namespace in this migration.
Share applicable configuration selection, engine loading, and request mapping across execution, preview, validation, and discovery. Preserve each operation's upstream lifecycle: discovery can work before artifacts exist; preparation loads and renders without generation. This is consistency of selection and mapping, not a promise that separate invocations see an immutable snapshot.
Generation, Reports, And Process Outcomes
Use a main CommandKit Report whose value is PromptKit's native RunResult and
whose text template emits only the resulting artifact content. The template
should emit artifact bytes without presentation decoration. Default/text serves raw
artifact consumers; JSON and YAML expose the full native result. The native
structured serialization, including its representation of artifact bytes,
remains upstream-owned. There is no Scriptorium result envelope.
| Selection | Behavior |
|---|---|
| Main result | Goes through the native invocation reporter to stdout using the selected format. |
--format text or default |
Main result contains only the artifact. |
--format json or --format yaml |
Main result contains the native result and metadata. |
--report PATH |
Additionally write the native result through CommandKit's renderer, independently of the main format and destination. Without --report-format, use native automatic rendering. |
--report-format text|yaml|json |
Explicitly select the separate report's native rendering format. |
The separate report contains the same native RunResult, without the main
report's artifact-only text template. Omission of --report-format leaves the
format unset so CommandKit decides how to render it. Its current automatic
rendering for structured values is YAML; future upstream default changes flow
through. Scriptorium does not set a default report format.
There is no --output or legacy --out flag. Callers save the main result by
redirecting stdout in a shell or supplying a file as the subprocess stdout
destination. Diagnostics remain on stderr. Callers wanting main output omit
--quiet, including when stdout is redirected. Filename extensions do not
select formats. The separate report includes the native result's content as
well as metadata; it replaces the CLI's old
observer-derived metadata projection. A caller wanting an artifact file plus
metadata redirects stdout and selects a separate --report path. The caller
manages redirected destinations and retention; there is no automatic reporting
directory or report collection.
Native result reporting is available when PromptKit returns a result.
Operational errors return nonzero status and native failure diagnostics, without
synthesizing replacement results. Preserve PromptKit's distinction between a
completed content check reporting ValidationFailed and an operational failure
to perform the check. Neither extra content judgments nor a structured JSON
invocation-error envelope is part of this migration.
Adopt CommandKit's quiet and verbosity semantics, including rendering and
presentation failures. Console results use the invocation reporter; diagnostics
use its diagnostic channel. --verbose preserves the selected stdout result
and exposes emitted Info and Warning messages on stderr under native rules.
An explicit --report write is an application
effect rendered through the writer API and still occurs in quiet mode.
Quiet does not cancel generation; it suppresses the main result even when
stdout is redirected, while failure explanations remain visible. Move any
retained generation summary into an appropriate native message category.
Map typed upstream failures and configuration diagnostics into native outcomes, without parsing error text. Standard statuses remain upstream-owned. Use an application domain outcome for completed validation failure, distinct from usage and diff-check outcomes. The implementation plan specifies the mapping. Delivery failures must produce a nonzero outcome and explanation, preserving native presentation-failure behavior where applicable, including an already nonzero domain outcome. Requested file errors must not disappear merely because they occur outside the invocation reporter.
For --report, use ordinary file replacement without creating parents. Attempt
the main output followed by the report, and attempt the report even if main
delivery fails. Open the report only when a native result exists. Redirection
and its file-creation or truncation behavior belong to the caller. Scriptorium
does not manage the main output file or check it against the report path. This
adds no rollback or transactional delivery; written bytes may remain after
failure.
Wire signal cancellation through the invocation context. Keep the application
whole-operation budget separate from the native per-attempt timeout binding.
Use --run-timeout with Go duration values mapped to PromptKit's
OperationTimeout, preserving upstream zero, negative-value, and timeout
behavior without a second timeout policy.
Preview And Consumer Inspection
Remove render, its compatibility aliases, defaults.render_format, and
unused prepared-output formatters. Native prepared preview uses its upstream
report, default/text YAML presentation, standard formats, request flags,
diagnostics, and outcomes. It does not call a model. Consumers save preview
output through stdout capture or redirection, as they do for generation.
Adopt native inspection reports, including captured prompt messages and rendered prepared content, without recreating old summary projections. Native schemas and adopted upstream versions govern structured output; this migration adds no separate schema-version wrapper or compatibility guarantee.
Implement the Narratio acceptance scenarios. Requirements discovery exposes native classification, completeness, and issue codes. Complete discovery is distinct from satisfied bindings and execution readiness; partial discovery can succeed with status zero. Narratio owns its pipeline, binding graph, and policy for incomplete findings. Preserve native metadata without inventing prompt versions, variable defaults, or input schemas.
Acceptance And Scope Boundaries
The target is met when Scriptorium exposes the native command surface and application behavior above, superseded CLI machinery is retired, and maintained documentation and examples describe the shipped interface. In particular:
- Configuration callbacks, runtime consumers, and native inspection agree on ConfigKit's completed values and evidence. Application-only inspection needs no PromptKit engine, and comparison sides retain independent selections.
- Applicable selection and request context remain consistent across execution, preparation, discovery, and inspection of multiple independently maintained collections. Their upstream lifecycle differences remain visible.
- Generation defaults to the artifact alone; structured output and separate reports expose the native result. Main output uses stdout and native quiet semantics; the optional report file uses native automatic or explicitly selected rendering, independently of quiet, with useful failure outcomes and nontransactional delivery.
- Narratio's linked acceptance scenarios are supported, including useful partial discovery and discovery before generated artifacts exist.
- Native help, aliases, completion, and explicit smoke testing are available. Including smoke testing adds no provider access prerequisite to startup or release validation.
- Server startup reaches the existing HTTP adapter with its transport, restricted-reading, execution-report, and shared-capacity behavior intact.
- Canonical contracts, examples, dependency attribution, and migration guidance reflect the cutover. The CLI migration includes positional prompt selection, command replacements, literal versus file inputs, repeated mappings, overlay selection, native endpoint/timeout controls, stdout redirection in place of output-file flags, content-bearing reports, optional report-format selection, report availability, quiet behavior, and changed exit statuses.
The implementation plan owns task sequencing, concrete adapter mappings, verification steps, and sprint status. The discovery and source/schema decisions are settled. Neither the selected-format accessor nor embedded framework configuration is a migration prerequisite.
The release policy governs the eventual breaking release version. This migration does not itself select or publish a release, introduce a compatibility layer, or settle the separate pre-v1.0 HTTP design review.