agentsbestfriend 0.10.0 → 0.11.1

package/assets/skills/abf/SKILL.md

@@ -0,0 +1,161 @@
+---
+name: abf
+description: "Use AgentsBestFriend (ABF) MCP tools for codebase navigation, search, and analysis instead of native file-reading tools. USE WHEN: exploring unfamiliar code, understanding architecture, searching across files, tracing imports/dependencies, analyzing change impact, reading large files, or needing project context. Prefer ABF tools over read_file, grep_search, semantic_search, and list_dir for multi-file workflows — they return pre-structured, token-efficient results in a single call."
+---
+
+# AgentsBestFriend (ABF) — Codebase Navigation Skill
+
+ABF is a local MCP server that provides AI-optimized tools for navigating, searching, and analyzing code repositories. These tools return structured, compact results that save 50–80% of tokens compared to manually reading files.
+
+## When to Use ABF Tools
+
+**Always prefer ABF tools when you need to:**
+- Understand a project's structure or tech stack
+- Search for code across files (exact, keyword, or semantic)
+- Read specific functions or classes from large files
+- Trace imports, dependencies, or reverse dependencies
+- Assess the impact of changing a symbol
+- Get multi-file context around an entry point
+
+**Use native tools only when:**
+- Making edits to files (ABF is read-only)
+- Checking for lint/compile errors
+- Running terminal commands
+- The ABF MCP server is not connected
+
+## Decision Matrix
+
+| Task | ABF Tool | Instead of |
+|------|----------|------------|
+| Orient in a new project | `abf_project_overview` | Reading README + listing directories + checking package.json |
+| Find where something is defined | `abf_search` (exact mode) | `grep_search` |
+| Find files related to a concept | `abf_search` (keyword mode) | Multiple `semantic_search` + `grep_search` calls |
+| Read a specific function from a large file | `abf_chunk` with symbol name | `read_file` (which loads entire file or requires guessing line ranges) |
+| List all exports of a file | `abf_symbols` | `read_file` and scanning manually |
+| Understand what a file imports and who imports it | `abf_dependencies` | Multiple `grep_search` calls for import statements |
+| Get multi-file context around one entry point | `abf_context_bundle` | 5–10 calls to `read_file` + `abf_symbols` + `abf_dependencies` |
+| Find all usages of a function/class | `abf_impact` | `grep_search` with manual filtering |
+| Understand project conventions | `abf_conventions` | Reading multiple config files manually |
+| Search by file purpose/description | `abf_file_summary` | No native equivalent |
+| Check git history or blame | `abf_git` | `run_in_terminal` with git commands |
+
+## Recommended Workflows
+
+### 1. First Contact with a Codebase
+
+```
+1. abf_project_overview              → architecture, tech stack, entry points
+2. abf_conventions                   → coding style, patterns, naming
+3. abf_search (keyword: "main topic") → find relevant files
+```
+
+### 2. Understanding a Specific File
+
+```
+1. abf_symbols (file)               → see all exports/functions at a glance
+2. abf_chunk (file, symbol: "name") → read just the function you care about
+3. abf_dependencies (file)          → see what it imports and who imports it
+```
+
+### 3. Deep Dive into a Feature
+
+```
+1. abf_context_bundle (entry file, depth: 2, include: "smart")
+   → full source of entry + signatures of all dependencies in ONE call
+2. If needed: abf_chunk to read specific dependency functions
+```
+
+### 4. Change Impact Analysis
+
+```
+1. abf_impact (symbol: "functionName")  → all files and lines referencing it
+2. abf_context_bundle (entry, focus_symbol: "functionName", reverse: true)
+   → focused view of the function + its callers
+```
+
+### 5. Searching for Code
+
+```
+- Know the exact name?       → abf_search mode: "exact"
+- Exploring a concept?       → abf_search mode: "keyword"
+- Describe what you need?    → abf_file_summary (searches LLM-generated descriptions)
+- Semantic similarity?       → abf_search mode: "semantic" (requires Ollama)
+```
+
+## Tool Reference
+
+### abf_project_overview
+**When:** Starting work on a project, or when asked "what does this project do?"
+**Saves:** Reading README + package.json + listing directories manually (3–5 calls → 1)
+- Returns: tech stack, frameworks, entry points, directory structure, language distribution, architectural patterns
+- No index required — works immediately
+
+### abf_search
+**When:** Looking for code, files, or patterns across the project
+**Saves:** Multiple grep_search or semantic_search calls
+- `mode: "exact"` — ripgrep-powered, supports regex, returns matching lines with context
+- `mode: "keyword"` — scores every file by keyword density, best for exploration
+- `mode: "semantic"` — embedding similarity (requires Ollama + index with embeddings)
+- Use `path_filter` to narrow scope (e.g. `"src/**/*.ts"`)
+
+### abf_context_bundle
+**When:** You need to understand a file in the context of its dependencies
+**Saves:** 5–10 calls to read_file + abf_symbols + abf_dependencies (biggest saver)
+- `include: "smart"` (default) — full source for entry, signatures for deps
+- `include: "signatures"` — compact type signatures only (minimal tokens)
+- `include: "full"` — full source code for all files up to depth
+- `focus_symbol` — only follows imports relevant to one function/class
+- `reverse: true` — also shows who imports this file
+- `depth: 0–4` — how far to follow the import graph
+
+### abf_chunk
+**When:** You need to read a specific function/class from a file without loading the entire file
+**Saves:** read_file loading hundreds of irrelevant lines
+- Call with `symbol: "functionName"` to get its full source code directly
+- Call without symbol first to get a chunk overview, then use `chunk_index` to retrieve specific sections
+
+### abf_symbols
+**When:** You need to see what a file exports without reading its full content
+**Saves:** read_file + mentally parsing the file structure
+- Returns: function signatures, classes, interfaces, types, variables with line ranges
+- Shows export status (★ = exported) and nesting
+
+### abf_dependencies
+**When:** Tracing what a file imports or finding who depends on it
+**Saves:** Multiple grep_search calls for import statements
+- Returns both imports and reverse dependencies (imported_by)
+
+### abf_impact
+**When:** Assessing how widely a symbol is used before changing it
+**Saves:** grep_search + manual filtering of false positives
+- Returns all files and specific lines that reference the symbol
+- Classifies usage type (call, import, type reference, etc.)
+
+### abf_file_summary
+**When:** Searching by file purpose rather than exact code text
+**Saves:** No native equivalent — unique capability
+- Full-text search across LLM-generated file descriptions
+- Requires summaries to be generated first (`abf_index` action: summarize)
+
+### abf_conventions
+**When:** Understanding project style before making changes
+**Saves:** Reading eslint, tsconfig, prettier, and other config files manually
+- Detects naming patterns, design patterns, folder structure conventions
+- Returns confidence scores and examples
+
+### abf_git
+**When:** Checking history, blame, or diffs
+**Saves:** Running git commands in terminal and parsing output
+- Actions: log, file_history, blame, diff
+- Structured output ready for analysis
+
+### abf_index
+**When:** Managing the ABF index
+- `status` — check index health
+- `rebuild` — full re-index
+- `update` — incremental update
+- `summarize` — generate LLM summaries (requires Ollama)
+
+### abf_ping
+**When:** Verifying ABF is running
+- Returns server version, project root, and status

