commandkit/docs/roadmap/promptkit-v0.18.0.md

# PromptKit v0.18.0 adoption

Status: adoption scope recorded; implementation has not begun. Released
PromptKit v0.18.0 is the sole development target, as directed by the user.
[Scope decisions](#scope-decisions) record that dependency choice and the
selected example policy and capability scope. The
[implementation plan](implementation.md) owns staged work, validation commands,
and completion evidence; this document owns the desired state and scope.

## Purpose and authority

Adopt PromptKit's vanity module and current public APIs in the embedded
`ckprompt` integration, using the now-published ckconfig v0.3.0. Restore a
compatible three-module development workspace and composed consumer.

PromptKit and ConfigKit own their domain functionality and semantics.
CommandKit owns faithful adaptation, command selection and coordination,
presentation, and invocation outcomes. Expose upstream capabilities in a
neutral, consistent way, without adding independent guarantees or qualifying
upstream limitations. Application loaders retain engine construction and
configuration choices.

The [architecture](../policy/architecture.md), [agent](../policy/agents.md),
[testing](../policy/testing.md), [documentation](../policy/documentation.md),
[release](../policy/release.md), and [OSS](../policy/oss.md) policies govern the
work. Current behavior remains owned by Go declarations and GoDoc, the
[CLI reference](../cli.md), and the [consumer guide](../consumers/guide.md).
The shared inspection proposals in
[future work](future.md#configuration-inspection-extensions) retain their own
scope. This roadmap records how PromptKit could use that work and identifies
additional capabilities without selecting them as adoption requirements.

## Baseline and review evidence

Reviewed CommandKit revision: `eeae10fa0558bce8de963010fdcea2c40ef68691`.

| Component | Current state |
| --- | --- |
| ckprompt | `go.maximumdirect.net/ckprompt v0.2.0`; Go 1.26.0 minimum |
| PromptKit dependency | `gitea.maximumdirect.net/eric/promptkit v0.16.0` |
| ConfigKit dependency | `gitea.maximumdirect.net/eric/ConfigKit v0.8.0` |
| CommandKit dependencies | Core v0.3.0 and ckconfig v0.2.0 |
| Available ckconfig | v0.3.0, with vanity ConfigKit v1.1.0 and Go 1.27.0 |
| Maintainer toolchain | Go 1.27.0; root ReleaseKit v0.9.0 |

Direct module discovery verified PromptKit v0.18.0 at published commit
`d9f6aad30509e538fc73ea16710df3a3ec084502`. Its module requires Go 1.27.0 and
vanity ConfigKit v1.1.0. Published ckconfig v0.3.0 downloads through its vanity
path and selects that same ConfigKit identity. The current ckprompt still
selects ckconfig v0.2.0 independently and cannot compose with local ckconfig
v0.3.0 in the development workspace.

The upstream [v0.17 migration notes](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/d9f6aad30509e538fc73ea16710df3a3ec084502/docs/releases/v0.17.0.md),
[v0.18 release notes](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/d9f6aad30509e538fc73ea16710df3a3ec084502/docs/releases/v0.18.0.md),
and [configuration/API migration guide](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/d9f6aad30509e538fc73ea16710df3a3ec084502/docs/consumers/configuration-migration.md)
own the upstream changes crossed by this upgrade.

A disposable migration established the following, without changing repository
code or using local dependency replacements:

- Changing dependencies and imports alone fails at four production accesses to
  removed prompt-version metadata.
- After removing that metadata, production packages build on Go 1.27.0 against
  published ckconfig v0.3.0, ConfigKit v1.1.0, and PromptKit v0.18.0.
- After converting the composed example's PromptKit resources to identified
  lists, its profile catalog, source inventory, requirements inspection, and
  configuration validation run successfully. The native bundle appears in
  catalogs and as source evidence through ckconfig's current report path.
- The full suite still needs version-fixture, configuration-shape, and report
  expectation changes. These diagnostics do not establish completed adoption.

## API coverage and capability candidates

A follow-up review compared the published v0.18.0 API with ckprompt at
CommandKit revision `69cc642`. Existing report shapes cover the current prompt,
profile, requirements, catalog, and smoke inspection results after removing
obsolete prompt-version fields. Smoke reports already carry the native facts,
timing, attempts, and usage; the review found no additional report fields to add
in those operations.

Three capabilities merit consideration beyond compatibility migration:

| Capability | Current integration | Recommendation and scope decision |
| --- | --- | --- |
| Configuration metadata and history | Native `ConfigurationInspection.Metadata()` returns ConfigKit metadata. `ConfigScope` connects effective configuration, sources, explanations, and comparison, but has no metadata facet. | Extend the shared optional ckconfig capability first, then connect PromptKit's native metadata. Keep this as the next shared enhancement following adoption; see OD-3. |
| Prepared-request inspection | Native `Engine.Prepare` returns a `PreparedRun` snapshot. ckprompt exposes concrete request validation but has no operation returning preparation results. | Consider an optional provider capability and report as the next substantive ckprompt enhancement. This extends standard inspection into rendering and needs an explicit scope choice; see OD-4. |
| Namespace selection helpers | Native `Engine.WithNamespaces` supplies separate prompt, profile, and backend namespace defaults for unqualified selections. Applications can already return that view from an engine loader. Existing standard namespace selectors filter catalogs. | Begin with documented loader wiring; consider reusable helpers or standard selectors when consumers demonstrate repeated wiring. Keep name resolution distinct from catalog filtering; see OD-5. |

The released [configuration inspection API](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/d9f6aad30509e538fc73ea16710df3a3ec084502/configuration_inspection.go),
[preparation API](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/d9f6aad30509e538fc73ea16710df3a3ec084502/engine.go),
[prepared snapshot](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/d9f6aad30509e538fc73ea16710df3a3ec084502/types.go),
and [namespace API](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/d9f6aad30509e538fc73ea16710df3a3ec084502/namespaces.go)
own those capabilities. They are available in v0.18.0; this review does not imply
that each was introduced in that release.

Request execution and output-validation overrides, session IDs, appended
messages, and retry settings are already reachable through application request
builders. Engine construction and bundle options remain available through
loaders. Consider reusable bindings where consumers repeat the same wiring;
adoption does not require a standard flag for every native option.

`Run`, `PrepareExecution`, `RunPrepared`, and execution observers serve the
application-owned execution workflow. Prepared-request inspection can use
`Prepare` without adding model generation or prepared-handle lifecycle to the
standard suite. Execution, serving, and session operations retain their current
ownership. OD-4 addresses only the proposed rendering-inspection extension.

## Targeted end state

### Modules and Go compatibility

Prepare ckprompt v0.3.0 against this released dependency set under OD-1:

| Requirement | Target |
| --- | --- |
| PromptKit | `go.maximumdirect.net/promptkit v0.18.0` as released |
| ConfigKit | `go.maximumdirect.net/configkit v1.1.0` |
| ckconfig | `go.maximumdirect.net/ckconfig v0.3.0` |
| Core | Retain `go.maximumdirect.net/commandkit v0.3.0` |
| ckprompt consumer minimum | Go 1.27.0 |

Production code, tests, and the maintained composed example use the matching
vanity identities. Public callbacks and provider values exchange those types
consistently. Authentic module metadata and sums select released dependencies;
an old-path bridge or a permanent local replacement is unnecessary.

Core remains independent of the optional libraries and retains its own Go
minimum. The already-migrated ckconfig and root ReleaseKit selection need no
upgrade for this target. The existing Go 1.27.0 maintainer toolchain is suitable.

### Existing commands and faithful report adaptation

Keep the existing engine adapters, five catalogs, named inspections, requirements
discovery, request validation, smoke testing, and configuration scope/comparison.
The reviewed public methods remain suitable; adopting v0.18.0 does not require
a new command family or a second domain implementation.

Remove the descriptive prompt-version output that upstream removed:

- Prompt-catalog entries retain prompt ID and lose their optional `version`.
- Prompt inspection and requirements inspection lose their `version` member;
  prompt text inspection also loses the prompt-version line.
- Smoke-target reports lose their optional prompt `version` member.

Remove the associated DTO fields and projection logic rather than manufacturing
replacement values. Prompt IDs and opaque hashes retain their native meanings.
Collection release labels, source specification headers, and unrelated
application version fields are distinct and retain their owning semantics.
This is a deliberate pre-v1 report/API migration, described in the release note.

Configuration inspection now supplies recorded normalized values and derived
defaults through ConfigKit v1.1.0. Existing config reports, explanation, and native
comparison expose that evidence through ckconfig v0.3.0, including source
fallback, version evidence, and empty-import selections. Preserve the returned
history and values; do not reconstruct the former authored-only view. Native
effective-value diffs retain atomic lists. Configuration inspection, profile
inspection, and request preparation remain their respective upstream views.

### Configuration, bundle behavior, and maintained consumers

PromptKit-owned root and collection `prompts`, `profiles`, and `backends` use
lists with explicit `id` values. Calls to `ProfileSource` and `BackendSource`
use ordered record slices. Inheritance and configuration-inspection paths
match the adopted shapes. Consumer guidance links to upstream for whole-record
replacement, source-root `config` controls, import requiredness, and optional
version-2 specification headers.

Remove maintained-example plumbing whose only role was carrying PromptKit's
removed descriptive version. Preserve independently meaningful application
fields and collection `release_version` labels. Do not globally delete every
configuration member named `version` or rewrite application schema versions.

PromptKit v0.18.0 includes a default-on OpenRouter backend and seventeen root
profiles as a lowest-priority underlay. Catalogs, namespaces, configuration, and
source reports follow the supplied engine's native inventory. The integration
does not silently filter those definitions or disable the bundle. Applications
can select `WithBundledOpenRouter(false)` in their own engine loaders.
Under OD-2, retain the default bundle in the maintained composed example.
Focused fixture loaders may explicitly opt out when their purpose requires a
minimal application-only inventory. Include focused coverage showing that
bundled records and their source evidence reach CommandKit output; assertions
about application records alone would not detect accidental bundle filtering.
Use returned native evidence without duplicating the full bundled catalog or
fixing expectations to its count.

Existing offline test and smoke-example boundaries remain applicable. Use
explicit native selections and injected clients/transports as appropriate to
the fixture; account for bundled diagnostic fallback rather than accidentally
directing a default test at a live provider. This changes fixture wiring, not
the native capabilities made available to operators.

### Workspace, documentation, and release preparation

Independent module validation uses the real downloaded dependency graph with
workspace discovery off. The ignored workspace composes root, ckconfig, and
ckprompt with a Go version supporting its Go 1.27.0 members. Development guidance
describes the aligned workspace, and the maintained composed consumer works
with both the declared releases and the local module set.

Current GoDoc, CLI reports, README/module-selection guidance, maintained example
instructions, and attribution describe the implemented dependency set and
migration. Preserve published notes and historical records. Prepare a ckprompt
v0.3.0 note and full tag `integrations/ckprompt/v0.3.0`, subject to the existing
fresh-version guards. A pre-v1 minor accommodates the deliberate type-identity,
configuration, report, and minimum-Go changes.

Publication and hosted Gitea delivery remain separate operations under the
[release procedure](../release.md). Preparing this roadmap does not publish a
version or select new release gates.

## Scope boundaries

The adoption covers dependency, API/report, fixture, and workspace alignment
plus namespace-loader guidance. Core APIs and its Go minimum remain unchanged.
Shared metadata, prepared-request inspection, and reusable namespace helpers or
standard selectors are deferred to
[future work](future.md#promptkit-inspection-and-selection-extensions).
The shared detailed-comparison, failed-load-inventory, and structured-diagnostic
proposals remain separate too. Ordered work belongs in the
[implementation plan](implementation.md).

## Released upstream baseline

Develop and validate only against PromptKit v0.18.0 as released. Unreleased
upstream branches, sibling-checkout changes, audit notes, and proposed fixes do
not inform this adoption's implementation, scope, or release criteria. The
migration does not wait for upstream development or introduce local workarounds
for anticipated changes.

PromptKit v0.19.0 may be reviewed once it is available as a published release.
That is a separate dependency review of its released contracts and changes;
it does not automatically change this roadmap's v0.18.0 target. No investigation
or monitoring of unreleased work is part of this adoption.

## Scope decisions

OD-1 records the user's explicit dependency direction. OD-2 through OD-5 record
the selected scope for this sprint; deferred capabilities still require
focused API and CLI design. These decisions do not describe implemented features
or authorize publication.

| Decision | Disposition | Implementation consequence |
| --- | --- | --- |
| OD-1: Upstream baseline | Develop only against released PromptKit v0.18.0. Review v0.19.0 separately once published. | Use the pinned released dependency set; do not consider unreleased upstream work or wait for it. |
| OD-2: Example bundle policy | Retain the upstream default bundle in the composed example; opt out explicitly in focused minimal fixtures. | Verify bundled records and source evidence reach output, without asserting the complete catalog or count. Keep smoke fixtures on explicit offline targets. |
| OD-3: Shared metadata | Defer to the next shared functional sprint. | Design the optional ckconfig capability first, then forward PromptKit's native metadata. Retain ckconfig v0.3.0 for adoption. |
| OD-4: Prepared-request inspection | Defer to a separate design decision after adoption and shared metadata. | Select report content and the rendering scope explicitly before adding a provider or command. |
| OD-5: Namespace support | Include loader guidance now; defer reusable helpers and standard selectors. | Explain independent namespace defaults and keep unqualified-name resolution distinct from catalog filtering. |

The [future capability record](future.md#promptkit-inspection-and-selection-extensions)
owns the deferred PromptKit feature proposals and their design considerations.
Application loaders continue to own engine construction and bundle choices;
request builders continue to expose native request options without requiring a
standard flag for each one.

## Acceptance criteria

The final integration uses the selected released vanity dependencies and Go
minimum throughout production, tests, and the composed example. Its existing
operations faithfully expose the adopted upstream results, with descriptive
prompt-version fields removed and unrelated version meanings retained.

Maintained configuration uses the adopted resource shapes. The composed example
retains the native bundle; CommandKit output carries its records and source
evidence, and the default test suite and maintained smoke examples stay offline. The three modules compose in
the local workspace while independently validating against declared releases.

Current contracts, consumer and namespace-loader guidance, notices, and the
ckprompt v0.3.0 candidate note describe that implemented state. Workspace files
and local dependency replacements are absent from release inputs. Source
publication and hosted delivery remain separate under the existing release
procedure. The [implementation plan](implementation.md#stage-7-validate-the-final-modules-and-workspace-then-close-the-sprint)
owns concrete checks and their final evidence; the earlier disposable review
is preliminary evidence only.