commandkit/docs/roadmap/requirements.md

PromptKit requirements inspection

Status: implemented in CommandKit. Command placement, public API, caller-variable syntax, and initial presentation are settled and delivered. The implementation plan records completion evidence.

The implementation plan owns the ordered delivery steps and stage completion evidence.

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 selects an additional PromptKit operation within the established architecture. ADR 0004 remains unchanged; the command spelling and report belong in this roadmap until their canonical documentation is updated with implementation.

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

Baseline at roadmap acceptance

This table records the pre-implementation state at CommandKit commit 12b52b3.

Area	State then	Gap the roadmap addressed
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	The accepted baseline had optional prompt/profile inspection and prompt/profile catalog callbacks.	Add an independently optional requirements callback and its engine adapter.
Command assembly	The accepted baseline installed 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 former deferral is retained as an immutable historical record. This roadmap takes the capability up for delivery. Existing configuration, catalog, and named definition operations are not prerequisites for 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

Selected 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 requirements resource namespace follows the resource-first pattern of config show and gives future requirements operations a location without selecting them for this delivery.

The operation displays requirements for one selected prompt context. It accepts the existing singleton configuration selection flags (--config and --overlay) and the suite's application selectors. Repeated occurrences of either singleton use the last value; overlays do not accumulate. Its namespace already identifies PromptKit; an additional configuration --scope selector is not needed.

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 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.

Caller-variable syntax

Use repeatable --var KEY=VALUE, splitting each assignment at the first = and preserving the exact key and remaining value. A missing separator is a usage error. Repeated keys use the last supplied value, consistent with the existing singleton override convention. Every occurrence is parsed, so a later valid assignment does not erase an earlier malformed one.

Invocation fragment	Result
--var note=	Key note is supplied with an empty string value.
--var token=a=b	Key token has value a=b.
--var =value	The empty key has value value.
--var mode=brief --var mode=full	Key mode has value full.
--var 'note=hello, world'	Key note has value hello, world.
--var broken --var mode=full	Usage error because broken has no separator.

Preserve whitespace and commas literally after shell processing. Do not normalize keys or impose an identifier whitelist beyond the native string-map contract. Variable-context files can be considered later if inline assignments prove insufficient; file acquisition and override precedence are outside this delivery.

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 selected 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

Add this request type in ckprompt:

type RequirementsRequest struct {
    Selection  ckconfig.Selection
    Inspection promptkit.RequirementInspectionRequest
}

Extend Suite[I, S] with this optional callback field:

InspectRequirements func(
    context.Context, RequirementsRequest, I, S,
) (commandkit.Acquired[*promptkit.RequirementInspection], error)

The callback receives invocation context, configuration selection and native discovery context, selected application input I, and shared state S. Reusing the owning library's public request avoids duplicating its domain model and keeps 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.

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.

Initial report

Use YAML only initially, defaulting to YAML and accepting --format yaml explicitly. YAML expresses partial inventories, metadata presence, and structured issues readably and supports automation. Additional formats can follow operator needs. Define a CommandKit-owned report representation with these 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: []

For a prompt with the captured template {{if .mode}}{{input "notes"}}{{end}}, no input declarations, and profile editorial, omitting mode produces a useful partial inventory under the adopted native API. Its initial YAML presentation is illustrated here:

prompt_id: briefing
prompt_version: "2"
profile_id: editorial
complete: false
inputs:
  - name: notes
    kind: conditional
    declared: false
    content_type: null
    description: null
    explanation: This reference is not known to be reached on every execution path.
variables:
  - name: mode
    kind: required
    supplied: false
    explanation: ""
issues:
  - code: missing_variable
    input_name: ""
    variable_name: mode
    description: A missing variable prevents selecting a dependency-bearing branch.

For that same prompt, supplying --var mode=full lets native discovery select the branch: notes becomes required, mode is supplied, discovery is complete, and the issues sequence is empty. Both successfully delivered inspections return status 0. The human-readable explanation and description above illustrate the adopted upstream output; their wording remains upstream-owned.

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

Delivery and documentation targets

The implementation plan defines adaptation, command assembly, presentation, validation, and documentation work from the baseline. The maintained composed consumer should demonstrate a partial inventory and how supplying discovery context changes it, with both delivered reports returning status 0. Focused native and boundary coverage should substantiate the selected contracts without duplicating upstream's full analysis suite or adding new validation infrastructure, performance guarantees, or release gates.

At delivery, ckprompt GoDoc, the CLI reference, consumer guidance, and relevant internal summaries describe the implemented capability under their existing ownership rules. The deferred-work record reflects its actual status. The new operation fits the existing ownership and registration boundaries and requires no new ADR; ADR 0004 remains unchanged. Command spelling and report/API details belong with their canonical owners when implemented.

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.

The decisions needed for an implementation plan are settled.