audita/docs/roadmap/promptkit.md

PromptKit Adoption Outline

Updated: 2026-11-07

Status: Initial outline. Follow the master roadmap for shared adoption principles, dependency identities, and sequencing.

Baseline and Target

Audita currently uses PromptKit v0.14.0. Its LLM runtime uses a shared engine, application-owned backend overrides, curated profile inspection, and prepared execution.

Adopt PromptKit v0.20.0 through its native configuration and execution APIs. Retain the built-in OpenRouter backend and bundled profiles. They must be usable through the normal selection and credential mechanisms, not merely visible in an inventory while Audita rejects them for lacking a duplicate registration. Expose native resource and configuration inspection through the full standard ckprompt surface described in the CommandKit outline.

PromptKit owns resources, composition, provider settings and credentials, preparation, transport, structural repair, and backend admission. Audita owns proposal/validation role selection, transcript processing, domain decisions, response contracts, and truthful partial-success reporting. Review existing application-only endpoint and credential restrictions against those boundaries.

Use the pinned migration guide, format reference, and v0.20 release notes. The bundle is default-on; older migration prose about catalog removal does not mean the current release has no bundled resources. It does not select an implicit execution profile or make provider calls during construction.

Agreed Direction and Migration Work

1. Move to go.maximumdirect.net/promptkit together with ConfigKit's new types. Remove the old external catalog dependencies when no longer incorporated; retain PromptKit's built-in catalog rather than disabling it.
2. Convert root and collection backends, profiles, and prompts to identified lists with explicit id fields. Use sibling extends: {id: parent} and complete same-ID replacement records. Typed source builders use ordered slices. Preserve provider settings deliberately: partial same-ID replacements no longer merge fields. Use exact native collection references where collections are selected; mounting does not rewrite stored references.
3. Convert the seven embedded prompts and maintained operator examples/fixtures. Remove prompt version selectors and descriptive PromptVersion metadata from requests, registries, inspection, and diagnostics. Response-schema versions are separate and need not change. Keep domain instructions and per-call schemas; this adoption is not a prompt-quality rewrite. Shared instruction variables remain available to templates, while native operator overrides control their inclusion. Domain validation remains enforced after model responses.
4. Adapt resource inspection to optional profile fields and separate backend inspection. These describe resources, not completed requests. Use real PrepareExecution details and RunPrepared for execution of the same captured request. Do not duplicate PromptKit's full resolver or construct synthetic requests merely to reproduce the old profile summary. Inspect bundled and unselected partial resources without requiring them to be runnable.
5. Adopt native credential precedence, including bundled OpenRouter environment lookup. Migrate any retained application secret references deliberately; do not blanket-clear library credential sources or reject a valid native selection merely because it differs from today's Audita backend map. Preserve secret-safe diagnostics using the library's public boundaries and Audita's domain artifact redaction; evaluate actual gaps with synthetic keys.
6. Review presence semantics field by field. Null endpoint, credential-source, and whole provider map now allow backend defaults; explicit empty strings clear endpoint/credential sources. Null does not suppress the entire backend provider map. Sampling fields have distinct semantics. Avoid blanket null or zero conversion and document intentional request changes.
7. Update captured-source accounting for list indexes and collection prefixes, including inherited/moved content-file origins. Preserve output-collision protection for consumed host documents and effective message files. Array positions are addresses, not durable resource identities.
8. Keep self-contained embedded response schemas. The new schema rule does not require a bundler for Audita's current schemas. Check custom artifact-reader ownership only where such a reader is actually used. Preserve native retries, structural repair, cancellation, deadlines, and shared engine admission while retaining Audita's domain reconciliation and partial-success outcomes.

Update configuration, LLM integration, runtime internals, prompt guidance, operator examples, diagnostics metadata documentation, and attribution with the implementation. Standard inspection replaces curated-only disclosure; prompts and provider settings may appear where the library's normal inspection exposes them, with native redaction. Do not accidentally promise old prompt hashes.

Acceptance and Upstream Requests

Verify native bundle inventory and selection, configuration/resource/prepared view distinctions, inheritance and replacement, credential precedence, optional fields, source-relative messages and collisions, and captured configuration. Use controlled providers to verify actual targets, domain schemas, shared admission, retry/repair budgets, cancellation, and partial success. Standard inspection must work without model calls; library presence alone does not prove successful Audita integration.

No upstream request is yet selected. PromptKit is mature but pre-v1: significant blockers or awkward public boundaries can justify focused requests. Submit the minimal reproducer, desired outcome, and domain justification before building substantial local machinery. A review probe demonstrated distinct base/derived backend records preserving provider fields; that is an available native technique, not a decision to retain Audita's old backend ownership model.

Open Decisions

Backend, Credential, and Admission Ownership

Recommendation: make native PromptKit resources the authoritative backend configuration and remove duplicate application registration/endpoint enforcement unless a concrete processing requirement needs it. Keep Audita role selections and operation budgets, and use native backend capacity settings for workloads. This makes bundled profiles usable and avoids losing operator fields through a highest-priority application replacement. Plan the existing backend/secret file migration with the ConfigKit outline.

The current architecture policy requires finite shared admission. Determine whether that remains a domain requirement and how native configuration satisfies it for bundled and custom selections. Do not silently reject the bundle, impose an arbitrary cap, or weaken the policy during implementation. Any selected exception needs a documented reason and an explicit policy update.

Alternative: retain a narrow application capacity or credential policy and express it through native derived backends/profiles. The probe shows this can preserve provider fields while supplying application-owned fields. It is viable if operational requirements demand it, but introduces naming/reference conventions and can recreate duplicate ownership. Prefer an upstream facility if a justified policy cannot be applied cleanly without replacing whole resources or resolver logic. Blanket preservation of today's restrictions is not the selected default.

Existing Curated Profile Summary

Recommendation: use standard resource inspection and prepared-request preview for their distinct meanings; retire the old completed-profile summary unless a specific Audita role summary remains useful. This avoids a parallel target resolver and aligns operator expectations.

Alternative: retain a small role-to-resource summary alongside the full native commands. It helps transcript operators identify proposal and validation choices, but must clearly describe resource values rather than implying completed request settings. It adds maintenance and must not constrain native inspection.