2026-11-19 15:51:31 +00:00
# CommandKit Migration Discussion
## Purpose And Status
Working notepad for the CommandKit decisions that will be incorporated into the
[master PromptKit-native migration roadmap ](promptkit.md ). Record the proposal,
open questions, evidence, and decisions here as we discuss them.
2026-11-19 15:55:46 +00:00
**Direction agreed:** Make a full cutover to a CommandKit-native application as
part of the same migration as modern PromptKit, in separate, reviewable
implementation steps. Adopt CommandKit's public-facing conventions and
recommendations to the fullest extent. Bring its design decisions forward and
complete adoption before the overall cutover.
2026-11-19 15:51:31 +00:00
The master roadmap currently places CommandKit in a subsequent Phase 7 and leaves
its details in U10. That sequencing has not yet been revised. Once the relevant
details below are settled, fold them into the master roadmap, including its
dependency baseline, implementation phases, removal inventory, and acceptance
criteria. No application or dependency changes have been implemented through
this discussion.
2026-11-19 16:04:23 +00:00
Item 1 selects the dependency versions and standard capabilities, including
PromptKit v0.23.3 in place of the master roadmap's initial v0.23.2 target.
Application-specific commands, wiring, and reporting details remain open below.
2026-11-19 15:51:31 +00:00
The PromptKit architecture and checkpoint decisions remain in force. This
discussion develops the CommandKit portion of that migration and its interactions
with U1 (dependencies), U9 (records/reporting), and U10 (CommandKit adoption).
## Agreed Proposal
2026-11-19 15:55:46 +00:00
### Guiding Rule: Full Native Cutover
Backward compatibility with the existing CLI conventions is a non-goal. Use
CommandKit's native command, input, help/version, reporting, error, and outcome
conventions as the design baseline. This mirrors the PromptKit-native direction.
Existing command names, flags, aliases, parsing behavior, report shapes, and exit
conventions are migration evidence, not requirements to preserve. Do not add
legacy aliases, compatibility shims, parallel parsers, or reporting wrappers
solely to reproduce the old CLI. Any application-specific behavior should serve
an actual Notarius need and fit the native conventions.
Provide migration guidance in release documentation, explaining the new commands
and conventions and the actions operators or subprocess callers must take.
Documenting the transition replaces a requirement to keep the old CLI working.
Update canonical CLI and consumer documentation when the behavior lands.
Application responsibilities such as producing artifacts, reporting publication
outcomes, and managing checkpoint/debug storage remain meaningful. Their existing
CLI expression is not protected by an implicit compatibility exception. This
guiding rule does not itself choose stored artifact or checkpoint formats; those
remain separate application decisions in the master roadmap.
2026-11-19 15:51:31 +00:00
### Why Adopt Together
- Source assembly and preflight are already changing. CommandKit integrations
can consume the same application and native engine loaders.
- ckconfig and ckprompt can replace standard inspection commands directly,
avoiding an intermediate adaptation of commands that would soon be replaced.
- Native execution facts and application outcomes can feed the intended reporting
facilities while duplicate LLM bookkeeping is removed.
- Configuration and command migration can be documented and verified as one
coherent transition.
The added work is principally CLI composition and contract migration: dispatch,
flag parsing, configuration selection, reporting, and process-status mapping.
2026-11-19 15:55:46 +00:00
Choose their native forms deliberately and document the transition, rather than
spending migration effort recreating existing CLI conventions.
2026-11-19 15:51:31 +00:00
### Ownership And Scope
| Concern | Selected owner |
| --- | --- |
| Command hosting, standard input/help mechanics, common report formatting and visibility | CommandKit. |
| Standard configuration and PromptKit inspection commands | ckconfig and ckprompt, supplied with application loaders and request builders. |
| Configuration composition and model execution | ConfigKit and PromptKit, using the native boundaries already selected. |
| Pipeline execution and listing, pipeline-specific preflight, artifact publication, checkpoints, and domain outcomes | Notarius application handlers and framework. |
2026-11-19 15:55:46 +00:00
| Receipt content, debug artifact lifecycle, and application outcome meaning | Notarius, expressed through CommandKit's reporting and outcome conventions. |
2026-11-19 15:51:31 +00:00
2026-11-19 16:04:23 +00:00
Adopt the standard capability suite selected in item 1, including upstream
commands and recommendations beyond the existing Notarius surface. The remaining
discussion determines application-specific inputs, wiring, and result content.
2026-11-19 15:51:31 +00:00
Pipeline and domain code should remain independent of CommandKit. Native
PromptKit observations supply execution facts; Notarius attaches application
meaning and selects report content. CommandKit supplies presentation mechanics.
2026-11-19 15:55:46 +00:00
Two application needs already identified for deliberate treatment are:
2026-11-19 15:51:31 +00:00
2026-11-19 15:55:46 +00:00
- The current `run --json` publishes a receipt after output publication. Determine
the needed result information and express it through an appropriate native
output facility. The old flag, envelope, formatting, and stream conventions are
not compatibility requirements; reports must still describe the actual outcome.
- The current `--debug` requests durable artifacts. Retain the distinction between
artifact capture and reporting verbosity, while choosing native controls and
meanings rather than requiring that flag to retain its old behavior.
2026-11-19 15:51:31 +00:00
### Intended Sequencing
2026-11-19 16:04:23 +00:00
1. Incorporate item 1's selected dependency baseline and standard capabilities,
and resolve native application command design, bringing U10 forward.
2026-11-19 15:51:31 +00:00
2. Introduce CommandKit composition alongside native source assembly. Connect
shared loaders and standard inspection while retaining application
orchestration responsibilities.
3. Develop native execution and accounting against the intended CLI boundary,
with pipeline and domain tests independent of CommandKit.
4. Complete command and reporting migration before final end-to-end verification
and migration documentation.
This is the agreed sequencing direction, not a replacement phase plan. Concrete
work units and their placement in the master roadmap follow the discussion below.
## 1. Adoption Scope And Dependency Baseline
2026-11-19 16:04:23 +00:00
**Discussion / decision:** Versions and standard capability scope agreed. Adopt
the set below, including the move to PromptKit v0.23.3. Application-specific
command design and reporting details remain with the subsequent topics. These
are selected migration targets; the application dependencies have not changed.
### Selected Versions
| Module | Version | Role |
| --- | --- | --- |
| `go.maximumdirect.net/commandkit` | `v0.7.0` | Native command declarations, inputs, help/version, reporting, and completion. |
| `go.maximumdirect.net/ckconfig` | `v0.9.0` | Standard configuration commands and ConfigKit diagnostic classification. |
| `go.maximumdirect.net/ckprompt` | `v0.10.0` | Standard PromptKit inspection, validation, preparation, and smoke diagnostics. |
| `go.maximumdirect.net/configkit` | `v1.2.1` | Shared configuration dependency for the application and integrations. |
| `go.maximumdirect.net/promptkit` | `v0.23.3` | Native model execution, including corrected timeout/cancellation reporting. |
The CommandKit integration releases form a documented compatible set using
PromptKit v0.23.2. Select v0.23.3 explicitly for its timeout attribution and
cancellation/error identity fixes. It retains the same dependencies and requires
no configuration or request API migration from v0.23.2. The Go consumer minimum
remains 1.27. Verify the assembled dependency set through the migration's normal
integration checks and update attribution when the dependency changes land.
2026-11-19 15:51:31 +00:00
2026-11-19 16:04:23 +00:00
The version review used locally available release tags and tagged dependency
manifests. Remote release lookup was unavailable, so it did not establish whether
newer tags existed remotely. These are deliberate selected versions, not a claim
that every module is the latest published release.
2026-11-19 15:51:31 +00:00
2026-11-19 16:04:23 +00:00
Evidence: [integration version guidance ](../../../commandkit/docs/consumers/guide.md#module-selection )
and [PromptKit v0.23.3 release notes ](../../../promptkit/docs/releases/v0.23.3.md ).
### Selected Standard Capabilities
| Area | Adopt in the cutover |
| --- | --- |
| Core CLI | Native help, `version` , typed flags and operands, supplied-value semantics, standard outcomes, and command declaration/dispatch. |
| Reporting | Native `--format` with text/YAML/JSON, `--quiet` , `--verbose` , `--debug` , and `--progress` , including upstream visibility and failure behavior. |
| Configuration | `config scopes` , `validate` , `show` , `sources` , `explain` , and `diff` , for application and PromptKit configuration. |
| Resource discovery | PromptKit listings for prompts, profiles, backends, namespaces, and collections, with native filters and selectors. |
| Resource inspection | Native prompt, profile, and backend reports, plus requirements discovery. |
| Concrete request checks | Requirements validation and prepared-request preview using native inputs, variables, profiles, and execution overrides. |
| Provider diagnostics | Reachability, authentication, text-inference, structured-output, and aggregate smoke tests. |
| Convenience features | Bash, Zsh, and Fish completion, useful declaration hints, and upstream PromptKit convenience aliases. |
Use the [upstream CLI conventions ](../../../commandkit/docs/cli.md ) directly.
Providing the standard capability suite means supplying application loaders and
callbacks, not recreating those commands locally. Upstream convenience aliases
are selected native features; this does not reintroduce legacy Notarius aliases.
### Wiring Boundaries And Follow-Up
- Keep configuration validation, requirements discovery, and concrete request
validation distinct. Pipeline preflight remains application-owned. Concrete
preparation may read inputs and schemas and check credentials even though it
makes no model call.
- Install smoke commands for explicit invocation. Their availability does not
introduce provider calls during startup, ordinary validation, or offline tests.
- Enable application configuration overrides through ConfigKit. The selected
PromptKit configuration scope does not support arbitrary `--set` overrides;
use supported request-level controls rather than implementing a local equivalent.
- Retain application handlers for pipeline execution and discovery, with native
commands, inputs, and result presentation to be designed in items 2– 5.
No upstream feature request has been identified as a blocker for this scope.
Evaluate any later demonstrated gap on its actual application need. On roadmap
reconciliation, incorporate these versions into U1, replace U10's open standard
capability selection with this decision, and retain the unresolved application
wiring and presentation details explicitly.
2026-11-19 15:51:31 +00:00
2026-11-19 15:55:46 +00:00
## 2. Native Command Surface And Inputs
2026-11-19 15:51:31 +00:00
2026-11-19 15:55:46 +00:00
**Discussion / decision:** Full native cutover agreed; concrete command and input
choices pending. Preserving the existing CLI is not a selection criterion.
2026-11-19 15:51:31 +00:00
2026-11-19 15:55:46 +00:00
- How should Notarius workflows be exposed through native standard commands and
application handlers, including upstream naming and flag recommendations?
- Which application input semantics are needed, such as reference selection and
reasoning-effort inheritance or clearing, and how should native typed inputs
express them, including omitted versus explicitly supplied values?
- Which existing commands and custom parsing can disappear once standard
help/version, argument handling, and invalid-invocation behavior are adopted?
2026-11-19 15:51:31 +00:00
2026-11-19 15:55:46 +00:00
Use the [CLI reference ](../cli.md ) to identify current workflows and write
migration guidance, not as a compatibility constraint. Coordinate native inputs
with the master roadmap's retry and worker policy decisions; their domain meaning
is separate from how the CLI expresses them.
2026-11-19 15:51:31 +00:00
## 3. Application Composition, Loaders, And Preflight
**Discussion / decision:** Pending.
- How should command declarations, application handlers, and invocation state be
composed without introducing another general CLI or LLM wrapper?
2026-11-19 15:55:46 +00:00
- How should native command selections and overrides reach shared loaders while
retaining the selected ConfigKit source composition and main-source-relative
companion behavior across execution and inspection?
2026-11-19 15:51:31 +00:00
- Where should pipeline-specific validation attach to standard configuration
validation, and what state should be acquired only when a command needs it?
Retain the selected offline preflight boundary: it checks application composition
and known native resources without synthesizing a stage request or requiring
provider credentials. Help/version should not require runtime configuration or
provider work. Model-executing roles share one native engine within an execution;
the CLI wiring must preserve that ownership.
## 4. Reports, Machine Output, And Outcomes
**Discussion / decision:** Pending.
2026-11-19 15:55:46 +00:00
- How should native reports and output modes express application results? Where
does an application data requirement justify raw output rather than a standard
report, independently of the old CLI's output conventions?
2026-11-19 15:51:31 +00:00
- How should syntax, configuration, pipeline, and publication outcomes map to
2026-11-19 15:55:46 +00:00
native outcome/status conventions and user-facing explanations? How should
presentation failures remain distinguishable from the operation outcome?
2026-11-19 15:51:31 +00:00
- Which application scope and minimal projections connect native observations
to progress, terminal summaries, manifests, and receipts without duplicate
execution accounting?
2026-11-19 15:55:46 +00:00
Review the current [run-result contract ](../integrations/run-result.md ) and
[CLI failure mapping ](../internal/cli.md#failure-mapping-and-terminal-reporting )
to understand application needs and caller migration impact. Their existing CLI
shapes and status mappings do not override the native-cutover direction.
2026-11-19 15:51:31 +00:00
Item 6 of the [PromptKit discussion record ](promptkit-architecture-discussion.md#6-inspection-and-execution-bookkeeping )
2026-11-19 15:55:46 +00:00
provides the bookkeeping boundary; U9 still owns concrete durable record choices.
2026-11-19 15:51:31 +00:00
## 5. Debug Capture And Optional Diagnostics
**Discussion / decision:** Pending.
2026-11-19 15:55:46 +00:00
- How should artifact-capture controls fit alongside native quiet/verbose/debug
reporting selections without requiring the existing `--debug` behavior?
2026-11-19 15:51:31 +00:00
- How should requested debug artifact writes, failures, disclosure, and retention
connect to command completion and native callbacks?
- For selected preview, request-validation, or smoke capabilities, what native
request builders and explicit execution choices should the application supply?
Keep debug creation and physical storage in Notarius. Ordinary records exclude
sensitive response/history content, and provider smoke diagnostics remain
explicitly opt-in. Native inspection alone must not become a model call.
## 6. Verification, Migration, And Roadmap Incorporation
**Discussion / decision:** Pending.
2026-11-19 15:55:46 +00:00
- Which focused command and subprocess tests protect the new native command,
output, outcome, receipt, and debug behavior? Which tests of superseded CLI
contracts and parser/formatter implementation can retire?
2026-11-19 15:51:31 +00:00
- Which representative assembled workflows prove that execution, inspection,
and preflight use the same intended configuration without duplicating lower-level
coverage? Keep the default suite offline and independent of real credentials.
- How should CommandKit steps replace the master roadmap's deferred Phase 7,
and which migration examples, documentation, and ADRs need coordinated updates?
2026-11-19 15:55:46 +00:00
- What release-documentation guidance will show operators and subprocess callers
how to migrate their workflows and integrations to the new conventions?
2026-11-19 15:51:31 +00:00
After discussion, reconcile the master roadmap's U1/U9/U10 entries, sequencing,
2026-11-19 15:55:46 +00:00
removals, and acceptance criteria, including its treatment of existing inspection
commands and machine-output compatibility. Carry forward the explicit non-goal
of CLI backward compatibility and release migration guidance. Preserve other
unresolved choices explicitly. Then mark this document as the discussion record
and keep implementation status in the master roadmap.
2026-11-19 15:51:31 +00:00
## Evidence And Reading
These are starting points for discussion, not a completed CommandKit migration
audit. Sibling links assume the local repositories remain available.
- [Notarius CLI implementation overview ](../internal/cli.md ) and
[configuration internals ](../internal/configuration.md ).
- [CommandKit consumer guide ](../../../commandkit/docs/consumers/guide.md ), including
module selection, typed inputs, raw/formatted output, reporting, and loaders.
- [ckconfig integration ](../../../commandkit/integrations/ckconfig/README.md ) and
[ckprompt integration ](../../../commandkit/integrations/ckprompt/README.md ).
- [Audita command composition ](../../../audita/internal/cli/app_wiring.go ), showing
application handlers and upstream integrations in one CommandKit application.