Record CommandKit migration direction and open decisions
This commit is contained in:
206
docs/roadmap/commandkit-notepad.md
Normal file
206
docs/roadmap/commandkit-notepad.md
Normal file
@@ -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
|
||||
Reference in New Issue
Block a user