diff --git a/docs/roadmap/commandkit-notepad.md b/docs/roadmap/commandkit-notepad.md new file mode 100644 index 0000000..f53266c --- /dev/null +++ b/docs/roadmap/commandkit-notepad.md @@ -0,0 +1,206 @@ +# CommandKit migration notepad + +Status: discussion in progress. This is the working record for agreeing on +Scriptorium's CommandKit migration before preparing a feature roadmap. It +captures direction, open decisions, and discussion notes; implementation scope +and sequencing will follow once the relevant decisions are settled. + +## Product context + +Scriptorium is a neutral executable interface over PromptKit. Its primary +consumers are applications that need to run stored prompts and consume their +output without importing PromptKit or building an internal prompting workflow. +The CLI and its subprocess contract are therefore central to this migration. + +An installation may load many independently maintained collections. The +existing collection model remains the starting point: ConfigKit imports discover +`collection.yml` or `collection.yaml` entry points, each collection declares its +own namespace, and relative imports assemble its profiles and prompts. See the +[configuration contract](../config.md) and +[discovery example](../../examples/config.discovery.yml). + +HTTP remains secondary to the CLI discussion. A broader HTTP design review is +planned before v1.0; adopting CommandKit does not itself settle that design. + +## Agreed direction + +### Full native cutover + +Decision recorded 2026-11-19: become a CommandKit-native application, including +`ckconfig` and `ckprompt`, and adopt upstream public conventions and +recommendations as fully as possible. + +Backward compatibility with existing CLI conventions is an explicit non-goal. +Legacy command names, flag spellings, parsing rules, report shapes, and exit +semantics do not constrain the new interface. Do not add compatibility wrappers, +legacy aliases, or duplicate inspection implementations solely to preserve the +old CLI. Upstream convenience aliases can be considered on their own merits. + +Provide migration guidance in release documentation so consumers can update +their invocations and output handling. Guidance replaces a compatibility layer; +it does not require a transition period with both interfaces. The +[release policy](../policy/release.md#versioning-and-compatibility) governs +release version selection and documentation of breaking changes. + +### Ownership and integration + +Use CommandKit for command declarations, parsing, help, reporting, and outcomes; +use `ckconfig` and `ckprompt` for their standardized operator interfaces. +Scriptorium should retire the corresponding custom inspection machinery as +those interfaces take over. + +PromptKit continues to own preparation and execution semantics. ConfigKit +continues to own configuration resolution. Scriptorium supplies application +configuration and source selection, generation and server commands, process +lifecycle, and application-specific artifact handling. CommandKit adoption +does not introduce workflow or conversation state. + +Prefer shared upstream capabilities over new Scriptorium-specific equivalents. +If a required shared capability is missing, discuss an upstream request before +designing a local substitute. Application-specific behavior still belongs in +Scriptorium. + +## Upstream baseline + +The initial review covered CommandKit **v0.7.0**, ckconfig **v0.9.0**, and +ckprompt **v0.10.0**. These are a review baseline, not a final dependency choice +for implementation. The [upstream consumer guide][upstream-guide] describes +their composition and supported extension points. + +| Component | Relevant capabilities | +| --- | --- | +| CommandKit | Typed flags and operands with explicit-value presence, generated help and version, shared reporting and outcomes, optional shell completion. | +| ckconfig | Configuration scopes; validation, effective values, sources, explanations, and comparisons; temporary overrides where supported by the loader. | +| ckprompt | Prompt, profile, backend, namespace, and collection inventories; resource inspection; requirements discovery; optional concrete request validation, prepared-request previews, and provider smoke tests. Reusable request flags also serve application-owned commands. | + +Scriptorium currently uses PromptKit v0.23.3 and ConfigKit v1.2.1. The reviewed +ckprompt release declares PromptKit v0.23.2 and ConfigKit v1.2.1. Validate the +chosen dependency combination while retaining Scriptorium's adopted PromptKit +fixes; the older declared minimum is not a reason to downgrade. + +The [upstream CLI reference][upstream-cli] owns the detailed conventions. The +[current Scriptorium CLI](../cli.md) and +[subprocess contract](../integrations/subprocess.md) describe the starting point, +not requirements to reproduce during migration. + +## Open decisions + +### 1 Initial capability set + +The starting proposal is to expose application and PromptKit configuration +scopes, all resource inventories and inspection, requirements discovery, and +concrete request validation through the native integrations. + +Decide whether configuration comparison, provider smoke tests, and shell +completion all belong in the initial migration. Prepared-request preview is +addressed separately below. These capabilities already exist upstream; the +question is initial Scriptorium scope and wiring, not whether to reimplement +them. Provider smoke tests explicitly contact services, and inference tests can +incur model usage. + +### 2 Generation output and process outcomes + +The starting proposal is to keep generated artifact bytes easy to consume, +with execution metadata separately available. CommandKit supports both raw +output and structured reports; using it does not require wrapping generated +artifacts in a report envelope. + +Decide the new generation interface: stdout versus explicit file output, +execution-report delivery, and how those choices interact with standard format +and verbosity controls. In particular, quiet mode suppresses CommandKit output +but does not cancel execution; application-owned file effects need an explicit +design. Ordinary diagnostics should follow upstream reporting conventions. + +Adopt upstream usage and operational outcomes, then decide how to represent +generated-output validation failure as an application domain outcome. The +current use of exit 2 for that failure conflicts with CommandKit's usage and +invalid-configuration convention. Also settle output/report write failures and +how callers distinguish them from generation or validation failures. + +Signal cancellation and the whole-operation deadline remain application +responsibilities. Decide their mapping to the CommandKit invocation context +and PromptKit operation timeout, separately from the standard per-attempt +timeout flag. + +### 3 Prepared-request preview and the existing render command + +Upstream `promptkit show prepared` overlaps Scriptorium's `render` command. +Prefer one preparation path and the native prepared report. + +Decide whether the upstream command fully meets the product need, or whether an +application command still serves a distinct purpose such as artifact-oriented +file output. Retaining the old name or custom report solely for compatibility +is already ruled out. Review associated application defaults, including the +current render-format setting, when deciding the final interface. + +### 4 Configuration selection and namespace experience + +Use consistent application configuration and PromptKit source selection across +generation, inspection, requirements, and previews. Application-only +configuration inspection should not require constructing a PromptKit engine. + +Decide how the standard `app` and `promptkit` configuration scopes are exposed, +how application selectors map into their loaders, and which temporary overrides +are supported. Configuration scope, resource namespace, and profile selection +are distinct concepts and should remain clear to operators. + +For installations with many collections, decide whether to enable the optional +prompt, profile, and backend namespace selectors and how to present the native +namespace-filtered and all-namespace inventory views. Begin with upstream +behavior; identify any unmet collection-navigation need before adding local +conventions. Collection discovery itself does not need redesign for CommandKit. + +### 5 Native reports and executable consumer needs + +Adopt native inspection reports as the starting point. Standard prompt +inspection includes captured prompt messages, unlike the current Scriptorium +summary. Document that change and confirm how native inspection and preparation +reports meet operator needs without rebuilding custom projections. + +Reconcile the proposed [Narratio requirements request](narratio-feature-request.md) +with native `promptkit requirements show`. Its central need remains valid: +discover input requirements before expensive upstream work and before input +files exist. Preserve the distinction between successful discovery and complete +discovery; a successful partial report does not establish all requirements. + +The proposal's legacy syntax and prompt-version assumptions need revision. Its +illustrative versioned JSON envelope and structured-error request also need a +decision: native reports do not add that Scriptorium envelope, and `--format +json` does not automatically turn diagnostics into a JSON error protocol. +Determine which consumer requirements are essential and whether any genuine +gap belongs upstream. Avoid treating the existing proposal as a mandate for a +new compatibility facade. + +Keep discovery distinct from concrete request validation: validation prepares a +real request and may read input artifacts and check relevant credentials; +discovery must work before those artifacts exist. Neither guarantees a future +generation will succeed. + +### 6 Application commands and standard request flags + +Decide the final generation command operands and application-specific flags +around the reusable ckprompt request flag groups. Use their standard names, +value-presence behavior, and parsing semantics wherever applicable. + +Migration guidance will need to explain changes such as separate literal-text +and file-input flags, endpoint and timeout naming, and repeated mapping values. +In particular, upstream's optional `--input` alias denotes literal text, while +Scriptorium's existing flag denotes a file. Choose any upstream convenience +aliases deliberately and document the new meanings; preserving old meanings +is not a design requirement. + +## Continuing the discussion + +Record discussion notes under the relevant open decision. When a choice is +settled, move its conclusion and rationale into the agreed direction with its +decision date, and remove superseded alternatives. Add new questions when a +concrete product need emerges. + +Once the command surface, consumer outputs and outcomes, loader and namespace +behavior, and any upstream gaps are settled, fold the decisions into a feature +roadmap. That roadmap will define implementation sequence, removal of replaced +CLI code, appropriate validation, and migration documentation. This notepad does +not prescribe implementation phases or treat the open proposals as commitments. + +[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