botholomew 0.15.6 → 0.16.2

package/README.md

@@ -124,11 +124,10 @@ the agent or worker touches is a real file you can `vim`, `grep`, and
 ```
 my-project/
   config/config.json                # models, tick interval, API keys
-  prompts/                          # always-loaded markdown
-    soul.md                         #   identity (not agent-editable)
+  prompts/                          # markdown files loaded into every system prompt (or keyword-loaded)
+    goals.md                        #   identity + current goals (agent-editable)
     beliefs.md                      #   agent-editable priors
-    goals.md                        #   agent-editable goals
-    capabilities.md                 #   agent-editable tool inventory
+    capabilities.md                 #   auto-generated tool inventory
   skills/                           # slash commands (built-ins + user-defined)
     summarize.md
     standup.md
@@ -168,6 +167,7 @@ from `context/`.
 | `botholomew schedule list\|add\|view\|enable\|disable\|trigger\|delete` | Recurring work (markdown files in `schedules/`) |
 | `botholomew context add\|import\|tree\|stats\|reindex\|search\|read\|write\|edit\|move\|delete\|…` | Bring files/URLs into `context/`; rebuild the search index; expose the agent's file/dir tools as CLI subcommands |
 | `botholomew capabilities` | Rescan built-in + MCPX tools and rewrite `prompts/capabilities.md` |
+| `botholomew prompts list\|show\|create\|edit\|delete\|validate` | CRUD over the markdown files in `prompts/` (with strict frontmatter validation) |
 | `botholomew mcpx servers\|list\|add\|remove\|info\|search\|exec\|ping\|auth\|deauth\|import-global\|…` | Configure external MCP servers (passthrough to `mcpx`) |
 | `botholomew skill list\|show\|create\|validate` | Manage slash-command skills |
 | `botholomew thread list\|view` | Browse the agent's conversation history (CSVs in `threads/`) |
@@ -238,8 +238,8 @@ Topics worth understanding in detail:
   validation, and natural-language recurring schedules.
 - **[The Tool class](docs/tools.md)** — one Zod definition, three consumers
   (Anthropic tool-use, Commander CLI, tests).
-- **[Prompts](docs/prompts.md)** — `soul.md`, `beliefs.md`, `goals.md`,
-  frontmatter flags, and agent self-modification.
+- **[Prompts](docs/prompts.md)** — generic markdown files in `prompts/`,
+  strict frontmatter validation, and full CRUD via CLI + agent tools.
 - **[Skills (slash commands)](docs/skills.md)** — reusable prompt templates
   with positional arguments and tab completion; the chat agent can also
   create, edit, and search them at runtime.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "botholomew",
-  "version": "0.15.6",
+  "version": "0.16.2",
   "description": "An autonomous AI agent for knowledge work — works your task queue while you sleep.",
   "type": "module",
   "bin": {
@@ -42,6 +42,7 @@
     "onnxruntime-web": "1.26.0-dev.20260416-b7804b056c",
     "react": "^19.2.0",
     "uuid": "^14.0.0",
+    "wrap-ansi": "^10.0.0",
     "zod": "^4.4.2"
   },
   "devDependencies": {

package/src/chat/agent.ts

@@ -102,7 +102,7 @@ You do NOT execute long-running work directly — enqueue tasks for a background
 Use the available tools to look up tasks, threads, schedules, and context when the user asks about them. Files the agent can read and write live under \`context/\` as project-relative paths (e.g. \`notes/foo.md\`). Use \`context_tree\` to see what's there, \`search\` (hybrid regexp + semantic) to find content, then \`context_read\` / \`context_info\` to drill in.
 Past conversations live in CSV files under \`threads/\`; use \`list_threads\`, \`search_threads\`, and \`view_thread\` to find and page through them.
 When multiple tool calls are independent of each other (i.e., one does not depend on the result of another), call them all in a single response. They will be executed in parallel, which is faster than calling them one at a time.
-You can read and edit the agent's prompt files (beliefs, goals, capabilities, soul) under \`prompts/\` via \`prompt_read\` and \`prompt_edit\` (line-range patches). Files marked \`agent-modification: false\` (e.g. soul.md) are read-only.
+You can manage the agent's prompt files (always-on or keyword-loaded notes the agent sees in every turn) under \`prompts/\` via \`prompt_list\`, \`prompt_read\`, \`prompt_create\`, \`prompt_edit\` (git-style line-range patches), and \`prompt_delete\`. Files marked \`agent-modification: false\` are read-only — \`prompt_edit\` and \`prompt_delete\` will refuse them.
 You can author and refine slash-command skills (reusable prompt templates stored in \`skills/\`) via \`skill_list\`, \`skill_search\`, \`skill_read\`, \`skill_write\`, \`skill_edit\`, and \`skill_delete\`. New or edited skills are usable as \`/<name>\` on the user's next message.
 Format your responses using Markdown. Use headings, bold, italic, lists, and code blocks to make your responses clear and well-structured.
 `;

