commandkit/docs/roadmap/requirements.md

PromptKit requirements inspection

Status: proposed feature roadmap; no implementation in this document. The recommended command placement reflects the user's preference. The remaining API and presentation recommendations are identified under Open Decisions.

Purpose and authority

Expose PromptKit's prompt requirements inspection through the optional ckprompt integration. An operator should be able to select a prompt, supply discovery context, and inspect the resulting input and caller-variable inventory before input artifacts exist.

The governing principle is: CommandKit provides useful, consistent access to capabilities owned elsewhere. PromptKit owns requirement discovery and the meaning of its results. CommandKit owns command vocabulary, registration, selection, coordination, presentation, and invocation outcomes.

The architecture policy, standard inspection decision, outcome decision, module boundary decision, and declaration and input decision control this work. This roadmap proposes an additional PromptKit operation; ADR 0004 does not already specify its command spelling.

PromptKit's adopted public requirements API is the authority for discovery semantics. Descriptions below explain how CommandKit would expose that API, rather than establishing a separate discovery specification.

Current baseline

Baseline: CommandKit commit 12b52b3.

Area	Current implementation	Gap to target
Dependencies	ckprompt already adopts PromptKit v0.14.0, ConfigKit v0.7.1, and YAML v4. Modules require Go 1.26.0.	No dependency or toolchain upgrade is needed for this capability.
Native capability	PromptKit exposes Engine.InspectRequirements, its request, and its structured result.	Adapt this existing public API.
Public integration	Suite[I, S] provides optional prompt/profile inspection and prompt/profile catalog callbacks. FromEngine supplies those four callbacks.	Add an independently optional requirements callback and its engine adapter.
Command assembly	ckprompt.Command installs available show and list operations beneath the owned promptkit namespace.	Assemble the requirements operation from its own capability.
Invocation infrastructure	Typed selectors, configuration selection, input checks, shared state, diagnostics, and buffered report delivery already exist.	Apply those paths to the new operation.
Presentation	Named prompt/profile reports support text and YAML; catalogs use YAML only.	Define a requirements report with the native evidence and discovery context identities.

The deferred-work record records this capability's prior deferral. This roadmap takes it up for planning; the command remains unimplemented. Existing configuration, catalog, and named definition operations are not prerequisites for enabling requirements inspection.

Target ownership and package boundaries

Owner	Responsibility
PromptKit	Prompt/profile/version selection semantics, context interpretation, discovery, classifications, completeness, structured issues, disclosure rules, and native errors.
integrations/ckprompt	The optional callback, request adaptation, command declaration, engine adapter, requirements report, and integration-specific outcome coordination.
integrations/ckconfig	Existing configuration selection and reusable configuration adaptation paths consumed by ckprompt.
CommandKit core	Captured declarations, bindings, parsing, installation, dispatch, help, diagnostics, and outcomes.
Consuming application	Engine acquisition, application selectors and checks, runtime state, custom providers, and any application-owned effects.

Keep the dependency direction ckprompt → ckconfig → core, with ckprompt also using core and PromptKit directly. This feature belongs in ckprompt; it does not require PromptKit types in core, a reverse ckconfig dependency, or a new module. Use the existing public facade and internal backend boundary.

Target operator surface

Recommended operation:

app promptkit requirements show PROMPT_ID
app promptkit requirements show briefing --version 2 --profile editorial --var audience=internal --var language=en
app promptkit requirements show briefing --session-id session-42 --var note= --format yaml

The operation displays requirements for one selected prompt context. It accepts the existing configuration selection flags (--config and repeatable --overlay) and the suite's application selectors. Its namespace already identifies PromptKit; an additional configuration --scope selector is not needed.

Proposed input	Meaning
PROMPT_ID	One required prompt identifier, passed to PromptKit with its exact spelling.
--version VERSION	An exact prompt version; omission uses PromptKit's native selection rule.
--profile PROFILE_ID	A profile identity; omission uses the selected prompt's default under the native API.
Repeatable --var KEY=VALUE	Caller-variable discovery context, including explicitly empty string values.
--session-id SESSION_ID	Session context passed to PromptKit for its native normalization and discovery behavior.
--format yaml	Explicit selection of the recommended initial report format, also the default.

The existing grammar and binding contracts apply. CommandKit should not add independent prompt/profile lookup rules, infer a profile from the catalog, or reinterpret native session validity. Parse the new CLI representation, then delegate domain interpretation to PromptKit. The exact variable grammar and report format remain recommendations in the decisions below.

Native meaning and invocation outcomes

