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

PromptKit v0.18.0 adoption

Status: proposed; implementation has not begun. This roadmap captures the ckprompt migration and workspace alignment target. PromptKit v0.18.0 is the reviewed working baseline. Final release selection, the maintained example's bundle policy, and optional capability scope have recommendations under Open Decisions; those choices remain open.

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, agent, testing, documentation, release, and OSS policies govern the work. Current behavior remains owned by Go declarations and GoDoc, the CLI reference, and the consumer guide. The shared inspection proposals in future work 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, v0.18 release notes, and configuration/API migration guide 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, preparation API, prepared snapshot, and namespace API 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 with this dependency set, subject to OD-1 for the final PromptKit release pin:

Requirement	Target
PromptKit	go.maximumdirect.net/promptkit v0.18.0 as reviewed baseline
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

Migrate PromptKit-owned root and collection prompts, profiles, and backends to lists with explicit id values. Convert calls to ProfileSource and BackendSource to ordered record slices where used. Update inheritance and configuration-inspection paths to the new shapes. Link consumer guidance 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. OD-2 addresses that choice for the maintained composed example and fixtures.

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. Once ckprompt's types align, the ignored workspace can again compose root, ckconfig, and ckprompt, with a workspace Go version that supports its Go 1.27.0 members. Restore aligned-workspace development guidance and validate the maintained composed consumer with that local module set too.

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. Preparing this roadmap does not publish a version or select new release gates.

Work from the baseline

1. Record the working dependency baseline and resolve OD-2's example policy; carry OD-1's final shipping choice into release preparation. Prepare the ckprompt dependency/import and Go-minimum changes with the selected Go 1.27 toolchain, then tidy and inspect authentic metadata with workspace discovery off. Review the effective graph for attribution, including tool requirements.
2. Update native API uses and remove prompt-version DTOs, output, and obsolete version-only tests. Preserve meaningful adapter assertions and the remaining report fields, provider capabilities, diagnostics, and outcome coordination.
3. Migrate maintained configuration fixtures, programmatic resource builders, inheritance references, list-index paths, and composed-example plumbing. Apply the selected bundle policy explicitly in fixture-owned loaders.
4. Update focused tests for request forwarding and faithful native-result projection. Account for normalized inspection values and native inventories; test the CommandKit adaptation rather than independently establishing bundle contents, normalization rules, inheritance, or provider behavior.
5. Run the full ckprompt suite and maintained example tests against its own declared dependencies. Validate the restored local workspace and composed consumer, and perform appropriate core/ckconfig regression checks. Preserve checks of help/preflight acquisition, selectors, aliases, repeated invocation state, cancellation, writer failures, and supported native error identity.
6. Update current contract owners, dependency notices and pinned license/source references, and the candidate release note. Review links, examples, and whitespace. Record final validation and publication status separately from the earlier disposable review evidence. Under OD-5's recommendation, include native namespace-view loader guidance while keeping standard selector design separate.

The native adapter structure remains the starting point. OD-3 through OD-5 are unselected scope choices, not additional adoption completion conditions. The recommended sequence is dependency/report and workspace migration, then shared metadata inspection, followed by separately selected prepared-request inspection. Namespace loader guidance can accompany migration documentation. The detailed-comparison, failed-load-inventory, and structured-diagnostic proposals in future work remain separate too. If capability scope is expanded into this release, revise the dependency target, implementation work, validation, and release documentation to match that decision before implementation.

Upstream remediation boundary

Post-release audit notes in the sibling PromptKit checkout identify issues in the same production source as v0.18.0. Relevant examples include unrestricted authentication-response buffering in the native authentication probe and inference request-construction errors reported as concluded diagnostics by the native smoke tester. Those findings inform OD-1; the disposable CommandKit review did not reproduce the full upstream audit set.

Keep domain corrections upstream. This adoption does not add local response limits, duplicate request validation, or replacement error classification to compensate for those defects. Evaluate any published corrective release for compatibility and adapt to its public contract using ordinary change review.

Open Decisions

OD-1: Ship on v0.18.0 or await relevant upstream corrections?

