base-layer/commandkit
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Document PromptKit requirements discovery

Browse Source
This commit is contained in:
Eric Rakestraw
2026-10-12 17:26:11 +00:00
parent 3710492d2d
commit d3cbfc4e9a
13 changed files with 179 additions and 67 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
README.md
View File

@@ -16,7 +16,7 @@ constructing them, and returns outcomes without exiting the process. Its
| --- | --- | --- |
| `gitea.maximumdirect.net/eric/CommandKit` | `commandkit` | Typed commands, bindings, execution, outcomes, help, and version. |
| `gitea.maximumdirect.net/eric/CommandKit/integrations/ckconfig` | `ckconfig` | ConfigKit-backed `config` scopes and inspection commands. |
| `gitea.maximumdirect.net/eric/CommandKit/integrations/ckprompt` | `ckprompt` | PromptKit engine configuration/comparison, prompt/profile catalogs, and named inspection. |
| `gitea.maximumdirect.net/eric/CommandKit/integrations/ckprompt` | `ckprompt` | PromptKit engine configuration/comparison, prompt/profile catalogs, named inspection, and requirements discovery. |
Importing an integration does not install commands. Pass its declaration to
`commandkit.New` or `App.Register` to install it. The integrations depend on the

79
docs/cli.md
View File

@@ -382,6 +382,85 @@ error identity. Cancellation is also operational: standard handlers check the
caller's context at inspection boundaries, and PromptKit can return cancellation
from its own inspection methods. Supported cancellation identity is preserved.
## PromptKit requirements
When `Suite.InspectRequirements` is present,
`ckprompt.Command(suite)` installs the following optional operation. It accepts
one required prompt ID and uses PromptKit's native selection and discovery
rules:
```text
example promptkit requirements show briefing --campaign spring
example promptkit requirements show briefing --version 2 --profile editorial --var mode=full
example promptkit requirements show briefing --session-id session-42 --var note= --format yaml
```
The command accepts these flags:
| Flag | Values | Default | Meaning |
| --- | --- | --- | --- |
| `--config` | path string | omitted | Select the configuration input; explicit presence is retained. |
| `--overlay` | path string | omitted | Select one overlay; explicit presence is retained. Repeated occurrences use the last value. |
| Suite selectors | application-defined | per selector | The flags captured from `Suite.Selectors`. |
| `--version` | string | empty | Pass the prompt version to PromptKit; empty uses its native version-selection rule. |
| `--profile` | string | empty | Pass the profile ID to PromptKit; empty uses its native profile-selection rule. |
| `--session-id` | string | empty | Pass session context to PromptKit. |
| `--var` | repeatable `KEY=VALUE` | none | Supply caller-variable context for native discovery. |
| `--format` | `yaml` | `yaml` | Select the requirements report format. Other formats are usage errors for this operation. |
The `promptkit` namespace identifies the PromptKit operation, so there is no
built-in `--scope` flag. The version, profile, and session fields use native
empty-string semantics: an explicit empty string has the same meaning as
omission. PromptKit owns their interpretation, including default version and
profile selection, session context, and selection errors. Requirements
inspection does not require a profile to be execution-ready. See the pinned
[PromptKit requirements API](https://gitea.maximumdirect.net/eric/promptkit/src/commit/143c6e9b3a675872117b0471e2ff8bcb25055a54/requirements.go)
for the owning discovery contract. The built-in flags are singleton bindings;
when repeated, the last value is used. Suite selectors retain their declared
binding behavior.
Each `--var` occurrence must contain `=`. CommandKit splits at the first
separator and preserves the exact key and remaining value. Empty keys and
values, whitespace, commas, and additional `=` characters are retained. All
occurrences are parsed; duplicate keys use the last value, while any malformed
occurrence is a usage error even if a later assignment is valid.
The successful report is YAML with selected identities, native completeness,
and the input, variable, and issue inventories. False values and empty
inventories are retained. Input metadata preserves null versus an empty string.
The shape is:
```yaml
prompt_id: briefing
prompt_version: "2"
profile_id: editorial
complete: false
inputs:
- name: notes
kind: conditional
declared: false
content_type: null
description: null
explanation: ""
variables: []
issues:
- code: missing_variable
input_name: ""
variable_name: mode
description: ""
```
PromptKit owns the inventory, classifications, explanations, completeness,
and structured issues. Completeness means discovery covered the relevant
dependencies; it does not mean inputs or variables are supplied, artifacts are
valid, credentials are available, or execution is ready. A complete report can
contain unsupplied required variables, and an incomplete report can still be
useful. Successfully acquired and delivered partial reports return status `0`;
structured issues remain in YAML and do not independently fail the command.
Provider errors, native selection errors, cancellation, and report delivery
failures use the operational path (status `1`) with supported cause identity.
Syntax, operand, variable-assignment, and format errors use usage status `2`.
### PromptKit catalogs
An installed `ckprompt.Command(suite)` exposes the catalog commands supplied by

36
docs/consumers/guide.md
View File

@@ -11,7 +11,7 @@ through `commandkit.New` or `App.Register`.
| --- | --- |
| `gitea.maximumdirect.net/eric/CommandKit` | The application needs typed command declarations and common CLI behavior. |
| `gitea.maximumdirect.net/eric/CommandKit/integrations/ckconfig` | The application wants ConfigKit-backed configuration scopes and reports. |
| `gitea.maximumdirect.net/eric/CommandKit/integrations/ckprompt` | The application wants PromptKit engine configuration/comparison, prompt/profile catalogs, or named inspection. |
| `gitea.maximumdirect.net/eric/CommandKit/integrations/ckprompt` | The application wants PromptKit engine configuration/comparison, prompt/profile catalogs, named inspection, or requirements discovery. |
The two integrations are independent optional imports. `ckprompt` uses the
public scope and error contracts from `ckconfig`; importing it does not add the
@@ -124,31 +124,35 @@ owns operator syntax and report details.
`ckprompt.ConfigScope(loadEngine)` returns a `ckconfig.Scope` for the PromptKit
engine's captured configuration. Add that scope to a `ckconfig.Suite` to expose
it under `config` with validate/show/sources/explain and native diff operations;
it does not install named definition commands.
it does not install PromptKit catalog, definition, or requirements commands.
`ckprompt.FromEngine(loadEngine)` supplies the prompt/profile catalog callbacks
and named inspection callbacks. Set its `NewInput`, `NewState`, selectors, or
validation when the application needs them, then pass `ckprompt.Command(suite)`
to core. The four callbacks are independently optional; `Command` creates `list`
and `show` groups only when their corresponding callbacks are present. Narrow a
bundled suite before command capture when the application wants catalogs without
named inspections:
`ckprompt.FromEngine(loadEngine)` supplies the prompt/profile catalog callbacks,
named inspection callbacks, and native requirements callback. Set its
`NewInput`, `NewState`, selectors, or validation when the application needs
them, then pass `ckprompt.Command(suite)` to core. All five callbacks are
independently optional; `Command` creates each operation group only when its
callbacks are present. Applications can use the requirements callback alone,
clear it while retaining other operations, wrap it, or replace it with their
own provider. For catalogs without named or requirements inspection, narrow the
suite before command capture:
```go
definitions := ckprompt.FromEngine(loadEngine)
definitions.InspectPrompt = nil
definitions.InspectProfile = nil
definitions.InspectRequirements = nil
definitionCommand := ckprompt.Command(definitions)
```
Each selected inspection or catalog operation prepares one input, applies its
captured selectors, checks that input, and initializes one state value when
those steps are reached. See
Each selected inspection, requirements, or catalog operation prepares one input,
applies its captured selectors, checks that input, and initializes one state
value when those steps are reached. See
[ckprompt.Suite's GoDoc](../../integrations/ckprompt/adapters.go) for factory
timing, omitted-factory zero values, and caller-owned objects and effects.
The loader receives invocation context, explicitly supplied selection, input,
and state. The adapter uses PromptKit's public listing and inspection methods
and preserves acquisition diagnostics and supported error identity.
and state. The adapter uses PromptKit's public listing and inspection methods,
including `Engine.InspectRequirements`, and preserves acquisition diagnostics
and supported error identity.
CommandKit-owned listing and inspection code does not execute prompts, contact model
providers, or resolve credential values; application loaders and direct callbacks
@@ -156,8 +160,8 @@ retain their own effects. The [CLI reference](../cli.md#promptkit-definition-ins
owns the command and report contracts.
The [composed example](../../integrations/ckprompt/examples/composed/README.md)
combines app and PromptKit config scopes, comparison and catalogs, named
inspection, and an application-owned `session restore` command.
combines app and PromptKit config scopes, comparison and catalogs, named and
requirements inspection, and an application-owned `session restore` command.
## Outcomes and ownership

6
docs/development.md
View File

@@ -3,8 +3,8 @@
CommandKit is distributed as a core Go module and two optional integration
modules. Core owns captured declarations, typed input preparation, installation,
dispatch, outcomes, help, and version. `integrations/ckconfig` owns ConfigKit
scope adaptation and reports; `integrations/ckprompt` owns PromptKit engine and
definition inspection adapters. The maintained
scope adaptation and reports; `integrations/ckprompt` owns PromptKit engine,
definition inspection, and requirements discovery adapters. The maintained
[consumer guide](consumers/guide.md) links to the three maintained consumers.
The [README](../README.md) provides project orientation; the
[documentation policy](policy/documentation.md#canonical-ownership) assigns
@@ -141,6 +141,8 @@ go run ./examples/core workspace greet --count=0 --tag=first --tag second
(cd integrations/ckprompt/examples/composed && go run . promptkit list prompts --config fixtures/before.yml --campaign spring)
(cd integrations/ckprompt/examples/composed && go run . promptkit list profiles --config fixtures/after.yml --campaign autumn --format yaml)
(cd integrations/ckprompt/examples/composed && go run . promptkit show prompt briefing --campaign spring --format yaml)
(cd integrations/ckprompt/examples/composed && go run . promptkit requirements show briefing --campaign spring)
(cd integrations/ckprompt/examples/composed && go run . promptkit requirements show briefing --campaign spring --var mode=full --format yaml)
(cd integrations/ckprompt/examples/composed && go run . session restore session-42 --campaign spring)
```

11
docs/internal/overview.md
View File

@@ -47,11 +47,12 @@ initialized input, while one suite-owned state value is shared by an invocation'
acquisitions or comparison callback.
`integrations/ckprompt` owns PromptKit engine loading, configuration-scope
adaptation and native comparison, plus optional prompt/profile catalogs and
named inspection. It uses public core and ckconfig contracts plus PromptKit's
public APIs. It does not add a configuration family when its declaration is
installed; callers compose `ckprompt.ConfigScope` with `ckconfig.Command`
separately when they want configuration operations alongside definition commands.
adaptation and native comparison, plus optional prompt/profile catalogs, named
inspection, and native requirements discovery. It uses public core and ckconfig
contracts plus PromptKit's public APIs. It does not add a configuration family
when its declaration is installed; callers compose `ckprompt.ConfigScope` with
`ckconfig.Command` separately when they want configuration operations alongside
PromptKit commands.
The three maintained consumers live at `examples/core`,
`integrations/ckconfig/examples/simple`, and

8
docs/roadmap/deferred.md
View File

@@ -18,14 +18,6 @@ an idea here does not select its syntax, API, priority, or delivery date.
## Deferred capability targets
### PromptKit requirement inspection
PromptKit exposes `Engine.InspectRequirements`, but a standard CommandKit
operation for requirement inspection remains deferred. Its command syntax,
selection behavior, presentation, and readiness semantics have not been
selected. Reassess the owning library's public contract and make those product
choices before planning delivery.
### Comparison extensions
Independent per-side domain selectors and an optional assertion mode remain

17
docs/roadmap/implementation.md
View File

@@ -1,6 +1,6 @@
# Implement PromptKit requirements inspection
Status: in progress; Stages 1 through 5 are complete.
Status: in progress; Stages 1 through 6 are complete.
## Authority and working rules
@@ -423,6 +423,21 @@ Historical release notes and pinned retired plans remain historical evidence;
do not rewrite them as current reference pages. Current canonical docs must not
depend on this temporary plan for their implemented contracts.
**Completed:** Updated the exported API comments in
`integrations/ckprompt/adapters.go`, `command.go`, and `doc.go`; the command and
report contract in `docs/cli.md`; optional callback guidance in
`docs/consumers/guide.md`; module, root, internal, and contributor summaries;
and the composed example README. Removed the delivered capability from
`docs/roadmap/deferred.md` and updated
`docs/roadmap/requirements.md` to describe its historical baseline and point to
the immutable commit that contains the prior deferral. The two example commands
and their semantics match the Stage 5 test and observed output. `gofmt -w
integrations/ckprompt/adapters.go integrations/ckprompt/command.go
integrations/ckprompt/doc.go` and `git diff --check -- '*.md' COPYRIGHT` passed.
A local link and fragment check across nine changed Markdown documents passed;
the stale four-callback and deferred-requirement claim search found no current
documentation claims. No material limitations were encountered.
## Stage 7: Validate the final module boundaries and complete the sprint
**Outcome:** the implemented feature works with its committed dependency graph,

23
docs/roadmap/requirements.md
View File

@@ -1,8 +1,8 @@
# PromptKit requirements inspection
Status: accepted feature roadmap; implementation has not started. Command
Status: accepted feature roadmap; implementation is in progress. Command
placement, public API, caller-variable syntax, and initial presentation are
settled.
settled. The implementation plan records delivery and final validation status.
The [implementation plan](implementation.md) owns the ordered delivery steps and
stage completion evidence.
@@ -35,24 +35,25 @@ is the authority for discovery semantics. Descriptions below explain how
CommandKit will expose that API, rather than establishing a separate discovery
specification.
## Current baseline
## Baseline at roadmap acceptance
Baseline: CommandKit commit
This table records the pre-implementation state at CommandKit commit
[`12b52b3`](https://gitea.maximumdirect.net/eric/CommandKit/src/commit/12b52b3174545d22960c91c3a782a151ab813447).
| Area | Current implementation | Gap to target |
| 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 | `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. |
| 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 [deferred-work record](deferred.md#promptkit-requirement-inspection) 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.
The former deferral is retained as an
[immutable historical record](https://gitea.maximumdirect.net/eric/CommandKit/src/commit/ee038df530bfd3518906dc77e8e8f55eef237dda/docs/roadmap/deferred.md).
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

18
integrations/ckprompt/README.md
View File

@@ -1,8 +1,9 @@
# CommandKit ckprompt
`ckprompt` is the optional PromptKit integration for CommandKit. It adapts
PromptKit engine configuration, native comparison, prompt/profile catalogs, and
named inspection. Importing it does not install either command family.
PromptKit engine configuration, native comparison, prompt/profile catalogs,
named inspection, and prompt requirements discovery. Importing it does not
install either command family.
## Module
@@ -19,12 +20,13 @@ Add `ckprompt.ConfigScope(loadEngine)` to the scopes passed to
`ckconfig.Command` when the application wants PromptKit engine configuration
and native comparison in the `config` family. Install
`ckprompt.Command(ckprompt.FromEngine(loadEngine))` separately for prompt/profile
catalogs and named inspections. `FromEngine` supplies all four PromptKit-backed
callbacks; applications may narrow them before capture or provide their own
callbacks with `ckprompt.Suite`. CommandKit-owned inspection and listing code
does not execute prompts or contact model providers; application loaders and
direct callbacks retain their own effects. See the
[CLI reference](https://gitea.maximumdirect.net/eric/CommandKit/src/branch/main/docs/cli.md#promptkit-definition-inspection)
catalogs, named inspections, and requirements discovery. `FromEngine` supplies
all five PromptKit-backed callbacks; applications may narrow, wrap, or replace
them before capture or provide custom callbacks with `ckprompt.Suite`.
Requirements is independently optional. CommandKit-owned inspection and
listing code does not execute prompts or contact model providers; application
loaders and direct callbacks retain their own effects. See the
[CLI reference](https://gitea.maximumdirect.net/eric/CommandKit/src/branch/main/docs/cli.md#promptkit-requirements)
for operator commands and report semantics. The maintained
[composed example](examples/composed) shows complete application wiring.

20
integrations/ckprompt/adapters.go
View File

@@ -36,7 +36,9 @@ type ProfileRequest struct {
type RequirementsRequest struct {
// Selection carries the configuration and overlay values supplied to the command.
Selection ckconfig.Selection
// Inspection carries PromptKit's discovery context for the selected prompt.
// Inspection forwards PromptKit's native prompt, version, profile, variable,
// and session discovery context. Optional version, profile, and session
// strings retain PromptKit's empty-value semantics.
Inspection promptkit.RequirementInspectionRequest
}
@@ -156,13 +158,15 @@ func promptKitContextError(ctx context.Context) error {
return ctx.Err()
}
// FromEngine supplies callbacks for prompt and profile catalogs, named
// inspections, and requirements inspection backed by a PromptKit engine loader.
// It does not call the loader during construction. Each selected operation
// passes its context, supplied selection, initialized input, and shared
// invocation state to the loader before calling PromptKit's public listing or
// inspection method. Applications can narrow these callbacks before Command
// captures them. A nil loader is retained as an adapter issue.
// FromEngine supplies prompt and profile catalog callbacks, named inspection
// callbacks, and a requirements inspection callback backed by a PromptKit engine
// loader. The requirements callback forwards RequirementsRequest.Inspection to
// Engine.InspectRequirements. FromEngine does not call the loader during
// construction. Each selected operation passes its context, supplied
// selection, initialized input, and shared invocation state to the loader before
// calling PromptKit's public listing or inspection method. Applications can
// narrow, wrap, or replace these callbacks before Command captures them. A nil
// loader is retained as an adapter issue.
func FromEngine[I, S any](load func(context.Context, ckconfig.Selection, I, S) (*promptkit.Engine, error)) Suite[I, S] {
if load == nil {
return Suite[I, S]{issues: []error{errors.New("PromptKit engine loader is nil")}}

6
integrations/ckprompt/command.go
View File

@@ -49,8 +49,10 @@ type variableAssignment struct {
// absent suite claims no namespace; attached construction issues remain
// reportable. It adds no configuration family; callers compose ConfigScope
// independently. Construction, installation, help, and version do not run
// suite factories or providers. Suite documents invocation input and state
// initialization, zero values, and caller ownership of returned objects.
// suite factories or providers. Command captures suite callbacks and selector
// metadata; callback-referenced objects and effects remain caller-owned. Suite
// documents invocation input and state initialization, zero values, and caller
// ownership of returned objects.
// Catalog commands accept config/overlay selection and suite selectors, and
// render YAML with `yaml` as the only format and default. Named-show formats are
// unchanged.

6
integrations/ckprompt/doc.go
View File

@@ -1,5 +1,5 @@
// Package ckprompt provides optional PromptKit configuration comparison,
// definition catalogs, and named inspections for CommandKit. Importing ckprompt
// installs neither family; callers compose its declarations with core and
// ckconfig explicitly.
// definition catalogs, named inspections, and prompt requirements inspection
// for CommandKit. Importing ckprompt installs neither family; callers compose
// its declarations with core and ckconfig explicitly.
package ckprompt

14
integrations/ckprompt/examples/composed/README.md
View File

@@ -1,8 +1,8 @@
# Composed consumer
This example composes application configuration, PromptKit configuration,
PromptKit comparison and catalogs, definition inspection, and one
application-owned command:
PromptKit comparison and catalogs, definition and requirements inspection, and
one application-owned command:
```sh
go run . config scopes
@@ -14,6 +14,8 @@ go run . promptkit list prompts --config fixtures/before.yml --campaign spring
go run . promptkit list profiles --config fixtures/after.yml --campaign autumn --format yaml
go run . promptkit show prompt briefing --campaign spring --format yaml
go run . promptkit show profile spring --campaign spring
go run . promptkit requirements show briefing --campaign spring
go run . promptkit requirements show briefing --campaign spring --var mode=full --format yaml
go run . session restore session-42 --campaign spring
```
@@ -38,3 +40,11 @@ supplied configuration/overlay selection and the supplied campaign, including
presence. The campaign override is applied through ConfigKit before loading.
These are choices for this example's loader and do not define a CommandKit cache
policy.
The first requirements command reports incomplete discovery: PromptKit records
the conditional `notes` input and a missing `mode` issue. Supplying `mode=full`
selects that branch, classifies the undeclared `notes` input as required, and
completes discovery. Both commands return successful reports; the result does
not execute the prompt or establish input, credential, or execution readiness.
See the [CLI reference](../../../../docs/cli.md#promptkit-requirements) for the
command and report contract.