Files
commandkit/docs/roadmap/implementation.md

27 KiB
Raw Blame History

ConfigKit and PromptKit adoption implementation plan

Status: implementation complete; coordinated releases pending. Prepared 2026-11-21. Implementation baseline: 320526d3fc92fac7795b4b5e65c623181680452d.

Authority and execution

Implement the accepted feature roadmap in the numbered order below. That document owns intent, scope, upstream targets, and resolved decisions. This plan selects the API shape, implementation steps, and completion evidence for a Luna coding agent.

Read development guidance, the applicable policies in its reading guide, and ADRs 0003 and 0004. Prefer the codebase knowledge graph for code discovery. Inspect the actual worktree before editing and preserve unrelated work, ignored workspace files, and local credentials.

This is one end-to-end implementation sprint. Continue through all stages without intermediate approval or compilation gates. Earlier stages may temporarily fail to build while later migrations are pending. Resolve failures before declaring the implementation complete. After a focused unit is complete, record its actual evidence here and commit it under the agent policy. Do not create empty commits or claim checks that have not run.

Implementation approval authorizes the implementation and local commits. Source publication and hosted delivery follow the release procedure when separately authorized. Publication is follow-up coordination, not an internal gate in this sprint. Stage 7 defines honest pre-publication validation when ckprompt needs the new, still-unpublished ckconfig API.

Use the existing command families, reporters, classification, and provider lifetimes. Keep domain resolution, schemas, validation, preparation, redaction, and comparison upstream. Do not add a core cache, new commands, constructor wrapper, arbitrary-view adapter, cross-root-type loader API, or options framework for this adoption. The roadmap's scope choices do not establish permanent bans.

Stage 1: Select the released upstream dependencies

Status: complete.

Evidence: With Go 1.27.4 and the workspace disabled, selected the specified versions using go get, ran go mod tidy and go mod download in both integrations, and reviewed the module graphs, checksums, and selected upstream copyright and license material. The upstream license texts match the previously selected versions; the remaining selected transitive versions are unchanged. Updated both integration attribution entries. The existing workspace includes all three modules. The independent ckconfig suite passed. The ckprompt suite currently fails on removed WithSchemaFile and unmigrated composed-example resources; those migrations are assigned to Stages 4 and 5.

  1. With Go 1.27.4 on PATH, update ConfigKit to v1.4.0 in both integration modules and PromptKit to v0.24.0 in ckprompt. Keep core v0.7.0, the root module's requirements, and the consumer minimum of Go 1.27.0 unless an actual dependency requirement demonstrates a necessary change.
  2. Prepare dependencies from each integration directory using GOWORK=off GOTOOLCHAIN=local go get for these exact versions, then download/tidy actual dependencies and review the resulting requirements and checksums. Leave ckprompt's ckconfig requirement at published v0.9.0 until the new ckconfig is published. Do not record a fictitious future checksum or commit a local replacement to make the new API appear published. Repeat tidy after source migration if temporary compilation errors prevent it now.
  3. Use the existing ignored workspace containing the root and both integrations for development. Preserve it, or create it following the developer guide if absent. Do not depend on sibling upstream checkouts.
  4. Review the selected upstream license and notice material and update affected module-local and root attribution entries under the OSS policy. ConfigKit's selected source is 4a7ae664a6287d71cba20f59c7c5b37b6f05b0a3; PromptKit's is 5ea60e9b96651fd7dfcbc7d05b6f43d131df358f. Update changed transitive entries only where the selected graphs warrant it. Finalize graph and notice review after the migrations; no unrelated dependency sweep.

Completion evidence: reviewed integration module diffs and genuine sums selecting the two target releases. Record any temporary test/build failures as migration work for subsequent stages, not reasons to stop.

Stage 2: Separate native path enumeration from metadata lookup

Status: complete.

Evidence: Added the optional native path reader and metadata fallback, populated whole-result views, and exercised selected candidates, empty readers, the legacy fallback, and discovery filters alongside existing missing-metadata coverage. GOWORK=off GOTOOLCHAIN=local go test ./... passed in ckconfig with Go 1.27.4.

