commandkit/docs/roadmap/upgrades.md

ConfigKit, PromptKit, and ReleaseKit adoption

Status: adoption roadmap; implementation has not started. The release targets, adoption order, and OD-1 through OD-4 are accepted. Smoke testing is included in the current scope. This document defines the desired end state and required work; a separate implementation plan will sequence coding tasks.

Purpose and authority

Adopt ReleaseKit v0.4.2, ConfigKit v0.8.0, and PromptKit v0.16.0 while providing useful operator access to their capabilities. The organizing principle remains: CommandKit provides useful, consistent access to capabilities owned elsewhere.

CommandKit owns vocabulary, registration, selection, coordination, presentation, and invocation outcomes. Integrated libraries own configuration composition, resource identity and resolution, validation, inspection evidence, and diagnostic meaning. Applications choose their inputs, policies, defaults, credentials, artifacts, and runtime construction.

Keep adaptation proportionate to that ownership. Reports are direct projections of upstream data, with small presentation DTOs where YAML naming and formatting need them. Preserve native values and meanings rather than introducing a parallel semantic model or normalization layer.

The architecture policy, accepted ADRs, and release policy govern this work. Upstream contract changes flow through the owning integration; they do not justify reimplementing removed behavior in CommandKit. The existing API and CLI references describe the current implementation until these changes land.

Baseline and reviewed releases

The CommandKit baseline is 5f633e3feea71f623e5e378a7df476ff7e811e5e.

Dependency	Current baseline	Target	Owning CommandKit area
ReleaseKit	Root tool requirement v0.4.0; integration graphs currently select v0.4.1	v0.4.2	Root tool pin, launcher integration, release documentation, and notices
ConfigKit	v0.7.1 in both integrations	v0.8.0	ckconfig adaptation and reports; ckprompt's direct dependency
PromptKit	v0.15.0	v0.16.0	ckprompt adapters, standard commands, reports, and composed consumer

The root module owns generic commands, dispatch, bindings, help/version, and outcomes. ckconfig owns the configuration family. ckprompt currently supplies prompt/profile catalogs, named inspection, requirements discovery, and concrete request validation; its engine configuration scope is composed through ckconfig.

The completed requirements roadmap, implementation plan, and remediation record remain historical evidence for the delivered baseline. This roadmap describes new work and does not restart those completed assignments.

Reviewed upstream references:

Release	Source commit	Release record
ReleaseKit v0.4.2	7d033c5ca1c95aec7db9690293638a0a1ac887b8	Release notes
ConfigKit v0.8.0	137769f3f18a370c68444242fb5d88e620e307e5	Release notes
PromptKit v0.16.0	9178f3eb91c2b2138caa78e22be93c048b4bc992	Release notes

All three releases retain Go 1.26.0 as their consumer minimum. The adoption does not require changing CommandKit's Go minimum or selected release toolchain.

Adoption order and delivery boundaries

Order	Adoption	Reason
First	ReleaseKit v0.4.2	A small, independent maintainer-tool update establishes the selected tool before integration migration.
Next	ConfigKit v0.8.0, including richer source inspection	Supplies the prerequisite for PromptKit v0.16.0 and exposes useful native evidence through ckconfig.
Then	PromptKit v0.16.0 API/configuration migration	Removes obsolete version selectors and bundled-catalog assumptions across ckprompt.

Expanded PromptKit discovery and explicitly invoked smoke testing are included after its base migration. These are product/dependency relationships, not a staged implementation plan or a requirement for separately releasable intermediate commits. ConfigKit and PromptKit can be handled in one coordinated sprint.

ReleaseKit has no runtime ordering dependency on the other two. ConfigKit must be adopted before, or atomically with, PromptKit: Go module selection would otherwise introduce v0.8.0 transitively while ckconfig still declares v0.7.1. Keep both integrations' direct ConfigKit requirements aligned with the adopted version and verify their independent module graphs.

Publication remains source-only and follows the existing core, ckconfig, ckprompt dependency order for affected releases. CommandKit module versions remain independent of upstream version numbers. Explain intentional public API/CLI changes under the existing pre-v1 compatibility policy; select concrete release versions during release preparation.

