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

Settle PromptKit requirements inspection roadmap

Browse Source
This commit is contained in:
Eric Rakestraw
2026-10-12 16:34:56 +00:00
parent fa0cd9a73b
commit 49b7e686b3
1 changed files with 125 additions and 105 deletions
Download Patch File Download Diff File Expand all files Collapse all files

230
docs/roadmap/requirements.md
View File

@@ -1,9 +1,8 @@
# 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](#open-decisions).
Status: accepted feature roadmap; implementation has not started. Command
placement, public API, caller-variable syntax, and initial presentation are
settled.
## Purpose and authority
@@ -22,13 +21,15 @@ The [architecture policy](../policy/architecture.md),
[outcome decision](../adr/0005-invocation-outcomes.md),
[module boundary decision](../adr/0010-optional-integration-modules.md), and
[declaration and input decision](../adr/0011-captured-declarations-and-installation.md)
control this work. This roadmap proposes an additional PromptKit operation;
ADR 0004 does not already specify its command spelling.
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](https://gitea.maximumdirect.net/eric/promptkit/src/commit/143c6e9b3a675872117b0471e2ff8bcb25055a54/requirements.go)
is the authority for discovery semantics. Descriptions below explain how
CommandKit would expose that API, rather than establishing a separate discovery
CommandKit will expose that API, rather than establishing a separate discovery
specification.
## Current baseline
@@ -67,7 +68,7 @@ Use the existing public facade and internal backend boundary.
## Target operator surface
Recommended operation:
Selected operation:
```sh
app promptkit requirements show PROMPT_ID
@@ -75,26 +76,52 @@ app promptkit requirements show briefing --version 2 --profile editorial --var a
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.
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.
| Proposed input | Meaning |
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 recommended initial report format, also the default. |
| `--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. The exact variable grammar and
report format remain recommendations in the decisions below.
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
@@ -130,7 +157,7 @@ Apply the established outcomes to actual failures:
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
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
@@ -141,11 +168,32 @@ 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.
Add this request type in ckprompt:
```go
type RequirementsRequest struct {
Selection ckconfig.Selection
Inspection promptkit.RequirementInspectionRequest
}
```
Extend `Suite[I, S]` with this optional callback field:
```go
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
@@ -172,10 +220,12 @@ 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
## Initial report
Use YAML only initially, with a CommandKit-owned report representation rather
than serialization that relies on incidental Go field names. Proposed fields:
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 |
| --- | --- |
@@ -209,15 +259,50 @@ variables:
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:
```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: 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; this example does not define PromptKit discovery behavior.
the final schema; these examples do 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
Add `RequirementsRequest`, 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.
@@ -241,14 +326,16 @@ acquisition diagnostics and readiness claims.
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
request forwarding, the selected variable-parsing cases, 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
Extend the maintained composed consumer with fixtures that demonstrate a partial
inventory and how supplying discovery context changes it. Show that both
successfully delivered inspections return status `0`. 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.
@@ -256,11 +343,10 @@ infrastructure, performance guarantees, or release gates.
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.
Reconcile the deferred-work entry with this feature's actual status. The new
operation fits the existing ownership and registration boundaries and requires
no new ADR. Leave ADR 0004 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,
@@ -279,70 +365,4 @@ 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.
The decisions needed for an implementation plan are settled.