Primary files: contracts.go, explain.go, and configkit_adapter.go.

  1. Add this narrow public capability alongside the existing reader interfaces:

    type PathReader interface {
        HistoricalPaths() []configkit.Path
    }
    

    Add Paths PathReader to View. It supplies the native discovery candidates. Metadata continues to supply presence, explicitness, and history. Update GoDoc for View, PathReader, and ScopeFeatures.PathDiscovery together.

  2. In runConfigExplanation listing mode, retain the metadata requirement. Enumerate View.Paths.HistoricalPaths() when Paths is nonnil; otherwise enumerate View.Metadata.HistoricalPaths() for existing custom providers. A nonnil reader returning nil or an empty slice means an empty native list, and must not trigger the fallback. Apply the existing --under, --historical, and --explicit filters to those candidates using metadata. Keep explicit-path handling on ExplanationReader.

  3. Populate whole-result FromConfigKit views with their metadata as the path reader. Keep native paths and existing report projection. This change does not require new sorting, deduplication, path rebasing, or metadata copying.

  4. Extend existing discovery tests with a reader whose candidates exclude a real metadata sibling, a valid empty reader, and the legacy nil-reader fallback. Exercise the existing filter meanings on supplied candidates. Retain missing-metadata failure coverage instead of creating a second path metadata model.

Completion evidence: focused ckconfig discovery coverage proves that enumeration comes from the supplied capability while metadata still describes each path. Existing whole-result discovery remains supported.

Stage 3: Add the typed-result subtree scope adapter

Status: complete.

Evidence: Added the typed loader and native subtree adapter, sharing acquisition and comparison coordination with the whole-result adapter. Offline scope and CLI tests cover focused output and paths, explicit outside-focus explanations, whole-load warnings and failures, error identity, absence and null, unavailable inspection, and native comparison including an atomic ancestor. The independent ckconfig suite passed with Go 1.27.4 and GOWORK=off GOTOOLCHAIN=local.

Add the following public sibling of FromConfigKit in the ckconfig package:

func FromConfigKitSubtree[I, S, T any](
    name, summary string,
    path configkit.Path,
    load func(context.Context, Selection, I, S) (*configkit.Result[T], error),
) Scope[I, S]
  1. Declare the same operations and path features as FromConfigKit. Retain its application-owned loader, input/state, selection, and operation-list customization conventions. Attach a nil-loader construction error with WithScopeError; declaration/help/discovery must not invoke loading.
  2. Share ordinary result acquisition and diagnostic adaptation with FromConfigKit through a small private helper. Preserve the existing handling of LoadError, nonnil results accompanying other errors, nil-result failures, findings, sources, and terminal explanations. A successful result remains the source of whole-load diagnostics. Do not expose a new envelope or callback framework to applications.
  3. After successful loading, call result.InspectSubtree(path). Use the returned inspection for Effective, Explanation, and Paths, and its whole-load metadata and sources for the corresponding fields. Keep Findings from the result. If selection returns false, return a contextual operational error with the already acquired source/diagnostic evidence. This covers invalid paths and results without captured inspection. Do not classify an unavailable view as invalid user configuration without supporting native evidence.
  4. A valid absent scope is a successful acquisition, not an unavailable view. Let its native writer report an unavailable effective value through existing show/render delivery handling. Preserve explicit null. Explicit queries, including root and paths outside the focus, continue to use native semantics.
  5. Reuse loadComparisonSide and the existing pair-loading cancellation and diagnostic accumulation conventions. Extract the common pair-acquisition portion privately if needed to avoid duplicating that coordination. Select the same path from both successful results and call leftView.Diff(rightView). Preserve existing left/right selection inputs, shared state, warnings, explanations, cause wrapping, and checks before the next acquisition or diff. Do not filter native ancestor differences or compare rendered YAML. Keep ordinary FromConfigKit on its existing same-type configkit.Diff.
  6. Add focused public-scope/CLI coverage, using real offline ConfigKit results: focused show/list/explain with a sibling outside the focus; native diff with distinct selections; whole-load warnings and failed-load findings outside the focus; and error identity/outcomes for loader failure. Reuse existing evidence and delivery tests where they already protect the shared path. Cover valid absence versus null and unavailable inspection without building an upstream inspection conformance suite. Compare representative diff values to native results, including a retained atomic ancestor where applicable.

Completion evidence: standard scope commands expose a native subtree using only the ordinary typed loader and path. Whole-load failures remain failures and available evidence survives adaptation. Exported GoDoc describes this handoff.

Stage 4: Migrate ckprompt adapters, fixtures, and boundary coverage

Status: complete.