Return the native input and variable inventories, including optional and conditional entries. Carry selected identities, metadata presence, classifications, completeness, explanations, and structured issues into the report. Preserve the returned inventories and issues without introducing a second analyzer, filtering out partial evidence, or interpreting explanation strings as machine-readable rules.

Complete describes discovery coverage. It does not mean that dependencies are supplied, artifacts are valid, templates will render, or execution is ready. A complete inspection can contain an unsupplied required variable. An incomplete inspection can still provide a useful inventory. The command's documentation should explain this distinction and link to the adopted PromptKit contract.

For a successfully acquired and delivered inspection, return success (status 0), including when Complete is false or structured issues are present. Discovery issues are report data; they do not independently become fatal CommandKit diagnostics. Existing acquisition diagnostics and diagnostic delivery rules still apply.

Apply the established outcomes to actual failures:

• CLI syntax, operand, format, and variable-assignment parsing failures are usage failures (status 2).
• Engine acquisition, native selection or inspection, cancellation, and report delivery failures use the existing operational paths (status 1), preserving supported public error identity. Input checks and application-supplied classifications retain their existing handling.
• A provider that returns no inspection and no error is a provider failure, consistent with existing named inspection handling.

The default adapter calls the native inspection API. It does not add request preparation, artifact loading, template rendering, execution, credential probes, or a separate readiness verdict. These are limits of the proposed standard operation, not new restrictions on application loaders or custom callbacks.

PromptKit does not return supplied variable values as a separate inventory of values. A resolved input identifier can nevertheless equal a supplied value and is intentionally included. Preserve the adopted disclosure contract; do not invent blanket masking or a guarantee that application content can never appear in output.

Target public integration and lifecycle

Extend Suite[I, S] with an optional InspectRequirements callback returning commandkit.Acquired[*promptkit.RequirementInspection] and an error. It receives the invocation context, a requirements request, the selected application input I, and shared state S. The recommended request representation is described under OD-2.

FromEngine supplies this callback using the same loader and diagnostics adaptation as its existing inspection callbacks, followed by Engine.InspectRequirements. Applications can clear, wrap, or replace it using ordinary suite composition. No additional registration mechanism is needed.

When only this callback is present, ckprompt.Command installs a usable promptkit requirements show command without empty catalog or named-definition groups. A nil requirements callback omits its operation without disabling the others. When every callback is absent, retain the existing absent-family behavior and attached wiring errors. Namespace ownership continues to follow actual installation.

Apply captured selector metadata and the existing preparation lifecycle: prepare one application input, apply applicable selectors, finish preflight and input checks, then initialize shared state and invoke the selected provider. Omitted factories retain zero-value behavior. Construction, installation, help, and version leave factories and acquisition callbacks uninvoked, as required by the existing contracts.

Keep parsed variable storage local to the invocation. Do not introduce arbitrary deep-copy promises for caller input/state or inspection results. Reuse existing diagnostic ownership and buffered report delivery, including cancellation checks and incomplete-delivery reporting, without claiming rollback of written bytes or interruption of a blocking writer.

Recommended report

Use YAML only initially, with a CommandKit-owned report representation rather than serialization that relies on incidental Go field names. Proposed fields:

Report area	Fields
Selected context and coverage	prompt_id, prompt_version, profile_id, complete
inputs entries	name, kind, declared, content_type, description, explanation
variables entries	name, kind, supplied, explanation
issues entries	code, input_name, variable_name, description

Include false boolean values and represent empty inventories as sequences ([]). For nullable input metadata, preserve the distinction available from PromptKit: nil becomes YAML null, while an explicitly empty string remains "". Do not attempt to distinguish absent metadata from an explicit upstream null when the native API does not distinguish them. Preserve native kind and issue-code values rather than rejecting future values solely because they are not in today's set.

Illustrative shape, showing that complete discovery can still identify an unsupplied variable:

prompt_id: briefing
prompt_version: "2"
profile_id: editorial
complete: true
inputs: []
variables:
  - name: audience
    kind: required
    supplied: false
    explanation: ""
issues: []

Structured discovery issues stay in this report. Engine acquisition diagnostics continue through the diagnostic stream. The implemented CLI reference will own the final schema; this example does not define PromptKit discovery behavior.

Work needed from the baseline

Public contracts and adaptation

Finalize the open API choices, extend the suite and its GoDoc, and adapt FromEngine through the existing acquisition path. Preserve native errors and diagnostics. Reuse ckconfig selection instead of adding parallel configuration loading or asking providers to construct a CommandKit-specific discovery model.

Command assembly and invocation

Add the optional requirements group and handler, bind the prompt operand and discovery-context flags, and integrate selected input/state preparation. Update the empty-suite check to include the new callback. Reuse captured declarations and binding composition; introduce a helper only where the concrete reuse makes the flow simpler.

