commandkit/docs/roadmap/implementation.md

PromptKit v0.18.0 implementation plan

Status: Stages 1–6 complete; Stage 7 remains.

Authority and execution

Implement the target and OD-1 through OD-5 in the feature roadmap. This plan owns the steps and completion evidence. Read docs/development.md and its applicable policies before editing. Use codebase-memory MCP for code discovery as instructed by AGENTS.md; fall back to text searches for literals and configuration fixtures.

The intended implementer is a Luna coding agent. Execute Stage 1 through Stage 7 in order as one end-to-end sprint. Intermediate stages may fail to compile or test. Do not introduce compatibility bridges, temporary public APIs, or extra commits merely to make intermediate stages green. Follow the repository's local commit policy for completed, reviewable units; final validation covers the whole sprint. Record stage progress and final evidence here as work proceeds.

Develop only against released PromptKit v0.18.0. Its reviewed source commit is d9f6aad30509e538fc73ea16710df3a3ec084502; use its downloaded module, GoDoc, and the pinned migration/release references in the feature roadmap. Do not inspect unreleased upstream or sibling-checkout development. Upstream owns domain semantics and their tests; CommandKit owns forwarding, coordination, reporting, and outcomes. Expose the adopted public contract neutrally.

The sprint adds no core API or command, metadata/history facet, prepared-request inspection, namespace helper, or standard namespace selector. Those capabilities remain in future work. Namespace-loader consumer guidance is included. Publication, tagging, pushing, and hosted delivery are separate from implementation completion and are not authorized by this plan.

Baseline and working locations

Planning baseline: CommandKit ee0debe (scope decisions recorded), with a clean worktree. Recheck the actual worktree before implementing and preserve unrelated work. The three modules are repository root, integrations/ckconfig, and integrations/ckprompt. The composed example is a package inside ckprompt, not a fourth module.

Area	Starting points
Dependencies	integrations/ckprompt/go.mod, go.sum; root and ckconfig manifests for comparison
Native adapters	integrations/ckprompt/adapters.go, smoke.go (acquisition diagnostics live in adapters.go)
Reports	integrations/ckprompt/command.go, smoke_report.go
Adapter and CLI tests	ckprompt adapters_test.go, command_test.go, requirements_*test.go, validation_*test.go, smoke_*test.go, composition, cancellation, and native-explanation tests
Maintained consumer	integrations/ckprompt/examples/composed/main.go, main_test.go, fixtures/before.yml, fixtures/after.yml, README.md
Current contract owners	docs/cli.md, docs/consumers/guide.md, ckprompt GoDoc and README, docs/development.md, docs/release.md
Notices and candidate	integrations/ckprompt/docs/oss/attribution.md, local license texts, integrations/ckprompt/docs/releases/v0.3.0.md

ckprompt currently selects old-path PromptKit v0.16.0, old-path ConfigKit v0.8.0, and vanity ckconfig v0.2.0. Local ckconfig v0.3.0 already selects vanity ConfigKit v1.1.0. The ignored go.work currently declares Go 1.26.10 and includes all three modules. Preserve it and go.work.sum; align the workspace only after the module changes. Never read or stage .releasekit/gitea-token contents.

Stage 1: Align module identities and imports

Complete. Go 1.27.0, dependency preparation, and the declared module graph were verified.

1. Select Go 1.27.0 on PATH using the existing toolchain instructions. Confirm with GOWORK=off GOTOOLCHAIN=local go version. Do not change the root consumer minimum, ckconfig's dependency selection, or the ReleaseKit version.
2. In every ckprompt production, test, and example Go import, replace gitea.maximumdirect.net/eric/promptkit with go.maximumdirect.net/promptkit, and gitea.maximumdirect.net/eric/ConfigKit with go.maximumdirect.net/configkit. Retain package names and the current core and ckconfig vanity identities. Historical release documents are not import migration targets.
3. Edit ckprompt's manifest to declare go 1.27.0, remove the two old-path requirements, require vanity PromptKit v0.18.0 and ConfigKit v1.1.0, raise ckconfig to v0.3.0, and retain core v0.3.0. Use go mod edit or equivalent explicit edits; do not select latest or add a local replace.
4. From integrations/ckprompt, run dependency preparation with GOWORK=off GOTOOLCHAIN=local go mod tidy and GOWORK=off GOTOOLCHAIN=local go mod download. Keep the actual generated sums and indirect selections, including tool dependencies. If source migration prevents tidying, finish it after Stage 5. Review GOWORK=off GOTOOLCHAIN=local go list -m all against the target dependency table; remove stale direct requirements rather than hand-editing sums.

