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; the implementation plan sequences 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 and remediation record, together with their original implementation plan, 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.

Dependency and delivery boundaries

The target includes all three upgrades, richer configuration source inspection, expanded PromptKit discovery, and explicitly invoked smoke testing. The implementation plan owns coding order and stage boundaries. These changes can be delivered in one coordinated sprint without separately releasable intermediate commits.

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

The optional family exposes these additional catalogs:

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 promptkit test command in this roadmap. Keep request construction and report presentation close to the native public API, reusing the suite's typed input/state, configuration selection, and engine acquisition paths.

Command vocabulary

The selected syntax is:

app promptkit test KIND [options]
app promptkit test all [options]

One operand selects either a native kind or the aggregate all operation. The native kind spellings are reachability, authentication, text_inference, and structured_output. all is CommandKit-owned coordination syntax, not a native SmokeTestKind.

For example:

app promptkit test reachability --backend local
app promptkit test authentication --profile editorial
app promptkit test text_inference --prompt briefing
app promptkit test structured_output --profile editorial --model example-model
app promptkit test all --profile editorial

Request bindings

Bind operator inputs directly to promptkit.SmokeTestRequest and its native ExecutionTargetOverride:

CLI input	Native destination	Binding
KIND	Kind	Native kind string; aggregate expansion is described below.
--backend	BackendID	String.
--prompt	PromptID	String.
--profile	ProfileID	String.
--endpoint	Execution.Endpoint	String.
--model	Execution.Model	String.
--temperature	Execution.Temperature	Optional floating-point value.
--max-tokens	Execution.MaxTokens	Optional integer.
--top-p	Execution.TopP	Optional floating-point value.
--timeout-seconds	Execution.TimeoutSeconds	Optional integer.
--service-tier	Execution.ServiceTier	String.
--reasoning-effort	Execution.ReasoningEffort	Optional string.
--api-key-env	Execution.APIKeyEnv	String.
--transient-retries	TransientRetries	Optional integer.

Also accept the existing --config, --overlay, and suite selectors. Reports are YAML-only; --format defaults to yaml and accepts yaml. Built-in flags are singleton bindings with the established last-occurrence behavior; suite selectors retain their declared binding behavior.

Preserve omission versus explicit zero or empty values for native pointer fields. Leave Execution nil when no execution override was supplied. Backend, prompt, and profile selectors may be supplied together: PromptKit owns their precedence, resolution, defaults, ranges, and request validation. CommandKit owns CLI syntax and primitive value conversion.

Direct APIKey and structured ExtraParams remain available through the optional application request builder. This scope uses that existing integration pattern rather than adding a credential-source mechanism or generic override language.

Consumer API and request construction

Use a narrow ckprompt-owned envelope:

type SmokeRequest struct {
    Selection ckconfig.Selection
    Request   promptkit.SmokeTestRequest
}

An independently optional Suite.SmokeTest callback receives context, SmokeRequest, typed application input, and shared state, and returns (commandkit.Acquired[*promptkit.SmokeTestReport], error). It represents one concrete test and preserves both a returned native report and error.

Provide WithSmokeTesting(suite, load, build) following the existing request-validation adapter pattern. The loader uses the existing engine-loader signature. The optional builder receives context, SmokeRequest, typed input, and shared state, and returns a complete native SmokeTestRequest and error. With no builder, forward the CLI-created native request. With a builder, its returned request is authoritative; do not merge CLI values back over it.

For aggregate execution, invoke the optional builder separately for each concrete kind, seeding that kind into the otherwise common bound request. Applications can supply per-kind credentials, structured parameters, or other native request choices. The synthetic all value does not reach the native request or the per-test builder.

Aggregate execution

app promptkit test all selects these four tests sequentially, in order:

1. reachability
2. authentication
3. text_inference
4. structured_output

Coordinate the concrete test callbacks within one CommandKit invocation, using its configuration selection, prepared typed input, and shared state. Reuse configuration acquisition and the engine where practical within the existing loader model; this does not require a new caching framework or guarantee a particular loader call count.

Continue to the next kind after an individual test error so that remaining results can be collected. When the invocation is canceled, stop scheduling further tests and retain the results already available. PromptKit owns each individual operation; CommandKit coordinates the selected sequence.

Reports and invocation outcomes

Present the native SmokeTestReport, including observations, timing, attempts, and available usage. For all, deliver one YAML report containing the individual results in execution order, with each selected kind's returned report and associated error, when present. Retain useful partial reports returned with errors. Preserve supported error identity through the invocation outcome as well as presenting the errors.

For a single test, a nil native error and successful report delivery mean success. For all, success requires all selected calls to return without errors and reporting to succeed. Native invocation errors use the normal operational failure classification; cancellation and delivery failures retain their existing outcome handling. Native negative or unknown findings remain reported facts; CommandKit does not derive an additional readiness verdict or failure rule from them.

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. Describe returned data neutrally, without adding warnings about perceived upstream limitations.

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 request bindings, per-kind builder forwarding, aggregate order and continuation, cancellation, 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 explicit smoke testing target records the accepted promptkit test KIND and promptkit test all vocabulary, native request bindings, per-kind builder, and aggregate execution/reporting semantics. A separate smoke feature roadmap is not required.