10 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: Adopt CommandKit as part of the same migration as modern PromptKit, in separate, reviewable implementation steps. Bring CommandKit 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
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. Adopting both libraries together reduces transitional code, but does not make those compatibility decisions automatic.
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. |
| Published receipts, debug artifact lifecycle, and mapping application outcomes to process results | Notarius, integrated with CommandKit presentation. |
Keep adoption focused on these responsibilities. Optional upstream capabilities can be installed individually; adoption does not require enabling every preview, smoke, completion, or inspection feature. Exact command exposure remains open.
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 boundaries already identified for deliberate treatment are:
run --jsonpublishes a defined receipt after successful output publication. Retain a deliberate machine protocol; a generic report format is not a reason to change its schema or publication timing.--debugrequests durable debug artifacts. Artifact capture and reporting verbosity remain distinct choices, even when a command exposes both.
Intended Sequencing
- Resolve CommandKit compatibility and 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. Command Surface And Flag Compatibility
Discussion / decision: Pending.
- Map the existing command surface to native standard commands and application handlers. Which names, aliases, flags, and inspection report shapes should be preserved, changed deliberately, or retired?
- How should typed inputs preserve omitted versus explicitly supplied values, repeated reference options, and reasoning-effort inherit/replace/clear behavior?
- Which help/version, argument, and invalid-invocation behaviors are meaningful compatibility requirements, and which are incidental to the existing parser?
Use the CLI reference as the inventory of current contracts. Coordinate flag changes with the master roadmap's retry and worker configuration decisions; do not silently choose those policies as a consequence of changing the parser.
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 shared loaders preserve configuration discovery, explicit selections, overrides, and main-source-relative companions 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.
- Which outputs should use standard formatted reports, and which should use deliberate raw output, including the published run-result receipt?
- How should syntax, configuration, pipeline, and publication outcomes map to process status and user-facing explanations? How should presentation failures remain distinguishable from the underlying operation outcome?
- Which application scope and minimal projections connect native observations to progress, terminal summaries, manifests, and receipts without duplicate execution accounting?
Review stream ownership, output publication timing, and failure delivery against the run-result contract and CLI failure mapping. Item 6 of the PromptKit discussion record provides the agreed bookkeeping boundary; concrete durable compatibility remains part of U9.
5. Debug Capture And Optional Diagnostics
Discussion / decision: Pending.
- How should artifact-capture options interact with quiet/verbose/debug reporting selections while retaining their separate meanings?
- 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 selected flag, stream, outcome, receipt, and debug contracts? Which parser/formatter implementation tests can retire with the removed machinery?
- 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?
After discussion, reconcile the master roadmap's U1/U9/U10 entries, sequencing, removals, and acceptance criteria. 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.