# 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 product intent, incorporating the decisions in the [migration notepad](commandkit-notepad.md). The notepad remains the discussion record. The [Narratio proposal](narratio-feature-request.md) supplies consumer acceptance scenarios for requirements discovery. The [implementation plan](implementation.md) owns the ordered stages and concrete adapter choices. [ADR 0006](../adr/0006-adopt-commandkit-native-operator-interfaces.md) 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](../cli.md), [configuration contract](../config.md), [adapter internals](../internal/adapters.md), and [subprocess contract](../integrations/subprocess.md) 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][upstream-guide]: composition, loading, reusable bindings, reporting, and outcomes. - [CLI reference][upstream-cli]: 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](../policy/architecture.md). 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](../adr/0004-definition-boundary.md). 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 Authority And Native Inspection The migration implements the ownership decision in [ADR 0006](../adr/0006-adopt-commandkit-native-operator-interfaces.md) 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](../adr/0005-configkit-boundary.md). 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. Preserve useful application source and server controls through appropriate selectors. 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. ConfigKit deliberately leaves preset selection and ordering to the application; settle that choice before completing the loader migration. Selection, exhaustion, and selected-file errors remain native ConfigKit behavior. Enable temporary configuration overrides where the loader supports them, passing native override records into loading. Named selectors and `--set` may be combined for nonconflicting paths. ConfigKit owns rejection and diagnostics for duplicate or ancestor/descendant-overlapping override records; `--set` does not supersede named selectors. 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, 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](../../examples/config.discovery.yml) 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 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](narratio-feature-request.md#consumer-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](implementation.md) owns task sequencing, concrete adapter mappings, verification steps, and sprint status. Discovery preset selection and ordering remain to be settled; the selected-format accessor is not a release prerequisite. The [release policy](../policy/release.md#versioning-and-compatibility) 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. [upstream-guide]: https://forge.maximumdirect.net/base-layer/commandkit/src/commit/d330d7637f2e7507eca931a899397222c82bc892/docs/consumers/guide.md [upstream-cli]: https://forge.maximumdirect.net/base-layer/commandkit/src/commit/d330d7637f2e7507eca931a899397222c82bc892/docs/cli.md