13 KiB
CommandKit Migration Discussion
Purpose And Status
Working notepad for the CommandKit decisions that will be incorporated into the master PromptKit-native migration roadmap. Record the proposal, open questions, evidence, and decisions here as we discuss them.
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.
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.
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
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.
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. Choose their native forms deliberately and document the transition, rather than spending migration effort recreating existing CLI conventions.
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. |
| Receipt content, debug artifact lifecycle, and application outcome meaning | Notarius, expressed through CommandKit's reporting and outcome conventions. |
Evaluate the full standard capability set and adopt applicable upstream commands and recommendations directly. Optional capability selection remains open; assess its usefulness rather than limiting the initial surface to commands Notarius already has.
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.
Two application needs already identified for deliberate treatment are:
- The current
run --jsonpublishes 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
--debugrequests 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.
Intended Sequencing
- Resolve compatible dependency versions and native command scope alongside the dependency baseline, bringing U10 forward.
- Introduce CommandKit composition alongside native source assembly. Connect shared loaders and standard inspection while retaining application orchestration responsibilities.
- Develop native execution and accounting against the intended CLI boundary, with pipeline and domain tests independent of CommandKit.
- 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
Discussion / decision: Detailed choices pending.
- Which compatible tagged CommandKit, ckconfig, and ckprompt versions should join the final PromptKit/ConfigKit dependency set?
- Which standard capabilities belong in the initial cutover, and which can remain optional future additions?
- Are any actual Notarius requirements unsupported upstream, warranting a feature request rather than retention of duplicate local mechanics?
The previously reviewed integrations already align with the roadmap's initial PromptKit v0.23.2 and ConfigKit v1.2.1 targets. Confirm the selected release set and attribution when this choice is resolved; do not infer final pins from the current sibling checkouts.
2. Native Command Surface And Inputs
Discussion / decision: Full native cutover agreed; concrete command and input choices pending. Preserving the existing CLI is not a selection criterion.
- 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?
Use the CLI reference 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.
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?
- 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?
- 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.
- 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?
- How should syntax, configuration, pipeline, and publication outcomes map to native outcome/status conventions and user-facing explanations? How should presentation failures remain distinguishable from the operation outcome?
- Which application scope and minimal projections connect native observations to progress, terminal summaries, manifests, and receipts without duplicate execution accounting?
Review the current run-result contract and CLI failure mapping to understand application needs and caller migration impact. Their existing CLI shapes and status mappings do not override the native-cutover direction. Item 6 of the PromptKit discussion record provides the bookkeeping boundary; U9 still owns concrete durable record choices.
5. Debug Capture And Optional Diagnostics
Discussion / decision: Pending.
- How should artifact-capture controls fit alongside native quiet/verbose/debug
reporting selections without requiring the existing
--debugbehavior? - 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.
- 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?
- 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?
- What release-documentation guidance will show operators and subprocess callers how to migrate their workflows and integrations to the new conventions?
After discussion, reconcile the master roadmap's U1/U9/U10 entries, sequencing, 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.
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 and configuration internals.
- CommandKit consumer guide, including module selection, typed inputs, raw/formatted output, reporting, and loaders.
- ckconfig integration and ckprompt integration.
- Audita command composition, showing application handlers and upstream integrations in one CommandKit application.