4.1 KiB
ADR 0004: Define standard inspection operations by family and capability
Status
Accepted.
Date
2026-10-06
Context
CommandKit serves applications with shared ConfigKit 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.
Decision
CommandKit supplies help and version reporting and defines ConfigKit 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.
Adoption can use the supported subset under ADR 0001. Missing comparison or catalog capabilities leave other inspection operations available.
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.
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.
The CLI roadmap tracks command details and delivery. The CLI reference will own exact flags, operands, defaults, and report schemas when implemented.
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. |
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.
The scope model and comparison policy describe related capability and behavioral decisions.