pi-beer-promptbook 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,20 @@
+# Changelog
+
+## 0.1.0
+
+Initial release.
+
+- Task-routed prompt profiles: a profile is a plain `.md` (frontmatter
+  `name`/`version`/`task`; the body IS the prompt); `resolveTask("task")`
+  returns it. Dumb registry — no roles, no decisions, no LLM calls.
+- Pi extension via the official `before_agent_start` hook: appends the
+  resolved rules block every turn; never doubles, never breaks the prompt.
+- 9 bundled disciplines: multilingual-rules (default), classify-memory,
+  code-review, security-review, handoff-summary, ui-design,
+  library-research, debug, test-write.
+- Fail-safe tiers: task-scoped pin → `PROMPTBOOK_TASK_MAP` env → user
+  dir → builtin → caller fallback. Never throws; typo'd tasks get a
+  near-match suggestion.
+- User override: drop a `.md` in `~/.pi/agent/pi-beer-promptbook-profiles/`.
+- CI: strict typecheck, 80-assert smoke (real compile + real import),
+  28-case routing matrix.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 DanHuy-04
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,174 @@
+# pi-beer-promptbook
+
+Prompt profiles as markdown, routed by task. A profile is a plain `.md` file whose frontmatter declares its `task`; any package asks `resolveTask("the-task")` and gets that prompt. Zero runtime dependencies, zero LLM calls, zero registration.
+
+Formerly `pi-promptbook`. Old URLs redirect; profiles dropped in the pre-rename user dirs (`~/.pi/agent/pi-promptbook-profiles/`, `pi-beer-prompt-profiles/`) keep resolving — writes go to `pi-beer-promptbook-profiles/`.
+
+## The idea
+
+- **Profile** = one `.md` file. Frontmatter is the metadata (`name`, `task`, …); the body *is* the prompt.
+- **Task** = the routing key — kebab-case, e.g. `summarize`, `audit`, `rules`.
+- **Registry** = this package. It answers exactly one question — *which profile serves task X?* — and nothing else.
+
+Swap the prompt behind a task by dropping a different file in the user dir. No code changes, no registration, no config. The old file simply stops winning.
+
+## Quick start — as a Pi extension
+
+```sh
+pi install git:github.com/DanHuy-04/pi-beer-promptbook
+```
+
+That's it. Every turn, the resolved rules block is appended to the system prompt: the agent parses messy multilingual messages itself (goal → knowns → constraints, code/paths/errors kept verbatim) and answers in the user's language. The block never doubles across turns, and a broken profile never touches the prompt — set `PROMPTBOOK_OFF=1` to disable.
+
+Default profile: `multilingual-rules`. Point another one at your model with `PROMPTBOOK_PROFILE`, or per-model with `PROMPTBOOK_PROFILE_MAP` (see [Configuration](#configuration)).
+
+## Quick start — as a library
+
+For package authors who need prompts without hardcoding them:
+
+```jsonc
+// package.json
+"dependencies": { "pi-beer-promptbook": "github:DanHuy-04/pi-beer-promptbook" }
+```
+
+```ts
+import { resolveTask, getBuiltin } from "pi-beer-promptbook";
+
+const { profile, warnings } = resolveTask({
+	task: "summarize",                // your package's task key
+	spec: configuredPin || undefined, // explicit pin wins when set
+	fallback: getBuiltin("multilingual-rules"),
+});
+const prompt = profile?.build();     // → string
+```
+
+Your users override the prompt without touching your code:
+
+```
+~/.pi/agent/pi-beer-promptbook-profiles/my-summary.md   ← task: summarize
+```
+
+The file is picked up on the next `resolveTask` call. Task vocabularies belong to consumers — this package knows no task names, which is what keeps drop-in distribution possible.
+
+## Routing rules
+
+```
+ resolveTask(task)
+        |
+        v
+ 1  explicit pin (spec)         -- hit -->  profile
+        | miss
+        v
+ 2  PROMPTBOOK_TASK_MAP env     -- hit -->  profile
+        | miss
+        v
+ 3  user profile declaring it   -- hit -->  profile
+        | miss
+        v
+ 4  builtin declaring it        -- hit -->  profile
+        | miss
+        v
+ 5  caller's fallback           --------->  profile
+```
+
+- **The pin is task-scoped.** A pinned profile is used only if it declares
+  the task being asked; otherwise resolution warns and continues down the
+  chain — a pin can prefer, never redirect across tasks.
+- **Never throws.** Every tier falls through; an unserved task returns warnings instead:
+  `task "compact-clasify" has no profile — did you mean "compact-classify"? — using fallback`
+- **Ambiguity is deterministic.** Several user profiles declaring the same task → first by path, with a warning.
+- **Task form is enforced at parse time** (`^[a-z][a-z0-9-]*$`) — a typo like `Compact Classify` fails when the file is saved, not silently at routing time.
+
+## Profile format
+
+```md
+---
+name: my-rules
+version: 1.0.0
+task: rules
+description: What behavior this profile shapes.
+placeholders: []
+---
+<my-rules>
+Answer in {{language}}.
+…your rules…
+</my-rules>
+```
+
+- `name`, `version`, `task` are required; body must be non-empty.
+- The body after the frontmatter IS the prompt block.
+- `{{var}}` and `{{#if x}}…{{/if}}` render at build time (empty/missing → empty string).
+- XML tags are convention, not requirement.
+
+Bundled profiles:
+
+| Profile | Task | Purpose |
+|---|---|---|
+| `multilingual-rules` | `rules` | Multilingual message parsing, verbatim facts, answer in the user's language |
+| `classify-memory` | `compact-classify` | Language-agnostic fact classifier for compaction pipelines |
+| `code-review` | `code-review` | Findings ordered correctness → security → maintainability, each with evidence and fix |
+| `security-review` | `security-review` | Evidence-backed vulnerability hunting — location, class, attack path, trigger |
+| `handoff-summary` | `summarize` | Compressed handoff: state, decisions, risks, next steps — nothing else |
+| `ui-design` | `ui-design` | Token-first design system, all UI states, accessibility, AI-slop avoidance |
+| `library-research` | `library-research` | Source-verified library answers — verbatim signatures, cross-referenced evidence |
+| `debug` | `debug` | Root-cause discipline — reproduce, quote evidence, fix the mechanism, re-run |
+| `test-write` | `test-write` | Tests verify the contract — failing test before fix, never edit a test to pass |
+
+## Configuration
+
+| Env | Mode | Effect |
+|---|---|---|
+| `PROMPTBOOK_PROFILE=<name or path>` | extension | profile for every model |
+| `PROMPTBOOK_PROFILE_MAP='{"sonnet":"./terse.md","gpt-5":"multilingual-rules"}'` | extension | per-model — a key matches when the model id contains it; longest key wins |
+| `PROMPTBOOK_TASK_MAP='{"summarize":"my-profile"}'` | library | per-task pin |
+| `PROMPTBOOK_OFF=1` | extension | hook not registered |
+
+Legacy `BEER_PROMPT_*` names are still honored. Use **forward slashes** in JSON paths (`C:/rules/my.md`) — single backslashes are invalid JSON escapes; bad values fall back safely.
+
+## Library surface
+
+| Export | Purpose |
+|---|---|
+| `resolveTask({ task, spec?, fallback? })` | Route by task key → `{ profile, source, warnings }` |
+| `loadProfile(spec?)` | Resolve by builtin name or `.md` path → `{ profile, source, warning? }` |
+| `listUserProfiles()` / `userProfilesDir()` | User-dir scan (current + legacy dirs) / where writes go |
+| `listBuiltins()` / `getBuiltin(name)` | Bundled profile registry |
+| `resolveForModel({ mapRaw, profileRaw, modelId, fallback })` | Per-model resolution (extension-mode internals) |
+| `parseProfileMarkdown(md, label?)` | Compile markdown into a `PromptProfile` |
+| `render(template, input)` | `{{var}}` + `{{#if}}` rendering |
+| `DEFAULT_PROFILE_NAME` | `"multilingual-rules"` |
+| types: `ProfileMeta`, `PromptProfile`, `LoadResult`, `TaskResolveInput/Result`, `UserProfileEntry`, `ResolveInput/Result` | |
+
+## Architecture
+
+```
+pi-beer-promptbook/
+├── index.ts            # shell: extension factory (before_agent_start) + public exports
+├── src/
+│   ├── core/           # PURE — no SDK imports, no I/O
+│   │   ├── types.ts           # contract
+│   │   ├── frontmatter.ts     # mini YAML parser
+│   │   ├── render.ts          # {{var}}/{{#if}} renderer
+│   │   ├── profile-parser.ts  # markdown → PromptProfile (task form enforced)
+│   │   └── resolve.ts         # per-model tier resolution (delegates disk to the loader seam)
+│   ├── registry.ts     # disk seam: bundled profiles dir
+│   ├── loader.ts       # disk seam: one .md by name/path
+│   └── task.ts         # disk seam: user dirs + task routing
+├── profiles/           # data: the bundled profiles
+└── scripts/            # smoke.mjs (compile+import, no mocks) · matrix.mjs (28-case routing)
+```
+
+Pure core / imperative shell: decisions live in `src/core/` and are testable with plain Node; every filesystem read sits behind the three `src/` seams (`registry`, `loader`, `task`) — `core/resolve.ts` reaches disk only through the loader seam.
+
+## Development
+
+```sh
+npm install
+npm run check            # typecheck (strict) + smoke: real compile, real import
+npm run build            # tsc emit → dist/ (what consumers run)
+node scripts/matrix.mjs  # 28-case routing matrix (same gates CI runs)
+```
+
+## License
+
+MIT — see [LICENSE](LICENSE).

package/dist/index.d.ts

@@ -0,0 +1,27 @@
+/**
+ * pi-beer-promptbook — task-routed prompt profiles for Pi.
+ *
+ * As a Pi extension (default export): appends a rule block from a markdown
+ * profile to the system prompt every turn, via the official
+ * `before_agent_start` hook. The agent itself then parses messy
+ * multilingual user messages and answers in the user's language —
+ * ZERO extra LLM calls, zero latency, no second model that could distort
+ * the user's words.
+ *
+ * As a library (named exports): profiles are plain markdown; the loader
+ * resolves builtin names, file paths, or env specs with fail-safe, and
+ * resolveTask routes by the frontmatter `task` key (the dumb registry:
+ * task -> prompt, no roles, no decisions).
+ */
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+declare const _default: (pi: ExtensionAPI) => void;
+export default _default;
+export type { ProfileMeta, PromptProfile, LoadResult } from "./src/core/types.js";
+export { parseProfileMarkdown } from "./src/core/profile-parser.js";
+export { render } from "./src/core/render.js";
+export { DEFAULT_PROFILE_NAME, getBuiltin, listBuiltins } from "./src/registry.js";
+export { loadProfile } from "./src/loader.js";
+export { resolveTask, listUserProfiles, userProfilesDir } from "./src/task.js";
+export type { TaskResolveInput, TaskResolveResult, UserProfileEntry } from "./src/task.js";
+export { resolveForModel } from "./src/core/resolve.js";
+export type { ResolveInput, ResolveResult } from "./src/core/resolve.js";

package/dist/index.js

@@ -0,0 +1,49 @@
+import { DEFAULT_PROFILE_NAME, getBuiltin } from "./src/registry.js";
+import { resolveForModel } from "./src/core/resolve.js";
+const modelIdOf = (ctx) => {
+    const model = ctx?.model;
+    const id = typeof model?.id === "string" ? model.id : typeof model?.name === "string" ? model.name : "";
+    return id.toLowerCase();
+};
+/**
+ * Resolve the active profile for the current model. Priority:
+ *   1. BEER_PROMPT_PROFILE_MAP — JSON object { "<model-id substring>": "<spec>" };
+ *      a key matches when the model id contains it; the longest matching key wins.
+ *   2. BEER_PROMPT_PROFILE — every model.
+ *   3. Built-in default.
+ * A failed tier falls through to the next — never breaks the system prompt.
+ */
+const resolveProfile = (ctx) => resolveForModel({
+    mapRaw: process.env.PROMPTBOOK_PROFILE_MAP ?? process.env.BEER_PROMPT_PROFILE_MAP,
+    profileRaw: process.env.PROMPTBOOK_PROFILE ?? process.env.BEER_PROMPT_PROFILE,
+    modelId: modelIdOf(ctx),
+    fallback: getBuiltin(DEFAULT_PROFILE_NAME),
+}).profile;
+export default (pi) => {
+    if (process.env.PROMPTBOOK_OFF || process.env.BEER_PROMPT_OFF)
+        return;
+    pi.on("before_agent_start", (event, ctx) => {
+        const base = event.systemPrompt;
+        if (!base)
+            return;
+        const rules = resolveProfile(ctx);
+        if (!rules)
+            return;
+        let block;
+        try {
+            block = rules.build().trim();
+        }
+        catch {
+            return; // a broken profile must never damage the system prompt
+        }
+        if (!block || base.includes(block))
+            return; // never append twice
+        return { systemPrompt: `${base}\n\n${block}` };
+    });
+};
+export { parseProfileMarkdown } from "./src/core/profile-parser.js";
+export { render } from "./src/core/render.js";
+export { DEFAULT_PROFILE_NAME, getBuiltin, listBuiltins } from "./src/registry.js";
+export { loadProfile } from "./src/loader.js";
+export { resolveTask, listUserProfiles, userProfilesDir } from "./src/task.js";
+export { resolveForModel } from "./src/core/resolve.js";

package/dist/src/core/frontmatter.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Minimal YAML frontmatter parser — scalars and string lists only.
+ * Zero dependencies by design: profiles are data, and the accepted
+ * frontmatter shape is deliberately small (name/version/task/description/
+ * placeholders). Profiles needing more belong to the caller, not the format.
+ */
+export type FrontmatterValue = string | string[];
+export interface Frontmatter {
+    [key: string]: FrontmatterValue;
+}
+export interface ParsedMarkdown {
+    fm: Frontmatter;
+    /** Body after the closing `---`. */
+    body: string;
+}
+/** Parse a `---` frontmatter block; throws with a clear message when absent or malformed. */
+export declare const parseFrontmatter: (md: string) => ParsedMarkdown;

package/dist/src/core/frontmatter.js

@@ -0,0 +1,35 @@
+const FRONTMATTER_RE = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/;
+const LIST_ITEM_RE = /^\s+-\s+(.*)$/;
+const KEY_VALUE_RE = /^([A-Za-z0-9_-]+):\s*(.*)$/;
+const stripQuotes = (value) => value.length >= 2 && value.startsWith('"') && value.endsWith('"') ? value.slice(1, -1) : value;
+/** Parse a `---` frontmatter block; throws with a clear message when absent or malformed. */
+export const parseFrontmatter = (md) => {
+    const match = FRONTMATTER_RE.exec(md);
+    if (!match)
+        throw new Error("profile markdown must start with a --- frontmatter block");
+    const fm = {};
+    let currentList = null;
+    for (const line of match[1].split(/\r?\n/)) {
+        const trimmed = line.trim();
+        if (!trimmed || trimmed.startsWith("#"))
+            continue;
+        const listItem = LIST_ITEM_RE.exec(line);
+        if (listItem && currentList) {
+            currentList.push(stripQuotes(listItem[1].trim()));
+            continue;
+        }
+        const kv = KEY_VALUE_RE.exec(line);
+        if (!kv)
+            throw new Error(`unparseable frontmatter line: "${line}"`);
+        const value = kv[2].trim();
+        if (value === "") {
+            currentList = [];
+            fm[kv[1]] = currentList;
+        }
+        else {
+            currentList = null;
+            fm[kv[1]] = stripQuotes(value);
+        }
+    }
+    return { fm, body: match[2] ?? "" };
+};

package/dist/src/core/profile-parser.d.ts

@@ -0,0 +1,15 @@
+import type { PromptProfile } from "./types.js";
+/**
+ * Compile a rules profile (frontmatter + rule-block body) into a
+ * PromptProfile. Layout — the body after the closing `---` IS the rule
+ * block, appended verbatim (after {{var}} rendering) to the host agent's
+ * system prompt:
+ *
+ *   ---
+ *   name / version / task / description / placeholders
+ *   ---
+ *   <user-messages>
+ *   …rules the agent itself follows…
+ *   </user-messages>
+ */
+export declare const parseProfileMarkdown: (md: string, sourceLabel?: string) => PromptProfile;

package/dist/src/core/profile-parser.js

@@ -0,0 +1,43 @@
+import { parseFrontmatter } from "./frontmatter.js";
+import { render } from "./render.js";
+/**
+ * Compile a rules profile (frontmatter + rule-block body) into a
+ * PromptProfile. Layout — the body after the closing `---` IS the rule
+ * block, appended verbatim (after {{var}} rendering) to the host agent's
+ * system prompt:
+ *
+ *   ---
+ *   name / version / task / description / placeholders
+ *   ---
+ *   <user-messages>
+ *   …rules the agent itself follows…
+ *   </user-messages>
+ */
+export const parseProfileMarkdown = (md, sourceLabel = "profile") => {
+    const { fm, body } = parseFrontmatter(md);
+    const name = typeof fm.name === "string" ? fm.name : "";
+    const version = typeof fm.version === "string" ? fm.version : "";
+    const task = typeof fm.task === "string" ? fm.task : "";
+    if (!name || !version || !task) {
+        throw new Error(`${sourceLabel}: frontmatter requires name, version, task`);
+    }
+    // Task is a routing key, so its FORM is part of the contract: kebab-case
+    // only. A typo ("Compact Classify", "compact_clasify") must fail HERE —
+    // at parse/save time — instead of silently never matching at resolve time.
+    if (!/^[a-z][a-z0-9-]*$/.test(task)) {
+        throw new Error(`${sourceLabel}: task "${task}" must be kebab-case (lowercase letters, digits, dashes)`);
+    }
+    const ruleBlock = body.trim();
+    if (!ruleBlock) {
+        throw new Error(`${sourceLabel}: rule block body must be non-empty`);
+    }
+    const build = (input = {}) => render(ruleBlock, input);
+    return {
+        name,
+        version,
+        task,
+        description: typeof fm.description === "string" ? fm.description : undefined,
+        placeholders: Array.isArray(fm.placeholders) ? fm.placeholders : [],
+        build,
+    };
+};

package/dist/src/core/render.d.ts

@@ -0,0 +1 @@
+export declare const render: (template: string, input: Record<string, unknown>) => string;

package/dist/src/core/render.js

@@ -0,0 +1,21 @@
+/**
+ * Template renderer: `{{variable}}` substitution and `{{#if variable}}…{{/if}}`
+ * blocks (truthy = non-empty string after trim, or non-null non-false value).
+ * No nesting, no else — deliberately minimal; profiles are data, not programs.
+ */
+const IF_BLOCK_RE = /\{\{#if\s+([A-Za-z0-9_.-]+)\}\}([\s\S]*?)\{\{\/if\}\}/;
+const VAR_RE = /\{\{\s*([A-Za-z0-9_.-]+)\s*\}\}/g;
+const isTruthy = (value) => typeof value === "string" ? value.trim().length > 0 : value !== null && value !== undefined && value !== false;
+export const render = (template, input) => {
+    let out = template;
+    let match = IF_BLOCK_RE.exec(out);
+    while (match !== null) {
+        const replacement = isTruthy(input[match[1]]) ? match[2] : "";
+        out = out.slice(0, match.index) + replacement + out.slice(match.index + match[0].length);
+        match = IF_BLOCK_RE.exec(out);
+    }
+    return out.replace(VAR_RE, (_full, key) => {
+        const value = input[key];
+        return value === null || value === undefined ? "" : String(value);
+    });
+};

package/dist/src/core/resolve.d.ts

@@ -0,0 +1,20 @@
+import type { PromptProfile } from "./types.js";
+export interface ResolveInput {
+    /** JSON object `{ "<model-id substring>": "<spec>" }` — a key matches when
+     *  the model id contains it; the longest matching key wins. */
+    mapRaw?: string | undefined;
+    /** Single spec applied to every model. */
+    profileRaw?: string | undefined;
+    /** Model id (case-insensitive match). "" simply never matches the MAP tier. */
+    modelId: string;
+    /** Last-resort profile — usually a bundled builtin. May be null. */
+    fallback: PromptProfile | null;
+}
+export interface ResolveResult {
+    profile: PromptProfile | null;
+    tier: "map" | "profile" | "fallback" | "none";
+}
+/** Per-model profile resolution shared by every Beer package: MAP tier,
+ *  then the single-profile tier, then the caller's fallback. A failed tier
+ *  falls through to the next — this never throws and never breaks a caller. */
+export declare const resolveForModel: (input: ResolveInput) => ResolveResult;

package/dist/src/core/resolve.js

@@ -0,0 +1,31 @@
+import { loadProfile } from "../loader.js";
+/** Per-model profile resolution shared by every Beer package: MAP tier,
+ *  then the single-profile tier, then the caller's fallback. A failed tier
+ *  falls through to the next — this never throws and never breaks a caller. */
+export const resolveForModel = (input) => {
+    if (input.mapRaw) {
+        try {
+            const map = JSON.parse(input.mapRaw);
+            const id = input.modelId.toLowerCase();
+            const keys = Object.keys(map)
+                .filter((key) => id.includes(key.toLowerCase()))
+                .sort((a, b) => b.length - a.length);
+            if (keys.length > 0) {
+                const byModel = loadProfile(map[keys[0]]);
+                if (byModel.profile)
+                    return { profile: byModel.profile, tier: "map" };
+            }
+        }
+        catch {
+            // malformed MAP JSON — skip the tier, fall through
+        }
+    }
+    if (input.profileRaw) {
+        const { profile } = loadProfile(input.profileRaw);
+        if (profile)
+            return { profile, tier: "profile" };
+    }
+    if (input.fallback)
+        return { profile: input.fallback, tier: "fallback" };
+    return { profile: null, tier: "none" };
+};

package/dist/src/core/types.d.ts

@@ -0,0 +1,29 @@
+/** Metadata parsed from a profile's YAML frontmatter. */
+export interface ProfileMeta {
+    /** Stable identifier used for routing: "multilingual-rules", … */
+    name: string;
+    /** Profile version traced alongside every result it produces. */
+    version: string;
+    /** Routing key — kebab-case, validated at parse time. */
+    task: string;
+    /** Routing hint: what behavior this profile shapes. */
+    description?: string;
+    /** Variable names the rule block references (all optional at runtime). */
+    placeholders: string[];
+}
+/**
+ * A rules profile: markdown compiled into a builder. `build` returns the
+ * rule block to append to the host agent's system prompt.
+ */
+export interface PromptProfile extends ProfileMeta {
+    build(input?: Record<string, unknown>): string;
+}
+/** Result of resolving a profile by spec. */
+export interface LoadResult {
+    /** null when nothing was specified or the spec failed — caller falls back. */
+    profile: PromptProfile | null;
+    /** "builtin:<name>" | "file:<resolved path>" | "none" */
+    source: string;
+    /** Set when a spec failed to resolve. */
+    warning?: string;
+}

package/dist/src/core/types.js

@@ -0,0 +1 @@
+export {};

package/dist/src/frontmatter.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Minimal YAML frontmatter parser — scalars and string lists only.
+ * Zero dependencies by design: profiles are data, and the accepted
+ * frontmatter shape is deliberately small (name/version/task/description/
+ * placeholders). Profiles needing more belong to the caller, not the format.
+ */
+export type FrontmatterValue = string | string[];
+export interface Frontmatter {
+    [key: string]: FrontmatterValue;
+}
+export interface ParsedMarkdown {
+    fm: Frontmatter;
+    /** Body after the closing `---`. */
+    body: string;
+}
+/** Parse a `---` frontmatter block; throws with a clear message when absent or malformed. */
+export declare const parseFrontmatter: (md: string) => ParsedMarkdown;

package/dist/src/frontmatter.js

@@ -0,0 +1,35 @@
+const FRONTMATTER_RE = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/;
+const LIST_ITEM_RE = /^\s+-\s+(.*)$/;
+const KEY_VALUE_RE = /^([A-Za-z0-9_-]+):\s*(.*)$/;
+const stripQuotes = (value) => value.length >= 2 && value.startsWith('"') && value.endsWith('"') ? value.slice(1, -1) : value;
+/** Parse a `---` frontmatter block; throws with a clear message when absent or malformed. */
+export const parseFrontmatter = (md) => {
+    const match = FRONTMATTER_RE.exec(md);
+    if (!match)
+        throw new Error("profile markdown must start with a --- frontmatter block");
+    const fm = {};
+    let currentList = null;
+    for (const line of match[1].split(/\r?\n/)) {
+        const trimmed = line.trim();
+        if (!trimmed || trimmed.startsWith("#"))
+            continue;
+        const listItem = LIST_ITEM_RE.exec(line);
+        if (listItem && currentList) {
+            currentList.push(stripQuotes(listItem[1].trim()));
+            continue;
+        }
+        const kv = KEY_VALUE_RE.exec(line);
+        if (!kv)
+            throw new Error(`unparseable frontmatter line: "${line}"`);
+        const value = kv[2].trim();
+        if (value === "") {
+            currentList = [];
+            fm[kv[1]] = currentList;
+        }
+        else {
+            currentList = null;
+            fm[kv[1]] = stripQuotes(value);
+        }
+    }
+    return { fm, body: match[2] ?? "" };
+};

package/dist/src/loader.d.ts

@@ -0,0 +1,7 @@
+import type { LoadResult } from "./core/types.js";
+/** Resolve ONE spec — a built-in profile name or a path to a `.md` file.
+ * Resolution NEVER falls back silently inside this function — a failed spec
+ * returns `profile: null` plus a warning, and the caller chooses its own
+ * fallback (typically `getBuiltin(DEFAULT_PROFILE_NAME)`). A bad spec can
+ * never break the caller. */
+export declare const loadProfile: (spec?: string) => LoadResult;

package/dist/src/loader.js

@@ -0,0 +1,41 @@
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { getBuiltin } from "./registry.js";
+import { parseProfileMarkdown } from "./core/profile-parser.js";
+const isPathLike = (value) => value.startsWith(".") ||
+    value.startsWith("/") ||
+    value.startsWith("\\") ||
+    /^[a-zA-Z]:[\\/]/.test(value) ||
+    value.endsWith(".md");
+/** Resolve ONE spec — a built-in profile name or a path to a `.md` file.
+ * Resolution NEVER falls back silently inside this function — a failed spec
+ * returns `profile: null` plus a warning, and the caller chooses its own
+ * fallback (typically `getBuiltin(DEFAULT_PROFILE_NAME)`). A bad spec can
+ * never break the caller. */
+export const loadProfile = (spec) => {
+    const raw = spec?.trim() || "";
+    if (!raw)
+        return { profile: null, source: "none" };
+    const builtin = getBuiltin(raw);
+    if (builtin)
+        return { profile: builtin, source: `builtin:${raw}` };
+    if (isPathLike(raw)) {
+        const path = resolve(raw);
+        try {
+            const profile = parseProfileMarkdown(readFileSync(path, "utf8"), raw);
+            return { profile, source: `file:${path}` };
+        }
+        catch (error) {
+            return {
+                profile: null,
+                source: "none",
+                warning: `profile "${raw}" failed to load (${error.message})`,
+            };
+        }
+    }
+    return {
+        profile: null,
+        source: "none",
+        warning: `profile "${raw}" not found (not a built-in name, not a path)`,
+    };
+};

package/dist/src/profile-parser.d.ts

@@ -0,0 +1,15 @@
+import type { PromptProfile } from "./types.js";
+/**
+ * Compile a rules profile (frontmatter + rule-block body) into a
+ * PromptProfile. Layout — the body after the closing `---` IS the rule
+ * block, appended verbatim (after {{var}} rendering) to the host agent's
+ * system prompt:
+ *
+ *   ---
+ *   name / version / task / description / placeholders
+ *   ---
+ *   <user-messages>
+ *   …rules the agent itself follows…
+ *   </user-messages>
+ */
+export declare const parseProfileMarkdown: (md: string, sourceLabel?: string) => PromptProfile;