322 lines
20 KiB
Markdown
322 lines
20 KiB
Markdown
# 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 product intent,
|
|
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. The
|
|
[implementation plan](implementation.md) owns the ordered stages and concrete
|
|
adapter choices.
|
|
|
|
[ADR 0006](../adr/0006-adopt-commandkit-native-operator-interfaces.md) records
|
|
the native-interface adoption and ownership boundaries, complementing ADRs 0004
|
|
and 0005.
|
|
|
|
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.
|
|
|
|
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
|
|
[architecture policy](../policy/architecture.md).
|
|
|
|
One approved upstream addition is needed: a released selected-format accessor.
|
|
CommandKit v0.7.0 provides a writer-level renderer but no public access to the
|
|
invocation's selected format. The accessor enables formatted application-owned
|
|
output files, including in quiet mode, without duplicating reporting-flag
|
|
parsing. The implementation plan tracks adoption of its released API; the
|
|
agreed file-output contract remains the target.
|
|
|
|
## 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.
|
|
|
|
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.
|
|
|
|
### 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. 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.
|
|
|
|
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, distinct from
|
|
usage and diff-check outcomes. The implementation plan specifies the mapping.
|
|
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: 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.
|
|
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.
|
|
|
|
### 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.
|
|
|
|
## 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. Requested files remain independent of
|
|
console quiet mode, with useful failure outcomes and nontransactional delivery.
|
|
- 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, content-bearing reports, report
|
|
availability, quiet behavior, and changed exit statuses.
|
|
|
|
The [implementation plan](implementation.md) owns task sequencing, concrete
|
|
adapter mappings, verification steps, and sprint status. There are no unresolved
|
|
product decisions; the approved upstream selected-format accessor remains an
|
|
external release prerequisite.
|
|
|
|
The [release policy](../policy/release.md#versioning-and-compatibility) governs
|
|
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.
|
|
|
|
[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
|