botholomew 0.15.6 → 0.16.0

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.0",
   "description": "An autonomous AI agent for knowledge work — works your task queue while you sleep.",
   "type": "module",
   "bin": {

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>;

package/src/tools/prompt/delete.ts

@@ -0,0 +1,103 @@
+import { unlink } from "node:fs/promises";
+import { join } from "node:path";
+import { z } from "zod";
+import { getPromptsDir } from "../../constants.ts";
+import {
+  PromptValidationError,
+  parsePromptFile,
+} from "../../utils/frontmatter.ts";
+import type { ToolDefinition } from "../tool.ts";
+
+const inputSchema = z.object({
+  name: z
+    .string()
+    .describe("Prompt name without extension. Resolves to prompts/<name>.md."),
+});
+
+const outputSchema = z.object({
+  name: z.string(),
+  path: z.string().nullable(),
+  deleted: z.boolean(),
+  is_error: z.boolean(),
+  error_type: z.string().optional(),
+  message: z.string().optional(),
+  next_action_hint: z.string().optional(),
+});
+
+export const promptDeleteTool = {
+  name: "prompt_delete",
+  description:
+    "[[ bash equivalent command: rm ]] Delete a prompt file under prompts/. Files marked `agent-modification: false` are protected and will not be removed.",
+  group: "context",
+  inputSchema,
+  outputSchema,
+  execute: async (input, ctx) => {
+    if (input.name.includes("/") || input.name.includes("..")) {
+      return {
+        name: input.name,
+        path: null,
+        deleted: false,
+        is_error: true,
+        error_type: "invalid_name",
+        message: `Invalid prompt name: ${input.name}`,
+      };
+    }
+
+    const filePath = join(getPromptsDir(ctx.projectDir), `${input.name}.md`);
+    const file = Bun.file(filePath);
+    if (!(await file.exists())) {
+      return {
+        name: input.name,
+        path: null,
+        deleted: false,
+        is_error: true,
+        error_type: "not_found",
+        message: `Prompt not found: prompts/${input.name}.md`,
+        next_action_hint: "Use prompt_list to see available prompts.",
+      };
+    }
+
+    const raw = await file.text();
+    try {
+      const { meta } = parsePromptFile(filePath, raw);
+      if (!meta["agent-modification"]) {
+        return {
+          name: input.name,
+          path: filePath,
+          deleted: false,
+          is_error: true,
+          error_type: "agent_modification_disabled",
+          message: `Agent deletion not allowed for prompts/${input.name}.md`,
+          next_action_hint:
+            "Edit the file manually with `botholomew prompts delete` or your editor.",
+        };
+      }
+    } catch (err) {
+      // A malformed prompt is still a valid target for deletion — the agent
+      // shouldn't be locked out of cleaning up an unparseable file. Surface
+      // the parse error in the message but allow the unlink.
+      const reason =
+        err instanceof PromptValidationError
+          ? err.reason
+          : err instanceof Error
+            ? err.message
+            : String(err);
+      await unlink(filePath);
+      return {
+        name: input.name,
+        path: filePath,
+        deleted: true,
+        is_error: false,
+        message: `Deleted unparseable prompt (${reason})`,
+      };
+    }
+
+    await unlink(filePath);
+    return {
+      name: input.name,
+      path: filePath,
+      deleted: true,
+      is_error: false,
+    };
+  },
+} satisfies ToolDefinition<typeof inputSchema, typeof outputSchema>;

package/src/tools/prompt/edit.ts

@@ -8,8 +8,9 @@ import {
 } from "../../fs/atomic.ts";
 import { applyLinePatches, LinePatchSchema } from "../../fs/patches.ts";
 import {
-  parseContextFile,
-  serializeContextFile,
+  PromptValidationError,
+  parsePromptFile,
+  serializePromptFile,
 } from "../../utils/frontmatter.ts";
 import type { ToolDefinition } from "../tool.ts";
 
@@ -17,7 +18,7 @@ const inputSchema = z.object({
   name: z
     .string()
     .describe(
-      "Prompt name without extension (e.g. 'beliefs', 'goals', 'capabilities'). Resolves to prompts/<name>.md.",
+      "Prompt name without extension (e.g. 'beliefs', 'goals'). Resolves to prompts/<name>.md.",
     ),
   patches: z.array(LinePatchSchema).describe("Patches to apply"),
 });
@@ -36,7 +37,7 @@ const outputSchema = z.object({
 export const promptEditTool = {
   name: "prompt_edit",
   description:
-    "[[ bash equivalent command: patch ]] Apply git-style line-range patches to a prompt file under prompts/. Operates on the whole file (frontmatter + body). Files marked `agent-modification: false` (e.g. soul.md) are protected. Use prompt_read first to inspect current line numbers.",
+    "[[ bash equivalent command: patch ]] Apply git-style line-range patches to a prompt file under prompts/. Operates on the whole file (frontmatter + body). Files marked `agent-modification: false` are protected. Use prompt_read first to inspect current line numbers.",
   group: "context",
   inputSchema,
   outputSchema,
@@ -65,11 +66,31 @@ export const promptEditTool = {
         is_error: true,
         error_type: "not_found",
         message: `Prompt not found: prompts/${input.name}.md`,
+        next_action_hint:
+          "Use prompt_list to see available prompts, or prompt_create to add a new one.",
       };
     }
 
     const original = file.content;
-    const preParsed = parseContextFile(original);
+    let preParsed: ReturnType<typeof parsePromptFile>;
+    try {
+      preParsed = parsePromptFile(filePath, original);
+    } catch (err) {
+      return {
+        name: input.name,
+        path: filePath,
+        applied: 0,
+        content: original,
+        is_error: true,
+        error_type: "invalid_frontmatter",
+        message:
+          err instanceof PromptValidationError
+            ? err.message
+            : `Existing prompt failed to parse: ${err instanceof Error ? err.message : String(err)}`,
+        next_action_hint:
+          "Fix the file's frontmatter directly before patching. Required keys: title, loading, agent-modification.",
+      };
+    }
     if (!preParsed.meta["agent-modification"]) {
       return {
         name: input.name,
@@ -83,9 +104,9 @@ export const promptEditTool = {
     }
 
     const updated = applyLinePatches(original, input.patches);
-    let postParsed: { meta: Record<string, unknown>; content: string };
+    let postParsed: ReturnType<typeof parsePromptFile>;
     try {
-      postParsed = parseContextFile(updated);
+      postParsed = parsePromptFile(filePath, updated);
     } catch (err) {
       return {
         name: input.name,
@@ -94,9 +115,12 @@ export const promptEditTool = {
         content: original,
         is_error: true,
         error_type: "invalid_frontmatter",
-        message: `Patched content failed to parse: ${err instanceof Error ? err.message : String(err)}`,
+        message:
+          err instanceof PromptValidationError
+            ? `Patched content failed to parse — ${err.reason}`
+            : `Patched content failed to parse: ${err instanceof Error ? err.message : String(err)}`,
         next_action_hint:
-          "Check that the frontmatter delimiters and YAML stay valid.",
+          "Check that the frontmatter delimiters and YAML stay valid (title, loading, agent-modification all required).",
       };
     }
     if (!postParsed.meta["agent-modification"]) {
@@ -113,10 +137,7 @@ export const promptEditTool = {
       };
     }
 
-    const serialized = serializeContextFile(
-      postParsed.meta,
-      postParsed.content,
-    );
+    const serialized = serializePromptFile(postParsed.meta, postParsed.content);
 
     try {
       await atomicWriteIfUnchanged(filePath, serialized, file.mtimeMs);

package/src/tools/prompt/list.ts

@@ -0,0 +1,109 @@
+import { readdir, stat } from "node:fs/promises";
+import { join } from "node:path";
+import { z } from "zod";
+import { getPromptsDir } from "../../constants.ts";
+import {
+  PromptValidationError,
+  parsePromptFile,
+} from "../../utils/frontmatter.ts";
+import type { ToolDefinition } from "../tool.ts";
+
+const inputSchema = z.object({
+  limit: z
+    .number()
+    .optional()
+    .default(100)
+    .describe("Max number of prompts to return (default 100)"),
+  offset: z
+    .number()
+    .optional()
+    .default(0)
+    .describe("Skip the first N prompts (default 0)"),
+});
+
+const outputSchema = z.object({
+  prompts: z.array(
+    z.object({
+      name: z.string(),
+      title: z.string().nullable(),
+      loading: z.string().nullable(),
+      agent_modification: z.boolean(),
+      size_bytes: z.number(),
+      path: z.string(),
+      valid: z.boolean(),
+      error: z.string().nullable(),
+    }),
+  ),
+  total: z.number(),
+  is_error: z.boolean(),
+});
+
+export const promptListTool = {
+  name: "prompt_list",
+  description:
+    "[[ bash equivalent command: ls ]] List prompt files under prompts/. Returns name, title, loading mode, agent_modification flag, file size, and a valid/error pair per file (so you can see at a glance which prompts have broken frontmatter).",
+  group: "context",
+  inputSchema,
+  outputSchema,
+  execute: async (input, ctx) => {
+    const dir = getPromptsDir(ctx.projectDir);
+    let entries: string[];
+    try {
+      entries = await readdir(dir);
+    } catch (err) {
+      if ((err as NodeJS.ErrnoException).code === "ENOENT") {
+        return { prompts: [], total: 0, is_error: false };
+      }
+      throw err;
+    }
+
+    const mdFiles = entries.filter((f) => f.endsWith(".md")).sort();
+    const total = mdFiles.length;
+    const offset = input.offset ?? 0;
+    const limit = input.limit ?? 100;
+    const page = mdFiles.slice(offset, offset + limit);
+
+    const rows = await Promise.all(
+      page.map(async (filename) => {
+        const filePath = join(dir, filename);
+        const name = filename.replace(/\.md$/, "");
+        const [raw, st] = await Promise.all([
+          Bun.file(filePath).text(),
+          stat(filePath),
+        ]);
+        try {
+          const { meta } = parsePromptFile(filePath, raw);
+          return {
+            name,
+            title: meta.title,
+            loading: meta.loading,
+            agent_modification: meta["agent-modification"],
+            size_bytes: st.size,
+            path: filePath,
+            valid: true,
+            error: null,
+          };
+        } catch (err) {
+          const reason =
+            err instanceof PromptValidationError
+              ? err.reason
+              : err instanceof Error
+                ? err.message
+                : String(err);
+          return {
+            name,
+            title: null,
+            loading: null,
+            agent_modification: false,
+            size_bytes: st.size,
+            path: filePath,
+            valid: false,
+            error: reason,
+          };
+        }
+      }),
+    );
+
+    return { prompts: rows, total, is_error: false };
+  },
+} satisfies ToolDefinition<typeof inputSchema, typeof outputSchema>;

package/src/tools/prompt/read.ts

@@ -1,13 +1,17 @@
 import { join } from "node:path";
 import { z } from "zod";
 import { getPromptsDir } from "../../constants.ts";
+import {
+  PromptValidationError,
+  parsePromptFile,
+} from "../../utils/frontmatter.ts";
 import type { ToolDefinition } from "../tool.ts";
 
 const inputSchema = z.object({
   name: z
     .string()
     .describe(
-      "Prompt name without extension (e.g. 'beliefs', 'goals', 'capabilities'). Resolves to prompts/<name>.md.",
+      "Prompt name without extension (e.g. 'beliefs', 'goals'). Resolves to prompts/<name>.md.",
     ),
 });
 
@@ -15,16 +19,19 @@ const outputSchema = z.object({
   name: z.string(),
   path: z.string().nullable(),
   content: z.string(),
+  title: z.string().nullable(),
+  loading: z.string().nullable(),
   agent_modification: z.boolean(),
   is_error: z.boolean(),
   error_type: z.string().optional(),
   message: z.string().optional(),
+  next_action_hint: z.string().optional(),
 });
 
 export const promptReadTool = {
   name: "prompt_read",
   description:
-    "[[ bash equivalent command: cat ]] Read a prompt file under prompts/ (e.g. beliefs, goals, capabilities, soul). Returns the whole file (frontmatter + body) for use with prompt_edit.",
+    "[[ bash equivalent command: cat ]] Read a prompt file under prompts/. Returns the whole file (frontmatter + body) plus the parsed title / loading / agent_modification flags so you can decide whether prompt_edit will be accepted.",
   group: "context",
   inputSchema,
   outputSchema,
@@ -34,6 +41,8 @@ export const promptReadTool = {
         name: input.name,
         path: null,
         content: "",
+        title: null,
+        loading: null,
         agent_modification: false,
         is_error: true,
         error_type: "invalid_name",
@@ -47,24 +56,47 @@ export const promptReadTool = {
         name: input.name,
         path: null,
         content: "",
+        title: null,
+        loading: null,
         agent_modification: false,
         is_error: true,
         error_type: "not_found",
         message: `Prompt not found: prompts/${input.name}.md`,
+        next_action_hint: "Use prompt_list to see available prompts.",
       };
     }
     const content = await file.text();
-    // Cheap header sniff so the agent knows whether prompt_edit will be
-    // accepted before it constructs patches.
-    const agent_modification = /agent-modification:\s*true/.test(
-      content.split("---", 3).slice(0, 3).join("---"),
-    );
-    return {
-      name: input.name,
-      path: filePath,
-      content,
-      agent_modification,
-      is_error: false,
-    };
+    try {
+      const { meta } = parsePromptFile(filePath, content);
+      return {
+        name: input.name,
+        path: filePath,
+        content,
+        title: meta.title,
+        loading: meta.loading,
+        agent_modification: meta["agent-modification"],
+        is_error: false,
+      };
+    } catch (err) {
+      const message =
+        err instanceof PromptValidationError
+          ? err.message
+          : err instanceof Error
+            ? err.message
+            : String(err);
+      return {
+        name: input.name,
+        path: filePath,
+        content,
+        title: null,
+        loading: null,
+        agent_modification: false,
+        is_error: true,
+        error_type: "invalid_frontmatter",
+        message,
+        next_action_hint:
+          "Fix the file's frontmatter (required: title, loading, agent-modification). The raw content is returned for inspection.",
+      };
+    }
   },
 } satisfies ToolDefinition<typeof inputSchema, typeof outputSchema>;

package/src/tools/registry.ts

@@ -23,7 +23,10 @@ import { mcpInfoTool } from "./mcp/info.ts";
 import { mcpListToolsTool } from "./mcp/list-tools.ts";
 import { mcpSearchTool } from "./mcp/search.ts";
 // Prompt tools
+import { promptCreateTool } from "./prompt/create.ts";
+import { promptDeleteTool } from "./prompt/delete.ts";
 import { promptEditTool } from "./prompt/edit.ts";
+import { promptListTool } from "./prompt/list.ts";
 import { promptReadTool } from "./prompt/read.ts";
 // Schedule tools
 import { createScheduleTool } from "./schedule/create.ts";
@@ -83,8 +86,11 @@ export function registerAllTools(): void {
   registerTool(contextInfoTool);
   registerTool(contextExistsTool);
   registerTool(contextCountLinesTool);
+  registerTool(promptListTool);
   registerTool(promptReadTool);
+  registerTool(promptCreateTool);
   registerTool(promptEditTool);
+  registerTool(promptDeleteTool);
   registerTool(readLargeResultTool);
   registerTool(pipeToContextTool);
 

package/src/utils/frontmatter.ts

@@ -1,12 +1,18 @@
 import matter from "gray-matter";
+import { z } from "zod";
+
+// --------------------------------------------------------------------------
+// Loose context-file metadata
+//
+// Used for files under `context/` (URL imports, agent-authored notes) and the
+// auto-generated `prompts/capabilities.md`. Frontmatter is permissive here:
+// imported pages may carry source_url / imported_at; agent notes may have
+// nothing at all.
+// --------------------------------------------------------------------------
 
 export interface ContextFileMeta {
   loading?: "always" | "contextual";
   "agent-modification"?: boolean;
-  // Set by `botholomew context import <url>` so the saved file remembers
-  // where it came from. Optional so files written by other paths
-  // (prompts/, beliefs/, agent-authored notes) aren't required to
-  // carry import metadata.
   source_url?: string;
   imported_at?: string;
   title?: string;
@@ -30,3 +36,86 @@ export function serializeContextFile(
 ): string {
   return matter.stringify(`\n${content}\n`, meta);
 }
+
+// --------------------------------------------------------------------------
+// Strict prompt-file schema
+//
+// Every file under `prompts/*.md` must conform. Validation runs at load time
+// (worker + chat) and on every CRUD operation; failures throw
+// PromptValidationError with the offending path so the user can fix it.
+// --------------------------------------------------------------------------
+
+export const PromptFrontmatterSchema = z
+  .object({
+    title: z.string().min(1),
+    loading: z.enum(["always", "contextual"]),
+    "agent-modification": z.boolean(),
+  })
+  .strict();
+
+export type PromptFrontmatter = z.infer<typeof PromptFrontmatterSchema>;
+
+export class PromptValidationError extends Error {
+  constructor(
+    readonly path: string,
+    readonly reason: string,
+  ) {
+    super(`${path}: ${reason}`);
+    this.name = "PromptValidationError";
+  }
+}
+
+export function parsePromptFile(
+  path: string,
+  raw: string,
+): { meta: PromptFrontmatter; content: string } {
+  let parsed: { data: Record<string, unknown>; content: string };
+  try {
+    const m = matter(raw);
+    parsed = {
+      data: (m.data ?? {}) as Record<string, unknown>,
+      content: m.content,
+    };
+  } catch (err) {
+    throw new PromptValidationError(
+      path,
+      `invalid YAML frontmatter — ${err instanceof Error ? err.message : String(err)}`,
+    );
+  }
+
+  if (Object.keys(parsed.data).length === 0) {
+    throw new PromptValidationError(
+      path,
+      "missing frontmatter (required: title, loading, agent-modification)",
+    );
+  }
+
+  const result = PromptFrontmatterSchema.safeParse(parsed.data);
+  if (!result.success) {
+    throw new PromptValidationError(path, formatZodIssues(result.error.issues));
+  }
+
+  return { meta: result.data, content: parsed.content.trim() };
+}
+
+export function serializePromptFile(
+  meta: PromptFrontmatter,
+  content: string,
+): string {
+  return matter.stringify(`\n${content}\n`, meta);
+}
+
+function formatZodIssues(issues: z.ZodIssue[]): string {
+  return issues
+    .map((issue) => {
+      if (issue.code === "unrecognized_keys") {
+        const keys = (issue as z.ZodIssue & { keys?: string[] }).keys ?? [];
+        return `unrecognized frontmatter key(s): ${keys.join(", ")}`;
+      }
+      const field = issue.path.join(".");
+      return field
+        ? `frontmatter field '${field}': ${issue.message}`
+        : issue.message;
+    })
+    .join("; ");
+}

package/src/worker/prompt.ts

@@ -3,7 +3,7 @@ import { join } from "node:path";
 import type { BotholomewConfig } from "../config/schemas.ts";
 import { getPromptsDir } from "../constants.ts";
 import type { Task } from "../tasks/schema.ts";
-import { parseContextFile } from "../utils/frontmatter.ts";
+import { parsePromptFile } from "../utils/frontmatter.ts";
 
 const pkg = await Bun.file(
   new URL("../../package.json", import.meta.url),
@@ -36,37 +36,43 @@ export function extractKeywords(text: string): Set<string> {
  * Load persistent context files from prompts/ as a single formatted
  * string. Includes "always" files unconditionally and "contextual" files
  * whose content overlaps the provided taskKeywords.
+ *
+ * Validation is strict: any *.md file under prompts/ that fails the prompt
+ * frontmatter schema throws PromptValidationError naming the offending file.
+ * The only swallowed error is a missing prompts/ directory (e.g. fresh
+ * working dir before `botholomew init`).
  */
 export async function loadPersistentContext(
   projectDir: string,
   taskKeywords?: Set<string> | null,
 ): Promise<string> {
   const dir = getPromptsDir(projectDir);
-  let out = "";
-
+  let files: string[];
   try {
-    const files = await readdir(dir);
-    const mdFiles = files.filter((f) => f.endsWith(".md"));
-
-    for (const filename of mdFiles) {
-      const filePath = join(dir, filename);
-      const raw = await Bun.file(filePath).text();
-      const { meta, content } = parseContextFile(raw);
-
-      if (meta.loading === "always") {
-        out += `## ${filename}\n${content}\n\n`;
-      } else if (meta.loading === "contextual" && taskKeywords) {
-        const contentLower = content.toLowerCase();
-        const hasOverlap = [...taskKeywords].some((kw) =>
-          contentLower.includes(kw),
-        );
-        if (hasOverlap) {
-          out += `## ${filename} (contextual)\n${content}\n\n`;
-        }
+    files = await readdir(dir);
+  } catch (err) {
+    if ((err as NodeJS.ErrnoException).code === "ENOENT") return "";
+    throw err;
+  }
+  const mdFiles = files.filter((f) => f.endsWith(".md")).sort();
+
+  let out = "";
+  for (const filename of mdFiles) {
+    const filePath = join(dir, filename);
+    const raw = await Bun.file(filePath).text();
+    const { meta, content } = parsePromptFile(filePath, raw);
+
+    if (meta.loading === "always") {
+      out += `## ${filename}\n${content}\n\n`;
+    } else if (meta.loading === "contextual" && taskKeywords) {
+      const contentLower = content.toLowerCase();
+      const hasOverlap = [...taskKeywords].some((kw) =>
+        contentLower.includes(kw),
+      );
+      if (hasOverlap) {
+        out += `## ${filename} (contextual)\n${content}\n\n`;
       }
     }
-  } catch {
-    // prompts/ might not have md files yet
   }
 
   return out;

package/src/worker/tick.ts

@@ -149,13 +149,22 @@ async function runClaimedTask(opts: {
     `Working: ${task.name}`,
   );
 
-  const systemPrompt = await buildSystemPrompt(
-    projectDir,
-    task,
-    dbPath,
-    config,
-    { hasMcpTools: mcpxClient != null },
-  );
+  let systemPrompt: string;
+  try {
+    systemPrompt = await buildSystemPrompt(projectDir, task, dbPath, config, {
+      hasMcpTools: mcpxClient != null,
+    });
+  } catch (err) {
+    const reason = err instanceof Error ? err.message : String(err);
+    await updateTaskStatus(projectDir, task.id, "failed", reason, null);
+    await logInteraction(projectDir, threadId, {
+      role: "system",
+      kind: "status_change",
+      content: `Task ${task.id} failed during prompt load: ${reason}`,
+    });
+    logger.error(`Task ${task.id} failed during prompt load: ${reason}`);
+    return;
+  }
 
   try {
     const result = await runAgentLoop({