333 lines
18 KiB
Markdown
333 lines
18 KiB
Markdown
# CommandKit migration notepad
|
|
|
|
Status: design direction agreed; ready for feature-roadmap preparation. This
|
|
working record captures the decisions for Scriptorium's CommandKit migration.
|
|
The remaining integration details below belong in the roadmap alongside
|
|
implementation sequencing and validation.
|
|
|
|
## 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. Adopt upstream convenience aliases as described below.
|
|
|
|
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.
|
|
|
|
### Initial capability set
|
|
|
|
Decision recorded 2026-11-19: include configuration comparison, provider smoke
|
|
tests, and shell completion in the initial migration, alongside application and
|
|
PromptKit configuration scopes, resource inventories and inspection,
|
|
requirements discovery, concrete request validation, and prepared-request
|
|
preview.
|
|
|
|
Use the existing upstream capabilities. Configuration comparison should cover
|
|
both application and PromptKit scopes, with independent selections for each
|
|
side. Provider smoke tests run when explicitly invoked; including them does not
|
|
make them startup checks or release prerequisites. Document provider usage and
|
|
the distinction between successful diagnostic execution and positive findings.
|
|
Shell completion should use upstream command, flag, static-value, and path
|
|
completion, with appropriate hints for application-owned inputs. Dynamic
|
|
completion of installed resource names is a separate possible enhancement.
|
|
|
|
Application-specific wiring remains to be designed, but inclusion of these
|
|
capabilities is settled. The prepared-request preview decision is recorded below.
|
|
|
|
### Generation and subprocess requirements
|
|
|
|
Decision recorded 2026-11-19: optimize the default generation response for the
|
|
majority of consumers, who want only the raw resulting artifact. Metadata is
|
|
optional and available through the native result reporting choices below.
|
|
|
|
Prefer native CommandKit reporting and PromptKit result types before introducing
|
|
a Scriptorium-specific response format. A failure must produce a nonzero process
|
|
status and information explaining the failure. This does not require a new
|
|
structured error envelope: native diagnostics are an acceptable way to deliver
|
|
that information.
|
|
|
|
Scriptorium remains a neutral interface to PromptKit. Pass through the errors,
|
|
validation outcomes, and result information that PromptKit supplies rather than
|
|
adding independent judgments about generated content or redefining upstream
|
|
failure semantics. Adapting those outcomes to CommandKit and process exit codes
|
|
is application work; deciding what constitutes a PromptKit failure is not.
|
|
|
|
### Native result reporting and separate report files
|
|
|
|
Decision recorded 2026-11-19: use a CommandKit `Report` containing PromptKit's
|
|
native `RunResult`, with a text template that emits only generated content.
|
|
Default/text output serves artifact consumers; standard JSON/YAML formats expose
|
|
the native result and its metadata. This composes existing upstream APIs;
|
|
ckprompt does not supply a general generation command or prescribe this template.
|
|
|
|
Include an optional `--report PATH` flag requiring an explicit file destination.
|
|
Omitting it creates no separate report file. When requested, save the native
|
|
result as JSON through CommandKit's renderer, using the same representation as
|
|
inline JSON reporting. The report file's format is JSON independently of the
|
|
main result's `--format`; requesting a report does not change the main result's
|
|
representation or destination.
|
|
Failure to write a requested report is a delivery failure and must produce a
|
|
nonzero outcome and diagnostic.
|
|
|
|
Do not include a configured reporting directory or automatic report collection
|
|
in the initial migration. The caller selects the report path and manages its
|
|
lifecycle. A configured directory may be considered later if automatic
|
|
collection becomes useful; an explicit report path would take precedence.
|
|
|
|
Native result reports are available when PromptKit returns a result. Operational
|
|
failures produce a nonzero exit and native diagnostics. This follows PromptKit's
|
|
capabilities and is the intended boundary, not a gap for Scriptorium to address.
|
|
Do not synthesize replacement results or add an alternative failure-report
|
|
format to compensate for the absence of a native result.
|
|
|
|
### Output destinations and verbosity
|
|
|
|
Decision recorded 2026-11-19: use `--output PATH` for the main result's file
|
|
destination. Without it, the main result goes to stdout. With it, the selected
|
|
representation goes to the file without duplicate stdout output. Use the
|
|
spelling `--output`, with no legacy `--out` compatibility alias.
|
|
|
|
`--format` selects the representation independently of the destination:
|
|
default/text emits the raw artifact, while JSON/YAML emits the native result
|
|
with metadata. The filename does not select the format. `--report PATH` remains
|
|
an additional native JSON report, so callers can save the raw artifact and its
|
|
report to separate files.
|
|
|
|
Adopt CommandKit's upstream verbosity and `--quiet` semantics fully, including
|
|
mode selection, message visibility, rendering, and presentation failures. Do
|
|
not add Scriptorium-specific exceptions to normal command-output suppression.
|
|
Quiet mode does not cancel generation, and failure explanations remain visible
|
|
through the native diagnostic channel.
|
|
|
|
Explicitly requested `--output` and `--report` writes are application-owned file
|
|
operations and still occur in quiet mode. Render those files through CommandKit's
|
|
writer API; the invocation reporter governs console output. This follows the
|
|
upstream distinction between reporting visibility and application effects.
|
|
With quiet mode and no requested files, generation still runs while ordinary
|
|
result output is suppressed. The [upstream reporting contract][upstream-cli]
|
|
owns the shared verbosity rules.
|
|
|
|
### Prepared-request preview
|
|
|
|
Decision recorded 2026-11-19: replace `render` entirely with the native
|
|
`promptkit show prepared PROMPT_ID` command, enabled through ckprompt's request
|
|
preparation integration. Remove `render` without a compatibility alias.
|
|
|
|
Use the native prepared-run report, standard request flags, diagnostics,
|
|
verbosity, and outcomes. Default and explicit text output use the upstream YAML
|
|
presentation; JSON remains available through `--format json`. Remove
|
|
`defaults.render_format` and any custom prepared-output formatting code left
|
|
unused by the migration.
|
|
|
|
Share application configuration selection, collection loading, and applicable
|
|
request construction with generation so previews describe the corresponding
|
|
execution request. PromptKit continues to own preparation semantics.
|
|
|
|
Use the native result stream for preview output; consumers can capture or
|
|
redirect stdout to save it. The generation command's `--output` decision does
|
|
not itself extend the native inspection commands. File-output convenience does
|
|
not justify retaining a separate preview command. Update maintained examples
|
|
and release migration guidance to use `promptkit show prepared`.
|
|
|
|
### Configuration selection and namespaces
|
|
|
|
Decision recorded 2026-11-19: fully adopt native configuration and namespace
|
|
conventions. Expose the `app` and `promptkit` configuration scopes through
|
|
ckconfig. `app` inspects Scriptorium's application settings; `promptkit`
|
|
inspects the framework configuration assembled from the selected sources.
|
|
Collections do not become separate configuration scopes. Application-only
|
|
inspection must not require constructing a PromptKit engine.
|
|
|
|
`--config` consistently selects Scriptorium's application configuration,
|
|
including when inspecting the `promptkit` scope. That configuration selects
|
|
the framework sources and collection-discovery file. Adopt the standard
|
|
`--overlay` spelling and use consistent source-selection and loading rules
|
|
across generation, preview, inspection, requirements, and other applicable
|
|
commands. Keep the established ConfigKit collection-import model.
|
|
|
|
Enable the native prompt, profile, and backend namespace selectors on
|
|
applicable commands. They independently scope short caller-supplied resource
|
|
IDs; qualified IDs remain exact selections. Namespace selection does not
|
|
rewrite stored references or change collection discovery. Keep configuration
|
|
scope, resource namespace, and profile selection distinct.
|
|
|
|
Use native inventory filters, including namespace selection and
|
|
`--all-namespaces`, and retain upstream default listing behavior. Support
|
|
standard temporary configuration overrides where the upstream loader supports
|
|
them. The reviewed PromptKit configuration scope does not support those
|
|
overrides; do not add local override semantics to compensate.
|
|
|
|
Do not add configurable default namespaces in the initial migration. Use
|
|
qualified IDs and explicit namespace flags when selecting namespaced resources,
|
|
while retaining upstream behavior for unqualified IDs. Configurable defaults
|
|
can be considered later if a need arises.
|
|
|
|
### Native inspection reports and consumer requirements
|
|
|
|
Decision recorded 2026-11-19: adopt native inspection reports and the native
|
|
`promptkit requirements show` interface for Narratio's early dependency
|
|
discovery. Its consumer needs and acceptance scenarios are recorded in the
|
|
[aligned Narratio proposal](narratio-feature-request.md). This direction is
|
|
accepted; Scriptorium integration remains to be implemented.
|
|
|
|
Consume native report fields without a Scriptorium-specific schema-version
|
|
envelope. Use native nonzero outcomes and diagnostics for invocation failures;
|
|
JSON report selection does not require JSON errors. Neither a separately
|
|
versioned envelope nor programmatic invocation-failure categories blocks this
|
|
migration. A future concrete need for either belongs in an upstream discussion.
|
|
|
|
PromptKit owns requirement classification, discovery completeness, and structured
|
|
discovery issues. Completeness is distinct from satisfied bindings or execution
|
|
readiness; Narratio owns comparison against its planned inputs. Keep early
|
|
discovery separate from concrete request validation. Use current exact resource
|
|
identities and native input/variable metadata, without restoring obsolete prompt
|
|
versions or inventing input schemas or variable-default semantics.
|
|
|
|
Standard prompt inspection includes captured messages; prepared preview includes
|
|
rendered content. Adopt these native reports without rebuilding Scriptorium's
|
|
previous summary projections, and explain the changed presentation in migration
|
|
guidance. Requirements discovery retains its distinct upstream content boundary.
|
|
|
|
### Application commands and standard request flags
|
|
|
|
Decision recorded 2026-11-19: use `run PROMPT_ID` for generation, with the prompt
|
|
as a required positional operand and no duplicate prompt-selection flag. Keep
|
|
`serve` as the application command for the HTTP service. Both are CommandKit
|
|
commands owned by Scriptorium, outside the reserved `config` and `promptkit`
|
|
families. The CLI migration does not redesign the HTTP API.
|
|
|
|
Reuse ckprompt's applicable resource, input, and execution flag bindings.
|
|
Preserve native parsing, explicit-value presence, repeated mapping semantics,
|
|
and PromptKit's interpretation of request values. Keep application-specific
|
|
configuration/source selection, `--output`, `--report`, server options, and the
|
|
whole-operation deadline separate from framework request controls.
|
|
|
|
Enable upstream convenience aliases consistently on applicable commands,
|
|
including `run`. Prefer their shorter spellings in user-facing documentation,
|
|
examples, migration guidance, and subprocess integration examples wherever they
|
|
are applicable and unambiguous. For example, prefer `--profile`, `--input-file`,
|
|
`--input-text`, and `--var` over their `--llm-*` equivalents. Canonical upstream
|
|
spellings remain available with identical semantics; the preference does not
|
|
remove or rename them.
|
|
|
|
Aliases retain upstream meanings. In particular, `--input` supplies literal
|
|
text; file references use `--input-file`. Migration guidance must explain this
|
|
change along with endpoint and timeout naming and repeated mapping values.
|
|
Use the canonical spelling where a shorter alias would be ambiguous; do not
|
|
assign an upstream alias a different application-specific meaning.
|
|
|
|
## 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.
|
|
|
|
## Details for the feature roadmap
|
|
|
|
The product and interface direction is settled. The following details need
|
|
concrete implementation choices in the roadmap, but do not require another
|
|
architectural discussion before drafting it.
|
|
|
|
### Outcomes and process lifecycle
|
|
|
|
Map PromptKit's typed errors and reported outcomes into CommandKit conventions,
|
|
preserving its distinction between a completed content check reporting
|
|
`ValidationFailed` and an operational error. Select any necessary domain exit
|
|
code without reusing the current validation-failure exit 2, which conflicts with
|
|
CommandKit's usage convention. Also specify artifact/report delivery failures
|
|
using CommandKit's presentation-failure behavior where applicable. These are
|
|
adapter mappings, not a new application validation policy.
|
|
|
|
Signal cancellation and the whole-operation deadline remain application
|
|
responsibilities. Specify their mapping to the CommandKit invocation context
|
|
and PromptKit operation timeout, including the application deadline flag and
|
|
units, separately from the standard per-attempt timeout flag.
|
|
|
|
### File delivery
|
|
|
|
Specify ordinary path handling, overwriting, parent-directory behavior,
|
|
destination collisions, and delivery ordering for `--output` and `--report`.
|
|
Describe partial delivery consistently with native outcome reporting and the
|
|
agreed upstream result-availability boundary.
|
|
|
|
### Adoption and verification
|
|
|
|
Confirm the released dependency combination, complete the application-specific
|
|
flag and loader mappings, and sequence replacement and removal of CLI code.
|
|
Define appropriate verification for the selected behavior and update canonical
|
|
documentation, examples, and release migration guidance as implementation lands.
|
|
|
|
## Preparing the roadmap
|
|
|
|
Fold the agreed decisions and remaining integration details into a feature
|
|
roadmap. Preserve the selected upstream conventions and explicit non-goals.
|
|
Record any concrete new issue found during preparation without reopening settled
|
|
product choices merely to preserve the old CLI. This notepad remains the
|
|
discussion record until its decisions have been incorporated into that roadmap.
|
|
|
|
[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
|