commandkit/docs/roadmap/implementation.md

# PromptKit v0.18.0 implementation plan

Status: Stages 1–5 complete; Stages 6–7 remain.

## Authority and execution

Implement the target and OD-1 through OD-5 in the
[feature roadmap](promptkit-v0.18.0.md#scope-decisions). 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](future.md#promptkit-inspection-and-selection-extensions).
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](../release.md#release-toolchain). 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

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:

   ```sh
   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:

   ```text
   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.