promptkit/docs/roadmap/listing.md

Profile And Prompt Listing

Status: Implemented (2026-10-09). All public listing behavior and verification are complete; see the implementation plan for completion and verification evidence.

Purpose

Let consumers discover the profiles and prompt versions available in an engine without knowing their identifiers in advance or interpreting configuration history. This supports application selectors, CLI discovery, and configuration editors while keeping PromptKit's public API small.

Listing supplies identities; the existing inspection methods supply details. The implementation plan records the completed work. This roadmap captures feature scope; the public GoDoc owns the current API behavior.

Current Baseline

Review baseline: 03c44923c8a14565dca30f65d93bde79e0962ea2.

• Engine.InspectProfile and Engine.InspectPrompt inspect a known identity. Neither enumerates available entries.
• Engine.InspectConfiguration exposes ConfigKit's captured inspection view. Consumers can enumerate historical paths and filter for surviving effective entries, but that is an indirect configuration-inspection workflow.
• The configuration adapter already captures profiles by literal ID and prompts by literal ID/version pair. Those execution-facing indexes are sufficient for listing; no new configuration loading or registry is needed.

The consumer guide describes existing inspection workflows. The format reference owns keyed definitions and literal identifier semantics. Preserve the final-configuration boundary in ADR 0001 and the facade ownership in the architecture policy.

Target End State

Small Public Listing API

Add two engine methods, following the context and error conventions of the existing prompt/profile inspection methods:

• ListProfiles(ctx) returns profile IDs.
• ListPrompts(ctx) returns small identity values containing ID and Version.

Expose only the identity value needed for prompt listing. GoDoc will own the exact signatures and behavior when implemented. Callers can pass the returned identities to InspectProfile, InspectPrompt, or their execution requests. Bulk inspection results, prompt text, execution targets, source provenance, and credential information do not belong in these results.

Effective Captured Inventory

List the identities present in the engine's final captured configuration, including maintained catalog profiles and consumer-defined profiles and prompts after ConfigKit layering and inheritance. A profile's configured alias or inherited identity remains its own list entry, not its base profile's name. Historical or superseded contributions do not create additional entries.

Each effective profile ID appears once. Each effective prompt ID/version pair appears once, including every configured version of a multi-version prompt. Listing does not choose a default or latest version; the existing omitted-version selection behavior remains unchanged.

Preserve exact identifier spelling. Return profiles in ascending lexical ID order and prompts in ascending lexical ID order, then lexical version order. Version ordering is for deterministic presentation, not semantic-version comparison or a recommendation about which version to execute.

Lightweight Snapshot Read

Listing reads the engine's captured identity indexes. It does not reload sources or files, analyze configuration provenance, resolve credentials, read artifacts or schemas, render, acquire backend capacity, or contact providers.

A profile need not be execution-ready to be listed. Presence in the inventory does not promise valid credentials, provider availability, or successful execution. Catalog entries remain subject to the existing catalog compatibility policy.

Returned slices are caller-owned; modifying one result cannot change the engine or later results. Listing supports concurrent engine use without adding mutable registry state. An empty inventory is a successful result. A nil engine uses ErrInvalidConfig, and cancellation preserves the context error under the existing inspection conventions.

Work Needed From The Baseline

• Add identity-only enumeration to the captured configuration adapter and route it through the internal engine to the public facade. Keep internal representations behind the existing package boundary.
• Add the two public methods and the small prompt identity value, with GoDoc. Avoid obtaining each item's full inspection or copying profile parameters and prompt content merely to list its identity.
• Keep traversal and allocation proportional to the inventory returned. Prefer straightforward reuse of captured indexes; ordering can be prepared during construction rather than repeatedly sorting unchanged identities. Exact storage layouts and allocation counts are implementation choices.
• Add focused tests for effective inventory membership, multiple prompt versions, literal identities and ordering, caller ownership, empty results, and the selected error/cancellation behavior. Include a representative public workflow that lists entries and inspects a returned identity. Reuse existing construction coverage rather than retesting ConfigKit's resolution machinery.
• Add concise listing guidance to the consumer guide and update the relevant internal documentation when implemented. Preserve existing inspection and execution contracts.

Backend enumeration, filtering, pagination, runtime registration, and live catalog/provider discovery are outside this feature's scope. No new caller limits, readiness checks, release gates, or performance guarantees are needed.

Completion

Consumers can enumerate effective profiles and exact prompt versions through the public facade, obtain independent deterministic results, and use those identities with existing operations. Verification follows the testing policy, including focused ownership and concurrent-use checks proportionate to the implementation. Current documentation describes the implemented API without duplicating ConfigKit history semantics.