27 KiB
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.
- 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. - Prepare dependencies from each integration directory using
GOWORK=off GOTOOLCHAIN=local go getfor 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. - 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.
- 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 is5ea60e9b96651fd7dfcbc7d05b6f43d131df358f. 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.
-
Add this narrow public capability alongside the existing reader interfaces:
type PathReader interface { HistoricalPaths() []configkit.Path }Add
Paths PathReadertoView. It supplies the native discovery candidates.Metadatacontinues to supply presence, explicitness, and history. Update GoDoc forView,PathReader, andScopeFeatures.PathDiscoverytogether. -
In
runConfigExplanationlisting mode, retain the metadata requirement. EnumerateView.Paths.HistoricalPaths()whenPathsis nonnil; otherwise enumerateView.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--explicitfilters to those candidates using metadata. Keep explicit-path handling onExplanationReader. -
Populate whole-result
FromConfigKitviews 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. -
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]
- 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 withWithScopeError; declaration/help/discovery must not invoke loading. - Share ordinary result acquisition and diagnostic adaptation with
FromConfigKitthrough a small private helper. Preserve the existing handling ofLoadError, 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. - After successful loading, call
result.InspectSubtree(path). Use the returned inspection forEffective,Explanation, andPaths, and its whole-load metadata and sources for the corresponding fields. KeepFindingsfrom the result. If selection returnsfalse, 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. - 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.
- Reuse
loadComparisonSideand 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 callleftView.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 ordinaryFromConfigKiton its existing same-typeconfigkit.Diff. - 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.
- Set successful
ConfigScopeviews'Pathsdirectly to PromptKit's nativeConfigurationInspection. 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. - Migrate complete-document test/configuration mappings beneath
promptkit. Mount wrapperless fragments throughSettingsInput, and collection fragments throughCollectionInput. 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. - Replace any
Config.SchemaDir,WithSchemaFS, orWithSchemaFileuses with the selected release's supported schema configuration/resource contexts. InTestPromptConstructorFailurePrecedence, replace the missing-schema constructor with a missing main configuration file passed toNewEngine. Retain the intended operational outcome andos.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. - Migrate request-builder replacements to
*promptkit.OutputContractInputwherever 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 ordinaryOutputContractuses for resolved prepared results where that is the upstream type. - 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_hashwith 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. - 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.
- Add a shared-load fixture with a genuine application sibling outside
/promptkit. ThroughConfigScope, prove list candidates follow nativeHistoricalPaths, 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.
- Add
PromptKit promptkit.Settingswithyaml:"promptkit"toappConfiguration, plus an illustrative typedstoragesection. Keep the existing campaign data, selector presence, request-builder, session outcome, alias, completion, and injected-client demonstrations. - Move the example's generated resources into the application load. Compose
its definition using
promptkit.Configurewith the settings selector. Supply the existing local collection and common prompt resources as an application-owned mapping underlay beneathpromptkit, so selecting a main fixture retains the example resources. Keep application defaults in the application definition. Retain the example's bundled OpenRouter catalog by selectingBundledOpenRouterUnderlay()before this load, once in its input composition. Engine construction must not perform a second configuration load. - 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. - Keep
loadApplicationConfigas 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. InloadPromptEngine, pass that result directly topromptkit.NewFromConfigwithRuntimeConfigand the existing injected LLM client. Remove the separate PromptKit source reconstruction andNewEnginecall from this shared path. Keep standaloneNewEnginefixtures elsewhere as supported usage. - Register a
storagescope withFromConfigKitSubtree, the existing result loader, andconfigkit.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. - 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 allexpectations to include the new application scope and the fact that theappwhole-result view now includes PromptKit settings. - 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.
- Finish exported GoDoc and package guidance in both integrations. Document
View.Pathsprecedence 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. - 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.
- 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.
- The ckconfig note covers the new adapter and optional reader. Adding a public
Viewfield 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 positionalPreparedRunliteral migration and older JSON's missing-hash behavior where relevant, linking upstream for its exact contract. - 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. - 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.
-
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.
-
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.modand matchinggo.sumto a temporary directory, add a temporaryreplace go.maximumdirect.net/ckconfig => ABSOLUTE_LOCAL_CKCONFIGwithgo mod edit -modfile=..., and run tidy andGOWORK=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. -
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.
-
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.
-
Record pending release coordination in
future.mdbefore 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. -
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.