package/src/chat/usage.ts

@@ -10,7 +10,7 @@ const CHARS_PER_TOKEN = 4;
  * line up exactly with the API's count.
  */
 export interface ContextBreakdown {
-  /** Persistent context files from `prompts/` (soul, beliefs, goals, capabilities, contextual). */
+  /** Files loaded from `prompts/` (always-on plus any contextual matches). */
   prompts: number;
   /** Chat instructions block + MCP guidance + style rules + meta header. */
   instructions: number;

package/src/cli.ts

@@ -11,6 +11,7 @@ import { registerInitCommand } from "./commands/init.ts";
 import { registerMcpxCommand } from "./commands/mcpx.ts";
 import { registerNukeCommand } from "./commands/nuke.ts";
 import { registerPrepareCommand } from "./commands/prepare.ts";
+import { registerPromptsCommand } from "./commands/prompts.ts";
 import { registerScheduleCommand } from "./commands/schedule.ts";
 import { registerSkillCommand } from "./commands/skill.ts";
 import { registerTaskCommand } from "./commands/task.ts";
@@ -43,6 +44,7 @@ registerChatCommand(program);
 registerContextCommand(program);
 registerDbCommand(program);
 registerCapabilitiesCommand(program);
+registerPromptsCommand(program);
 registerMcpxCommand(program);
 registerSkillCommand(program);
 registerNukeCommand(program);

package/src/commands/prompts.ts

@@ -0,0 +1,333 @@
+import { spawn } from "node:child_process";
+import { mkdir, readdir, stat, unlink } from "node:fs/promises";
+import { join, relative } from "node:path";
+import ansis from "ansis";
+import type { Command } from "commander";
+import { getPromptsDir } from "../constants.ts";
+import { atomicWrite } from "../fs/atomic.ts";
+import {
+  PromptValidationError,
+  parsePromptFile,
+  serializePromptFile,
+} from "../utils/frontmatter.ts";
+import { logger } from "../utils/logger.ts";
+
+const VALID_NAME = /^[a-zA-Z0-9._-]+$/;
+
+export function registerPromptsCommand(program: Command) {
+  const prompts = program
+    .command("prompts")
+    .description(
+      "Manage prompt files (always-on or contextual notes for the agent)",
+    );
+
+  prompts
+    .command("list")
+    .description("List prompts under prompts/")
+    .option("-l, --limit <n>", "max number of prompts", Number.parseInt)
+    .option("-o, --offset <n>", "skip first N prompts", Number.parseInt)
+    .action(async (opts: { limit?: number; offset?: number }) => {
+      const dir = program.opts().dir as string;
+      const promptsDir = getPromptsDir(dir);
+      const files = await listPromptFiles(promptsDir);
+
+      if (files.length === 0) {
+        logger.dim("No prompt files found.");
+        return;
+      }
+
+      const start = opts.offset ?? 0;
+      const end = opts.limit ? start + opts.limit : undefined;
+      const page = files.slice(start, end);
+
+      const header = `${ansis.bold("Name".padEnd(20))} ${ansis.bold("Title".padEnd(28))} ${ansis.bold("Loading".padEnd(12))} ${ansis.bold("Editable".padEnd(10))} ${ansis.bold("Size".padEnd(8))} ${ansis.bold("Status")}`;
+      console.log(header);
+      console.log("-".repeat(header.length));
+
+      for (const filename of page) {
+        const filePath = join(promptsDir, filename);
+        const name = filename.replace(/\.md$/, "");
+        const [raw, st] = await Promise.all([
+          Bun.file(filePath).text(),
+          stat(filePath),
+        ]);
+        try {
+          const { meta } = parsePromptFile(filePath, raw);
+          console.log(
+            [
+              name.padEnd(20),
+              meta.title.slice(0, 27).padEnd(28),
+              meta.loading.padEnd(12),
+              (meta["agent-modification"] ? "yes" : "no").padEnd(10),
+              `${st.size}`.padEnd(8),
+              ansis.green("ok"),
+            ].join(" "),
+          );
+        } catch (err) {
+          const reason =
+            err instanceof PromptValidationError
+              ? err.reason
+              : err instanceof Error
+                ? err.message
+                : String(err);
+          console.log(
+            [
+              name.padEnd(20),
+              ansis.dim("—".padEnd(28)),
+              ansis.dim("—".padEnd(12)),
+              ansis.dim("—".padEnd(10)),
+              `${st.size}`.padEnd(8),
+              ansis.red(`invalid: ${reason}`),
+            ].join(" "),
+          );
+        }
+      }
+
+      const footer =
+        page.length === files.length
+          ? `${files.length} prompt(s)`
+          : `showing ${page.length} of ${files.length} prompt(s)`;
+      console.log(`\n${ansis.dim(footer)}`);
+    });
+
+  prompts
+    .command("show <name>")
+    .description("Print the raw contents of a prompt file")
+    .action(async (name: string) => {
+      const dir = program.opts().dir as string;
+      const filePath = resolvePromptPath(dir, name);
+      if (!filePath) {
+        logger.error(`Invalid prompt name: ${name}`);
+        process.exit(1);
+      }
+      const file = Bun.file(filePath);
+      if (!(await file.exists())) {
+        logger.error(`Prompt not found: ${relative(dir, filePath)}`);
+        process.exit(1);
+      }
+      process.stdout.write(await file.text());
+    });
+
+  prompts
+    .command("create <name>")
+    .description("Create a new prompt file")
+    .option("--title <title>", "human-readable title (defaults to <name>)")
+    .option(
+      "--loading <mode>",
+      "'always' or 'contextual' (default: always)",
+      "always",
+    )
+    .option(
+      "--no-agent-modification",
+      "make this prompt read-only to the agent",
+    )
+    .option("--from-file <path>", "read body from a file (use '-' for stdin)")
+    .option("--force", "overwrite if a prompt with this name exists")
+    .action(
+      async (
+        name: string,
+        opts: {
+          title?: string;
+          loading: string;
+          agentModification: boolean;
+          fromFile?: string;
+          force?: boolean;
+        },
+      ) => {
+        const dir = program.opts().dir as string;
+        if (!VALID_NAME.test(name) || name.includes("..")) {
+          logger.error(`Invalid prompt name: ${name}`);
+          logger.dim("Use [a-zA-Z0-9._-] only — no slashes, no '..'.");
+          process.exit(1);
+        }
+        if (opts.loading !== "always" && opts.loading !== "contextual") {
+          logger.error(`--loading must be 'always' or 'contextual'`);
+          process.exit(1);
+        }
+
+        const promptsDir = getPromptsDir(dir);
+        const filePath = join(promptsDir, `${name}.md`);
+        if (!opts.force && (await Bun.file(filePath).exists())) {
+          logger.error(`Prompt already exists: ${relative(dir, filePath)}`);
+          logger.dim("Use --force to overwrite.");
+          process.exit(1);
+        }
+
+        let body: string;
+        if (opts.fromFile === "-") {
+          body = await readStdin();
+        } else if (opts.fromFile) {
+          body = await Bun.file(opts.fromFile).text();
+        } else {
+          body = `# ${opts.title ?? name}\n`;
+        }
+
+        const meta = {
+          title: opts.title ?? name,
+          loading: opts.loading as "always" | "contextual",
+          "agent-modification": opts.agentModification,
+        };
+        const serialized = serializePromptFile(meta, body);
+
+        try {
+          parsePromptFile(filePath, serialized);
+        } catch (err) {
+          logger.error(
+            err instanceof PromptValidationError
+              ? err.message
+              : `Generated content failed validation: ${err instanceof Error ? err.message : String(err)}`,
+          );
+          process.exit(1);
+        }
+
+        await mkdir(promptsDir, { recursive: true });
+        await atomicWrite(filePath, serialized);
+        logger.success(`Created prompt: ${relative(dir, filePath)}`);
+      },
+    );
+
+  prompts
+    .command("edit <name>")
+    .description("Open a prompt in $EDITOR; refuse to keep invalid output")
+    .action(async (name: string) => {
+      const dir = program.opts().dir as string;
+      const filePath = resolvePromptPath(dir, name);
+      if (!filePath) {
+        logger.error(`Invalid prompt name: ${name}`);
+        process.exit(1);
+      }
+      if (!(await Bun.file(filePath).exists())) {
+        logger.error(`Prompt not found: ${relative(dir, filePath)}`);
+        process.exit(1);
+      }
+
+      const editor = process.env.EDITOR || process.env.VISUAL || "nano";
+      await new Promise<void>((resolve, reject) => {
+        const child = spawn(editor, [filePath], { stdio: "inherit" });
+        child.on("exit", (code) => {
+          if (code === 0) resolve();
+          else reject(new Error(`${editor} exited with code ${code}`));
+        });
+        child.on("error", reject);
+      });
+
+      const raw = await Bun.file(filePath).text();
+      try {
+        parsePromptFile(filePath, raw);
+        logger.success(`Saved: ${relative(dir, filePath)}`);
+      } catch (err) {
+        const reason =
+          err instanceof PromptValidationError
+            ? err.message
+            : err instanceof Error
+              ? err.message
+              : String(err);
+        const quarantine = `${filePath}.tmp.invalid`;
+        await atomicWrite(quarantine, raw);
+        logger.error(`Validation failed: ${reason}`);
+        logger.dim(
+          `Wrote your edits to ${relative(dir, quarantine)} so you can recover them. The original file is unchanged.`,
+        );
+        process.exit(1);
+      }
+    });
+
+  prompts
+    .command("delete <name>")
+    .description("Delete a prompt file")
+    .option("--force", "delete even if marked agent-modification: false")
+    .action(async (name: string, opts: { force?: boolean }) => {
+      const dir = program.opts().dir as string;
+      const filePath = resolvePromptPath(dir, name);
+      if (!filePath) {
+        logger.error(`Invalid prompt name: ${name}`);
+        process.exit(1);
+      }
+      const file = Bun.file(filePath);
+      if (!(await file.exists())) {
+        logger.error(`Prompt not found: ${relative(dir, filePath)}`);
+        process.exit(1);
+      }
+
+      if (!opts.force) {
+        const raw = await file.text();
+        try {
+          const { meta } = parsePromptFile(filePath, raw);
+          if (!meta["agent-modification"]) {
+            logger.error(
+              `${relative(dir, filePath)} is marked agent-modification: false`,
+            );
+            logger.dim("Use --force to delete anyway.");
+            process.exit(1);
+          }
+        } catch {
+          // Malformed — let the user delete it; that's why they're here.
+        }
+      }
+
+      await unlink(filePath);
+      logger.success(`Deleted prompt: ${relative(dir, filePath)}`);
+    });
+
+  prompts
+    .command("validate")
+    .description("Validate every prompt file under prompts/")
+    .action(async () => {
+      const dir = program.opts().dir as string;
+      const promptsDir = getPromptsDir(dir);
+      const files = await listPromptFiles(promptsDir);
+
+      if (files.length === 0) {
+        logger.dim("No prompt files found.");
+        return;
+      }
+
+      let hasErrors = false;
+      for (const filename of files) {
+        const filePath = join(promptsDir, filename);
+        const raw = await Bun.file(filePath).text();
+        try {
+          parsePromptFile(filePath, raw);
+          logger.success(
+            `${ansis.bold(filename.padEnd(24))} ${ansis.green("ok")}`,
+          );
+        } catch (err) {
+          hasErrors = true;
+          const reason =
+            err instanceof PromptValidationError
+              ? err.reason
+              : err instanceof Error
+                ? err.message
+                : String(err);
+          logger.error(
+            `${ansis.bold(filename.padEnd(24))} ${ansis.red(reason)}`,
+          );
+        }
+      }
+
+      if (hasErrors) process.exit(1);
+    });
+}
+
+function resolvePromptPath(projectDir: string, name: string): string | null {
+  if (!VALID_NAME.test(name) || name.includes("..")) return null;
+  return join(getPromptsDir(projectDir), `${name}.md`);
+}
+
+async function listPromptFiles(promptsDir: string): Promise<string[]> {
+  try {
+    const entries = await readdir(promptsDir);
+    return entries.filter((f) => f.endsWith(".md")).sort();
+  } catch (err) {
+    if ((err as NodeJS.ErrnoException).code === "ENOENT") return [];
+    throw err;
+  }
+}
+
+async function readStdin(): Promise<string> {
+  const chunks: Buffer[] = [];
+  for await (const chunk of process.stdin) {
+    chunks.push(typeof chunk === "string" ? Buffer.from(chunk) : chunk);
+  }
+  return Buffer.concat(chunks).toString("utf-8");
+}

package/src/constants.ts

@@ -6,7 +6,7 @@ import { join } from "node:path";
  *
  *   <projectDir>/
  *     config/config.json
- *     prompts/{soul,beliefs,goals,capabilities}.md
+ *     prompts/*.md                     init seeds goals/beliefs/capabilities
  *     skills/*.md
  *     mcpx/servers.json
  *     models/                          embedding model cache

package/src/context/capabilities.ts

@@ -475,6 +475,7 @@ export async function writeCapabilitiesFile(
   const file = Bun.file(filePath);
 
   let meta: ContextFileMeta = {
+    title: "Capabilities",
     loading: "always",
     "agent-modification": true,
   };
@@ -485,6 +486,9 @@ export async function writeCapabilitiesFile(
     const parsed = parseContextFile(raw);
     if (parsed.meta && typeof parsed.meta === "object") {
       meta = {
+        title:
+          (typeof parsed.meta.title === "string" && parsed.meta.title) ||
+          meta.title,
         loading: parsed.meta.loading ?? meta.loading,
         "agent-modification":
           parsed.meta["agent-modification"] ?? meta["agent-modification"],

package/src/init/index.ts

@@ -36,7 +36,6 @@ import {
   DEFAULT_CONFIG,
   DEFAULT_MCPX_SERVERS,
   GOALS_MD,
-  SOUL_MD,
   STANDUP_SKILL,
   SUMMARIZE_SKILL,
 } from "./templates.ts";
@@ -74,9 +73,8 @@ export async function initProject(
 
   // Persistent-context template files
   const pcDir = getPromptsDir(projectDir);
-  await Bun.write(join(pcDir, "soul.md"), SOUL_MD);
-  await Bun.write(join(pcDir, "beliefs.md"), BELIEFS_MD);
   await Bun.write(join(pcDir, "goals.md"), GOALS_MD);
+  await Bun.write(join(pcDir, "beliefs.md"), BELIEFS_MD);
   await Bun.write(join(pcDir, "capabilities.md"), CAPABILITIES_MD);
 
   // Default skills
@@ -117,7 +115,9 @@ export async function initProject(
   logger.dim("");
   logger.dim("Layout:");
   logger.dim(`  ${CONFIG_DIR}/         settings`);
-  logger.dim(`  prompts/   soul, beliefs, goals, capabilities`);
+  logger.dim(
+    `  prompts/         goals, beliefs, capabilities (and any you add)`,
+  );
   logger.dim(`  ${CONTEXT_DIR}/        agent-writable knowledge tree`);
   logger.dim(`  ${TASKS_DIR}/          one markdown file per task`);
   logger.dim(`    ${LOCKS_SUBDIR}/        worker claim lockfiles`);

package/src/init/templates.ts

@@ -1,20 +1,26 @@
 import { DEFAULT_CONFIG as SCHEMA_DEFAULT_CONFIG } from "../config/schemas.ts";
 
-export const SOUL_MD = `---
+export const GOALS_MD = `---
+title: Goals
 loading: always
-agent-modification: false
+agent-modification: true
 ---
 
-# Soul
+# Goals
 
 You are Botholomew, an AI agent for knowledge work, personified by a wise owl. You help humans manage information, research topics, organize knowledge, and complete intellectual tasks.
 
 You are thoughtful, thorough, and proactive. You work through your task queue methodically, prioritizing appropriately and asking for clarification when needed.
 
 You are direct: lead with the answer, skip preambles, disagree when you have reason to, and never flatter.
+
+*The list below is the current set of goals for this project. Update it as goals are completed or new ones are added.*
+
+- Get set up and ready to help.
 `;
 
 export const BELIEFS_MD = `---
+title: Beliefs
 loading: always
 agent-modification: true
 ---
@@ -28,20 +34,8 @@ agent-modification: true
 - I should ask for help when I'm stuck rather than guessing.
 `;
 
-export const GOALS_MD = `---
-loading: always
-agent-modification: true
----
-
-# Goals
-
-*These are the current goals for this project.*
-*Botholomew updates this file as goals are completed or new ones are added.*
-
-- Get set up and ready to help.
-`;
-
 export const CAPABILITIES_MD = `---
+title: Capabilities
 loading: always
 agent-modification: true
 ---

package/src/tools/prompt/create.ts

@@ -0,0 +1,136 @@
+import { mkdir } from "node:fs/promises";
+import { join } from "node:path";
+import { z } from "zod";
+import { getPromptsDir } from "../../constants.ts";
+import { atomicWrite } from "../../fs/atomic.ts";
+import {
+  PromptValidationError,
+  parsePromptFile,
+  serializePromptFile,
+} from "../../utils/frontmatter.ts";
+import type { ToolDefinition } from "../tool.ts";
+
+const inputSchema = z.object({
+  name: z
+    .string()
+    .min(1)
+    .describe(
+      "Prompt name without extension (e.g. 'style-notes'). Resolves to prompts/<name>.md.",
+    ),
+  title: z
+    .string()
+    .min(1)
+    .describe("Human-readable title shown in prompt_list output."),
+  loading: z
+    .enum(["always", "contextual"])
+    .describe(
+      "'always' includes the prompt in every system prompt. 'contextual' includes it only when the latest user/task text shares keywords with the body.",
+    ),
+  agent_modification: z
+    .boolean()
+    .describe(
+      "If true, prompt_edit and prompt_delete may modify or remove this file. If false, the file is read-only to the agent.",
+    ),
+  body: z
+    .string()
+    .describe("Markdown body (everything after the frontmatter)."),
+  on_conflict: z
+    .enum(["error", "overwrite"])
+    .optional()
+    .default("error")
+    .describe(
+      "What to do if a prompt with this name already exists. Defaults to 'error'.",
+    ),
+});
+
+const outputSchema = z.object({
+  name: z.string().nullable(),
+  path: z.string().nullable(),
+  created: z.boolean(),
+  content: z.string(),
+  is_error: z.boolean(),
+  error_type: z.string().optional(),
+  message: z.string().optional(),
+  next_action_hint: z.string().optional(),
+});
+
+const VALID_NAME = /^[a-zA-Z0-9._-]+$/;
+
+export const promptCreateTool = {
+  name: "prompt_create",
+  description:
+    "[[ bash equivalent command: touch ]] Create a new prompt file under prompts/. Frontmatter (title, loading, agent-modification) is set from the arguments and re-validated before the file is committed. Fails with path_conflict if a prompt with this name exists unless on_conflict='overwrite'.",
+  group: "context",
+  inputSchema,
+  outputSchema,
+  execute: async (input, ctx) => {
+    if (!VALID_NAME.test(input.name) || input.name.includes("..")) {
+      return {
+        name: null,
+        path: null,
+        created: false,
+        content: "",
+        is_error: true,
+        error_type: "invalid_name",
+        message: `Invalid prompt name: ${input.name}`,
+        next_action_hint:
+          "Use [a-zA-Z0-9._-] only — no slashes, no '..', no extension.",
+      };
+    }
+
+    const dir = getPromptsDir(ctx.projectDir);
+    const filePath = join(dir, `${input.name}.md`);
+    const exists = await Bun.file(filePath).exists();
+    if (exists && input.on_conflict !== "overwrite") {
+      return {
+        name: input.name,
+        path: filePath,
+        created: false,
+        content: "",
+        is_error: true,
+        error_type: "path_conflict",
+        message: `Prompt already exists: prompts/${input.name}.md`,
+        next_action_hint:
+          "Pass on_conflict='overwrite' to replace, or use prompt_edit for a partial change.",
+      };
+    }
+
+    const meta = {
+      title: input.title,
+      loading: input.loading,
+      "agent-modification": input.agent_modification,
+    };
+    const serialized = serializePromptFile(meta, input.body);
+
+    // Round-trip validation: refuse to write content that wouldn't load back.
+    try {
+      parsePromptFile(filePath, serialized);
+    } catch (err) {
+      return {
+        name: input.name,
+        path: filePath,
+        created: false,
+        content: serialized,
+        is_error: true,
+        error_type: "invalid_frontmatter",
+        message:
+          err instanceof PromptValidationError
+            ? err.message
+            : `Generated content failed validation: ${err instanceof Error ? err.message : String(err)}`,
+        next_action_hint:
+          "Pick a title without unusual characters that break YAML.",
+      };
+    }
+
+    await mkdir(dir, { recursive: true });
+    await atomicWrite(filePath, serialized);
+
+    return {
+      name: input.name,
+      path: filePath,
+      created: !exists,
+      content: serialized,
+      is_error: false,
+    };
+  },
+} satisfies ToolDefinition<typeof inputSchema, typeof outputSchema>;