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

21 KiB

CommandKit Adoption

Status And Intent

Initial roadmap, prepared 2026-11-19. The product direction is agreed; implementation has not begun. This document owns the target and implementation sequence, incorporating the decisions in the migration notepad. The notepad remains the discussion record. The Narratio proposal supplies consumer acceptance scenarios for requirements discovery.

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.

Confirm a released dependency combination during implementation. The reviewed ckprompt release declares PromptKit v0.23.2 and ConfigKit v1.2.1; retain Scriptorium's adopted v0.23.3 fixes and verify the combined module graph. Do not infer compatibility merely from successful dependency resolution. Use supported public APIs and released dependencies under the existing architecture policy.

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 processing; PromptKit owns definition parsing, preparation, execution, validation, and domain results. Scriptorium owns application configuration and source selection, application commands, process lifecycle, and artifact delivery.

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 source selectors, server settings, output destinations, 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, 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. Map selections through the application's ConfigKit loader rather than retaining the old flag parser as a compatibility layer. Preserve useful application source and server controls through appropriate selectors.

Enable temporary configuration overrides where the loader supports them, passing native override records into loading. 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, including corresponding application selectors where needed.

Keep the established collection-discovery model: ConfigKit 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. No Git update manager or custom collection traversal is part of this migration.

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 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
No destination flag Main result goes to stdout using the selected format.
--output PATH Main result goes to that file, without duplicate stdout output.
--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 as JSON through CommandKit's renderer, independently of the main format and destination.

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 can select separate output and report paths. The caller manages paths 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. Explicit --output and --report writes are application effects rendered through the writer API and still occur in quiet mode. Quiet does not cancel generation; without requested files it suppresses ordinary result output 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; status 4 is the proposed mapping, avoiding usage status 2 and diff-check status 3. 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.

Use ordinary file operations. During implementation, settle and document overwrite behavior, missing parent directories, destination collisions, and delivery ordering. The recommended starting point is the existing simple file behavior: replace files without creating parents, reject output/report destinations known to name the same file before execution, attempt the main output followed by the report, and attempt the report even if main delivery fails. This adds no rollback, transactional delivery, or stronger filesystem protection. Already delivered output 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. Retaining --run-timeout with Go duration values is a suitable application choice; map it to PromptKit's OperationTimeout and preserve upstream zero, negative-value, and timeout behavior. Finalize that mapping with command help and outcome tests rather than adding 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; generation's --output does not extend the native inspection families.

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.

Implementation Sequence

1. Establish Dependencies And Command Composition

  • Confirm released module versions and public integration APIs; update modules and applicable attribution when dependencies land.
  • Build the CommandKit application with identity/version, standard families, application commands, aliases, and completion declarations. Keep help and declaration construction independent of runtime configuration loading.
  • Inventory existing CLI flags against reusable bindings and application selectors. Resolve spelling collisions in favor of native meanings, using canonical spellings where shorter aliases would be ambiguous.
  • Specify the concrete outcome and deadline mappings described above. Confirm public namespace binding support for the application command; raise any genuine missing shared adapter capability upstream.

2. Adapt Loading And Install Native Inspection

  • Adapt internal/config loading, explicit overrides, diagnostics, and application selection to ckconfig. Inspect the native overlay API mapping and update examples to its selected syntax; do not assume renaming the old flag alone completes adoption.
  • Supply app and PromptKit configuration scopes with native comparisons and independent comparison inputs. Avoid accidentally sharing one side's selected values or cached engine with the other.
  • Compose ckprompt inventories, named inspection, requirements discovery, validation, preparation, and smoke testing through public adapters.
  • Share request construction where applicable, starting from upstream seed values and preserving explicitly supplied values. Keep application-only inspection and early discovery free of execution-only prerequisites.

3. Cut Over Execution And Server Startup

  • Bind run PROMPT_ID through reusable request flags and application selectors; invoke PromptKit using the mapped request and cancellation context.
  • Implement native result reporting, artifact text output, explicit output and report destinations, and selected delivery/outcome handling.
  • Register serve with CommandKit and route its startup diagnostics through native reporting. Retain HTTP limits, restricted artifact reading, shared engine/backend admission state, DTOs, and optional HTTP execution reporting.
  • Complete the full command cutover without exposing legacy compatibility aliases or alternate old report formats.

4. Remove Superseded Code And Update Consumer Guidance

  • Remove obsolete CLI parsing, dispatch, custom config/source projections, definition and prepared presentation, and CLI observer-report wiring. Delete packages only after checking remaining consumers; HTTP still uses internal/report at the baseline.
  • Replace tests tied to deliberately removed behavior with protection for the selected adapter contracts. Retain relevant HTTP and dependency-boundary coverage; avoid copying upstream parser or formatter test matrices.
  • Update canonical CLI, configuration, subprocess, operations, and internal documentation alongside the behavior they own. Update architecture and test ownership descriptions to reflect the new library boundaries. Preserve accepted ADR history under the documentation policy.
  • Update README workflows and maintained examples, including the existing render script and collection workflows, with preferred native aliases.
  • Prepare release migration guidance covering positional prompt selection, command replacements, literal versus file inputs, repeated mappings, overlay selection, endpoint/timeout names, output/report formats and availability, quiet behavior, and exit-status changes. Explain native content-bearing reports and changed inspection presentation.

The release policy governs the eventual breaking release version. Preparing this roadmap does not select or publish a release.

Verification And Completion

Verify the application integration with real library collaborators and deterministic substitutes at provider boundaries. Prioritize these observable scenarios rather than exhaustive upstream behavior matrices:

  • Positional generation and preferred aliases preserve native input mapping, explicit zero/empty values, and independent namespace selection.
  • Multiple imported collections work across execution, preview, discovery, and inspection with consistent applicable selections; app-only inspection works without an engine. Comparison sides remain independent.
  • Default output is the artifact; structured output and separate reports use the native result representation. Format and destination are independent; quiet suppresses console results while requested files are still written.
  • Completed invalid content, operational failures without results, cancellation, and output/report failures produce the selected statuses and useful native diagnostics. Representative partial delivery does not report success.
  • Preview and discovery respect their distinct upstream lifecycles. Narratio's linked scenarios exercise complete, incomplete, and failed discovery.
  • Help, aliases, completion, and smoke-test wiring are reachable through the assembled CLI. Smoke tests use controlled providers in automated checks; live provider tests remain explicitly opt-in.
  • Server startup still reaches the existing HTTP adapter, whose established transport, reporting, restricted-reading, and shared-capacity behavior retains appropriate coverage.

Run the repository's baseline validation for implementation changes: go test ./..., go test -race ./..., go vet ./..., and go build ./cmd/scriptorium, plus formatting, diff, affected example, and documentation-link checks. These checks validate the implementation when it lands; this documentation-only roadmap does not claim the target interface has been built or tested.

Migration is complete when the native command surface and application behavior above are integrated and verified, superseded CLI machinery has been retired, and maintained documentation and examples describe the shipped interface. Use the roadmap for implementation status until those changes land. No significant product decision remains open; dependency confirmation and the ordinary adapter details identified above are implementation work, not reasons to reopen the agreed cutover.