Target state: ReleaseKit v0.4.2

The root Go tool requirement selects ReleaseKit v0.4.2. The existing launcher, three module profiles, shared-file selection, and source-publication procedure continue using its supported public contracts. No application command family or runtime ReleaseKit import is added.

v0.4.1 changed upstream test synchronization. v0.4.2 corrected maintained Woodpecker delivery workflows for annotated-tag-object events; their event and tag IDs are resolved to commits before verification and delivery. CommandKit has no copied Woodpecker delivery workflow and publishes no hosted deliverables, so adopting this patch does not require adding either.

Required work includes the root requirement/checksums, selected-graph notices, the version named in the release policy, and version/commit references in the maintainer release procedure. Review the launcher and release integration against the unchanged CLI/profile contracts; a script/profile redesign is not expected. The ignored .releasekit/ directory remains local bootstrap storage.

If a delivery workflow is introduced later, start from the corrected maintained example: changing a module pin does not update copied YAML. This adoption does not add delivery automation or new publication gates.

Target state: ConfigKit v0.8.0

Native behavior and ownership

Both integration modules use ConfigKit v0.8.0. Its input destinations, relative import destinations, sequence-item placement, shared source-version checking, and registered identified-sequence composition are available to application loaders through upstream public options and definitions.

CommandKit does not need a parallel composition layer or new generic flags to select those policies. Applications decide whether to enable source-version checking, which declarations to accept, and which sequences use identity-based composition. Existing ConfigKit defaults preserve prior loading behavior.

Source inspection

Extend config sources in text and YAML with useful native destination, placement, unresolved-destination, and source-version declaration evidence. The current source DTO omits all four. Preserve its existing source fields and native inventory order. The accepted representation is recorded in OD-1.

Project the native fields and their values directly into the report, including version_check corresponding to SourceInfo.VersionCheck. Use ConfigKit's returned, sanitized evidence and describe its fields neutrally. ConfigKit owns the meaning and disclosure of that evidence.

config explain continues to expose the native explanation/history contract; the new SourceInfo fields do not require adding a source inventory to every explanation. Compact diagnostic source legends can continue identifying sources by ID, label, and filesystem path.

Required adaptation

Update both dependency graphs, owning notices, native fixtures, and affected consumer guidance. Review unkeyed literals and any equality/map-key assumptions: ConfigKit's expanded SourceInfo contains a Path and is no longer comparable. Its release notes describe this source-compatibility change. The existing provider model need not be redesigned merely to adopt these additions.

Target state: PromptKit v0.16.0

ID-based prompt selection and descriptive labels

ckprompt uses native ID-only prompt selection. Remove the prompt-specific --version flag from named prompt inspection, requirements show, and requirements validate. Remove PromptRequest.Version and obsolete version-selector plumbing; use InspectPrompt(ctx, promptID) and the revised native request types. Application version reporting remains governed by its existing identity contract.

Version labels remain useful metadata. Update inspection/catalog report DTOs for the native optional representation. Use version for a prompt or collection's reported version, omit the field when absent, and retain "" when explicitly empty, as accepted in OD-2. Selection continues to use the native ID-only API.

The standard requirements operations continue delegating discovery and concrete preparation to PromptKit. Partial discovery remains a successful inspection; native validation remains authoritative for a constructed request. The existing typed input/state, nil-builder path, callback capture, error identity, and delivery behavior apply through the revised API.

Explicit configuration and collections

Replace version-keyed prompt fixtures with one definition per prompt ID. Where an application formerly supplied multiple definitions under one ID, it chooses which definition to install or gives distinct resources distinct IDs. PromptKit's optional resource labels do not make that deployment choice.

Treat a root configuration version as the upstream source specification header, distinct from a prompt's descriptive version or a collection's release_version. Their meaning and any configured acceptance checks remain with the owning library and application.

Supply backend/profile resources explicitly where needed. Remove assumptions about installed provider catalogs and the former built-in standard/auto profiles. CommandKit must not silently reintroduce those catalogs. The owning application chooses files, embedded inputs, programmatic mappings, and collections.

