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

349 lines
21 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;
2026-11-20 01:07:52 +00:00
implementation has not begun. This document owns the target and product intent,
incorporating the decisions in the [migration notepad](commandkit-notepad.md).
The notepad remains the discussion
2026-11-19 18:53:19 +00:00
record. The [Narratio proposal](narratio-feature-request.md) supplies consumer
2026-11-20 01:07:52 +00:00
acceptance scenarios for requirements discovery. The
[implementation plan](implementation.md) owns the ordered stages and concrete
adapter choices.
2026-11-19 18:53:19 +00:00
[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.
2026-11-20 01:07:52 +00:00
The selected released combination retains Scriptorium's adopted PromptKit
v0.23.3 fixes and ConfigKit v1.2.1. The reviewed ckprompt release's PromptKit
v0.23.2 minimum does not require a downgrade. Supported public APIs and released
dependencies remain subject to the existing
2026-11-19 18:53:19 +00:00
[architecture policy](../policy/architecture.md).
No selected-format accessor is required for this migration. The native
invocation reporter handles the main result on stdout; the existing writer API
handles the separate report with automatic or explicitly selected rendering.
The upstream accessor proposal remains optional API work, independent of
Scriptorium's adoption.
2026-11-20 01:07:52 +00:00
2026-11-19 18:53:19 +00:00
## 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
2026-11-20 01:07:52 +00:00
semantics. For ConfigKit v1.2.1 the supplied value selects an overlay by name,
not an arbitrary file path. 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.
2026-11-19 18:53:19 +00:00
For implicit application configuration discovery, adopt ConfigKit's built-in
directory presets and their native filename conventions through `SearchConfig`.
Replace the legacy two-file search. ConfigKit deliberately leaves preset
selection and ordering to the application; settle that choice before completing
the loader migration. Selection, exhaustion, and selected-file errors remain
native ConfigKit behavior.
2026-11-19 18:53:19 +00:00
Enable temporary configuration overrides where the loader supports them,
passing native override records into loading. Named selectors and `--set` may
be combined for nonconflicting paths. ConfigKit owns rejection and diagnostics
for duplicate or ancestor/descendant-overlapping override records; `--set` does
not supersede named selectors. Do not filter or merge conflicts locally.
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.
2026-11-19 18:53:19 +00:00
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 main 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
2026-11-19 18:53:19 +00:00
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 |
| --- | --- |
| Main result | Goes through the native invocation reporter to stdout using the selected format. |
2026-11-19 18:53:19 +00:00
| `--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 through CommandKit's renderer, independently of the main format and destination. Without `--report-format`, use native automatic rendering. |
| `--report-format text\|yaml\|json` | Explicitly select the separate report's native rendering format. |
The separate report contains the same native `RunResult`, without the main
report's artifact-only text template. Omission of `--report-format` leaves the
format unset so CommandKit decides how to render it. Its current automatic
rendering for structured values is YAML; future upstream default changes flow
through. Scriptorium does not set a default report format.
2026-11-19 18:53:19 +00:00
There is no `--output` or legacy `--out` flag. Callers save the main result by
redirecting stdout in a shell or supplying a file as the subprocess stdout
destination. Diagnostics remain on stderr. Callers wanting main output omit
`--quiet`, including when stdout is redirected. 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
2026-11-19 18:53:19 +00:00
observer-derived metadata projection. A caller wanting an artifact file plus
metadata redirects stdout and selects a separate `--report` path. The caller
manages redirected destinations and retention; there is no automatic reporting
directory or report collection.
2026-11-19 18:53:19 +00:00
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. `--verbose` preserves the selected stdout result
and exposes emitted Info and Warning messages on stderr under native rules.
An explicit `--report` write is an application
effect rendered through the writer API and still occurs in quiet mode.
Quiet does not cancel generation; it suppresses the main result even when
stdout is redirected, while failure explanations remain visible. Move any
2026-11-19 18:53:19 +00:00
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
2026-11-20 01:07:52 +00:00
application domain outcome for completed validation failure, distinct from
usage and diff-check outcomes. The implementation plan specifies the mapping.
2026-11-19 18:53:19 +00:00
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.
For `--report`, use ordinary file replacement without creating parents. Attempt
the main output followed by the report, and attempt the report even if main
delivery fails. Open the report only when a native result exists. Redirection
and its file-creation or truncation behavior belong to the caller. Scriptorium
does not manage the main output file or check it against the report path. This
adds no rollback or transactional delivery; written bytes may remain after
failure.
2026-11-19 18:53:19 +00:00
Wire signal cancellation through the invocation context. Keep the application
whole-operation budget separate from the native per-attempt timeout binding.
2026-11-20 01:07:52 +00:00
Use `--run-timeout` with Go duration values mapped to PromptKit's
`OperationTimeout`, preserving upstream zero, negative-value, and timeout
behavior without a second timeout policy.
2026-11-19 18:53:19 +00:00
### 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, as they do for generation.
2026-11-19 18:53:19 +00:00
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.
2026-11-20 01:07:52 +00:00
## Acceptance And Scope Boundaries
The target is met when Scriptorium exposes the native command surface and
application behavior above, superseded CLI machinery is retired, and maintained
documentation and examples describe the shipped interface. In particular:
- Configuration callbacks, runtime consumers, and native inspection agree on
ConfigKit's completed values and evidence. Application-only inspection needs
no PromptKit engine, and comparison sides retain independent selections.
- Applicable selection and request context remain consistent across execution,
preparation, discovery, and inspection of multiple independently maintained
collections. Their upstream lifecycle differences remain visible.
- Generation defaults to the artifact alone; structured output and separate
reports expose the native result. Main output uses stdout and native quiet
semantics; the optional report file uses native automatic or explicitly
selected rendering, independently of quiet, with useful failure outcomes and
nontransactional delivery.
2026-11-20 01:07:52 +00:00
- Narratio's linked acceptance scenarios are supported, including useful partial
discovery and discovery before generated artifacts exist.
- Native help, aliases, completion, and explicit smoke testing are available.
Including smoke testing adds no provider access prerequisite to startup or
release validation.
- Server startup reaches the existing HTTP adapter with its transport,
restricted-reading, execution-report, and shared-capacity behavior intact.
- Canonical contracts, examples, dependency attribution, and migration guidance
reflect the cutover. The CLI migration includes positional prompt selection,
command replacements, literal versus file inputs, repeated mappings, overlay
selection, native endpoint/timeout controls, stdout redirection in place of
output-file flags, content-bearing reports, optional report-format selection,
report availability, quiet behavior, and changed exit statuses.
2026-11-20 01:07:52 +00:00
The [implementation plan](implementation.md) owns task sequencing, concrete
adapter mappings, verification steps, and sprint status. Discovery preset
selection and ordering remain to be settled; the selected-format accessor is
not a release prerequisite.
2026-11-19 18:53:19 +00:00
The [release policy](../policy/release.md#versioning-and-compatibility) governs
2026-11-20 01:07:52 +00:00
the eventual breaking release version. This migration does not itself select
or publish a release, introduce a compatibility layer, or settle the separate
pre-v1.0 HTTP design review.
2026-11-19 18:53:19 +00:00
[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