Add CommandKit adoption roadmap
This commit is contained in:
349
docs/roadmap/commandkit-adoption.md
Normal file
349
docs/roadmap/commandkit-adoption.md
Normal file
@@ -0,0 +1,349 @@
|
|||||||
|
# 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](commandkit-notepad.md). The notepad remains the discussion
|
||||||
|
record. The [Narratio proposal](narratio-feature-request.md) 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](../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.
|
||||||
|
|
||||||
|
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](../policy/architecture.md).
|
||||||
|
|
||||||
|
## 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](../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, 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](../../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 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](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.
|
||||||
|
|
||||||
|
## Implementation Sequence
|
||||||
|
|
||||||
|
### 1. Establish Dependencies And Command Composition
|
||||||
|
|
||||||
|
- Confirm released module versions and public integration APIs; update modules
|
||||||
|
and applicable [attribution](../oss/attribution.md) 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](../policy/release.md#versioning-and-compatibility) 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](../development.md#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.
|
||||||
|
|
||||||
|
[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