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