Files
scriptorium/docs/roadmap/commandkit-adoption.md

22 KiB

CommandKit Adoption

Status And Intent

Initial roadmap, prepared 2026-11-19. The product direction is agreed; implementation is underway. 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.

Current Baseline And Upstream References

Reviewed Scriptorium baseline: 5f32a4f2adb2d382a6cfce3a787ada4576be7705. The module uses Go 1.27.0, PromptKit v0.23.3, and ConfigKit v1.2.1. CommandKit is not yet a dependency.

Current 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 describe the starting behavior, not a compatibility checklist for this migration.

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:

  1. 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.
  2. Standard inspection exposes that result through native adapters. Scriptorium selects and acquires the requested configuration and declares supported capabilities. Use ckconfig.FromConfigKit for the application result and ckprompt.ConfigScope for PromptKit's captured configuration inspection within the native ckconfig family. 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.