80 lines
4.1 KiB
Markdown
80 lines
4.1 KiB
Markdown
# 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](0001-command-dispatch-and-inputs.md). 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 reference](../cli.md) owns exact flags, operands, defaults, and report
|
|
schemas for implemented operations.
|
|
|
|
## 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 supported native comparison results, catalogs need
|
|
enumeration, and profile display needs safe execution-target inspection.
|
|
|
|
The [scope model](0009-configuration-scopes.md) and
|
|
[comparison policy](0008-semantic-configuration-diff.md) describe related
|
|
capability and behavioral decisions.
|