Evidence: Migrated discovered settings fragments to /promptkit, exposed native inspection paths, and added shared-load, requirements, schema, prepared-hash, and request-replacement coverage. GOTOOLCHAIN=local go test ./integrations/ckprompt passed in the aligned workspace with Go 1.27.4. The missing-main-file constructor retains PromptKit's invalid-config identity and produces an operational outcome with native load diagnostics. ConfigKit's LoadError explicitly does not unwrap underlying filesystem errors, so this native error cannot also match os.ErrNotExist as originally anticipated; the separate joined-error case verifies forwarding of that identity when supplied. The composed example migration remains in Stage 5.

Primary files: adapters.go, the integration's existing configuration/comparison/preparation/requirements tests, and constructor outcomes.

  1. Set successful ConfigScope views' Paths directly to PromptKit's native ConfigurationInspection. Retain its native effective writer, explanation, full metadata, sources, diagnostics, and native comparison. Do not convert it into a ConfigKit result to route it through the new adapter.
  2. Migrate complete-document test/configuration mappings beneath promptkit. Mount wrapperless fragments through SettingsInput, and collection fragments through CollectionInput. Discovery-produced fragments require an explicit destination when they are not whole documents. Update override paths, explanation assertions, and comparison paths to native locations such as /promptkit/profiles/0/model; resource IDs and references retain their names. Review inline maps, byte strings, embedded files, and filesystem fixtures, not just YAML files. In particular review composition and comparison fixtures.
  3. Replace any Config.SchemaDir, WithSchemaFS, or WithSchemaFile uses with the selected release's supported schema configuration/resource contexts. In TestPromptConstructorFailurePrecedence, replace the missing-schema constructor with a missing main configuration file passed to NewEngine. Retain the intended operational outcome and os.ErrNotExist/PromptKit cause identity checks, plus joined-error and cancellation precedence. Retain the real malformed companion-YAML regression and its structured load evidence. Schema-file failures now belong to preparation, so exercise their forwarding there only where needed to protect a distinct adapter path.
  4. Migrate request-builder replacements to *promptkit.OutputContractInput wherever used. Forward the whole replacement with pointer-valued repair budgets; omitted stays omitted and explicit zero stays zero. Do not insert the former repair default. Keep ordinary OutputContract uses for resolved prepared results where that is the upstream type.
  5. Keep prompt and prepared values on the existing native reporting path. Extend focused report tests to compare native returned inline/reference schema fields, repair-budget zero, and message_content_hash with CLI report values. Preserve text/JSON/YAML behavior through shared serialization tests and a small representative format selection, not an exhaustive cross-product of fields and formats. Do not calculate expected hashes locally.
  6. Verify requirements projections preserve the native result, including input metadata supplied by application defaults. Keep preparation, validation, namespace, smoke, cancellation, diagnostic, and outcome adaptation semantics. Use existing boundary tests for supported error identities; PromptKit owns tests of its v0.23.3 HTTP timeout/cancellation algorithms.
  7. Add a shared-load fixture with a genuine application sibling outside /promptkit. Through ConfigScope, prove list candidates follow native HistoricalPaths, filters still apply, explicit outside-focus paths retain native behavior, and full source/diagnostic evidence remains available. Expected values come from native inspection rather than a local scope filter.

Completion evidence: migrated ckprompt package coverage passes in the aligned workspace and resource-selection assertions detect silently unmigrated catalogs. The composed example is completed in Stage 5.

Stage 5: Demonstrate shared loading and the subtree adapter

Status: complete.

Evidence: The composed example loads application defaults, bundled and local resources, campaign-derived settings, and storage in one ConfigKit result; the engine consumes that result and the storage scope uses the subtree adapter. Updated fixtures and tests exercise native paths, shared inspection and reuse, storage show/explain/diff and overrides, whole-load failure evidence, and the existing campaign, comparison, catalog, and lifecycle cases. With Go 1.27.4, GOTOOLCHAIN=local go test ./integrations/ckprompt/examples/composed passed in the aligned workspace.