Presentation and delivery

Map the native result to the selected report representation and use the existing buffered delivery and failure paths. Keep discovery limitations separate from acquisition diagnostics and readiness claims.

Validation evidence

During implementation, add focused coverage using real native inspection where practical, together with boundary doubles for lifecycle and delivery failures. Cover independently enabled and disabled capabilities, help without acquisition, request forwarding, exact/empty variable presence, selected profile/version and session context, complete and partial inventories, structured issues, nullable metadata, native error identity, and invocation isolation. Exercise acquisition diagnostics and writer failures through existing outcome paths.

Extend the maintained composed consumer with a useful requirements example and fixtures. Validate the affected integration and composed example under the repository's existing module/workspace procedures. Reuse established core and configuration coverage; this feature does not justify new generic validation infrastructure, performance guarantees, or release gates.

Documentation and durable decisions

When implementation lands, update ckprompt GoDoc, the CLI reference, consumer guidance, and relevant internal summaries under their existing ownership rules. Reconcile the deferred-work entry with this feature's actual status. Assess whether extending ADR 0004's recorded surface needs a focused new ADR; preserve accepted decision content under the documentation policy rather than silently editing it. Report/API details that evolve within the existing architecture can remain with their canonical owners.

Release documentation and module version selection follow the existing release procedure when a release is prepared. No upstream release, dependency bump, publication, or consumer migration is required by this roadmap.

Completion boundary

The target is reached when an application can independently enable the new operation, select native discovery context, and receive the requirements report with the established lifecycle, diagnostic, error, and delivery handling. The maintained example and canonical documentation should demonstrate its purpose and explain completeness accurately.

Initial delivery does not include a requirements assertion mode, execution readiness checker, artifact binding workflow, or additional analysis beyond the native API. Further capabilities can be considered for concrete needs; these scope boundaries do not prohibit future extensions.

Open Decisions

OD-1: Command placement

Recommendation (user-selected): app promptkit requirements show PROMPT_ID. This gives requirements an explicit resource namespace and follows the resource-first pattern of config show. Future requirements operations have a clear location without being selected by this roadmap.

Alternative: app promptkit show requirements PROMPT_ID. This matches the existing promptkit show prompt and show profile layout and keeps display operations together. Requirements would sit beneath a verb, however, and later requirements verbs would need separate locations. The recommended shape accepts the small vocabulary difference within PromptKit in exchange for a coherent requirements resource.

OD-2: Public request representation

Recommendation: introduce a small ckprompt request with Selection ckconfig.Selection and Inspection promptkit.RequirementInspectionRequest. This deliberately uses the owning library's public request for domain context, avoids duplicating its model, and makes forwarding and future adoption straightforward. Configuration and application-selector presence retain their existing contracts; variable presence is represented by exact map keys. Native version/profile/session string fields use their native empty-value semantics, so this representation does not distinguish omission from explicit empty for those fields.

Alternative: define CommandKit-owned request fields, using commandkit.Supplied[string] for version, profile, and session ID, then translate to the native request in FromEngine. This resembles existing PromptRequest and lets custom providers distinguish omitted and explicitly empty flags. It requires another maintained domain-context representation and conversion, although native inspection currently treats those cases the same. Prefer it if that distinction is useful to an actual custom-provider contract.

OD-3: Caller-variable CLI representation

Recommendation: repeatable --var KEY=VALUE, splitting at the first = and preserving the exact key and remaining value, including empty strings and additional = characters. A missing separator is a usage error. Repeated keys use the last supplied value, consistent with the suite's existing singleton override convention. Do not add key normalization or an identifier whitelist that the native caller map does not require. This is a small, transparent representation of the native string map.

Alternative: accept a YAML variable-context file, potentially alongside explicit flag overrides. Files are convenient for large or repeatedly used contexts and reduce shell quoting. They add file acquisition, map/value validation, and precedence decisions to this feature. They are a viable later extension if inline variables prove insufficient; adding both now expands the initial delivery without an established consumer need.

OD-4: Initial report formats

Recommendation: YAML only, defaulting to YAML and accepting explicit --format yaml, using the report representation above. YAML expresses partial inventories, metadata presence, and structured issues readably and supports automation. Existing catalog and comparison operations already use this format policy, so the new operation need not duplicate presentation logic.

Alternative: text and YAML, with text as the default, matching existing named prompt/profile display. A tailored text summary could be easier to scan for large inventories. It requires an additional renderer and decisions about which evidence to retain in that summary. Add it if operator experience shows a clear benefit; the native structured result does not require it.