pi-custom-system-prompt 0.1.0 → 0.1.1

package/CHANGELOG.md

@@ -5,6 +5,18 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.1.1] - 2026-06-27
+
+### Fixed
+
+- **Replace mode no longer drops project context files.** Previously, switching to `replace` mode reconstructed the system prompt from the custom file but omitted the `<project_context>` block Pi builds from `AGENTS.md`, `.pi/rules`, and other configured context files. The model never saw project-specific instructions in `replace` mode. The replace branch now reads `systemPromptOptions.contextFiles` and emits the same `<project_context>` block Pi's own prompt builder produces, in the same assembly order.
+- **Replace mode no longer drops skills.** The `<available_skills>` block that tells the model which `SKILL.md` files it can read (frontend-design, librarian, context7-docs, pi-subagents, and any custom skills) was also missing in `replace` mode, so the model would not invoke skills even when a task matched one. The replace branch now reads `systemPromptOptions.skills` and emits the block.
+- The available-skills block is produced by an inlined helper (`formatSkillsBlock`) that mirrors Pi's `formatSkillsForPrompt` exactly — same XML escaping, same `disableModelInvocation` filtering — so the extension takes no runtime dependency on the host package and stays resolvable regardless of `node_modules` topology.
+
+### Changed
+
+- Documented the full `replace`-mode assembly order in the README (tools → append → project context → skills → date → cwd).
+
 ## [0.1.0] - 2026-06-21
 
 ### Added

package/README.md

@@ -19,7 +19,9 @@ Multiple `.md` files can live in the prompt directory; pick which one is active
 
 **`append`** (default) — keep Pi's default system prompt as the base, and add the custom prompt as an extra section. Safest for most models, since Pi's tool descriptions stay authoritative.
 
-**`replace`** — use the custom prompt as the base system prompt. Pi's tool descriptions, current date, working directory, and any `--append-system-prompt` you passed are appended after it.
+**`replace`** — use the custom prompt as the base system prompt. Pi appends the following after it, so nothing Pi would normally load is lost: the available-tools listing (with a note to use those tools instead of any fictional ones mentioned in the custom prompt), any `--append-system-prompt` text, project context files (e.g. `AGENTS.md`, `.pi/rules`) wrapped in `<project_context>`, the `<available_skills>` block listing loadable `SKILL.md` files, the current date, and the working directory.
+
+The project-context and skills blocks are mirrored from Pi's own prompt assembly, so in `replace` mode the model sees the same project instructions and skill list it would in `append` mode — the custom prompt just becomes the base instead of an add-on.
 
 ## Setup
 
@@ -83,6 +85,7 @@ system-prompt: disabled          # disabled
 ## How it works
 
 - The extension subscribes to `before_agent_start`, which fires on every user message. It reads the selected `.md` file from the prompt directory, then either appends it to or replaces Pi's resolved system prompt before sending to the model.
+- In `replace` mode, the extension reconstructs the prompt as `customPrompt + tools + appendSystemPrompt + <project_context> + <available_skills> + date + cwd`, matching Pi's own assembly order so project context files and skills survive the swap. The available-skills block is emitted by a small inlined helper that mirrors Pi's `formatSkillsForPrompt` exactly (same XML escaping, same `disableModelInvocation` filtering); it is inlined rather than imported so the extension takes no runtime dependency on the host package and stays resolvable regardless of `node_modules` topology.
 - State (`enabled`, `mode`, `selectedFile`) persists to `~/.pi/agent/state/system-prompt.json` and is reloaded on the next start.
 - All commands are non-destructive: they mutate in-memory state, save to the state file, and take effect on the next message.
 - If the prompt directory is missing, has no `.md` files, or the selected file is empty/unreadable, the extension logs the reason to `/system-prompt-info` and falls back to Pi's default prompt with no error.

package/extensions/system-prompt.ts

@@ -54,7 +54,7 @@
 import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
