@zle13/pi-prompt-snippets 0.1.0

package/README.md

@@ -0,0 +1,118 @@
+# @zle13/pi-prompt-snippets
+
+Mix-and-match single-purpose prompt rules that are prepended or appended to your message when you send it in Pi.
+
+Unlike full skills, each snippet is a lightweight, standalone instruction — toggle exactly the ones you want for your next message.
+
+> **Credits:** Originally created by [Amos Blomqvist](https://github.com/amosblomqvist) in [amosblomqvist/pi-config](https://github.com/amosblomqvist/pi-config).
+
+---
+
+## Installation
+
+```bash
+pi install npm:@zle13/pi-prompt-snippets
+```
+
+Or install locally from source:
+
+```bash
+pi install -l ./packages/prompt-snippets
+```
+
+Then restart Pi or run `/reload` in your active session.
+
+---
+
+## Usage
+
+- Press **Alt+S** or run **/snippets** to open the interactive toggle menu.
+  - `↑` / `↓` (or custom selection keybindings like `Ctrl+P` / `Ctrl+N`) to navigate items.
+  - `Space` to toggle snippet active / inactive.
+  - `Tab` to preview the highlighted snippet (shows name, placement, order, source origin, filename, and prompt body). Press `Tab` or `Esc` (or `Ctrl+G` / `Ctrl+C`) to return to the list with cursor position preserved.
+  - `Enter` to apply your selection.
+  - `Esc` to cancel and discard changes.
+- **Keybinding Integration:** Respects custom `tui.select.*` actions from `~/.pi/agent/keybindings.json` (such as `tui.select.up`, `tui.select.down`, `tui.select.pageUp`, `tui.select.pageDown`, `tui.select.confirm`, and `tui.select.cancel`).
+- **Active Snippet Indicator:** Active snippets appear as a widget above the editor:
+  - `↑ prepend: ...` (accent color) — inserted before your message.
+  - `↓ append: ...` (warning color) — inserted after your message.
+- When you send a message, active snippets are merged in order:
+  `[Prepend group (sorted by order)] → [Your message] → [Append group (sorted by order)]`, separated by blank lines.
+- **Automatic Reset:** Active toggles reset to all off after every send and at session start.
+
+---
+
+## Multi-Directory Hierarchy
+
+Snippets are discovered dynamically across three layers (in increasing precedence):
+
+1. **Bundled package snippets:** Default rules shipped with this extension.
+2. **Global user snippets:** `~/.pi/agent/snippets/*.md`
+3. **Project snippets:** `.pi/snippets/*.md` (in your workspace, honored when the project is trusted).
+
+Files are re-scanned whenever the menu opens or a message is sent, so edits take effect immediately without restarting Pi.
+
+---
+
+## Customizing, Overriding & Disabling Snippets
+
+### 1. Add Your Own Snippets
+
+Create any `.md` file in `~/.pi/agent/snippets/` (for all projects) or `.pi/snippets/` (for the current project):
+
+```markdown
+---
+name: Concise Output
+description: Short, direct answers without unnecessary fluff
+placement: prepend
+order: 10
+---
+Keep your response concise. Skip preamble and unnecessary explanation.
+```
+
+### 2. Override Existing Snippets
+
+Create a file with the same filename (e.g. `.pi/snippets/ask-questions.md` or `~/.pi/agent/snippets/ask-questions.md`). Higher-precedence layers completely override lower-precedence ones.
+
+### 3. Disable Default Snippets
+
+You can disable default or global snippets in two ways:
+
+#### Option A: Frontmatter `disabled: true`
+Create a file with the same filename in `~/.pi/agent/snippets/` or `.pi/snippets/` and set `disabled: true`:
+
+```markdown
+---
+disabled: true
+---
+```
+
+#### Option B: Configuration File
+Create `.pi/prompt-snippets.json` (project-level) or `~/.pi/agent/prompt-snippets.json` (global):
+
+```json
+{
+  "disabled": [
+    "ask-questions",
+    "diagnose-report.md"
+  ]
+}
+```
+
+---
+
+## Snippet Frontmatter Reference
+
+| Field | Type | Default | Description |
+|---|---|---|---|
+| `name` | `string` | Filename without `.md` | Display name shown in the menu |
+| `description` | `string` | `""` | Description subtitle shown in the menu |
+| `placement` | `"prepend"` \| `"append"` | `"append"` | Whether the rule is placed before or after your prompt |
+| `order` | `number` | `9999` | Sort order within its placement group (lower numbers first) |
+| `disabled` | `boolean` | `false` | When `true`, disables/hides this snippet ID from the list |
+
+---
+
+## License
+
+MIT © zle13. Original work © Amos Blomqvist.

package/extensions/loader.ts

@@ -0,0 +1,207 @@
+import { existsSync, readFileSync, readdirSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { CONFIG_DIR_NAME, getAgentDir } from "@earendil-works/pi-coding-agent";
+import type { LoadSnippetsOptions, Snippet, SnippetConfig, SnippetSource } from "./types.js";
+
+const extensionDir = dirname(fileURLToPath(import.meta.url));
+
+/**
+ * Parse frontmatter and body from a snippet markdown file.
+ */
+export function parseSnippet(
+	filename: string,
+	raw: string,
+	source: SnippetSource,
+	filePath: string,
+): { snippet: Snippet | null; disabled: boolean } {
+	const match = raw.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/);
+	if (!match) return { snippet: null, disabled: false };
+
+	const meta: Record<string, string> = {};
+	for (const line of match[1].split(/\r?\n/)) {
+		const kv = line.match(/^([A-Za-z][\w-]*)\s*:\s*(.*)$/);
+		if (kv) meta[kv[1].toLowerCase()] = kv[2].trim().replace(/^["']|["']$/g, "");
+	}
+
+	const disabled =
+		meta.disabled === "true" ||
+		meta.disabled === "yes" ||
+		meta.disabled === "1" ||
+		meta.enabled === "false" ||
+		meta.enabled === "no" ||
+		meta.enabled === "0";
+
+	if (disabled) {
+		return { snippet: null, disabled: true };
+	}
+
+	const body = match[2].trim();
+	if (!body) {
+		return { snippet: null, disabled: false };
+	}
+
+	const parsedOrder = Number.parseInt(meta.order ?? "", 10);
+	return {
+		snippet: {
+			id: filename,
+			name: meta.name || filename.replace(/\.md$/i, ""),
+			description: meta.description ?? "",
+			placement: meta.placement === "prepend" ? "prepend" : "append",
+			order: Number.isFinite(parsedOrder) ? parsedOrder : 9999,
+			body,
+			source,
+			filePath,
+		},
+		disabled: false,
+	};
+}
+
+/**
+ * Load optional prompt-snippets.json config from a directory.
+ */
+export function loadSnippetConfigFile(configPath: string): SnippetConfig | null {
+	if (!existsSync(configPath)) return null;
+	try {
+		const raw = readFileSync(configPath, "utf-8");
+		const parsed = JSON.parse(raw);
+		if (parsed && typeof parsed === "object") {
+			return {
+				disabled: Array.isArray(parsed.disabled) ? parsed.disabled.map(String) : undefined,
+			};
+		}
+	} catch {
+		// Ignore corrupt or unreadable config files
+	}
+	return null;
+}
+
+/**
+ * Resolve the directory where bundled default snippets live.
+ */
+export function resolveBundledSnippetsDir(customDir?: string): string | null {
+	if (customDir && existsSync(customDir)) {
+		return customDir;
+	}
+	const candidate1 = join(extensionDir, "snippets");
+	if (existsSync(candidate1)) return candidate1;
+
+	const candidate2 = join(extensionDir, "..", "snippets");
+	if (existsSync(candidate2)) return candidate2;
+
+	return null;
+}
+
+/**
+ * Load snippets from a single directory.
+ */
+export function scanSnippetDirectory(
+	dir: string,
+	source: SnippetSource,
+): { snippets: Snippet[]; disabledIds: Set<string> } {
+	const snippets: Snippet[] = [];
+	const disabledIds = new Set<string>();
+
+	if (!existsSync(dir)) {
+		return { snippets, disabledIds };
+	}
+
+	try {
+		for (const file of readdirSync(dir)) {
+			if (!file.toLowerCase().endsWith(".md")) continue;
+			const fullPath = join(dir, file);
+			try {
+				const content = readFileSync(fullPath, "utf-8");
+				const { snippet, disabled } = parseSnippet(file, content, source, fullPath);
+				if (disabled) {
+					disabledIds.add(file);
+				} else if (snippet) {
+					snippets.push(snippet);
+				}
+			} catch {
+				// Skip unreadable files
+			}
+		}
+	} catch {
+		// Skip unreadable directories
+	}
+
+	return { snippets, disabledIds };
+}
+
+/**
+ * Load all snippets hierarchically:
+ * 1. Bundled defaults (<package>/snippets)
+ * 2. Global user snippets (~/.pi/agent/snippets)
+ * 3. Project snippets (<cwd>/.pi/snippets)
+ *
+ * Snippets with the same filename override lower-priority ones.
+ * Snippets can be disabled via frontmatter (`disabled: true`) or in prompt-snippets.json.
+ */
+export function loadSnippets(options: LoadSnippetsOptions = {}): Snippet[] {
+	const map = new Map<string, Snippet>();
+	const disabledConfigs = new Set<string>();
+
+	// 1. Bundled defaults
+	const bundledDir = resolveBundledSnippetsDir(options.bundledDir);
+	if (bundledDir) {
+		const { snippets, disabledIds } = scanSnippetDirectory(bundledDir, "bundled");
+		for (const id of disabledIds) map.delete(id);
+		for (const s of snippets) map.set(s.id, s);
+	}
+
+	// 2. Global snippets & config (~/.pi/agent)
+	let agentDir: string;
+	try {
+		agentDir = options.agentDir ?? getAgentDir();
+	} catch {
+		agentDir = options.agentDir ?? join(process.env.HOME || "", ".pi", "agent");
+	}
+
+	if (agentDir) {
+		const globalSnippetsDir = join(agentDir, "snippets");
+		const { snippets, disabledIds } = scanSnippetDirectory(globalSnippetsDir, "global");
+		for (const id of disabledIds) map.delete(id);
+		for (const s of snippets) map.set(s.id, s);
+
+		const globalConfigFile = join(agentDir, "prompt-snippets.json");
+		const globalConfig = loadSnippetConfigFile(globalConfigFile);
+		if (globalConfig?.disabled) {
+			for (const id of globalConfig.disabled) disabledConfigs.add(id);
+		}
+	}
+
+	// 3. Project snippets & config (<cwd>/.pi)
+	const isTrusted = options.isProjectTrusted !== false;
+	if (options.cwd && isTrusted) {
+		const configDirName = CONFIG_DIR_NAME || ".pi";
+		const projectSnippetsDir = join(options.cwd, configDirName, "snippets");
+		const { snippets, disabledIds } = scanSnippetDirectory(projectSnippetsDir, "project");
+		for (const id of disabledIds) map.delete(id);
+		for (const s of snippets) map.set(s.id, s);
+
+		const projectConfigFile = join(options.cwd, configDirName, "prompt-snippets.json");
+		const projectConfig = loadSnippetConfigFile(projectConfigFile);
+		if (projectConfig?.disabled) {
+			for (const id of projectConfig.disabled) disabledConfigs.add(id);
+		}
+	}
+
+	// Filter out explicitly disabled snippet IDs/names from configuration
+	let result = Array.from(map.values()).filter((s) => {
+		const idWithoutExt = s.id.replace(/\.md$/i, "");
+		return (
+			!disabledConfigs.has(s.id) &&
+			!disabledConfigs.has(idWithoutExt) &&
+			!disabledConfigs.has(s.name)
+		);
+	});
+
+	const byOrder = (a: Snippet, b: Snippet) =>
+		a.order - b.order || a.name.localeCompare(b.name);
+
+	return [
+		...result.filter((s) => s.placement === "prepend").sort(byOrder),
+		...result.filter((s) => s.placement === "append").sort(byOrder),
+	];
+}

package/extensions/prompt-snippets.ts

@@ -0,0 +1,319 @@
+/**
+ * Prompt Snippets — mix-and-match single-purpose prompt rules for Pi.
+ *
+ * Originally created by Amos Blomqvist (https://github.com/amosblomqvist/pi-config).
+ *
+ * Snippets are markdown files with YAML frontmatter stored in:
+ * - Bundled package snippets (<package>/snippets/)
+ * - Global user snippets (~/.pi/agent/snippets/)
+ * - Project snippets (<cwd>/.pi/snippets/)
+ */
+
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { Key, matchesKey, truncateToWidth, wrapTextWithAnsi } from "@earendil-works/pi-tui";
+import { loadSnippets } from "./loader.js";
+import type { LoadSnippetsOptions, Snippet } from "./types.js";
+
+const WIDGET_ID = "prompt-snippets";
+
+export function createPromptSnippetsExtension(extensionOptions: LoadSnippetsOptions = {}) {
+	return function promptSnippetsExtension(pi: ExtensionAPI) {
+		let snippets: Snippet[] = [];
+		let enabled = new Set<string>();
+
+		function getSnippets(ctx: ExtensionContext): Snippet[] {
+			const isTrusted = typeof ctx.isProjectTrusted === "function" ? ctx.isProjectTrusted() : true;
+			return loadSnippets({
+				...extensionOptions,
+				cwd: ctx.cwd,
+				isProjectTrusted: isTrusted,
+			});
+		}
+
+		function updateWidget(ctx: ExtensionContext) {
+			if (!ctx.hasUI || ctx.mode !== "tui") return;
+			const active = snippets.filter((s) => enabled.has(s.id));
+			const prepends = active.filter((s) => s.placement === "prepend");
+			const appends = active.filter((s) => s.placement === "append");
+
+			if (prepends.length === 0 && appends.length === 0) {
+				ctx.ui.setWidget(WIDGET_ID, undefined);
+				return;
+			}
+
+			const theme = ctx.ui.theme;
+			const lines: string[] = [];
+			if (prepends.length > 0) {
+				lines.push(theme.fg("accent", `↑ prepend: ${prepends.map((s) => s.name).join(" · ")}`));
+			}
+			if (appends.length > 0) {
+				lines.push(theme.fg("warning", `↓ append: ${appends.map((s) => s.name).join(" · ")}`));
+			}
+			ctx.ui.setWidget(WIDGET_ID, lines);
+		}
+
+		async function openMenu(ctx: ExtensionContext) {
+			if (ctx.mode !== "tui") {
+				ctx.ui.notify("Snippet menu requires interactive mode", "warning");
+				return;
+			}
+
+			snippets = getSnippets(ctx);
+			enabled = new Set([...enabled].filter((id) => snippets.some((s) => s.id === id)));
+
+			if (snippets.length === 0) {
+				ctx.ui.notify("No snippets found in bundled, global, or project snippet directories", "warning");
+				updateWidget(ctx);
+				return;
+			}
+
+			const working = new Set(enabled);
+
+			const confirmed = await ctx.ui.custom<boolean>((tui, theme, keybindings, done) => {
+				const prepends = snippets.filter((s) => s.placement === "prepend");
+				const appends = snippets.filter((s) => s.placement === "append");
+				const items = [...prepends, ...appends];
+
+				let mode: "list" | "preview" = "list";
+				let cursor = 0;
+				let listScroll = 0;
+				let previewScroll = 0;
+
+				const isUp = (data: string) =>
+					Boolean(keybindings?.matches ? keybindings.matches(data, "tui.select.up") : matchesKey(data, Key.up));
+				const isDown = (data: string) =>
+					Boolean(keybindings?.matches ? keybindings.matches(data, "tui.select.down") : matchesKey(data, Key.down));
+				const isPageUp = (data: string) =>
+					Boolean(keybindings?.matches ? keybindings.matches(data, "tui.select.pageUp") : matchesKey(data, Key.pageUp));
+				const isPageDown = (data: string) =>
+					Boolean(keybindings?.matches ? keybindings.matches(data, "tui.select.pageDown") : matchesKey(data, Key.pageDown));
+				const isConfirm = (data: string) =>
+					Boolean(keybindings?.matches ? keybindings.matches(data, "tui.select.confirm") : matchesKey(data, Key.enter));
+				const isCancel = (data: string) =>
+					Boolean(keybindings?.matches ? keybindings.matches(data, "tui.select.cancel") : matchesKey(data, Key.escape));
+
+				const itemRow = (snippet: Snippet, idx: number, width: number): string => {
+					const pointer = idx === cursor ? theme.fg("accent", "> ") : "  ";
+					const checkbox = working.has(snippet.id) ? theme.fg("success", "[x]") : theme.fg("dim", "[ ]");
+					const desc = snippet.description ? theme.fg("dim", ` — ${snippet.description}`) : "";
+					return truncateToWidth(`${pointer}${checkbox} ${theme.bold(snippet.name)}${desc}`, width);
+				};
+
+				const buildListRows = (width: number): { text: string; itemIndex: number | null }[] => {
+					const rows: { text: string; itemIndex: number | null }[] = [];
+					if (prepends.length > 0) {
+						rows.push({ text: theme.fg("dim", "↑ PREPEND — added before your message"), itemIndex: null });
+						prepends.forEach((s, i) => rows.push({ text: itemRow(s, i, width), itemIndex: i }));
+					}
+					if (prepends.length > 0 && appends.length > 0) {
+						rows.push({ text: "", itemIndex: null });
+					}
+					if (appends.length > 0) {
+						rows.push({ text: theme.fg("dim", "↓ APPEND — added after your message"), itemIndex: null });
+						appends.forEach((s, i) =>
+							rows.push({
+								text: itemRow(s, prepends.length + i, width),
+								itemIndex: prepends.length + i,
+							}),
+						);
+					}
+					return rows;
+				};
+
+				const buildPreviewRows = (snippet: Snippet, width: number): string[] => {
+					const rows: string[] = [];
+					rows.push(truncateToWidth(theme.bold(snippet.name), width));
+					const sourceInfo = snippet.source ? ` · [${snippet.source}]` : "";
+					rows.push(
+						truncateToWidth(
+							theme.fg("dim", `${snippet.placement} · order ${snippet.order}${sourceInfo} · ${snippet.id}`),
+							width,
+						),
+					);
+					rows.push(theme.fg("dim", "─".repeat(Math.min(width, 40))));
+					for (const line of snippet.body.split("\n")) {
+						for (const wrapped of wrapTextWithAnsi(line, width)) {
+							rows.push(truncateToWidth(wrapped, width));
+						}
+					}
+					return rows;
+				};
+
+				const viewport = (
+					lines: string[],
+					scroll: number,
+					maxView: number,
+					focusRow?: number,
+				): { out: string[]; scroll: number } => {
+					const clipped = lines.length > maxView;
+					const view = clipped ? Math.max(1, maxView - 2) : maxView;
+
+					let s = Math.min(Math.max(0, scroll), Math.max(0, lines.length - view));
+					if (focusRow !== undefined) {
+						if (focusRow < s) s = focusRow;
+						else if (focusRow >= s + view) s = focusRow - view + 1;
+					}
+
+					const visible = lines.slice(s, s + view);
+					if (!clipped) return { out: visible, scroll: s };
+
+					const above = s;
+					const below = lines.length - (s + view);
+					return {
+						out: [
+							above > 0 ? theme.fg("dim", `  ↑ ${above} more`) : "",
+							...visible,
+							below > 0 ? theme.fg("dim", `  ↓ ${below} more`) : "",
+						],
+						scroll: s,
+					};
+				};
+
+				return {
+					render(width: number): string[] {
+						const maxView = Math.max(5, tui.terminal.rows - 10);
+
+						let content: string[];
+						let title: string;
+						let hints: string;
+						if (mode === "list") {
+							const rows = buildListRows(width);
+							const cursorRow = rows.findIndex((r) => r.itemIndex === cursor);
+							const v = viewport(
+								rows.map((r) => r.text),
+								listScroll,
+								maxView,
+								cursorRow >= 0 ? cursorRow : 0,
+							);
+							content = v.out;
+							listScroll = v.scroll;
+							title = "Prompt snippets";
+							hints = "↑↓ navigate • Space toggle • Tab preview • Enter apply • Esc cancel";
+						} else {
+							const snippet = items[cursor];
+							const rows = buildPreviewRows(snippet, width);
+							const v = viewport(rows, previewScroll, maxView);
+							content = v.out;
+							previewScroll = v.scroll;
+							title = `Preview: ${snippet.name}`;
+							hints = "↑↓ scroll • Tab/Esc back";
+						}
+
+						return [
+							theme.fg("accent", "─".repeat(width)),
+							truncateToWidth(` ${theme.fg("accent", theme.bold(title))}`, width),
+							"",
+							...content,
+							"",
+							truncateToWidth(theme.fg("dim", ` ${hints}`), width),
+							theme.fg("accent", "─".repeat(width)),
+						];
+					},
+					invalidate() {},
+					handleInput(data: string) {
+						const maxView = Math.max(5, tui.terminal.rows - 10);
+						const pageSize = Math.max(1, maxView - 2);
+
+						if (mode === "list") {
+							if (isUp(data)) {
+								cursor = (cursor - 1 + items.length) % items.length;
+								tui.requestRender();
+							} else if (isDown(data)) {
+								cursor = (cursor + 1) % items.length;
+								tui.requestRender();
+							} else if (isPageUp(data)) {
+								cursor = Math.max(0, cursor - pageSize);
+								tui.requestRender();
+							} else if (isPageDown(data)) {
+								cursor = Math.min(items.length - 1, cursor + pageSize);
+								tui.requestRender();
+							} else if (matchesKey(data, Key.space)) {
+								const id = items[cursor].id;
+								if (working.has(id)) working.delete(id);
+								else working.add(id);
+								tui.requestRender();
+							} else if (matchesKey(data, Key.tab)) {
+								mode = "preview";
+								previewScroll = 0;
+								tui.requestRender();
+							} else if (isConfirm(data)) {
+								done(true);
+							} else if (isCancel(data)) {
+								done(false);
+							}
+						} else {
+							if (isUp(data)) {
+								previewScroll = Math.max(0, previewScroll - 1);
+								tui.requestRender();
+							} else if (isDown(data)) {
+								previewScroll++;
+								tui.requestRender();
+							} else if (isPageUp(data)) {
+								previewScroll = Math.max(0, previewScroll - pageSize);
+								tui.requestRender();
+							} else if (isPageDown(data)) {
+								previewScroll += pageSize;
+								tui.requestRender();
+							} else if (matchesKey(data, Key.tab) || isCancel(data)) {
+								mode = "list";
+								tui.requestRender();
+							}
+						}
+					},
+				};
+			});
+
+			if (confirmed) {
+				enabled = working;
+			}
+			updateWidget(ctx);
+		}
+
+		pi.on("session_start", (_event, ctx) => {
+			enabled = new Set();
+			snippets = getSnippets(ctx);
+			updateWidget(ctx);
+		});
+
+		pi.on("session_shutdown", (_event, ctx) => {
+			enabled = new Set();
+			if (ctx.hasUI && ctx.mode === "tui") {
+				ctx.ui.setWidget(WIDGET_ID, undefined);
+			}
+		});
+
+		pi.on("input", async (event, ctx) => {
+			if (enabled.size === 0) return;
+
+			snippets = getSnippets(ctx);
+			const active = snippets.filter((s) => enabled.has(s.id));
+			enabled = new Set();
+			updateWidget(ctx);
+
+			if (active.length === 0) return;
+
+			const prependBodies = active.filter((s) => s.placement === "prepend").map((s) => s.body);
+			const appendBodies = active.filter((s) => s.placement === "append").map((s) => s.body);
+			return {
+				action: "transform",
+				text: [...prependBodies, event.text, ...appendBodies].join("\n\n"),
+			};
+		});
+
+		pi.registerShortcut("alt+s", {
+			description: "Toggle prompt snippets",
+			handler: async (ctx) => {
+				await openMenu(ctx);
+			},
+		});
+
+		pi.registerCommand("snippets", {
+			description: "Open the prompt snippet toggle menu",
+			handler: async (_args, ctx) => {
+				await openMenu(ctx);
+			},
+		});
+	};
+}
+
+export default createPromptSnippetsExtension();

package/extensions/types.ts

@@ -0,0 +1,37 @@
+export type SnippetPlacement = "prepend" | "append";
+export type SnippetSource = "bundled" | "global" | "project";
+
+export interface Snippet {
+	/** Filename identifier, e.g. "ask-questions.md" */
+	id: string;
+	/** Display name */
+	name: string;
+	/** Short description shown in menu */
+	description: string;
+	/** Placement before or after user message */
+	placement: SnippetPlacement;
+	/** Sort order within placement group (ascending) */
+	order: number;
+	/** Prompt content inserted into message */
+	body: string;
+	/** Origin of snippet definition */
+	source: SnippetSource;
+	/** File path on disk */
+	filePath: string;
+}
+
+export interface SnippetConfig {
+	/** List of snippet IDs (with or without .md) to disable */
+	disabled?: string[];
+}
+
+export interface LoadSnippetsOptions {
+	/** Current working directory for project snippets */
+	cwd?: string;
+	/** Pi agent directory (defaults to getAgentDir()) */
+	agentDir?: string;
+	/** Bundled snippets directory in extension/package */
+	bundledDir?: string;
+	/** Whether project-local configuration and snippets are trusted */
+	isProjectTrusted?: boolean;
+}

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@zle13/pi-prompt-snippets",
+  "version": "0.1.0",
+  "description": "Mix-and-match prompt snippets that prepend or append rules to messages in Pi",
+  "type": "module",
+  "keywords": [
+    "pi-package"
+  ],
+  "author": "zle13",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/LeZH13/zle-pi.git",
+    "directory": "packages/prompt-snippets"
+  },
+  "files": [
+    "extensions",
+    "snippets",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-agent-core": "*",
+    "@earendil-works/pi-ai": "*",
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-tui": "*",
+    "typebox": "*"
+  },
+  "pi": {
+    "extensions": [
+      "./extensions/prompt-snippets.ts"
+    ]
+  },
+  "scripts": {
+    "test": "vitest --run",
+    "typecheck": "tsc --noEmit"
+  }
+}

package/snippets/ask-questions.md

@@ -0,0 +1,8 @@
+---
+name: Ask questions
+description: Ask questions to reach a shared understanding.
+placement: append
+order: 10
+---
+Ask questions until you are 100% sure you know exactly what to do.
+Do not act on this until I confirm we have reached a shared understanding.

package/snippets/delegate-exploration.md

@@ -0,0 +1,7 @@
+---
+name: Delegate exploration
+description: Keep context lean. Subagents explore, you verify critical parts
+placement: append
+order: 30
+---
+Keep your context window lean. Delegate codebase exploration to subagents — ask them specific, targeted questions instead of reading many files yourself. Read files directly only to verify critical parts.

package/snippets/diagnose-report.md

@@ -0,0 +1,7 @@
+---
+name: Diagnose, don't fix
+description: Read-only, report findings and a proposed fix
+placement: append
+order: 40
+---
+Investigate and diagnose the issue. Do not change any code. Report back with your findings and a proposed fix. Do not apply the fix yet.

package/snippets/orchestrator-mode.md

@@ -0,0 +1,7 @@
+---
+name: Orchestrator mode
+description: Pure high-level orchestrator session
+placement: prepend
+order: 30
+---
+This is a pure high-level orchestrator session. Outsource mechanical work — file exploration, code reading, implementation — to subagents. Keep your own context window lean so your reasoning stays sharp; do not bloat it by reading code yourself.

package/snippets/session-kickoff.md

@@ -0,0 +1,7 @@
+---
+name: Session kickoff
+description: Get oriented, report back before starting work
+placement: prepend
+order: 10
+---
+Familiarize yourself with this project before we start. Once you have a clear picture, report back. Do not begin any work until we have aligned on what's next.

package/snippets/verify-not-assume.md

@@ -0,0 +1,7 @@
+---
+name: Verify, don't assume
+description: Do not assume — verify
+placement: append
+order: 20
+---
+Do not assume — verify. Verify critical facts rather than guessing. And ask me, if you cannot verify something. Only begin once you are 100% sure of what to do. If you catch yourself being even slightly unsure, that's a sign to check first.