275 lines
17 KiB
Markdown
275 lines
17 KiB
Markdown
# 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.
|