botholomew 0.6.1 → 0.6.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "botholomew",
-  "version": "0.6.1",
+  "version": "0.6.3",
   "description": "An AI agent for knowledge work",
   "type": "module",
   "bin": {
@@ -24,7 +24,7 @@
   "dependencies": {
     "@anthropic-ai/sdk": "^0.88.0",
     "@duckdb/node-api": "^1.5.2-r.1",
-    "@evantahler/mcpx": "0.18.3",
+    "@evantahler/mcpx": "0.18.6",
     "ansis": "^4.2.0",
     "commander": "^14.0.0",
     "gray-matter": "^4.0.3",

package/src/chat/agent.ts

@@ -25,7 +25,7 @@ const CHAT_TOOL_NAMES = new Set([
   "create_task",
   "list_tasks",
   "view_task",
-  "search_context",
+  "context_search",
   "search_grep",
   "search_semantic",
   "list_threads",

package/src/chat/session.ts

@@ -13,6 +13,8 @@ import {
   reopenThread,
 } from "../db/threads.ts";
 import { createMcpxClient } from "../mcpx/client.ts";
+import { loadSkills } from "../skills/loader.ts";
+import type { SkillDefinition } from "../skills/parser.ts";
 import type { ToolContext } from "../tools/tool.ts";
 import { generateThreadTitle } from "../utils/title.ts";
 import {
@@ -29,6 +31,7 @@ export interface ChatSession {
   messages: MessageParam[];
   systemPrompt: string;
   toolCtx: ToolContext;
+  skills: Map<string, SkillDefinition>;
   cleanup: () => Promise<void>;
 }
 
@@ -83,6 +86,7 @@ export async function startChatSession(
   const systemPrompt = await buildChatSystemPrompt(projectDir);
 
   const mcpxClient = await createMcpxClient(projectDir);
+  const skills = await loadSkills(projectDir);
 
   const toolCtx: ToolContext = {
     conn,
@@ -103,6 +107,7 @@ export async function startChatSession(
     messages,
     systemPrompt,
     toolCtx,
+    skills,
     cleanup,
   };
 }

package/src/cli.ts

@@ -10,9 +10,9 @@ import { registerInitCommand } from "./commands/init.ts";
 import { registerMcpxCommand } from "./commands/mcpx.ts";
 import { registerPrepareCommand } from "./commands/prepare.ts";
 import { registerScheduleCommand } from "./commands/schedule.ts";
+import { registerSkillCommand } from "./commands/skill.ts";
 import { registerTaskCommand } from "./commands/task.ts";
 import { registerThreadCommand } from "./commands/thread.ts";
-import { registerToolCommands } from "./commands/tools.ts";
 import { registerUpgradeCommand } from "./commands/upgrade.ts";
 import { maybeCheckForUpdate } from "./update/background.ts";
 
@@ -39,7 +39,7 @@ registerScheduleCommand(program);
 registerChatCommand(program);
 registerContextCommand(program);
 registerMcpxCommand(program);
-registerToolCommands(program);
+registerSkillCommand(program);
 registerPrepareCommand(program);
 registerCheckUpdateCommand(program);
 registerUpgradeCommand(program);

package/src/commands/context.ts

@@ -17,14 +17,18 @@ import type { DbConnection } from "../db/connection.ts";
 import {
   type ContextItem,
   deleteContextItemByPath,
-  getContextItemByPath,
   listContextItems,
   listContextItemsByPrefix,
+  resolveContextItem,
   updateContextItem,
   upsertContextItem,
 } from "../db/context.ts";
 import { getEmbeddingsForItem, hybridSearch } from "../db/embeddings.ts";
 import { logger } from "../utils/logger.ts";
+import {
+  registerContextToolSubcommands,
+  registerSearchToolSubcommands,
+} from "./tools.ts";
 import { withDb } from "./with-db.ts";
 
 function fmtDate(d: Date): string {
@@ -33,11 +37,11 @@ function fmtDate(d: Date): string {
 }
 
 export function registerContextCommand(program: Command) {
-  const ctx = program.command("context").description("Manage context items");
+  const ctx = program.command("context").description("Manage context");
 
   ctx
     .command("list")
-    .description("List context items")
+    .description("List context entries")
     .option("--path <prefix>", "filter by path prefix")
     .option("-l, --limit <n>", "max number of items", Number.parseInt)
     .option("-o, --offset <n>", "skip first N items", Number.parseInt)
@@ -55,7 +59,7 @@ export function registerContextCommand(program: Command) {
             });
 
         if (items.length === 0) {
-          logger.dim("No context items found.");
+          logger.dim("No context entries found.");
           return;
         }
 
@@ -80,37 +84,6 @@ export function registerContextCommand(program: Command) {
       }),
     );
 
-  ctx
-    .command("show <path>")
-    .description("Show details and content of a context item")
-    .action((path: string) =>
-      withDb(program, async (conn) => {
-        const item = await getContextItemByPath(conn, path);
-        if (!item) {
-          logger.error(`Context item not found: ${path}`);
-          process.exit(1);
-        }
-
-        console.log(ansis.bold(item.title));
-        if (item.description) console.log(`  Description: ${item.description}`);
-        console.log(`  Path:        ${item.context_path}`);
-        console.log(`  MIME type:   ${item.mime_type}`);
-        if (item.source_path) console.log(`  Source:      ${item.source_path}`);
-        const indexed = item.indexed_at
-          ? `${ansis.green("yes")} (${fmtDate(item.indexed_at)})`
-          : ansis.dim("no");
-        console.log(`  Indexed:     ${indexed}`);
-        console.log(`  Created:     ${fmtDate(item.created_at)}`);
-        console.log(`  Updated:     ${fmtDate(item.updated_at)}`);
-
-        if (item.is_textual && item.content) {
-          console.log(`\n${"─".repeat(60)}\n${item.content}`);
-        } else if (!item.is_textual) {
-          console.log(ansis.dim("\n  (binary content not shown)"));
-        }
-      }),
-    );
-
   ctx
     .command("add <paths...>")
     .description("Add files or directories to context")
@@ -236,12 +209,17 @@ export function registerContextCommand(program: Command) {
       }),
     );
 
-  ctx
-    .command("search <query>")
-    .description("Search context items")
+  const search = ctx
+    .command("search")
+    .description("Search context entries")
+    .argument("[query]", "search query (hybrid keyword + semantic)")
     .option("-k, --top-k <n>", "max results", Number.parseInt, 10)
     .action((query, opts) =>
       withDb(program, async (conn, dir) => {
+        if (!query) {
+          search.help();
+          return;
+        }
         const config = await loadConfig(dir);
         const queryVec = await embedSingle(query, config);
         const results = await hybridSearch(conn, query, queryVec, opts.topK);
@@ -267,27 +245,29 @@ export function registerContextCommand(program: Command) {
         }
       }),
     );
+
+  registerSearchToolSubcommands(search);
   ctx
     .command("delete <path>")
-    .description("Delete a context item by path")
+    .description("Delete a context entry by path")
     .action((path: string) =>
       withDb(program, async (conn) => {
         const deleted = await deleteContextItemByPath(conn, path);
         if (!deleted) {
-          logger.error(`Context item not found: ${path}`);
+          logger.error(`Context entry not found: ${path}`);
           process.exit(1);
         }
-        logger.success(`Deleted context item: ${path}`);
+        logger.success(`Deleted context entry: ${path}`);
       }),
     );
   ctx
     .command("chunks <path>")
-    .description("Show chunks and embeddings for a context item")
+    .description("Show chunks and embeddings for a context entry")
     .action((path: string) =>
       withDb(program, async (conn) => {
-        const item = await getContextItemByPath(conn, path);
+        const item = await resolveContextItem(conn, path);
         if (!item) {
-          logger.error(`Context item not found: ${path}`);
+          logger.error(`Context entry not found: ${path}`);
           process.exit(1);
         }
 
@@ -336,7 +316,7 @@ export function registerContextCommand(program: Command) {
       withDb(program, async (conn, dir) => {
         const items = await resolveItems(conn, path, !!opts.all);
         if (items.length === 0) {
-          logger.error("No matching context items found.");
+          logger.error("No matching context entries found.");
           process.exit(1);
         }
 
@@ -436,6 +416,10 @@ export function registerContextCommand(program: Command) {
         );
       }),
     );
+
+  // Register context tool subcommands (read, write, edit, list-dir, etc.)
+  // Must come after management subcommands so collision detection works.
+  registerContextToolSubcommands(ctx);
 }
 
 async function resolveItems(
@@ -449,12 +433,12 @@ async function resolveItems(
   }
   if (all) return listContextItems(conn);
   const p = path as string;
-  const exact = await getContextItemByPath(conn, p);
+  const exact = await resolveContextItem(conn, p);
   if (exact) return [exact];
   return listContextItemsByPrefix(conn, p, { recursive: true });
 }
 
-/** Upsert a file into the context DB. Returns the item ID if textual, null otherwise. */
+/** Upsert a file into context. Returns the item ID if textual, null otherwise. */
 async function addFile(
   conn: DbConnection,
   filePath: string,

package/src/commands/skill.ts

@@ -0,0 +1,100 @@
+import { join } from "node:path";
+import ansis from "ansis";
+import type { Command } from "commander";
+import { getSkillsDir } from "../constants.ts";
+import { loadSkills } from "../skills/loader.ts";
+import { parseSkillFile } from "../skills/parser.ts";
+import { logger } from "../utils/logger.ts";
+
+export function registerSkillCommand(program: Command) {
+  const skill = program
+    .command("skill")
+    .description("Manage skill slash-commands");
+
+  skill
+    .command("validate [file]")
+    .description("Validate skill files in .botholomew/skills/")
+    .action(async (file?: string) => {
+      const dir = program.opts().dir;
+
+      if (file) {
+        await validateSingleFile(file);
+      } else {
+        await validateAllSkills(dir);
+      }
+    });
+
+  skill
+    .command("create <name>")
+    .description("Create a new skill file from a template")
+    .option("--force", "overwrite existing file")
+    .action(async (name: string, opts: { force?: boolean }) => {
+      const dir = program.opts().dir;
+      const skillsDir = getSkillsDir(dir);
+      const normalized = name.toLowerCase().replace(/[^a-z0-9-]/g, "-");
+      const filePath = join(skillsDir, `${normalized}.md`);
+
+      if (!opts.force && (await Bun.file(filePath).exists())) {
+        logger.error(`Skill file already exists: ${filePath}`);
+        logger.dim("Use --force to overwrite.");
+        process.exit(1);
+      }
+
+      const template = `---
+name: ${normalized}
+description: ""
+arguments: []
+---
+
+Your prompt template here. Use $ARGUMENTS for the full argument string
+or $1, $2, etc. for positional arguments.
+`;
+
+      await Bun.write(filePath, template);
+      logger.success(`Created skill: ${filePath}`);
+    });
+}
+
+async function validateSingleFile(filePath: string): Promise<void> {
+  try {
+    const raw = await Bun.file(filePath).text();
+    const skill = parseSkillFile(raw, filePath);
+    logger.success(`${ansis.bold(skill.name)} — valid`);
+    if (skill.description) logger.dim(`  ${skill.description}`);
+    if (skill.arguments.length > 0) {
+      logger.dim(`  ${skill.arguments.length} argument(s)`);
+    }
+  } catch (e) {
+    logger.error(`${filePath}: ${e instanceof Error ? e.message : e}`);
+    process.exit(1);
+  }
+}
+
+async function validateAllSkills(dir: string): Promise<void> {
+  let hasErrors = false;
+
+  try {
+    const skills = await loadSkills(dir);
+
+    if (skills.size === 0) {
+      logger.dim("No skill files found.");
+      return;
+    }
+
+    for (const [name, skill] of skills) {
+      const argCount = skill.arguments.length;
+      const args = argCount > 0 ? `${argCount} arg(s)` : "no args";
+      logger.success(
+        `${ansis.bold(name).padEnd(20)} ${skill.description || ansis.dim("(no description)")}  ${ansis.dim(`[${args}]`)}`,
+      );
+    }
+
+    logger.info("");
+    logger.dim(`${skills.size} skill(s) validated.`);
+  } catch (e) {
+    logger.error(`Validation failed: ${e instanceof Error ? e.message : e}`);
+    hasErrors = true;
+  }
+
+  if (hasErrors) process.exit(1);
+}

package/src/commands/tools.ts

@@ -1,7 +1,7 @@
+import ansis from "ansis";
 import type { Command } from "commander";
 import { z } from "zod";
-import type { BotholomewConfig } from "../config/schemas.ts";
-import { DEFAULT_CONFIG } from "../config/schemas.ts";
+import { loadConfig } from "../config/loader.ts";
 import { registerAllTools } from "../tools/registry.ts";
 import {
   type AnyToolDefinition,
@@ -13,31 +13,42 @@ import { withDb } from "./with-db.ts";
 
 registerAllTools();
 
-const GROUP_DESCRIPTIONS: Record<string, string> = {
-  dir: "Directory operations on the virtual filesystem",
-  file: "File operations on the virtual filesystem",
-  search: "Search the virtual filesystem",
-};
-
-export function registerToolCommands(program: Command) {
-  for (const group of ["dir", "file", "search"]) {
-    const groupCmd = program
-      .command(group)
-      .description(GROUP_DESCRIPTIONS[group] ?? `${group} tools`);
+/**
+ * Register context tool subcommands (read, write, edit, etc.) onto an
+ * existing Commander command. Skips tools whose derived subcommand name
+ * collides with an already-registered subcommand on the parent.
+ */
+/** Context tools that are agent-only (not exposed as CLI subcommands) */
+const AGENT_ONLY_TOOLS = new Set(["update_beliefs", "update_goals"]);
+
+export function registerContextToolSubcommands(parent: Command) {
+  const existing = new Set(parent.commands.map((c: Command) => c.name()));
+
+  for (const tool of getToolsByGroup("context")) {
+    if (AGENT_ONLY_TOOLS.has(tool.name)) continue;
+    const subName = deriveSubName(tool.name);
+    if (existing.has(subName)) continue; // skip conflicts with management subcommands
+    registerToolAsCLI(parent, tool);
+  }
+}
 
-    for (const tool of getToolsByGroup(group)) {
-      registerToolAsCLI(groupCmd, tool, program);
-    }
+/**
+ * Register search tool subcommands (grep, semantic) onto an
+ * existing Commander command (e.g. the "context search" group).
+ */
+export function registerSearchToolSubcommands(parent: Command) {
+  for (const tool of getToolsByGroup("search")) {
+    registerToolAsCLI(parent, tool);
   }
 }
 
-function registerToolAsCLI(
-  parent: Command,
-  tool: AnyToolDefinition,
-  program: Command,
-) {
-  // Derive subcommand name: "file_read" → "read", "file_count_lines" → "count-lines"
-  const subName = tool.name.replace(/^[^_]+_/, "").replace(/_/g, "-");
+/** Derive CLI subcommand name from tool name: "context_read" → "read", "context_list_dir" → "list-dir" */
+function deriveSubName(toolName: string): string {
+  return toolName.replace(/^[^_]+_/, "").replace(/_/g, "-");
+}
+
+function registerToolAsCLI(parent: Command, tool: AnyToolDefinition) {
+  const subName = deriveSubName(tool.name);
 
   // Inspect zod schema to determine positional args and options
   const shape = tool.inputSchema.shape as Record<string, z.ZodType>;
@@ -92,15 +103,17 @@ function registerToolAsCLI(
     }
   }
 
-  cmd.action((...args: unknown[]) =>
-    withDb(program, async (conn, dir) => {
+  cmd.action((...args: unknown[]) => {
+    let root: Command = parent;
+    while (root.parent) root = root.parent;
+    return withDb(root, async (conn, dir) => {
       try {
         const input = buildInput(tool, positionals, options, shape, args);
 
         const ctx: ToolContext = {
           conn,
           projectDir: dir,
-          config: DEFAULT_CONFIG as Required<BotholomewConfig>,
+          config: await loadConfig(dir),
           mcpxClient: null,
         };
 
@@ -110,8 +123,8 @@ function registerToolAsCLI(
         logger.error(String(err));
         process.exit(1);
       }
-    }),
-  );
+    });
+  });
 }
 
 function buildInput(
@@ -214,6 +227,29 @@ function formatOutput(result: unknown, _toolName: string) {
       return;
     }
 
+    if ("results" in obj && Array.isArray(obj.results)) {
+      for (const [i, r] of (
+        obj.results as {
+          path: string;
+          title: string;
+          score: number;
+          snippet: string;
+        }[]
+      ).entries()) {
+        const score = (r.score * 100).toFixed(1);
+        console.log(
+          `${ansis.bold(`${i + 1}.`)} ${ansis.cyan(r.title)} ${ansis.dim(`(${score}%)`)}`,
+        );
+        console.log(`   ${ansis.dim(r.path)}`);
+        if (r.snippet) {
+          const snippet = r.snippet.slice(0, 120).replace(/\n/g, " ");
+          console.log(`   ${snippet}...`);
+        }
+        console.log("");
+      }
+      return;
+    }
+
     // Default: print as JSON
     console.log(JSON.stringify(obj, null, 2));
   } else {
@@ -224,20 +260,20 @@ function formatOutput(result: unknown, _toolName: string) {
 function isPositionalArg(key: string, toolName: string): boolean {
   // These keys are treated as positional arguments
   const positionalKeys: Record<string, string[]> = {
-    dir_create: ["path"],
-    dir_list: ["path"],
-    dir_tree: ["path"],
-    dir_size: ["path"],
-    file_read: ["path"],
-    file_write: ["path"],
-    file_edit: ["path"],
-    file_delete: ["path"],
-    file_copy: ["src", "dst"],
-    file_move: ["src", "dst"],
-    file_info: ["path"],
-    file_exists: ["path"],
-    file_count_lines: ["path"],
-    search_find: ["pattern"],
+    context_create_dir: ["path"],
+    context_list_dir: ["path"],
+    context_tree: ["path"],
+    context_dir_size: ["path"],
+    context_read: ["path"],
+    context_write: ["path"],
+    context_edit: ["path"],
+    context_delete: ["path"],
+    context_copy: ["src", "dst"],
+    context_move: ["src", "dst"],
+    context_info: ["path"],
+    context_exists: ["path"],
+    context_count_lines: ["path"],
+    context_search: ["query"],
     search_grep: ["pattern"],
     search_semantic: ["query"],
   };

package/src/constants.ts

@@ -17,6 +17,7 @@ export const PID_FILENAME = "daemon.pid";
 export const LOG_FILENAME = "daemon.log";
 export const CONFIG_FILENAME = "config.json";
 export const MCPX_DIR = "mcpx";
+export const SKILLS_DIR = "skills";
 export const MCPX_SERVERS_FILENAME = "servers.json";
 export const EMBEDDING_DIMENSION = 1536;
 export const EMBEDDING_MODEL = "text-embedding-3-small";
@@ -50,6 +51,10 @@ export function getMcpxDir(projectDir: string): string {
   return join(projectDir, BOTHOLOMEW_DIR, MCPX_DIR);
 }
 
+export function getSkillsDir(projectDir: string): string {
+  return join(projectDir, BOTHOLOMEW_DIR, SKILLS_DIR);
+}
+
 export function getWatchdogLogPath(projectDir: string): string {
   return join(projectDir, BOTHOLOMEW_DIR, WATCHDOG_LOG_FILENAME);
 }

package/src/db/context.ts

@@ -1,6 +1,6 @@
 import type { DbConnection } from "./connection.ts";
 import { buildSetClauses, buildWhereClause, sanitizeInt } from "./query.ts";
-import { uuidv7 } from "./uuid.ts";
+import { isUuid, uuidv7 } from "./uuid.ts";
 
 export interface ContextItem {
   id: string;
@@ -90,7 +90,7 @@ export async function createContextItem(
  *
  * DuckDB implements UPDATE as delete+insert on tables with unique indexes,
  * which violates foreign keys from the embeddings table. We must delete
- * embeddings before updating; callers (context add, file_write) re-create
+ * embeddings before updating; callers (context add, context_write) re-create
  * them in their ingestion phase.
  */
 export async function upsertContextItem(
@@ -140,6 +140,30 @@ export async function getContextItemByPath(
   return row ? rowToContextItem(row) : null;
 }
 
+/**
+ * Look up a context item by UUID (if the value looks like one) or by context_path.
+ */
+export async function resolveContextItem(
+  db: DbConnection,
+  pathOrId: string,
+): Promise<ContextItem | null> {
+  return isUuid(pathOrId)
+    ? getContextItem(db, pathOrId)
+    : getContextItemByPath(db, pathOrId);
+}
+
+/**
+ * Like resolveContextItem but throws if not found.
+ */
+export async function resolveContextItemOrThrow(
+  db: DbConnection,
+  pathOrId: string,
+): Promise<ContextItem> {
+  const item = await resolveContextItem(db, pathOrId);
+  if (!item) throw new Error(`Not found: ${pathOrId}`);
+  return item;
+}
+
 export async function listContextItems(
   db: DbConnection,
   filters?: {
@@ -207,6 +231,29 @@ export async function contextPathExists(
   return row != null;
 }
 
+export async function countContextItemsByPrefix(
+  db: DbConnection,
+  prefix: string,
+  opts?: { recursive?: boolean },
+): Promise<number> {
+  const normalizedPrefix = prefix.endsWith("/") ? prefix : `${prefix}/`;
+  let row: { cnt: number } | null;
+  if (opts?.recursive !== false) {
+    row = await db.queryGet<{ cnt: number }>(
+      `SELECT COUNT(*) AS cnt FROM context_items WHERE context_path LIKE ?1`,
+      `${normalizedPrefix}%`,
+    );
+  } else {
+    row = await db.queryGet<{ cnt: number }>(
+      `SELECT COUNT(*) AS cnt FROM context_items
+       WHERE context_path LIKE ?1 AND context_path NOT LIKE ?2`,
+      `${normalizedPrefix}%`,
+      `${normalizedPrefix}%/%`,
+    );
+  }
+  return row ? Number(row.cnt) : 0;
+}
+
 export async function getDistinctDirectories(
   db: DbConnection,
   prefix?: string,

package/src/db/uuid.ts

@@ -1 +1,8 @@
 export { v7 as uuidv7 } from "uuid";
+
+const UUID_RE =
+  /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+
+export function isUuid(value: string): boolean {
+  return UUID_RE.test(value);
+}

package/src/init/index.ts

@@ -1,6 +1,11 @@
 import { mkdir } from "node:fs/promises";
 import { join } from "node:path";
-import { getBotholomewDir, getDbPath, getMcpxDir } from "../constants.ts";
+import {
+  getBotholomewDir,
+  getDbPath,
+  getMcpxDir,
+  getSkillsDir,
+} from "../constants.ts";
 import { getConnection } from "../db/connection.ts";
 import { migrate } from "../db/schema.ts";
 import { logger } from "../utils/logger.ts";
@@ -10,6 +15,8 @@ import {
   DEFAULT_MCPX_SERVERS,
   GOALS_MD,
   SOUL_MD,
+  STANDUP_SKILL,
+  SUMMARIZE_SKILL,
 } from "./templates.ts";
 
 export async function initProject(
@@ -18,6 +25,7 @@ export async function initProject(
 ): Promise<void> {
   const dotDir = getBotholomewDir(projectDir);
   const mcpxDir = getMcpxDir(projectDir);
+  const skillsDir = getSkillsDir(projectDir);
 
   // Check if already initialized
   const dirExists = await Bun.file(join(dotDir, "soul.md")).exists();
@@ -30,12 +38,17 @@ export async function initProject(
   // Create directories
   await mkdir(dotDir, { recursive: true });
   await mkdir(mcpxDir, { recursive: true });
+  await mkdir(skillsDir, { recursive: true });
 
   // Write template files
   await Bun.write(join(dotDir, "soul.md"), SOUL_MD);
   await Bun.write(join(dotDir, "beliefs.md"), BELIEFS_MD);
   await Bun.write(join(dotDir, "goals.md"), GOALS_MD);
 
+  // Write default skills
+  await Bun.write(join(skillsDir, "summarize.md"), SUMMARIZE_SKILL);
+  await Bun.write(join(skillsDir, "standup.md"), STANDUP_SKILL);
+
   // Write config (with placeholder API key)
   await Bun.write(
     join(dotDir, "config.json"),