base-layer/commandkit
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 1 Wiki Activity

Retire completed PromptKit planning documents

Browse Source
This commit is contained in:
Eric Rakestraw
2026-11-06 01:18:55 +00:00
parent 540e2359d6
commit ad16bfc521
4 changed files with 15 additions and 626 deletions
Download Patch File Download Diff File Expand all files Collapse all files

3
docs/development.md
View File

@@ -72,7 +72,8 @@ Read all applicable rows for cross-cutting work. Go declarations and GoDoc own
current exported contracts; the CLI reference owns operator behavior. The
[maintainer release procedure](release.md) owns current release operations.
Completed roadmaps and implementation evidence remain available in Git history,
including [ConfigKit adoption, reporting, release-tooling, and remediation records](https://forge.maximumdirect.net/base-layer/commandkit/src/commit/260256d722f52bc947103d078cb67a129f4cc9f1/docs/roadmap),
including [PromptKit v0.18.0 adoption and implementation](https://forge.maximumdirect.net/base-layer/commandkit/src/commit/540e2359d66d604a563df0be1c9fc961588f5b9c/docs/roadmap),
[ConfigKit adoption, reporting, release-tooling, and remediation records](https://forge.maximumdirect.net/base-layer/commandkit/src/commit/260256d722f52bc947103d078cb67a129f4cc9f1/docs/roadmap),
[application-owned alias planning, implementation, and remediation](https://gitea.maximumdirect.net/eric/CommandKit/src/commit/f42aefe02d84e154855ac922173e6f367180929f/docs/roadmap)
and [PromptKit requirements implementation and remediation](https://gitea.maximumdirect.net/eric/CommandKit/src/commit/40499a43608bf60d1104cd8ee24caf18ac0e9e66/docs/roadmap).
These records are not assignments to restart completed work. The

21
docs/roadmap/future.md
View File

@@ -8,6 +8,9 @@ No delivery dates are selected here.
Completed roadmaps, implementation plans, and review findings have been retired.
This document preserves unfinished work and unselected ideas under the
[release policy](../policy/release.md#release-documentation-and-preparation).
The completed PromptKit v0.18.0 adoption roadmap and implementation plan remain
available in the
[PromptKit retirement snapshot](https://forge.maximumdirect.net/base-layer/commandkit/src/commit/540e2359d66d604a563df0be1c9fc961588f5b9c/docs/roadmap).
The completed ConfigKit adoption, reporting, dependency alignment, release-tooling,
and remediation records remain available at the
[retirement snapshot](https://forge.maximumdirect.net/base-layer/commandkit/src/commit/260256d722f52bc947103d078cb67a129f4cc9f1/docs/roadmap).
@@ -23,19 +26,20 @@ an idea here does not select its syntax, API, priority, or delivery date.
### ckprompt release
The [PromptKit v0.18.0 adoption roadmap](promptkit-v0.18.0.md) records the
completed migration and its unpublished ckprompt v0.3.0 candidate. Publication
and hosted delivery remain separate operations under the [release procedure](../release.md).
The PromptKit v0.18.0 migration is complete. The
[ckprompt v0.3.0 candidate](../../integrations/ckprompt/docs/releases/v0.3.0.md)
remains unpublished. Publication and hosted delivery remain separate operations
under the [release procedure](../release.md).
The published ckprompt v0.2.0 retains its earlier dependencies; see the
[consumer guide](../consumers/guide.md#module-selection) for module selection.
### Later PromptKit release review
The current adoption develops only against PromptKit v0.18.0 as released.
The completed adoption used PromptKit v0.18.0 as released.
Review v0.19.0 separately once it is published; do not inspect or monitor
unreleased upstream work in anticipation of that review. A later released
version requires its own contract and compatibility assessment before selection
and does not delay completion of the v0.18.0 adoption.
and does not reopen the completed v0.18.0 adoption.
## Future capability targets
@@ -96,7 +100,7 @@ those capabilities primarily serve application loading and startup.
### PromptKit inspection and selection extensions
The [PromptKit adoption scope](promptkit-v0.18.0.md#scope-decisions) defers these
The [completed PromptKit adoption scope](https://forge.maximumdirect.net/base-layer/commandkit/src/commit/540e2359d66d604a563df0be1c9fc961588f5b9c/docs/roadmap/promptkit-v0.18.0.md#scope-decisions) deferred these
capabilities beyond the v0.18.0 compatibility migration. Shared configuration
metadata remains the recommended next functional sprint, under
[configuration inspection extensions](#configuration-inspection-extensions).
@@ -118,8 +122,9 @@ from the ConfigKit review identifiers above.
boundary. PromptKit retains preparation and rendering semantics. Keeping this
operation application-owned remains an alternative; model execution and
prepared-handle lifecycle are outside this proposal.
- **Namespace helpers or standard selectors (PromptKit OD-5).** Begin with the
adoption's consumer guidance for loaders returning `Engine.WithNamespaces`.
- **Namespace helpers or standard selectors (PromptKit OD-5).** The
[consumer guidance](../consumers/guide.md#namespace-views) covers loaders
returning `Engine.WithNamespaces`.
Consider reusable bindings or helpers when consumers demonstrate repeated
wiring. Design independent prompt/profile/backend defaults, applicable
operations, and their interaction with existing catalog filters together.

343
docs/roadmap/implementation.md
View File

@@ -1,343 +0,0 @@
# PromptKit v0.18.0 implementation plan
Status: all stages complete; publication and hosted delivery are not performed.
## 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
**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
**Complete.** Validation used Go 1.27.0 against source revision `e28ba63`
with the final import-formatting and roadmap-closure changes in the completion
commit. Dependency preparation (`go mod tidy`, `go mod download`, and
`go list -m all`) used `GOWORK=off GOTOOLCHAIN=local`; the selected graph has
the intended vanity modules and no local replacements or old-path PromptKit or
ConfigKit imports. The root, ckconfig, and ckprompt modules each passed
`GOWORK=off GOTOOLCHAIN=local go test -mod=readonly ./...` independently.
The preserved ignored workspace was set to Go 1.27.0, keeping its three existing
`use` entries. From the root, `GOTOOLCHAIN=local go test ./...`,
`go test ./integrations/ckconfig/...`, and `go test ./integrations/ckprompt/...`
all passed with workspace discovery. Changed Go files were formatted. Local
Markdown destinations and fragments, source/notice pins, the complete sprint
diff, and whitespace checks were reviewed. Deferred capabilities remain in
[future work](future.md#promptkit-inspection-and-selection-extensions).
All six standalone composed-consumer commands listed below returned status 0.
The inspected source report included the application and bundled evidence;
the selected spring profile and prompt, hash, and request validation appeared
in their reports. Aggregate smoke selected the local backend, reported unavailable
HTTP diagnostics, used the injected inference client, and recorded
`valid_json: false` for structured output; its native facts did not alter the
successful aggregate outcome. No publication or hosted delivery was performed.
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.

274
docs/roadmap/promptkit-v0.18.0.md
View File

@@ -1,274 +0,0 @@
# PromptKit v0.18.0 adoption
Status: implementation and validation complete; the ckprompt v0.3.0 candidate
remains unpublished. Released PromptKit v0.18.0 was the sole development target.
[Scope decisions](#scope-decisions) record that dependency choice and the
selected example policy and capability scope. The
[implementation plan](implementation.md) owns staged work, validation commands,
and completion evidence; this document owns the desired state and scope.
## Purpose and authority
Adopt PromptKit's vanity module and current public APIs in the embedded
`ckprompt` integration, using the now-published ckconfig v0.3.0. Restore a
compatible three-module development workspace and composed consumer.
PromptKit and ConfigKit own their domain functionality and semantics.
CommandKit owns faithful adaptation, command selection and coordination,
presentation, and invocation outcomes. Expose upstream capabilities in a
neutral, consistent way, without adding independent guarantees or qualifying
upstream limitations. Application loaders retain engine construction and
configuration choices.
The [architecture](../policy/architecture.md), [agent](../policy/agents.md),
[testing](../policy/testing.md), [documentation](../policy/documentation.md),
[release](../policy/release.md), and [OSS](../policy/oss.md) policies govern the
work. Current behavior remains owned by Go declarations and GoDoc, the
[CLI reference](../cli.md), and the [consumer guide](../consumers/guide.md).
The shared inspection proposals in
[future work](future.md#configuration-inspection-extensions) retain their own
scope. This roadmap records how PromptKit could use that work and identifies
additional capabilities without selecting them as adoption requirements.
## Baseline and review evidence
Reviewed CommandKit revision: `eeae10fa0558bce8de963010fdcea2c40ef68691`.
| Component | Current state |
| --- | --- |
| ckprompt | `go.maximumdirect.net/ckprompt v0.2.0`; Go 1.26.0 minimum |
| PromptKit dependency | `gitea.maximumdirect.net/eric/promptkit v0.16.0` |
| ConfigKit dependency | `gitea.maximumdirect.net/eric/ConfigKit v0.8.0` |
| CommandKit dependencies | Core v0.3.0 and ckconfig v0.2.0 |
| Available ckconfig | v0.3.0, with vanity ConfigKit v1.1.0 and Go 1.27.0 |
| Maintainer toolchain | Go 1.27.0; root ReleaseKit v0.9.0 |
Direct module discovery verified PromptKit v0.18.0 at published commit
`d9f6aad30509e538fc73ea16710df3a3ec084502`. Its module requires Go 1.27.0 and
vanity ConfigKit v1.1.0. Published ckconfig v0.3.0 downloads through its vanity
path and selects that same ConfigKit identity. The current ckprompt still
selects ckconfig v0.2.0 independently and cannot compose with local ckconfig
v0.3.0 in the development workspace.
The upstream [v0.17 migration notes](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/d9f6aad30509e538fc73ea16710df3a3ec084502/docs/releases/v0.17.0.md),
[v0.18 release notes](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/d9f6aad30509e538fc73ea16710df3a3ec084502/docs/releases/v0.18.0.md),
and [configuration/API migration guide](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/d9f6aad30509e538fc73ea16710df3a3ec084502/docs/consumers/configuration-migration.md)
own the upstream changes crossed by this upgrade.
A disposable migration established the following, without changing repository
code or using local dependency replacements:
- Changing dependencies and imports alone fails at four production accesses to
removed prompt-version metadata.
- After removing that metadata, production packages build on Go 1.27.0 against
published ckconfig v0.3.0, ConfigKit v1.1.0, and PromptKit v0.18.0.
- After converting the composed example's PromptKit resources to identified
lists, its profile catalog, source inventory, requirements inspection, and
configuration validation run successfully. The native bundle appears in
catalogs and as source evidence through ckconfig's current report path.
- The full suite still needs version-fixture, configuration-shape, and report
expectation changes. These diagnostics do not establish completed adoption.
## API coverage and capability candidates
A follow-up review compared the published v0.18.0 API with ckprompt at
CommandKit revision `69cc642`. Existing report shapes cover the current prompt,
profile, requirements, catalog, and smoke inspection results after removing
obsolete prompt-version fields. Smoke reports already carry the native facts,
timing, attempts, and usage; the review found no additional report fields to add
in those operations.
Three capabilities merit consideration beyond compatibility migration:
| Capability | Current integration | Recommendation and scope decision |
| --- | --- | --- |
| Configuration metadata and history | Native `ConfigurationInspection.Metadata()` returns ConfigKit metadata. `ConfigScope` connects effective configuration, sources, explanations, and comparison, but has no metadata facet. | Extend the shared optional ckconfig capability first, then connect PromptKit's native metadata. Keep this as the next shared enhancement following adoption; see OD-3. |
| Prepared-request inspection | Native `Engine.Prepare` returns a `PreparedRun` snapshot. ckprompt exposes concrete request validation but has no operation returning preparation results. | Consider an optional provider capability and report as the next substantive ckprompt enhancement. This extends standard inspection into rendering and needs an explicit scope choice; see OD-4. |
| Namespace selection helpers | Native `Engine.WithNamespaces` supplies separate prompt, profile, and backend namespace defaults for unqualified selections. Applications can already return that view from an engine loader. Existing standard namespace selectors filter catalogs. | Begin with documented loader wiring; consider reusable helpers or standard selectors when consumers demonstrate repeated wiring. Keep name resolution distinct from catalog filtering; see OD-5. |
The released [configuration inspection API](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/d9f6aad30509e538fc73ea16710df3a3ec084502/configuration_inspection.go),
[preparation API](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/d9f6aad30509e538fc73ea16710df3a3ec084502/engine.go),
[prepared snapshot](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/d9f6aad30509e538fc73ea16710df3a3ec084502/types.go),
and [namespace API](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/d9f6aad30509e538fc73ea16710df3a3ec084502/namespaces.go)
own those capabilities. They are available in v0.18.0; this review does not imply
that each was introduced in that release.
Request execution and output-validation overrides, session IDs, appended
messages, and retry settings are already reachable through application request
builders. Engine construction and bundle options remain available through
loaders. Consider reusable bindings where consumers repeat the same wiring;
adoption does not require a standard flag for every native option.
`Run`, `PrepareExecution`, `RunPrepared`, and execution observers serve the
application-owned execution workflow. Prepared-request inspection can use
`Prepare` without adding model generation or prepared-handle lifecycle to the
standard suite. Execution, serving, and session operations retain their current
ownership. OD-4 addresses only the proposed rendering-inspection extension.
## Targeted end state
### Modules and Go compatibility
Prepare ckprompt v0.3.0 against this released dependency set under OD-1:
| Requirement | Target |
| --- | --- |
| PromptKit | `go.maximumdirect.net/promptkit v0.18.0` as released |
| ConfigKit | `go.maximumdirect.net/configkit v1.1.0` |
| ckconfig | `go.maximumdirect.net/ckconfig v0.3.0` |
| Core | Retain `go.maximumdirect.net/commandkit v0.3.0` |
| ckprompt consumer minimum | Go 1.27.0 |
Production code, tests, and the maintained composed example use the matching
vanity identities. Public callbacks and provider values exchange those types
consistently. Authentic module metadata and sums select released dependencies;
an old-path bridge or a permanent local replacement is unnecessary.
Core remains independent of the optional libraries and retains its own Go
minimum. The already-migrated ckconfig and root ReleaseKit selection need no
upgrade for this target. The existing Go 1.27.0 maintainer toolchain is suitable.
### Existing commands and faithful report adaptation
Keep the existing engine adapters, five catalogs, named inspections, requirements
discovery, request validation, smoke testing, and configuration scope/comparison.
The reviewed public methods remain suitable; adopting v0.18.0 does not require
a new command family or a second domain implementation.
Remove the descriptive prompt-version output that upstream removed:
- Prompt-catalog entries retain prompt ID and lose their optional `version`.
- Prompt inspection and requirements inspection lose their `version` member;
prompt text inspection also loses the prompt-version line.
- Smoke-target reports lose their optional prompt `version` member.
Remove the associated DTO fields and projection logic rather than manufacturing
replacement values. Prompt IDs and opaque hashes retain their native meanings.
Collection release labels, source specification headers, and unrelated
application version fields are distinct and retain their owning semantics.
This is a deliberate pre-v1 report/API migration, described in the release note.
Configuration inspection now supplies recorded normalized values and derived
defaults through ConfigKit v1.1.0. Existing config reports, explanation, and native
comparison expose that evidence through ckconfig v0.3.0, including source
fallback, version evidence, and empty-import selections. Preserve the returned
history and values; do not reconstruct the former authored-only view. Native
effective-value diffs retain atomic lists. Configuration inspection, profile
inspection, and request preparation remain their respective upstream views.
### Configuration, bundle behavior, and maintained consumers
PromptKit-owned root and collection `prompts`, `profiles`, and `backends` use
lists with explicit `id` values. Calls to `ProfileSource` and `BackendSource`
use ordered record slices. Inheritance and configuration-inspection paths
match the adopted shapes. Consumer guidance links to upstream for whole-record
replacement, source-root `config` controls, import requiredness, and optional
version-2 specification headers.
Remove maintained-example plumbing whose only role was carrying PromptKit's
removed descriptive version. Preserve independently meaningful application
fields and collection `release_version` labels. Do not globally delete every
configuration member named `version` or rewrite application schema versions.
PromptKit v0.18.0 includes a default-on OpenRouter backend and seventeen root
profiles as a lowest-priority underlay. Catalogs, namespaces, configuration, and
source reports follow the supplied engine's native inventory. The integration
does not silently filter those definitions or disable the bundle. Applications
can select `WithBundledOpenRouter(false)` in their own engine loaders.
Under OD-2, retain the default bundle in the maintained composed example.
Focused fixture loaders may explicitly opt out when their purpose requires a
minimal application-only inventory. Include focused coverage showing that
bundled records and their source evidence reach CommandKit output; assertions
about application records alone would not detect accidental bundle filtering.
Use returned native evidence without duplicating the full bundled catalog or
fixing expectations to its count.
Existing offline test and smoke-example boundaries remain applicable. Use
explicit native selections and injected clients/transports as appropriate to
the fixture; account for bundled diagnostic fallback rather than accidentally
directing a default test at a live provider. This changes fixture wiring, not
the native capabilities made available to operators.
### Workspace, documentation, and release preparation
Independent module validation uses the real downloaded dependency graph with
workspace discovery off. The ignored workspace composes root, ckconfig, and
ckprompt with a Go version supporting its Go 1.27.0 members. Development guidance
describes the aligned workspace, and the maintained composed consumer works
with both the declared releases and the local module set.
Current GoDoc, CLI reports, README/module-selection guidance, maintained example
instructions, and attribution describe the implemented dependency set and
migration. Preserve published notes and historical records. Prepare a ckprompt
v0.3.0 note and full tag `integrations/ckprompt/v0.3.0`, subject to the existing
fresh-version guards. A pre-v1 minor accommodates the deliberate type-identity,
configuration, report, and minimum-Go changes.
Publication and hosted Gitea delivery remain separate operations under the
[release procedure](../release.md). Preparing this roadmap does not publish a
version or select new release gates.
## Scope boundaries
The adoption covers dependency, API/report, fixture, and workspace alignment
plus namespace-loader guidance. Core APIs and its Go minimum remain unchanged.
Shared metadata, prepared-request inspection, and reusable namespace helpers or
standard selectors are deferred to
[future work](future.md#promptkit-inspection-and-selection-extensions).
The shared detailed-comparison, failed-load-inventory, and structured-diagnostic
proposals remain separate too. Ordered work belongs in the
[implementation plan](implementation.md).
## Released upstream baseline
Develop and validate only against PromptKit v0.18.0 as released. Unreleased
upstream branches, sibling-checkout changes, audit notes, and proposed fixes do
not inform this adoption's implementation, scope, or release criteria. The
migration does not wait for upstream development or introduce local workarounds
for anticipated changes.
PromptKit v0.19.0 may be reviewed once it is available as a published release.
That is a separate dependency review of its released contracts and changes;
it does not automatically change this roadmap's v0.18.0 target. No investigation
or monitoring of unreleased work is part of this adoption.
## Scope decisions
OD-1 records the user's explicit dependency direction. OD-2 through OD-5 record
the selected scope for this sprint; deferred capabilities still require
focused API and CLI design. These decisions do not describe implemented features
or authorize publication.
| Decision | Disposition | Implementation consequence |
| --- | --- | --- |
| OD-1: Upstream baseline | Develop only against released PromptKit v0.18.0. Review v0.19.0 separately once published. | Use the pinned released dependency set; do not consider unreleased upstream work or wait for it. |
| OD-2: Example bundle policy | Retain the upstream default bundle in the composed example; opt out explicitly in focused minimal fixtures. | Verify bundled records and source evidence reach output, without asserting the complete catalog or count. Keep smoke fixtures on explicit offline targets. |
| OD-3: Shared metadata | Defer to the next shared functional sprint. | Design the optional ckconfig capability first, then forward PromptKit's native metadata. Retain ckconfig v0.3.0 for adoption. |
| OD-4: Prepared-request inspection | Defer to a separate design decision after adoption and shared metadata. | Select report content and the rendering scope explicitly before adding a provider or command. |
| OD-5: Namespace support | Include loader guidance now; defer reusable helpers and standard selectors. | Explain independent namespace defaults and keep unqualified-name resolution distinct from catalog filtering. |
The [future capability record](future.md#promptkit-inspection-and-selection-extensions)
owns the deferred PromptKit feature proposals and their design considerations.
Application loaders continue to own engine construction and bundle choices;
request builders continue to expose native request options without requiring a
standard flag for each one.
## Acceptance criteria
The final integration uses the selected released vanity dependencies and Go
minimum throughout production, tests, and the composed example. Its existing
operations faithfully expose the adopted upstream results, with descriptive
prompt-version fields removed and unrelated version meanings retained.
Maintained configuration uses the adopted resource shapes. The composed example
retains the native bundle; CommandKit output carries its records and source
evidence, and the default test suite and maintained smoke examples stay offline. The three modules compose in
the local workspace while independently validating against declared releases.
Current contracts, consumer and namespace-loader guidance, notices, and the
ckprompt v0.3.0 candidate note describe that implemented state. Workspace files
and local dependency replacements are absent from release inputs. Source
publication and hosted delivery remain separate under the existing release
procedure. The [implementation plan](implementation.md#stage-7-validate-the-final-modules-and-workspace-then-close-the-sprint)
owns concrete checks and their final evidence; the earlier disposable review
is preliminary evidence only.