package/dist/index.js

@@ -12405,7 +12405,7 @@ var init_sql = __esm({
         return new SQL([new StringChunk(str)]);
       }
       sql2.raw = raw;
-      function join13(chunks, separator) {
+      function join14(chunks, separator) {
         const result = [];
         for (const [i, chunk] of chunks.entries()) {
           if (i > 0 && separator !== void 0) {
@@ -12415,7 +12415,7 @@ var init_sql = __esm({
         }
         return new SQL(result);
       }
-      sql2.join = join13;
+      sql2.join = join14;
       function identifier(value) {
         return new Name(value);
       }
@@ -15400,7 +15400,7 @@ var init_select2 = __esm({
           const baseTableName = this.tableName;
           const tableName = getTableLikeName(table);
           for (const item of extractUsedTable(table)) this.usedTables.add(item);
-          if (typeof tableName === "string" && this.config.joins?.some((join13) => join13.alias === tableName)) {
+          if (typeof tableName === "string" && this.config.joins?.some((join14) => join14.alias === tableName)) {
             throw new Error(`Alias "${tableName}" is already used in this query`);
           }
           if (!this.isPartialSelect) {
@@ -16290,7 +16290,7 @@ var init_update = __esm({
       createJoin(joinType) {
         return (table, on) => {
           const tableName = getTableLikeName(table);
-          if (typeof tableName === "string" && this.config.joins.some((join13) => join13.alias === tableName)) {
+          if (typeof tableName === "string" && this.config.joins.some((join14) => join14.alias === tableName)) {
             throw new Error(`Alias "${tableName}" is already used in this query`);
           }
           if (typeof on === "function") {
@@ -18342,10 +18342,10 @@ async function getIndexStatus(projectRoot) {
     }
     const lastUpdated = allFiles.length > 0 ? new Date(Math.max(...allFiles.map((f) => f.lastIndexedAt.getTime()))) : null;
     const { statSync: statSync3 } = await import("fs");
-    const { join: join13 } = await import("path");
+    const { join: join14 } = await import("path");
     let indexSizeBytes = 0;
     try {
-      const dbPath = join13(projectRoot, ".abf", "index.db");
+      const dbPath = join14(projectRoot, ".abf", "index.db");
       indexSizeBytes = statSync3(dbPath).size;
     } catch {
     }
@@ -19265,8 +19265,9 @@ __export(init_exports, {
   initCommand: () => initCommand
 });
 import * as clack from "@clack/prompts";
-import { resolve as resolve3 } from "path";
+import { resolve as resolve3, dirname as dirname3, join as join13 } from "path";
 import { existsSync as existsSync6, mkdirSync as mkdirSync3, readFileSync as readFileSync10, appendFileSync } from "fs";
+import { fileURLToPath } from "url";
 import { execFile as execFile5 } from "child_process";
 import { promisify as promisify5 } from "util";
 async function initCommand(projectPath) {
@@ -19357,6 +19358,7 @@ async function initCommand(projectPath) {
       "LLM enrichment skipped (Ollama not available). Run `abf index --summarize` later."
     );
   }
+  await installSkill(root);
   const installMcp = await clack.confirm({
     message: "Install ABF as an MCP server for your coding agents?",
     initialValue: true
@@ -19415,7 +19417,7 @@ async function initCommand(projectPath) {
     clack.outro(isNew ? "Project initialized!" : "Index rebuilt!");
     return;
   }
-  const mcpCommand = mcpSource === "npx" ? "npx agentsbestfriend start" : "abf start";
+  const mcpCommand = mcpSource === "npx" ? "npx -y agentsbestfriend start" : "abf start";
   const addMcpArgs = ["add-mcp", mcpCommand, "--name", "abf", "-y"];
   for (const agent of selectedAgents) {
     addMcpArgs.push("-a", agent);
@@ -19453,6 +19455,117 @@ You can install manually: npx add-mcp "${mcpCommand}" --name abf -y`
   }
   clack.outro(isNew ? "Project initialized!" : "Index rebuilt!");
 }
+function getSkillDir() {
+  const candidates = [
+    // Installed via npm/npx — assets is sibling to dist/
+    join13(dirname3(fileURLToPath(import.meta.url)), "..", "assets", "skills"),
+    // Monorepo dev — two levels up from dist/
+    join13(
+      dirname3(fileURLToPath(import.meta.url)),
+      "..",
+      "..",
+      "assets",
+      "skills"
+    )
+  ];
+  for (const candidate of candidates) {
+    const resolved = resolve3(candidate);
+    if (existsSync6(join13(resolved, "abf", "SKILL.md"))) return resolved;
+  }
+  return null;
+}
+async function installSkill(projectRoot) {
+  const doInstall = await clack.confirm({
+    message: "Install ABF workflow skill? (Helps agents prefer ABF tools over native read_file/grep)",
+    initialValue: true
+  });
+  if (clack.isCancel(doInstall) || !doInstall) return;
+  const skillDir = getSkillDir();
+  if (!skillDir) {
+    clack.log.warn("Could not find bundled skill asset \u2014 skipping.");
+    return;
+  }
+  const agentChoice = await clack.select({
+    message: "Install skill for which agents?",
+    options: [
+      {
+        value: "all",
+        label: "All detected agents",
+        hint: "Auto-detects installed agents"
+      },
+      {
+        value: "pick",
+        label: "Let me pick"
+      }
+    ]
+  });
+  if (clack.isCancel(agentChoice)) return;
+  let skillAgentArgs = [];
+  if (agentChoice === "pick") {
+    const skillAgents = AGENTS.filter((a) => a.skillAgent);
+    const selected = await clack.multiselect({
+      message: "Which agents should get the ABF skill?",
+      options: skillAgents.map((a) => ({
+        value: a.skillAgent,
+        label: a.label
+      })),
+      required: true
+    });
+    if (clack.isCancel(selected)) return;
+    for (const agent of selected) {
+      skillAgentArgs.push("-a", agent);
+    }
+  }
+  const scope = await clack.select({
+    message: "Skill installation scope?",
+    options: [
+      {
+        value: "project",
+        label: "Project (default)",
+        hint: "Committed with your repo, shared with team"
+      },
+      {
+        value: "global",
+        label: "Global",
+        hint: "Available across all projects"
+      }
+    ]
+  });
+  if (clack.isCancel(scope)) return;
+  const skillArgs = [
+    "skills",
+    "add",
+    skillDir,
+    "--skill",
+    "abf",
+    "--copy",
+    "-y"
+  ];
+  if (agentChoice === "all") {
+    skillArgs.push("--all");
+  } else {
+    skillArgs.push(...skillAgentArgs);
+  }
+  if (scope === "global") {
+    skillArgs.push("-g");
+  }
+  const skillSpinner = clack.spinner();
+  skillSpinner.start("Installing ABF skill...");
+  try {
+    await execFileAsync5("npx", skillArgs, {
+      cwd: projectRoot,
+      timeout: 6e4
+    });
+    skillSpinner.stop("ABF skill installed successfully");
+  } catch (err) {
+    skillSpinner.stop("Skill installation failed");
+    const msg = err instanceof Error ? err.message : String(err);
+    clack.log.warn(
+      `Could not install skill: ${msg}
+You can install manually: npx skills add ${skillDir} --skill abf --copy -y`
+    );
+  }
+}
 var execFileAsync5, AGENTS;
 var init_init = __esm({
   "src/commands/init.ts"() {
@@ -19461,16 +19574,20 @@ var init_init = __esm({
     init_llm();
     execFileAsync5 = promisify5(execFile5);
     AGENTS = [
-      { value: "cursor", label: "Cursor" },
-      { value: "vscode", label: "VS Code / GitHub Copilot" },
-      { value: "claude-code", label: "Claude Code" },
-      { value: "claude-desktop", label: "Claude Desktop" },
-      { value: "codex", label: "Codex" },
-      { value: "cline", label: "Cline" },
-      { value: "zed", label: "Zed" },
-      { value: "gemini-cli", label: "Gemini CLI" },
-      { value: "goose", label: "Goose" },
-      { value: "opencode", label: "OpenCode" }
+      { value: "cursor", label: "Cursor", skillAgent: "cursor" },
+      {
+        value: "vscode",
+        label: "VS Code / GitHub Copilot",
+        skillAgent: "github-copilot"
+      },
+      { value: "claude-code", label: "Claude Code", skillAgent: "claude-code" },
+      { value: "claude-desktop", label: "Claude Desktop", skillAgent: void 0 },
+      { value: "codex", label: "Codex", skillAgent: "codex" },
+      { value: "cline", label: "Cline", skillAgent: "cline" },
+      { value: "zed", label: "Zed", skillAgent: void 0 },
+      { value: "gemini-cli", label: "Gemini CLI", skillAgent: "gemini-cli" },
+      { value: "goose", label: "Goose", skillAgent: "goose" },
+      { value: "opencode", label: "OpenCode", skillAgent: "opencode" }
     ];
   }
 });
@@ -43471,7 +43588,7 @@ function registerPingTool(server) {
     const status = {
       status: "ok",
       server: "agents-best-friend",
-      version: "0.10.0",
+      version: "0.11.1",
       projectRoot,
       timestamp: (/* @__PURE__ */ new Date()).toISOString()
     };
@@ -46002,7 +46119,7 @@ Use reverse=true to also find files that import the entry file.`, {
 
 // ../server/dist/server.js
 var SERVER_NAME = "agents-best-friend";
-var SERVER_VERSION = "0.10.0";
+var SERVER_VERSION = "0.11.1";
 function createAbfServer() {
   const server = new McpServer({
     name: SERVER_NAME,
@@ -46052,7 +46169,7 @@ async function startCommand() {
 
 // src/index.ts
 var program = new Command();
-program.name("abf").description("AgentsBestFriend \u2014 AI-first code navigation and analysis tools").version("0.10.0");
+program.name("abf").description("AgentsBestFriend \u2014 AI-first code navigation and analysis tools").version("0.11.1");
 program.command("start").description("Start the MCP server in stdio mode (for AI agent connections)").action(async () => {
   await startCommand();
 });