Files
scriptorium/docs/roadmap/commandkit-adoption.md

396 lines
24 KiB
Markdown
Raw Normal View History

2026-11-19 18:53:19 +00:00
# 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.
[ADR 0006](../adr/0006-adopt-commandkit-native-operator-interfaces.md) records
the native-interface adoption and ownership boundaries, complementing ADRs 0004
and 0005.
2026-11-19 18:53:19 +00:00
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 policy through the fully resolved handoff,
including resolution of PromptKit's configuration using PromptKit's schema and
rules. PromptKit owns definition, preparation, execution, validation, and
inspection semantics. Scriptorium owns the application domain: it interprets
resolved values and uses upstream APIs and results to satisfy user requests.
Application commands, process lifecycle, and artifact delivery remain local.
2026-11-19 18:53:19 +00:00
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 Authority And Native Inspection
The migration implements the ownership decision in
[ADR 0006](../adr/0006-adopt-commandkit-native-operator-interfaces.md) through
these two boundaries:
1. **ConfigKit's completed result is authoritative configuration.** Scriptorium
supplies its schema, domain defaults, validation, and genuine application
configuration-resolution logic through ConfigKit's supported extension
points. Those callbacks operate within ConfigKit's lifecycle and evidence
model, including recording resolution changes through the supported APIs.
Scriptorium consumes the completed result without subsequently revising what
effective configuration means. Runtime conversion and request construction
may consume resolved values; they do not introduce another configuration
merge, defaulting, or normalization pass. This follows the configuration
boundary established in [ADR 0005](../adr/0005-configkit-boundary.md).
2. **Standard inspection exposes that result through native adapters.**
Scriptorium selects and acquires the requested configuration and declares
supported capabilities. Use `ckconfig.FromConfigKit` for the application
result and `ckprompt.ConfigScope` for PromptKit's captured configuration
inspection within the native `ckconfig` family. Scriptorium does not assemble
a different effective document, reconcile separate explanation trees, or
reinterpret upstream path semantics. Effective values, sources, explanations,
metadata, and comparisons come from the acquired upstream result through
those adapters. CommandKit owns their standard presentation.
Application selection and supported configuration overrides feed the loading
lifecycle before its completed result is exposed. Adapting loaders or supplying
scopes below does not authorize a second configuration-resolution or inspection
model. The `app` and `promptkit` scopes retain their respective upstream evidence;
they are not combined into a synthetic effective configuration.
2026-11-19 18:53:19 +00:00
### 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 while preserving the
[configuration authority boundary](#configuration-authority-and-native-inspection).
Keep application resolution callbacks inside ConfigKit's lifecycle and
return its completed result to the native adapter. Inspect the native overlay
API mapping and update examples to its selected syntax; do not assume renaming
the old flag alone completes adoption.
- Install the native application and PromptKit configuration adapters with
native comparisons and independent comparison inputs. Avoid accidentally
sharing one side's selected values or cached engine with the other.
2026-11-19 18:53:19 +00:00
- 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.
- Application callback changes appear consistently in ConfigKit's completed
values and inspection evidence. Runtime conversion preserves those values,
and standard inspection exposes the acquired result through native adapters,
including native explanation and path behavior. Reuse existing boundary
tests where they already provide this coverage.
2026-11-19 18:53:19 +00:00
- 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