Keep the maintained composed consumer migration small: update its configuration, loader, request builder, and fixtures as needed for direct definitions and the new interfaces, without requiring a model service. Use a small configuration to illustrate the relevant wiring and identities; a comprehensive collections example or migration framework is not required. Collections are available through native CollectionInput and configuration sources; applications need not use them to adopt v0.16.0.

Configured references retain their native exact identities. Mounting a source does not rewrite backend/profile references or extend profile inheritance beyond its native scope. Migration guidance should link to the upstream configuration/API migration guide.

Expanded operator discovery

After the base migration, extend the existing optional family with:

Operation	Native capability
app promptkit list backends	Engine.ListBackends
app promptkit list namespaces	Engine.ListNamespaces
app promptkit list collections	Engine.ListCollections

Keep prompt/profile listings and add native namespace filtering where applicable. These capabilities remain independently optional; one missing inventory does not disable other operations. Reuse the existing construction, registration, typed input/state, configuration selection, and diagnostic machinery.

Forward native namespace filters and resource-kind selections to their respective APIs. PromptKit performs identity resolution and inventory membership selection; the adapter translates the selected CLI syntax into those native inputs.

The namespace behavior has two distinct owners:

• An application loader may return a native WithNamespaces engine view. That view controls short caller-ID resolution and default resource listing scopes.
• An explicit native listing filter overrides membership selection for one listing call. It does not change the engine view or rewrite configuration.

Omitted filters retain native defaults: the corresponding resource view scope, or all identities when unscoped. Namespace and collection inventories remain global under the upstream contract. Reports show native identities and versions. OD-3 records the accepted request/API and CLI filter choices.

Explicit smoke testing

Expose PromptKit's Engine.SmokeTest through an independently optional command in this roadmap. Forward a native SmokeTestRequest and present the returned SmokeTestReport, including native reachability, authentication, text inference, or structured-output observations, timing, and available usage as applicable. Reuse the suite's typed input/state, configuration selection, and engine acquisition paths. Keep request construction and report presentation close to the native public API.

Retain a returned report when the native call also returns an error, preserving supported error identity and reporting output-delivery failures through the existing outcome model. A nil native error and successful report delivery mean success; native invocation errors receive the normal operational failure classification. Present native observations without deriving an additional readiness verdict or adding warnings about perceived upstream limitations.

Use a focused report-delivery path that preserves a returned report alongside its native error, including cancellation. The existing success-only inspection writer cannot be reused unchanged for that case. Adapt delivery within the current outcome model; this work does not require a general diagnostics framework.

Smoke testing runs when its command is explicitly invoked. Configuration, requirements, help, and release operations retain their own existing behavior. OD-4 records its inclusion in the current delivery scope; a separate feature roadmap is unnecessary. The broader deferred proposals in deferred work do not defer this selected native capability.

Work across the integrations

Dependencies and attribution

Update the owning module requirements and real checksums for the selected releases. PromptKit v0.16.0 drops its bundled backend-catalog dependencies; remove obsolete indirect requirements, sums, and notices when absent from the resulting CommandKit graphs. Do not replace them with implicit catalog loading.

Keep root and integration attribution entries matched to their actual selected graphs. ConfigKit and PromptKit still declare ReleaseKit v0.4.1 upstream; a CommandKit graph may select v0.4.2 through its own core dependency. Record the effective selection rather than blindly assigning the root tool version to every module. Verify pinned license/notice source links for each adopted release.

Core remains independent of optional ConfigKit/PromptKit dependencies, including through examples, tests, and tools. Committed builds use released public modules, not adjacent checkout replacements.

Documentation and compatibility

Update GoDoc, the CLI reference, consumer guidance, maintained examples, internal inventory, and release-tool references as their owning implementations land. Document changed prompt configuration, ID-only selection, optional label data, source evidence, new discovery behavior, and smoke testing under their canonical owners.

The accepted architecture already supports independently optional operations and native-library authority. Adding these optional capabilities and following upstream selection semantics fit those accepted boundaries. Any concrete new architectural decision is evaluated under the ADR policy.

Retain historical release records. Explain incompatible ckprompt changes in an appropriately versioned future module release. New source-report fields and catalog and smoke capabilities also need accurate CLI/API release notes. This roadmap does not require a CommandKit version to mirror any upstream version.