Stage result: imports and declarations use the intended public type identities. Compilation failures caused by removed version fields and old fixtures are expected until subsequent stages. No dependency replacement is needed.

Stage 2: Adapt production reports and their projection tests

Complete. Focused catalog, prompt, requirements, and smoke projection tests pass on Go 1.27.0; native fixtures remain for migration.

1. In command.go, remove the PromptVersion members from promptInspectionReport and requirementsInspectionReport, their projection assignments, and the prompt text formatter's version line. Remove Version from promptCatalogEntry; encodePromptCatalog projects prompt ID only.
2. In smoke_report.go, remove PromptVersion from smokeTargetDTO and its native target conversion. These are the four production reads of removed upstream metadata identified in the review. Search for remaining uses of PromptVersion and PromptIdentity.Version, including composite literals.
3. Update synthetic DTO/command tests in command_test.go, requirements_command_test.go, smoke_report_test.go, and other affected report tests. Remove obsolete optional-version-only cases such as TestOptionalPromptVersionsPreserveAbsenceAndEmptyValues. Preserve their independent coverage of string encoding, ordering, empty inventories, presence, diagnostics, and delivery where that coverage remains useful.
4. Assert the intended report migration at the consumer boundary: prompt catalogs, prompt/requirements YAML, and smoke target YAML omit the removed member, and prompt text omits its version line. Preserve native IDs, hashes, output contracts, profile parameters, smoke facts/timing/attempts/usage, and optional-value semantics. Preserve collection release_version, source specification headers, and application identity/version behavior.
5. Keep Suite, FromEngine, ConfigScope, request-validation and smoke callbacks, operation availability, selectors, and invocation lifetimes intact except for the necessary upstream import/type migration. Do not add an alternate template engine, local domain validation, bundle filtering, or error taxonomy.

Stage result: production report projection matches the adopted API. Existing commands and their non-version report data remain available. Old real-engine fixtures may still prevent the full test suite from running.

Stage 3: Convert native engine fixtures

Complete. Native fixtures use identified resource lists and explicit minimal bundle choices; focused engine-backed tests pass. Report path expectations remain for Stage 4.

1. Inspect ckprompt test configurations outside the composed example (Stage 5), including embedded YAML, MapFS files, and programmatic mappings. Start with adapterEngine and adapterEngineFrom in adapters_test.go, then the requirements, validation, smoke, composition/comparison, and native-explanation fixtures that load real engines. Convert PromptKit-owned root and collection resource maps to ordered prompts, profiles, and backends lists with explicit id fields. Preserve unrelated application maps and collection namespace mappings.
2. Remove descriptive versions from prompt records. Translate resource inheritance, imports, and source-root controls according to the released migration guide: sibling identity references, config controls where old configkit controls occur, and explicit import requiredness where the test requires a missing import to fail. Retain meaningful source headers. Convert any ProfileSource/BackendSource map arguments to ordered native record slices with IDs. Do not broaden this into adopting unrelated upstream options.
3. For focused tests needing a minimal inventory, explicitly opt out with WithBundledOpenRouter(false) in the owning fixture loader. Keep a separate default-constructed fixture for the bundle projection coverage below; do not disable the bundle in production adapters or every fixture indiscriminately.

Stage result: module test engine inputs use the released shapes and deliberate fixture bundle choices. Existing assertions can still fail until Stage 4.

Stage 4: Refresh adapter expectations and bundle coverage

Complete. The ckprompt package suite passes with native normalized reports, and bundled profile and source evidence reach command output.