Recommendation: develop the migration now against the published v0.18.0 baseline and prefer a published corrective release addressing the relevant native diagnostic issues for the final shipping pin. That keeps integration work concrete while keeping fixes with their upstream owner. Taking a newer release requires reviewing its actual changes and rerunning affected checks; waiting for corrections can delay ckprompt publication. Whether to publish on v0.18.0 if those corrections are not yet available remains a release choice.

Viable alternative: finish and publish the ckprompt migration with exactly v0.18.0 using the existing release workflow, then adopt an upstream correction separately. This restores the compatible module set without an upstream-dependent schedule. It ships with the recorded native defects still present and requires a later dependency update. Neither option selects local workarounds or makes completion of every upstream audit finding a new release prerequisite.

OD-2: Which bundle policy should the maintained example demonstrate?

Recommendation: retain upstream's default bundle in the composed example and make catalog/report assertions about the application-defined records and returned native evidence rather than duplicating the complete bundled catalog. Use explicit opt-out in focused fixture loaders when their purpose is a minimal application-only inventory. This demonstrates the current native default while keeping adapter tests focused. Example inventories and list-index paths need updating, and offline smoke wiring must still select the intended fixture target.

Viable alternative: opt out explicitly in the composed example with WithBundledOpenRouter(false). This is a supported application-loader choice that keeps the example's inventory small and its resource positions simple. It does not demonstrate the default-on inventory; documentation should state the example's choice, and focused adoption coverage should still show that the integration exposes a default-constructed engine's returned bundle evidence.

OD-3: Include shared metadata inspection in adoption or a later sprint?

Recommendation: retain metadata inspection as the next shared functional sprint after dependency adoption. The configuration inspection proposal owns the field metadata, path discovery, and history scope. Design the optional ckconfig provider capability and reports once, then connect PromptKit's native Metadata() result. Existing providers remain usable without the new facet. Preserve upstream field presence, explicitness, origins, and history, including history for removed paths; do not recreate provenance logic within ckprompt.

Viable alternative: include the shared capability and PromptKit wiring in this adoption release. That expands the work beyond dependency alignment and requires a newly released ckconfig version containing the capability, replacing the current v0.3.0 target. Command grammar, selectors, report shapes, and provider design remain open under the shared proposal. The adoption can ship without this extension while retaining ckconfig v0.3.0.

OD-4: Add prepared-request inspection to the standard suite?

Recommendation: treat this as the next substantive ckprompt enhancement after adoption and shared metadata inspection, with an explicit decision to extend standard inspection into rendering. Add an optional provider capability and report based on native Engine.Prepare and PreparedRun, reusing the concrete request-builder pattern. The native snapshot supplies selected prompt/profile/backend IDs, effective execution settings, rendered messages and session ID, output contract and schema metadata, input and rendered hashes, and preparation timing without calling an LLM. PromptKit owns preparation semantics.

Command grammar, callback shape, selected report content and formats, and the relationship to existing request validation remain open. Any selected feature needs acquisition/availability, request forwarding, native-result projection, and report-delivery coverage at CommandKit's boundary; upstream retains tests of preparation and rendering. Selecting snapshot inspection would not select model execution or prepared-handle management.

Viable alternatives: retain preparation inspection in application-owned commands, or deliberately include the optional feature in ckprompt v0.3.0 after resolving that design. The latter expands the release scope and validation; neither alternative requires local template resolution or a parallel preparation implementation. No new command or provider contract is selected here.

OD-5: Document namespace views or add standard selection support?

Recommendation: begin with consumer guidance showing an application engine loader returning Engine.WithNamespaces with independently chosen prompt, profile, and backend defaults. Applications can already combine their typed selectors and loaders for this purpose. Include that guidance with migration documentation; consider a reusable helper or standard selectors when concrete consumers show repetition that CommandKit could remove.

Namespace views resolve unqualified caller selections. Qualified selections retain their native treatment; captured configuration references and global configuration inspection are not rewritten, and namespace/collection inventories remain global. Existing catalog filtering keeps its current meaning.

Viable alternative: design standard namespace-selection bindings or a helper as part of this release. The public API, applicable operations, independent resource defaults, and interaction with catalog filtering would need explicit decisions and focused forwarding coverage. No new flag names or changed meaning for existing namespace filters are selected by this roadmap.