5.6 KiB
ADR 0004: Define standard inspection operations by family and capability
Status
Proposed
Date
2026-10-06
Context
CommandKit serves applications with shared configuration and PromptKit inspection needs. A defined operator surface establishes the infrastructure CommandKit provides. Different integrations expose different resources and inspection capabilities, while shared verbs benefit from consistent meanings.
ADR 0001 establishes dispatch, registration, capability-based installation, and the boundary of CommandKit policy. The remaining decisions are the operator questions the initial standard answers.
Decision
CommandKit supplies help and version reporting and defines configuration and PromptKit inspection operations. Each family defines its own supported set of operations. Registration installs handlers for the capabilities supplied by the integration and exposes their availability through help and discovery metadata.
| Standard operation | Responsibility |
|---|---|
help |
Describe registered standard and application commands. |
version |
Report application version by default; report embedded CommandKit version when explicitly selected. |
config scopes |
List registered configuration scopes and supported operations. |
config validate |
Validate the selected configuration and its configured definitions. |
config show |
Display final effective configuration. |
config sources |
Describe the acquired and synthetic input source inventory. |
config explain |
Explain effective or historical values and provenance at a selected path. |
config diff |
Compare effective configuration selections semantically. |
The optional PromptKit suite supplies promptkit list prompts,
promptkit list profiles, promptkit show prompt, and promptkit show profile.
These operations expose captured definition catalogs, prompt metadata, and
backend-completed named execution targets. PromptKit definition capabilities and
its configuration scope are registered according to their available provider
operations. Either can be integrated independently.
CommandKit assembles each installed family from its declared capabilities, keeping standard handlers and metadata together. The inventory describes available standard operations; adoption can use the supported subset. Semantic diff depends on safe comparison snapshots for its selected scope. Its availability is independent of display, validation, and other inspection capabilities.
Shared verbs keep consistent purposes: list enumerates resources, show
displays a selected resource, and diff compares supported representations. Each
family specializes those purposes for its own resources. For example, a future
FeedKit family could supply list and show as its intended operation set.
app version and root app --version report application version. The version
command defaults to --scope app; app version --scope commandkit reports the
embedded CommandKit release version. --format selects presentation of the same
subject. Future component identities can use registered version metadata. Version
subjects are independent of configuration scopes and loading providers.
CommandKit owns vocabulary and observable contracts within its standard families. Custom execution, rendering, serving, sessions, and artifact workflows retain their application-owned meanings. Additional shared operations enter through versioned CommandKit releases under the release policy.
The CLI reference owns exact flags, operands, defaults, and report schemas when implemented. This record owns operation purposes and capability-based availability.
Alternatives considered
| Alternative | Analysis |
|---|---|
| Initial operations limited to validation and display | Accelerates first integrations. Source explanation, comparison, and discovery remain repeated application infrastructure. |
| Require every operation for every integration | Gives a uniform inventory. One unavailable capability blocks other useful operations and future resource families. |
| Definition inspection through configuration operations alone | Source values and provenance share one path. Captured catalogs and completed execution targets require additional interpretation. |
| Standardize execution and mutation alongside inspection | Expands shared vocabulary to more workflows. Additional domain and state-management contracts require their own evidence and design. |
| Display dependency identities in ordinary application version output | Makes dependency information immediately visible. Application identity becomes coupled to dependency reporting. |
| A combined dependency-version option | Gives a useful diagnostic inventory. Scoped version reporting also supports selecting one identity. |
Consequences
CommandKit supplies shared handlers with predictable meanings and discovers their availability from registration. Each enabled operation needs its own data contract: comparison needs safe snapshots, catalogs need enumeration, and profile display needs safe execution-target inspection.
Shared operations retain clear purposes. CommandKit release notes describe changes to its published operations. Coordinated application documentation and caller updates are recommended migration practices.
Help and discovery describe actual supported capabilities. The scope model, inspection lifecycle, and comparison policy describe the proposed provider and behavioral contracts supporting this surface.