promptkit/docs/roadmap/future.md

Future Feature Ideas

Purpose

This document catalogs reasonably specific ideas that may be useful in future Promptkit development. It is an idea pool, not a commitment, schedule, or description of current behavior.

Ideas belong here while they are worth retaining but have not been selected for active development. Keep each entry at the level of intended capability, consumer value, and important scope boundaries. Defer API design, implementation details, sequencing, and acceptance criteria until an idea is selected.

Using This Catalog

• Add an idea when its purpose and likely value can be stated clearly.
• Keep entries independent enough that maintainers can evaluate and select them individually.
• Note significant dependencies or boundary concerns, but do not turn entries into implementation plans.
• Treat inclusion as an invitation to evaluate, not as approval or priority.
• When an idea is selected, move its active planning to a focused roadmap or, when it requires a durable architectural decision, an ADR. Update current-state documentation only when implementation lands.
• Remove ideas that are no longer relevant. Retain a rejected idea only when its rationale is likely to prevent repeated reconsideration.

Future capabilities must continue to respect the architecture policy, particularly Promptkit's role as an application-neutral library and its boundary with downstream consumers.

Ideas

Executable preparation handles

Allow a consumer to prepare one exact execution, inspect and retain its caller-owned preparation details, and later execute that already-prepared work without reloading or rerendering prompt, profile, schema, or input sources. This would remove the duplicate Prepare-then-Run workaround reported by Notarius and Weatherreporter.

• Keep the handle opaque, engine-bound, non-serializable, and initially one-shot.
• Keep existing Prepare and Run workflows available.
• Return public preparation details under existing caller-ownership and credential-redaction rules.
• Perform backend admission when execution begins rather than reserving capacity while a consumer retains the prepared handle.
• Treat a separate atomic detailed-run method as possible later convenience rather than a second initial execution model.

Prompt-independent profile inspection

Provide exact profile lookup and structural resolution without requiring a synthetic prompt, placeholder inputs, or model generation. This shared need is described by Notarius and Weatherreporter.

• Apply ordinary built-in, file-backed, and programmatic profile precedence.
• Validate referenced backend membership and the structurally resolved execution target.
• Report credential requirements and environment-variable names without exposing credential values or requiring current credential availability.
• Support exact lookup by profile ID; enumeration is not required initially.

Prompt-definition inspection

Provide exact prompt-definition lookup without rendering, placeholder inputs, profile resolution, or model generation, as requested by Weatherreporter.

• Return caller-owned identity, version, input definitions, default-profile, output-contract, and opaque definition-equality information.
• Apply ordinary prompt-source precedence and exact ID/version selection.
• Validate the selected definition and referenced prompt content structurally, without returning source bodies or rendered messages.
• Leave complete cross-source corpus validation and enumeration outside the initial inspection contract.

Structured capacity errors

Add safe structured context to backend admission rejection, as requested by Notarius and Weatherreporter.

• Preserve compatibility with errors.Is(err, ErrCapacityExceeded).
• Support errors.As to obtain the stable backend ID.
• Do not expose endpoints, credential configuration or values, request content, or speculative retry timing.
• Keep retry and backoff policy with downstream consumers.

Entry Format

Use a short heading followed by a concise summary. Add focused bullets when they help preserve important scope boundaries without becoming an implementation plan:

### Idea name

Describe the intended capability, who benefits, and the most important scope
boundary or dependency.

- Optionally record an important behavior or boundary.