Evidence for the eventual implementation

The implementation plan should test CommandKit-owned interfaces and adaptation under the upstream testing ownership policy. Verify that command inputs and context reach the intended native APIs, including ID-only prompt requests, default/explicit listing filters, and smoke requests. Verify faithful representation of upstream-returned source evidence, optional labels, inventories, diagnostics, and errors, together with CommandKit's optional command availability, invocation lifetimes, outcome classification, and output delivery. Include smoke report-plus-error delivery and error identity in this boundary coverage.

These checks establish CommandKit's access to the capabilities. They should not test whether ConfigKit correctly places or composes sources, checks versions, or classifies sensitivity, nor whether PromptKit correctly resolves namespaces, discovers requirements, or validates concrete requests. Those domain tests belong to the upstream libraries. Real upstream fixtures and maintained offline consumers can exercise CommandKit's boundary without duplicating native feature test matrices. Existing release-launcher coverage likewise owns CommandKit's tool invocation, not ReleaseKit's publication algorithms.

Verify all affected modules both in the local workspace and with their own readonly dependency graphs. Temporary replacements for unpublished CommandKit prerequisites may support development checks; they are not evidence for a sibling-replaced upstream dependency or committed build requirements. The developer guide owns the established module-check practices.

New tests should protect selected contracts without requiring incidental factory activity after failure, complete diagnostic text snapshots, YAML key ordering, or arbitrary copies of caller-owned objects. The migration, discovery, and smoke adapter checks can use offline fixtures and test doubles; smoke tests verify request forwarding and report/error adaptation, leaving provider behavior to PromptKit.

Accepted Decisions

OD-1: Representation of the added source evidence

Accepted: Extend both existing source formats with destination using ConfigKit's canonical JSON Pointer string (root is ""), placement using native mode names, destination_unresolved, and version_check corresponding to SourceInfo.VersionCheck.

Preserve the native nested evidence: path, version presence/null/text, optional source location, and redaction flag. Use native sanitized values and maximize API-to-report correspondence. Field descriptions explain the returned data neutrally, without promising additional checker behavior or warning about perceived upstream limitations.

OD-2: Optional versions in reports

Accepted: Report a prompt or collection's version as version. Omit this optional field when the native value is absent; retain "" when it is present and empty. For collections, this projects the native ReleaseVersion value. Use the same naming and presence treatment across the affected reports.

Version metadata retains its upstream meaning. ID-only selection and source configuration headers remain governed by their respective native APIs.

OD-3: Catalog requests and namespace-filter syntax

Accepted: Use narrow ckprompt-owned request envelopes carrying configuration selection and native promptkit.NamespaceFilter for prompt, profile, and backend catalogs. Give namespace enumeration its native resource-kind selection, and leave collection enumeration aligned with its unfiltered native API. Revise existing catalog callback shapes coherently rather than retaining parallel filtered/unfiltered variants solely for the prototype API.

For applicable listing commands, map operator input directly to native filters:

Operator input	Native filter mode
No namespace option	NamespaceDefault
--namespace NAME	NamespaceNamed with the supplied name
--namespace ""	NamespaceUnqualified
--all-namespaces	NamespaceAll

Existing flag-presence tracking distinguishes omission from an explicitly empty namespace. These choices need no separate --unqualified flag or reserved namespace name such as all. Conflicting namespace choices are usage errors: one native listing accepts at most one namespace filter.

Namespace enumeration uses repeatable --kind prompt|profile|backend; omission retains the native union. Application-created engine views and explicit listing filters retain their separate native meanings.

OD-4: Delivery boundary for smoke testing

Accepted: Include an independently optional smoke command in this roadmap, alongside dependency migration and expanded discovery. Expose the native request, operation, and report directly through the existing integration model.

Deliver native reports, including a report returned with an error. Successful native invocation and report delivery yield success; native errors remain operational failures with supported error identity preserved. Native observations are reported neutrally. CommandKit does not add an aggregate readiness judgment or warnings about perceived upstream limitations.

The implementation plan must settle concrete command vocabulary and request bindings within this scope. A separate smoke feature roadmap is not required.