Update the maintained composed example, its fixtures, and its existing tests. A separate consumer example is unnecessary.

  1. Add PromptKit promptkit.Settings with yaml:"promptkit" to appConfiguration, plus an illustrative typed storage section. Keep the existing campaign data, selector presence, request-builder, session outcome, alias, completion, and injected-client demonstrations.
  2. Move the example's generated resources into the application load. Compose its definition using promptkit.Configure with the settings selector. Supply the existing local collection and common prompt resources as an application-owned mapping underlay beneath promptkit, so selecting a main fixture retains the example resources. Keep application defaults in the application definition. Retain the example's bundled OpenRouter catalog by selecting BundledOpenRouterUnderlay() before this load, once in its input composition. Engine construction must not perform a second configuration load.
  3. Derive campaign-specific profiles and prompt defaults during the application definition's resolve callback, before PromptKit's composed resolve callback. Use ConfigKit's resolution recording helpers for changes, with native /promptkit/... paths and relevant campaign dependencies. This keeps frozen inspection and engine settings consistent. Do not mutate the completed result's settings to inject a campaign before handing it to the engine. Preserve existing campaign selection and override precedence, including explicit empty selections and native conflicting-override errors.
  4. Keep loadApplicationConfig as the ordinary result loader, retaining its application-owned successful-result reuse keyed by the full selection and campaign presence/value. Keep failed loads out of that reuse. In loadPromptEngine, pass that result directly to promptkit.NewFromConfig with RuntimeConfig and the existing injected LLM client. Remove the separate PromptKit source reconstruction and NewEngine call from this shared path. Keep standalone NewEngine fixtures elsewhere as supported usage.
  5. Register a storage scope with FromConfigKitSubtree, the existing result loader, and configkit.Keys("storage"). Enable overrides for this scope because that loader supports them. Apply the existing campaign selector and its comparison counterpart to this scope as well; retain the app-only limit selector and input checks. Keep PromptKit scope capability declarations at their existing supported settings; shared loading itself does not require expanding its advertised override modes.
  6. Give before/after fixtures distinct storage values while retaining campaign differences. Extend existing tests to demonstrate subtree show/explanation and comparison through the standard commands and available failed-load diagnostics. Use package-level adapter tests for the fuller evidence matrix. Update --scope all expectations to include the new application scope and the fact that the app whole-result view now includes PromptKit settings.
  7. Retain tests distinguishing left/right configuration, campaigns, overrides, and repeated invocation state. Confirm help/completion do not acquire an engine, catalogs still contain selected IDs, and preparation does not call the LLM client. Smoke examples use the existing local injected client. Test successful reuse as example behavior, without creating a library-wide exact-load-count contract or redesigning its small cache.

Completion evidence: existing composed-example coverage plus focused subtree cases passes offline. Both scope adapters consume the same application-owned result for corresponding selections, and comparison sides remain independent.

Stage 6: Update canonical guidance and candidate release notes

Status: complete.

Evidence: Updated GoDoc, CLI, consumer, development, internal, and composed example guidance, plus candidate notes for ckconfig v0.10.0 and ckprompt v0.11.0. Neither candidate tag exists locally or on origin. Reviewed selected module graphs and upstream license material; affected attribution was updated in Stage 1 and no transitive version changed. Local Markdown links and fragments passed a repository link check, git diff --check passed, and the ckprompt workspace suite including the example passed with Go 1.27.4. Publication and the ckprompt released-dependency update remain pending.

  1. Finish exported GoDoc and package guidance in both integrations. Document View.Paths precedence and metadata fallback, the subtree helper signature, typed loader ownership, whole-load validation/evidence, and native path/diff behavior. Keep exact upstream format rules linked to the selected releases.
  2. Update CLI guidance for native scoped listings and explicit paths, focused rendering, source evidence, and comparison. Update the consumer guide with the maintained shared-load and storage-scope example, upstream migration links, and request-builder changes. Update development guidance and internal documentation where the changed mechanics affect them. Describe the local development dependency state accurately until release coordination is finished.
  3. Write candidate notes for ckconfig v0.10.0 and ckprompt v0.11.0. These are the next minor targets from the reviewed v0.9.0/v0.10.0 baselines. Check existing notes/tags before creating them; if another release has consumed either target, use the next appropriate fresh minor and adjust candidate references. The release command performs authoritative publication guards later.
  4. The ckconfig note covers the new adapter and optional reader. Adding a public View field can require migration of positional struct literals; recommend keyed fields and explain the metadata fallback for existing custom scopes. The ckprompt note covers the upstream breaking configuration/API migration, native path changes, removed schema options and explicit schema roots, OutputContractInput, resolved repair-budget zero/defaults, new prepared evidence, and whole-load context. Mention possible extra generation latency and usage from upstream's enabled repair default. Include positional PreparedRun literal migration and older JSON's missing-hash behavior where relevant, linking upstream for its exact contract.
  5. Preserve upstream ownership of resource-version policy and extension-field sensitivity. Keep unrelated deferred CLI capabilities in future.md. Add the required module-specific immutable release footer to each candidate note. Do not rewrite previously published notes or tags.
  6. Finalize affected attribution against the selected module graphs. Review prose diffs, local links/fragments, copied notices, commands, examples, and future tag URL paths under the documentation/OSS policies. Published compatibility tables must distinguish available releases from these candidates.

