prompts: expose a reusable Markdown prompt-document resolver

[kamilio]

Problem

Poe-code already has advanced prompt-composition primitives, but they are spread across internal or feature-specific packages:

• @poe-code/config-extends parses Markdown frontmatter, resolves layered base documents, composes prompt bodies with extends: true and {{yield}}, tracks sources/chains, and detects cycles/depth errors.
• @poe-code/design-system provides the one-pass Mustache-compatible renderTemplate implementation used by composition.
• Pipeline provides project-root-constrained {{file "..."}} prompt includes.

New prompt-owning features currently have to either import private workspace packages, copy these patterns, or invent another prompt format. Code review is one current consumer that needs reusable Markdown composition and exact effective-prompt preview.

Proposal

Expose a documented public prompt-document abstraction from poe-code that composes and renders Markdown prompts using the existing poe-code semantics rather than creating a new composition system.

A possible public shape:

const resolved = await resolvePromptDocument({
  filePath,
  basePaths,
  variables,
  cwd,
});

The exact API can differ, but it should provide a high-level prompt-focused wrapper over the existing lower-level pieces.

Reuse existing semantics

The abstraction should reuse and preserve:

• Markdown frontmatter parsing from config-extends;
• extends: true base discovery and chained inheritance;
• {{yield}} layout composition before template rendering;
• one-pass Mustache rendering through the existing template renderer;
• source and resolved-chain reporting;
• existing cycle, maximum-depth, and invalid-document errors;
• pipeline-style file includes if file inclusion is supported.

Do not introduce a separate includes: composition format for the same use case.

Prompt-focused public result

The resolved result should make it easy for a feature to consume and inspect the final prompt, for example:

• composed template before variable rendering;
• rendered final prompt;
• resolved frontmatter/metadata;
• source file and inheritance chain;
• included file paths, if file includes are supported.

The abstraction should support resolving an optional user/project prompt over one or more packaged base directories, so features can ship defaults while allowing small Markdown overrides.

Safety requirements

• Base and included-file resolution must stay inside explicitly configured roots.
• Traversal and symlink escapes must be rejected.
• Circular inheritance and recursive includes must fail with actionable paths.
• Missing bases/includes and unresolved required variables must produce actionable errors.
• Rendering remains one pass after composition so yielded content can contain normal Mustache variables without requiring multi-pass rendering.

Public exposure

Consumers should be able to use the abstraction through documented exports from the published poe-code package. They should not need direct imports from private @poe-code/* workspace packages.

First consumers

• poe-code code-review prompt loading and prompt preview: code-review: expose prompt composition and spawn preview through public config/SDK #384
• Other prompt-owning packages that currently combine config inheritance, rendering, or file includes independently

Acceptance criteria

• A public SDK consumer can resolve a Markdown prompt over packaged base paths using extends: true and {{yield}}.
• The final prompt is rendered once with the existing Mustache renderer.
• The result exposes enough provenance for an exact prompt-preview/debug command.
• File inclusion, if exposed, reuses the established pipeline syntax and is hardened for shared use.
• Tests cover chained inheritance, child/base wrappers, variables inside yielded content, cycles, missing bases, traversal, symlink escapes, and provenance.
• Documentation includes a packaged-base plus project-override example.