1. Adjust configuration path expectations to the new list indexes and returned native normalized values/history. With the bundle enabled, derive relevant records/paths from the returned view rather than assuming application records occupy index zero. Preserve native effective-value diffs, including atomic lists; do not reconstruct authored-only values or merge lists locally.
2. Update adapter assertions that read removed version fields. Retain tests proving request, selection, filters, typed input, and context forwarding; load and operation diagnostics; supported native error identity; cancellation; help/preflight without acquisition; independent optional operations; and writer failure handling. Replace obsolete assertions with boundary coverage, not new tests of upstream inheritance, rendering, or validation correctness.
3. Add or adapt focused end-to-end coverage comparing returned native bundled records and source evidence with CommandKit catalog/config-source output. Prove a bundled item actually reaches output so accidental filtering would fail the test. Do not copy the full bundled catalog or assert its total count.
4. Keep smoke fixtures deterministic and offline. Use explicit application or local-fixture prompt/profile/backend selections and existing injected clients/transports. An injected LLM client covers inference, not arbitrary HTTP probes; retain local transport/server seams for HTTP diagnostics where used. Account for native bundled fallback selection in default smoke requests.

Stage result: module test fixtures load under v0.18.0, meaningful adapter coverage survives, and bundle forwarding is covered. Run focused affected package tests to guide corrections; full final validation is Stage 7.

Stage 5: Migrate the composed consumer and its tests

Complete. The composed suite passes with identified lists, the native bundle, and explicit local smoke targets; the aggregate report was inspected.

1. In examples/composed/main.go, convert the root resources and field-notes collection resources assembled by loadPromptEngine to identified lists. Preserve qualified stored references such as field-notes/demo and field-notes/assistant, and preserve the collection's release label.
2. Remove campaign PromptVersion and the generated prompt version members. Remove the now-unused prompt_version values from both application YAML fixtures and the default mapping in loadApplicationConfig. Retain campaign selection, defaults, models, IDs, application identity, session behavior, request-builder presence handling, and per-run loading/cache behavior. Do not redesign the consumer loader/cache.
3. Retain the default native bundle in this example. Update main_test.go catalog, config show/explain/diff, requirements, smoke, aliases, and completion expectations for lists, normalized evidence, and version removal. Assert relevant application records without treating the whole native inventory as a fixed snapshot. Keep bundle projection evidence from Stage 4 or add it here if this is the simpler public boundary; avoid duplicate coverage.
4. Preserve the existing injected example client and explicit local smoke selections, including aggregate tests. Inspect any default-target calls for native fallback to bundled providers. Keep tests independent of credentials and live services without restricting the operator-facing capabilities.
5. Keep namespace-view support as consumer guidance in Stage 6. Do not add new flags, change existing --namespace catalog filtering, or silently scope this example's engine as part of migration.

Stage result: the composed application still demonstrates config and PromptKit families, application commands, aliases, and shared reporting with the aligned public types and native bundle. Its tests remain part of ckprompt's suite.

Stage 6: Update current guidance, notices, and the candidate note

Complete. Current guidance, namespace loader wiring, dependency attribution, and the unpublished v0.3.0 candidate note are updated. Local Markdown destinations and fragments were checked.

1. Update ckprompt GoDoc/README, root README where affected, docs/cli.md, docs/consumers/guide.md, and the composed example README to match Stage 2's reports and the selected dependency/configuration migration. Replace stale current v0.16 guidance with pinned v0.18 owning references. Preserve old release notes and historical source links as history. Do not globally replace all occurrences of version or old URLs.
2. Document namespace views in the consumer guide with a small application-owned loader example calling engine.WithNamespaces(promptkit.Namespaces{...}) and returning its result/error. Show independent prompt/profile/backend defaults. Explain unqualified caller-name resolution, qualified IDs passing through, unchanged stored references/config inspection, and global namespace/collection inventories. Keep catalog filtering distinct. Use released GoDoc for meaning; add no helper, new binding, or standard selector. Check example identifiers and signatures against the adopted module.
3. Restore aligned workspace instructions in docs/development.md and the consumer guide; remove the temporary warning that local ckprompt cannot compose with local ckconfig. Update minimum-Go descriptions, including docs/release.md: core retains Go 1.26.0, both integrations use Go 1.27.0, and the existing maintainer toolchain remains Go 1.27.0.
4. Review the actual tidied ckprompt module graph and the selected upstream license/notice files under the OSS policy. Update module-local attribution, exact source/notice commit links, and necessary standard license texts. Remove entries only when their material/dependency is no longer distributed; account for transitive tool requirements as well as runtime packages. Inspect shared root notices for affected facts without changing independent module selections or copying whole notice lists from a sibling checkout.
5. Prepare integrations/ckprompt/docs/releases/v0.3.0.md with the correct product title, dependency identities, Go minimum, list-configuration migration, removed report fields, native default bundle, and consumer actions. Use the full tag integrations/ckprompt/v0.3.0 for the immutable footer links to this module's COPYRIGHT, LICENSE, and ATTRIBUTION, following docs/release.md. Prepare the candidate only; do not create a tag or hosted page.

