8.9 KiB
CommandKit CLI planning record
Status: initial CLI planning complete; remaining proposals deferred.
Original review: 2026-10-06. Reconciled: 2026-10-07.
Purpose and current owners
This document preserves the initial command-suite review and identifies remaining future work. Its completed implementation tasks and obsolete contract drafts have been retired. The initial feature target and completed implementation plan record delivery scope and execution history.
The CLI reference owns implemented commands, syntax, formats, and outcomes. Go declarations and GoDoc own exact exported APIs; the consumer guide explains integration. Accepted ADRs own architectural rationale, and the architecture policy owns responsibility boundaries. This planning record does not define a second current command contract.
Completed initial scope
| Planning area | Delivered boundary and current reference |
|---|---|
| Discovery and identity | Generated help and version reporting. |
| Configuration inspection | Scope discovery, validation, native display including aggregate display, sources, and path explanation. |
| PromptKit integration | Engine configuration scope and optional named prompt/profile inspection, registered independently. |
| Common command infrastructure | Instance registry, typed inputs, presence, routing, and outcomes; see the consumer guide and internal overview. |
CommandKit owns its standard families. Applications retain custom commands, source selection, schema/domain work, acquisition callbacks, and executable lifecycle. Migration of existing applications remains separate work; the maintained simple and composed consumers demonstrate library usage.
Superseded proposal choices
The following entries are historical reconciliation notes. They summarize why older drafts no longer describe the selected implementation; use the linked owner for the complete current contract.
| Earlier proposal, now superseded | Selected result and owner |
|---|---|
| Bare validation defaults to every scope | Configuration operations default to app; aggregate validation/display is explicit. See configuration scopes. |
| Reject repeated singleton flags | Last occurrence supplies the value; every supplied occurrence is converted. See registered syntax. |
Prompt inspection uses --prompt-version |
It uses --version. See definition inspection. |
| Rich profile reports await an upstream provider-parameter redaction API | Current public inspection supplies effective ExtraParams, included without additional redaction requirements. See profile reports. |
| Fix application root/overlay interpretation in CommandKit, reject empty config values, and derive PromptKit selection from one prescribed root | Values and presence are passed to application callbacks, which interpret them. See scope integration and selection declarations. |
| Validation failure always emits no success report | Completed scope records can precede a later failure. See validation. |
| Native display has no format flag | config show --format yaml is accepted. See effective display for syntax and framing. |
| Scope inventory includes description/default fields; sources use a prescribed table | The selected report shapes are defined in scope discovery and source inventory. |
Root app --version is a standard entry point |
The delivered entry point is app version; text can include revision and YAML has explicit identity fields. See version reporting. |
| Blank definition IDs are usage failures | Missing operands are usage failures; explicitly blank values reach owning inspection and produce operational results. See definition inspection. |
| CommandKit automatically coordinates shared loads and dependencies | Applications compose acquisition and may use invocation-local caches. See consumer integration and the composed example. |
The selected namespace/resource-first grammar, capability-based family assembly, application-focused default version, native aggregate YAML, and initial JSON deferral remain reflected in the accepted ADRs and delivered target. The earlier alternatives are review history, not unresolved implementation choices.
Deferred work and remaining proposals
config diff
Semantic comparison is deferred pending supported upstream safe snapshot APIs. ADR 0008 owns its accepted comparison and sensitivity-gap decisions. The deferred capability target records dependencies.
Exact comparison selection syntax and report layout remain future design work. The original proposal considered separate right-side root/overlay selection, shared versus independent domain context, and an optional assertion mode. None of those flags or modes is installed or promised by the initial implementation. CommandKit should use owning public APIs rather than compare rendered YAML or implement another configuration engine.
PromptKit catalogs
Prompt/profile listing is deferred pending public catalog APIs. Catalog resource names and enumeration/report details can be specified when supported APIs exist; CommandKit does not enumerate by reparsing PromptKit configuration YAML. See the deferred capability target.
Other proposals outside the initial delivery
Configuration mutation, reloadable export, credential diagnostics, live provider probes, shell completion, exhaustive field-origin inventories, generic value assignment, additional component identity registration, and domain artifact catalogs remain outside the initial scope. Their inclusion requires a concrete operator purpose and an appropriate ownership/behavior decision. JSON remains deferred without a commitment to add it.
Execution, rendering, serving, and session operations remain application-owned. Shared vocabulary is guidance under ADR 0006, not a reserved implementation contract for every consumer.
Application migrations should replace divergent standard paths and update subprocess consumers and documentation for intentional breaking changes. The original review considered Scriptorium/Notarius followed by Audita/Narratio; that ordering is historical evidence, not a completed migration or mandatory adoption sequence. Future capabilities can be adopted independently.
Historical review evidence
The initial review on 2026-10-06 compared Audita's print-effective, Notarius's
effective, and Narratio/Scriptorium's show; inconsistent scope/source reports;
repeated dispatch/loading/report plumbing; and differing help, syntax, and status
conventions. Those differences informed the shared standard, rather than imposing
compatibility requirements. Narratio's subprocess interpretation of application
statuses also demonstrated the need to coordinate consumer adoption.
Evidence sources, relative to this roadmap in the sibling workspace checkouts:
- Audita CLI contract and configuration parsing.
- Narratio CLI contract, configuration inspection, and comparison.
- Notarius CLI contract and configuration commands.
- Scriptorium CLI contract, application inspection, and framework inspection.
- ConfigKit inspection API, source records, and configuration contract.
- PromptKit configuration inspection and consumer guide.
These links identify sibling-checkout evidence from that review. They are not build dependencies, permanent implementation references, or claims about the applications' present adoption status. Current contracts are owned in CommandKit.