-import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import type { ExtensionAPI, Skill } from "@earendil-works/pi-coding-agent";
 
 const DEFAULT_PROMPT_DIR = path.join(
 	os.homedir(),
@@ -79,6 +79,40 @@ interface PersistedState {
 	selectedFile: string;
 }
 
+function escapeXml(str: string): string {
+	return str
+		.replace(/&/g, "&")
+		.replace(/</g, "&lt;")
+		.replace(/>/g, "&gt;")
+		.replace(/"/g, "&quot;")
+		.replace(/'/g, "&apos;");
+}
+
+// Mirror pi's formatSkillsForPrompt exactly so the <available_skills> block the
+// model sees is identical to what pi's own default prompt would emit. Inlined
+// (rather than imported) so the extension takes no runtime dependency on the
+// host package and stays resolvable regardless of node_modules topology.
+function formatSkillsBlock(skills: Skill[]): string {
+	const visible = skills.filter((s) => !s.disableModelInvocation);
+	if (visible.length === 0) return "";
+	const lines = [
+		"\n\nThe following skills provide specialized instructions for specific tasks.",
+		"Use the read tool to load a skill's file when the task matches its description.",
+		"When a skill file references a relative path, resolve it against the skill directory (parent of SKILL.md / dirname of the path) and use that absolute path in tool commands.",
+		"",
+		"<available_skills>",
+	];
+	for (const skill of visible) {
+		lines.push("  <skill>");
+		lines.push(`    <name>${escapeXml(skill.name)}</name>`);
+		lines.push(`    <description>${escapeXml(skill.description)}</description>`);
+		lines.push(`    <location>${escapeXml(skill.filePath)}</location>`);
+		lines.push("  </skill>");
+	}
+	lines.push("</available_skills>");
+	return lines.join("\n");
+}
+
 export default function systemPromptExtension(pi: ExtensionAPI) {
 	const promptDir: string =
 		process.env.PI_SYSTEM_PROMPT_DIR?.trim() || DEFAULT_PROMPT_DIR;
@@ -385,6 +419,10 @@ export default function systemPromptExtension(pi: ExtensionAPI) {
 
 		if (mode === "replace") {
 			// Custom prompt is the base. Stack Pi's tools + user customizations after.
+			// Mirror pi's own assembly order (system-prompt.js): append → context →
+			// skills → date → cwd, so we don't silently drop project context files
+			// or the <available_skills> block that tells the model which SKILL.md
+			// files it can read.
 			const now = new Date();
 			const dateStr = `${now.getFullYear()}-${String(now.getMonth() + 1).padStart(2, "0")}-${String(now.getDate()).padStart(2, "0")}`;
 			const cwd = opts?.cwd ?? "unknown";
@@ -392,12 +430,30 @@ export default function systemPromptExtension(pi: ExtensionAPI) {
 			const appendSection = appendSystemPrompt
 				? `\n\n${appendSystemPrompt}`
 				: "";
+			const contextFiles = opts?.contextFiles ?? [];
+			const contextSection =
+				contextFiles.length > 0
+					? "\n\n<project_context>\n\nProject-specific instructions and guidelines:\n\n" +
+						contextFiles
+							.map(
+								(f) =>
+									`<project_instructions path="${f.path}">\n${f.content}\n</project_instructions>\n\n`,
+							)
+							.join("") +
+						"</project_context>\n"
+					: "";
+			// Emit the <available_skills> block so the model knows which SKILL.md
+			// files it can read. Skills with disableModelInvocation=true are hidden.
+			const skills: Skill[] = opts?.skills ?? [];
+			const skillsSection = skills.length > 0 ? formatSkillsBlock(skills) : "";
 			return {
 				systemPrompt:
 					promptContent +
 					toolsSection +
 					customSection +
 					appendSection +
+					contextSection +
+					skillsSection +
 					`\nCurrent date: ${dateStr}` +
 					`\nCurrent working directory: ${cwd}`,
 			};

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "pi-custom-system-prompt",
-	"version": "0.1.0",
+	"version": "0.1.1",
 	"description": "Pi extension that loads a custom system prompt from `~/.pi/agent/system-prompts/*.md` and injects it on every agent turn, with commands to select, toggle, reload, and switch between replace and append modes.",
 	"type": "module",
 	"license": "MIT",