Stage result: current documentation describes implemented behavior, notices reflect the selected graph, and the candidate note explains the pre-v1 changes. Deferred proposals remain future work and are not presented as implemented.

Stage 7: Validate the final modules and workspace, then close the sprint

1. Finish tidying/downloading ckprompt dependencies with workspace discovery off if deferred from Stage 1. Format changed Go files with gofmt. Inspect final imports, manifests, and graph for old-path PromptKit/ConfigKit packages, unintended upgrades, and local replacements. Do not change authentic sums to force a preferred graph. Investigate any remaining old identity by its actual dependency rather than deleting graph entries blindly.

2. On Go 1.27.0, run each command from the named directory. These independent suites exercise actual declared releases, not local workspace substitutions:

   Directory	Command
   integrations/ckprompt	GOWORK=off GOTOOLCHAIN=local go test -mod=readonly ./...
   integrations/ckconfig	GOWORK=off GOTOOLCHAIN=local go test -mod=readonly ./...
   Repository root	GOWORK=off GOTOOLCHAIN=local go test -mod=readonly ./...

   The ckprompt command includes examples/composed; the root command does not traverse the integrations. Fix failures at their owning boundary and rerun affected checks. Do not add race/matrix/live-service gates for this migration.

3. Preserve the ignored workspace files and existing use entries. Set its Go directive to 1.27.0 with GOTOOLCHAIN=local go work edit -go=1.27.0. From the repository root, run with normal workspace discovery:

   GOTOOLCHAIN=local go test ./...
   GOTOOLCHAIN=local go test ./integrations/ckconfig/...
   GOTOOLCHAIN=local go test ./integrations/ckprompt/...
   

   This tests local core/ckconfig composition as well as the maintained consumer. Allow normal ignored workspace sum maintenance; do not stage workspace files.

4. From integrations/ckprompt, exercise representative standalone consumer commands with GOWORK=off GOTOOLCHAIN=local go run ./examples/composed followed by each argument set below. Inspect reports against the selected contracts:

   config validate --scope all --campaign spring --limit=0
   config sources --scope promptkit --campaign spring
   promptkit list profiles --campaign spring
   promptkit show prompt briefing --campaign spring --format yaml
   promptkit requirements validate briefing --campaign spring --input topic=examples/composed/fixtures/topic.txt
   promptkit test all --campaign spring --prompt briefing --profile spring
   

   Use the maintained example's local client and intended offline diagnostic wiring. Inspect the aggregate smoke report and outcome according to its existing contract; concluded native diagnostic facts are not a new universal success assertion. The composed tests also cover aliases, completion, domain commands, comparison, and failure/report delivery.

5. Review Markdown links/fragments, current examples, pinned provenance, and git diff --check -- '*.md' COPYRIGHT. Review the full diff for scope and accidental changes to histories, secrets, or independent modules. No code generation, new test framework, or publication check is needed for prose.

6. Record the actual commands/results and final source revision in this plan. Mark completion only after all selected scope is implemented and required validation succeeds; the earlier disposable migration is not final evidence. Confirm the feature roadmap's target is met and the deferred capabilities remain tracked. Keep source-publication and hosted-delivery status separate.

7. Follow the local commit policy: inspect status and staged changes, stage only intended sprint files, run the staged whitespace check, and commit completed work with a short plain-English message. Report commits and any remaining changes. No push or release action follows automatically.

Open Questions

None required for this adoption. OD-1 through OD-5 fix the dependency, bundle, and capability scope. Deferred metadata, preparation reports, and namespace helpers retain their future design questions; they are not decisions Luna needs to resolve to complete this sprint.