Completion evidence: canonical guidance and candidate notes agree with the implemented APIs and examples, have valid local navigation, and describe the remaining dependency release coordination without claiming publication.

Stage 7: Validate the result and record release coordination

Status: complete.

Evidence: With Go 1.27.4, GOWORK=off GOTOOLCHAIN=local go test ./... passed separately in core and ckconfig; ckconfig go mod tidy and go mod download completed without further changes. From the root, the aligned workspace commands GOTOOLCHAIN=local go test ./..., go test ./integrations/ckconfig/..., and go test ./integrations/ckprompt/... all passed. For isolated ckprompt validation, copied its module files to a temporary directory, replaced ckconfig with the local module only in that temporary modfile, ran tidy and GOWORK=off GOTOOLCHAIN=local go test -modfile=... ./..., and removed the temporary files; both package and example passed. This is not independent validation against the published ckconfig v0.9.0 requirement. Reviewed the module and attribution diffs, focused evidence, prose whitespace, and local links and fragments. No core optional dependencies were introduced. The remaining release order and dependency validation are recorded in future work. The Stage 4 record explains the upstream missing-file error-identity limitation.

  1. Format changed Go files, finish tidy/download with the workspace disabled where the module can resolve its selected APIs, and inspect all module and attribution diffs. Keep downloaded checksum evidence real. Root should not acquire optional integration dependencies.

  2. With Go 1.27.4 selected, run the complete affected independent/default suites and the aligned workspace suites. From the root, use these commands:

    (cd integrations/ckconfig && GOWORK=off GOTOOLCHAIN=local go test ./...)
    GOTOOLCHAIN=local go test ./...
    GOTOOLCHAIN=local go test ./integrations/ckconfig/...
    GOTOOLCHAIN=local go test ./integrations/ckprompt/...
    

    Run ckprompt's ordinary independent suite once its required ckconfig release is selected. Before publication, that suite cannot resolve the new API from its v0.9.0 requirement. For isolated development validation, copy ckprompt's go.mod and matching go.sum to a temporary directory, add a temporary replace go.maximumdirect.net/ckconfig => ABSOLUTE_LOCAL_CKCONFIG with go mod edit -modfile=..., and run tidy and GOWORK=off GOTOOLCHAIN=local go test -modfile=... ./... from the ckprompt directory. Remove the temporary files afterward. Label this result as isolated validation against local ckconfig, not independent validation against its published requirements. Do not block subsequent sprint work on the publication dependency.

  3. Review focused evidence from Stages 2–5 against the roadmap's targeted end state. Reuse successful checks for unchanged content. No performance benchmarks, live provider calls, new CI gates, or mandatory expanded matrices are needed for this adoption. Investigate concrete failures and rerun the affected checks after fixes.

  4. Run prose whitespace checks and validate affected local links/fragments, including new notes. Review intended new files as well as tracked diffs. Record actual commands, outcomes, and any remaining independent-dependency limitation here; do not mark unrun checks passed.

  5. Record pending release coordination in future.md before retiring any completed planning records. Keep this plan's implementation completion separate from publication status. The follow-up order is ckconfig first, then ckprompt with that actual released ckconfig selected, real sums/tidy, updated matching-version attribution, and its independent default suite. Core remains v0.7.0 for this scope. Follow the runbook for candidate commits, authorized pushes/tags, and separately authorized hosted delivery. The release command runs candidate validation itself; no duplicate mandatory preflight.

  6. Review and commit the completed implementation units and records under the agent policy. Report changed APIs and migration requirements, tests and their limits, commit identifiers, and the pending coordinated integration releases. Do not pause midway for an approval already covered by implementation scope.

Completion evidence: all implementation-stage work is finished, focused and workspace checks pass, ckconfig passes independently, documentation is validated, and any ckprompt published-dependency validation still awaiting release is explicitly recorded. Eventual adoption completion includes both coordinated releases; this sprint does not claim that follow-up has occurred.

Open Questions

None. The feature roadmap resolves product scope and adapter direction; this plan selects the remaining API, migration, example, and validation approach.