codebase-analyzer-mcp 2.1.2 → 2.3.0

package/README.md

@@ -3,30 +3,11 @@
 [![npm](https://img.shields.io/npm/v/codebase-analyzer-mcp)](https://www.npmjs.com/package/codebase-analyzer-mcp)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-Analyze any codebase with Gemini AI. Progressive disclosure keeps costs low - start with free structural analysis, drill into semantic details only when needed.
+MCP server for codebase analysis with Gemini AI. Progressive disclosure keeps costs low — start with free structural analysis, drill into semantic details only when needed.
 
 ## Install
 
-### Option 1: Claude Code Plugin (recommended)
-
-```bash
-claude /plugin install jaykaycodes/codebase-analyzer-mcp
-```
-
-This gives you MCP tools + agents + the `/cba:analyze` command. Just ask questions naturally.
-
-**Gemini API key (optional):** Enables semantic analysis, pattern detection, and dataflow tracing. Without it, you still get structural analysis.
-
-```bash
-mkdir -p ~/.config/codebase-analyzer
-echo '{"geminiApiKey":"YOUR_KEY"}' > ~/.config/codebase-analyzer/config.json
-```
-
-Get a free key at https://aistudio.google.com/apikey
-
-### Option 2: Standalone MCP Server
-
-Add to `~/.mcp.json`:
+Add to your MCP config (`~/.mcp.json` for Claude Code):
 
 ```json
 {
@@ -42,20 +23,23 @@ Add to `~/.mcp.json`:
 }
 ```
 
-Restart Claude Code, then use `analyze_repo`, `query_repo`, etc.
+Restart Claude Code. The tools will be available immediately.
 
-### Option 3: CLI
+**Gemini API key** is optional — enables semantic analysis, pattern detection, and dataflow tracing. Without it, you still get structural analysis. Get a free key at https://aistudio.google.com/apikey
 
-```bash
-npx codebase-analyzer-mcp analyze .                              # Standard analysis
-npx codebase-analyzer-mcp analyze . -d surface                   # Fast, free overview
-npx codebase-analyzer-mcp analyze . -d deep -s                   # Full semantic analysis
-npx codebase-analyzer-mcp query . "how is auth handled?"         # Ask a question
-npx codebase-analyzer-mcp patterns .                             # Find design patterns
-npx codebase-analyzer-mcp dataflow . "user login"                # Trace data flow
-```
+## Tools
 
-## What It Does
+| Tool | Description | Requires Gemini |
+|------|-------------|:---:|
+| `analyze_repo` | Full analysis with progressive disclosure | No |
+| `query_repo` | Ask questions about a codebase | Optional |
+| `expand_section` | Drill into specific analysis sections | No |
+| `read_files` | Read source files from a cached analysis | No |
+| `find_patterns` | Detect design/architecture patterns | Yes |
+| `trace_dataflow` | Trace data flow through the system | Yes |
+| `get_analysis_capabilities` | List supported languages and options | No |
+
+## Analysis Layers
 
 | Layer | Cost | What You Get |
 |-------|------|--------------|
@@ -63,38 +47,37 @@ npx codebase-analyzer-mcp dataflow . "user login"                # Trace data fl
 | **Structural** | Free | Symbols, imports, complexity (via tree-sitter) |
 | **Semantic** | Gemini | Architecture insights, pattern detection |
 
-Analysis results include expandable sections - you only pay for what you drill into.
+Results include expandable sections — you only pay for what you drill into.
 
-## MCP Tools
+## CLI
 
-| Tool | Description |
-|------|-------------|
-| `analyze_repo` | Full analysis with progressive disclosure |
-| `query_repo` | Ask questions about a codebase |
-| `expand_section` | Drill into specific sections |
-| `read_files` | Read source files from a cached analysis |
-| `find_patterns` | Detect design/architecture patterns |
-| `trace_dataflow` | Trace data flow through the system |
-| `get_analysis_capabilities` | List supported languages and analysis options |
+```bash
+npx codebase-analyzer-mcp analyze .                      # Standard analysis
+npx codebase-analyzer-mcp analyze . -d surface            # Fast, free overview
+npx codebase-analyzer-mcp analyze . -d deep -s            # Full semantic analysis
+npx codebase-analyzer-mcp analyze . -o analysis.md        # Write structured markdown to file
+npx codebase-analyzer-mcp analyze . -o analysis.json      # Write JSON to file
+npx codebase-analyzer-mcp query . "how is auth handled?"  # Ask a question
+npx codebase-analyzer-mcp patterns .                      # Find design patterns
+npx codebase-analyzer-mcp dataflow . "user login"         # Trace data flow
+```
 
-## Plugin Components
+## Usage with Claude Code
 
-### Command
+Dump an analysis and reference it from your CLAUDE.md:
 
-```
-/cba:analyze [source] [--depth surface|standard|deep] [--focus <paths>]
+```bash
+npx codebase-analyzer-mcp analyze . -o docs/codebase-analysis.md
 ```
 
-### Agents
+Then add to your project's CLAUDE.md:
 
-| Agent | Purpose |
-|-------|---------|
-| `architecture-analyzer` | Full codebase architecture analysis |
-| `pattern-detective` | Design/anti-pattern detection |
-| `dataflow-tracer` | Data flow tracing through systems |
-| `codebase-explorer` | Quick exploration and Q&A |
+```markdown
+## Codebase Analysis
+See [docs/codebase-analysis.md](docs/codebase-analysis.md) for full analysis.
+```
 
-Agents are routed automatically based on your question.
+Claude Code will read the summary (~50 lines) for context, then drill into specific module sections as needed using `Read` with offset/limit.
 
 ## Development
 
@@ -102,8 +85,7 @@ Agents are routed automatically based on your question.
 git clone https://github.com/jaykaycodes/codebase-analyzer-mcp.git
 cd codebase-analyzer-mcp
 bun install
-bun run build         # Build dist/
-bun run dev           # Watch mode
+bun run build
 ```
 
 For local MCP testing, create `.mcp.json` at repo root:

package/dist/cli/index.js

@@ -44251,8 +44251,8 @@ var package_default;
 var init_package = __esm(() => {
   package_default = {
     name: "codebase-analyzer-mcp",
-    version: "2.1.2",
-    description: "Multi-layer codebase analysis with Gemini AI. MCP server + Claude plugin with progressive disclosure.",
+    version: "2.3.0",
+    description: "Multi-layer codebase analysis MCP server with Gemini AI and progressive disclosure.",
     type: "module",
     main: "dist/mcp/server.js",
     packageManager: "bun@1.3.8",
@@ -44262,13 +44262,7 @@ var init_package = __esm(() => {
     },
     files: [
       "dist/cli",
-      "dist/mcp",
-      "agents",
-      "commands",
-      "skills",
-      ".claude-plugin",
-      "CLAUDE.md",
-      "AGENTS.md"
+      "dist/mcp"
     ],
     scripts: {
       build: "bun scripts/build.ts",
@@ -44277,7 +44271,7 @@ var init_package = __esm(() => {
       typecheck: "tsc --noEmit",
       test: "bun test",
       cli: "bun src/cli/index.ts",
-      version: "bun scripts/sync-version.ts && git add .",
+      version: "git add .",
       postversion: "git push --follow-tags",
       prepublishOnly: "bun run build"
     },
@@ -74135,7 +74129,7 @@ function extractSourceName3(source) {
 }
 var program2 = new Command;
 program2.name("cba").description("Codebase Analyzer - Multi-layer repository analysis with Gemini AI").version(package_default.version);
-program2.command("analyze").description("Perform architectural analysis of a repository").argument("<source>", "Local path or GitHub URL").option("-d, --depth <depth>", "Analysis depth: surface, standard, deep", "standard").option("-f, --focus <areas...>", "Specific areas to focus on").option("-e, --exclude <patterns...>", "Glob patterns to exclude").option("-t, --token-budget <tokens>", "Maximum token budget", "800000").option("-s, --semantics", "Include deep semantic analysis (uses LLM)").option("-v, --verbose", "Show detailed progress and subagent activity").option("-q, --quiet", "Only output the final result (no progress)").option("--format <format>", "Output format (json or markdown)", "json").action(async (source, options) => {
+program2.command("analyze").description("Perform architectural analysis of a repository").argument("<source>", "Local path or GitHub URL").option("-d, --depth <depth>", "Analysis depth: surface, standard, deep", "standard").option("-f, --focus <areas...>", "Specific areas to focus on").option("-e, --exclude <patterns...>", "Glob patterns to exclude").option("-t, --token-budget <tokens>", "Maximum token budget", "800000").option("-s, --semantics", "Include deep semantic analysis (uses LLM)").option("-v, --verbose", "Show detailed progress and subagent activity").option("-q, --quiet", "Only output the final result (no progress)").option("--format <format>", "Output format (json or markdown)", "json").option("-o, --output <path>", "Write analysis to a file (markdown by default, .json for JSON)").action(async (source, options) => {
   try {
     if (options.verbose)
       logger.setVerbose(true);
@@ -74152,7 +74146,12 @@ program2.command("analyze").description("Perform architectural analysis of a rep
         includeSemantics: options.semantics,
         sourceName
       });
-      if (options.format === "markdown") {
+      if (options.output) {
+        const { writeFile: writeFile2 } = await import("fs/promises");
+        const content = options.output.endsWith(".json") ? JSON.stringify(result, null, 2) : formatAnalysisAsMarkdown(result);
+        await writeFile2(options.output, content, "utf-8");
+        console.error(`Analysis written to ${options.output}`);
+      } else if (options.format === "markdown") {
         console.log(formatAnalysisAsMarkdown(result));
       } else {
         console.log(JSON.stringify(result, null, 2));
@@ -74226,66 +74225,137 @@ program2.command("capabilities").description("Show available analysis capabiliti
   const { formatCapabilitiesResponse: formatCapabilitiesResponse2 } = await Promise.resolve().then(() => (init_capabilities(), exports_capabilities));
   console.log(JSON.stringify(formatCapabilitiesResponse2(), null, 2));
 });
+function renderTree(node, depth, maxDepth) {
+  const SKIP_DIRS = new Set(["node_modules", ".git", "dist", ".next", "__pycache__", ".cache", "coverage"]);
+  const lines = [];
+  const indent = "  ".repeat(depth);
+  if (depth > 0) {
+    lines.push(`${indent}${node.name}${node.type === "directory" ? "/" : ""}`);
+  }
+  if (node.type === "directory" && node.children && depth < maxDepth) {
+    const dirs = node.children.filter((c) => c.type === "directory" && !SKIP_DIRS.has(c.name)).sort((a, b) => a.name.localeCompare(b.name));
+    const files = node.children.filter((c) => c.type === "file").sort((a, b) => a.name.localeCompare(b.name));
+    for (const dir of dirs) {
+      lines.push(...renderTree(dir, depth + 1, maxDepth));
+    }
+    if (depth === 0 || files.length <= 5) {
+      for (const file2 of files) {
+        lines.push(`${"  ".repeat(depth + 1)}${file2.name}`);
+      }
+    } else if (files.length > 5) {
+      lines.push(`${"  ".repeat(depth + 1)}... ${files.length} files`);
+    }
+  }
+  return lines;
+}
 function formatAnalysisAsMarkdown(result) {
   const lines = [];
-  lines.push(`# ${result.repositoryMap?.name || "Repository"} Analysis`);
+  const name = result.repositoryMap?.name || "Repository";
+  const date6 = new Date().toISOString().split("T")[0];
+  lines.push(`<!-- codebase-analyzer-mcp | ${date6} | depth: ${result.depth} | id: ${result.analysisId} -->`);
   lines.push("");
-  lines.push(`**Analysis ID:** \`${result.analysisId}\``);
-  lines.push(`**Depth:** ${result.depth}`);
-  lines.push(`**Duration:** ${result.durationMs}ms`);
+  lines.push(`# ${name}`);
   lines.push("");
-  if (result.summary) {
-    lines.push("## Summary");
-    lines.push(`- **Architecture:** ${result.summary.architectureType}`);
-    lines.push(`- **Complexity:** ${result.summary.complexity}`);
-    if (result.summary.primaryPatterns?.length > 0) {
-      lines.push(`- **Patterns:** ${result.summary.primaryPatterns.join(", ")}`);
+  if (result.forAgent?.quickSummary) {
+    lines.push(result.forAgent.quickSummary);
+    lines.push("");
+  }
+  const repoMap = result.repositoryMap;
+  const summary = result.summary;
+  if (repoMap || summary) {
+    lines.push("## Overview");
+    lines.push("");
+    lines.push("| Metric | Value |");
+    lines.push("|--------|-------|");
+    if (repoMap?.fileCount != null) {
+      lines.push(`| Files | ${repoMap.fileCount} |`);
+    }
+    if (repoMap?.languages?.length > 0) {
+      const langs = repoMap.languages.map((l) => `${l.language} (${l.percentage}%)`).join(", ");
+      lines.push(`| Languages | ${langs} |`);
+    }
+    if (summary?.architectureType) {
+      lines.push(`| Architecture | ${summary.architectureType} |`);
+    }
+    if (summary?.complexity) {
+      lines.push(`| Complexity | ${summary.complexity} |`);
+    }
+    if (repoMap?.entryPoints?.length > 0) {
+      lines.push(`| Entry points | ${repoMap.entryPoints.slice(0, 5).join(", ")} |`);
     }
-    if (result.summary.techStack?.length > 0) {
-      lines.push(`- **Tech Stack:** ${result.summary.techStack.join(", ")}`);
+    if (summary?.techStack?.length > 0) {
+      lines.push(`| Tech stack | ${summary.techStack.join(", ")} |`);
+    }
+    if (summary?.primaryPatterns?.length > 0) {
+      lines.push(`| Patterns | ${summary.primaryPatterns.join(", ")} |`);
     }
     lines.push("");
   }
-  if (result.repositoryMap) {
-    lines.push("## Repository Map");
-    lines.push(`- **Total Files:** ${result.repositoryMap.fileCount}`);
-    lines.push(`- **Estimated Tokens:** ${result.repositoryMap.estimatedTokens}`);
-    lines.push(`- **Languages:** ${result.repositoryMap.languages?.map((l) => `${l.language} (${l.percentage}%)`).join(", ")}`);
-    lines.push(`- **Entry Points:** ${result.repositoryMap.entryPoints?.slice(0, 5).join(", ")}`);
+  if (result.forAgent?.keyInsights?.length > 0) {
+    lines.push("## Key Insights");
     lines.push("");
-  }
-  if (result.sections?.length > 0) {
-    lines.push("## Sections");
-    for (const section of result.sections) {
-      lines.push(`### ${section.title}`);
-      lines.push(section.summary);
-      if (section.canExpand) {
-        lines.push(`*Expandable (detail: ~${section.expansionCost?.detail} tokens, full: ~${section.expansionCost?.full} tokens)*`);
-      }
-      lines.push("");
+    for (const insight of result.forAgent.keyInsights) {
+      lines.push(`- ${insight}`);
     }
+    lines.push("");
   }
-  if (result.forAgent) {
-    lines.push("## Agent Hints");
-    lines.push(result.forAgent.quickSummary);
+  if (repoMap?.structure) {
+    lines.push("## Structure");
     lines.push("");
-    if (result.forAgent.keyInsights?.length > 0) {
-      lines.push("**Key Insights:**");
-      for (const insight of result.forAgent.keyInsights) {
-        lines.push(`- ${insight}`);
-      }
+    lines.push("```");
+    const treeLines = renderTree(repoMap.structure, 0, 3);
+    lines.push(...treeLines);
+    lines.push("```");
+    lines.push("");
+  }
+  const moduleSections = result.sections?.filter((s2) => s2.type === "module") || [];
+  if (moduleSections.length > 0) {
+    lines.push("## Modules");
+    lines.push("");
+    for (const section of moduleSections) {
+      const modulePath = section.id.replace("module_", "").replace(/_/g, "/");
+      const detail = section.detail;
+      let header = `### ${modulePath}`;
+      const meta3 = [];
+      if (section.summary)
+        meta3.push(section.summary);
+      if (meta3.length)
+        header += ` — ${meta3.join(", ")}`;
+      lines.push(header);
       lines.push("");
-    }
-    if (result.forAgent.suggestedNextSteps?.length > 0) {
-      lines.push("**Suggested Next Steps:**");
-      for (const step of result.forAgent.suggestedNextSteps) {
-        lines.push(`- ${step}`);
+      if (detail) {
+        if (detail.type === "documentation") {
+          if (detail.headings?.length > 0) {
+            lines.push(`Headings: ${detail.headings.map((h2) => h2.title).join(", ")}`);
+          }
+        } else {
+          if (detail.exports?.length > 0) {
+            lines.push(`Exports: ${detail.exports.slice(0, 10).join(", ")}${detail.exports.length > 10 ? ", ..." : ""}`);
+          }
+          const cx = detail.complexity;
+          if (cx) {
+            lines.push(`Complexity: ${cx.cyclomaticComplexity} cyclomatic | ${cx.linesOfCode} LOC | ${cx.functionCount} functions | ${cx.classCount} classes`);
+          }
+          if (detail.symbolCount != null || detail.importCount != null) {
+            lines.push(`Symbols: ${detail.symbolCount ?? 0} | Imports: ${detail.importCount ?? 0}`);
+          }
+        }
+        lines.push("");
       }
+    }
+  }
+  const otherSections = result.sections?.filter((s2) => s2.type !== "module") || [];
+  if (otherSections.length > 0) {
+    for (const section of otherSections) {
+      lines.push(`## ${section.title}`);
+      lines.push("");
+      lines.push(section.summary);
       lines.push("");
     }
   }
   if (result.warnings?.length > 0) {
     lines.push("## Warnings");
+    lines.push("");
     for (const warning of result.warnings) {
       lines.push(`- ${warning}`);
     }

package/dist/mcp/server.js

@@ -71136,8 +71136,8 @@ function buildFallbackAnswer(question, analysisId, cached2, scored, fileContents
 // package.json
 var package_default = {
   name: "codebase-analyzer-mcp",
-  version: "2.1.2",
-  description: "Multi-layer codebase analysis with Gemini AI. MCP server + Claude plugin with progressive disclosure.",
+  version: "2.3.0",
+  description: "Multi-layer codebase analysis MCP server with Gemini AI and progressive disclosure.",
   type: "module",
   main: "dist/mcp/server.js",
   packageManager: "bun@1.3.8",
@@ -71147,13 +71147,7 @@ var package_default = {
   },
   files: [
     "dist/cli",
-    "dist/mcp",
-    "agents",
-    "commands",
-    "skills",
-    ".claude-plugin",
-    "CLAUDE.md",
-    "AGENTS.md"
+    "dist/mcp"
   ],
   scripts: {
     build: "bun scripts/build.ts",
@@ -71162,7 +71156,7 @@ var package_default = {
     typecheck: "tsc --noEmit",
     test: "bun test",
     cli: "bun src/cli/index.ts",
-    version: "bun scripts/sync-version.ts && git add .",
+    version: "git add .",
     postversion: "git push --follow-tags",
     prepublishOnly: "bun run build"
   },

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "codebase-analyzer-mcp",
-  "version": "2.1.2",
-  "description": "Multi-layer codebase analysis with Gemini AI. MCP server + Claude plugin with progressive disclosure.",
+  "version": "2.3.0",
+  "description": "Multi-layer codebase analysis MCP server with Gemini AI and progressive disclosure.",
   "type": "module",
   "main": "dist/mcp/server.js",
   "packageManager": "bun@1.3.8",
@@ -11,13 +11,7 @@
   },
   "files": [
     "dist/cli",
-    "dist/mcp",
-    "agents",
-    "commands",
-    "skills",
-    ".claude-plugin",
-    "CLAUDE.md",
-    "AGENTS.md"
+    "dist/mcp"
   ],
   "scripts": {
     "build": "bun scripts/build.ts",
@@ -26,7 +20,7 @@
     "typecheck": "tsc --noEmit",
     "test": "bun test",
     "cli": "bun src/cli/index.ts",
-    "version": "bun scripts/sync-version.ts && git add .",
+    "version": "git add .",
     "postversion": "git push --follow-tags",
     "prepublishOnly": "bun run build"
   },

package/.claude-plugin/marketplace.json

@@ -1,34 +0,0 @@
-{
-  "name": "codebase-analyzer",
-  "owner": {
-    "name": "Jake Correa",
-    "url": "https://github.com/jaykaycodes"
-  },
-  "metadata": {
-    "description": "Multi-layer codebase analysis tools",
-    "version": "2.1.2"
-  },
-  "plugins": [
-    {
-      "name": "codebase-analyzer",
-      "description": "Multi-layer codebase analysis with Gemini AI. 4 agents, 1 command, 1 skill for architecture analysis, pattern detection, and dataflow tracing.",
-      "version": "2.1.2",
-      "author": {
-        "name": "Jake Correa",
-        "url": "https://github.com/jaykaycodes"
-      },
-      "homepage": "https://github.com/jaykaycodes/codebase-analyzer-mcp",
-      "tags": [
-        "codebase-analysis",
-        "architecture",
-        "patterns",
-        "gemini",
-        "mcp"
-      ],
-      "source": {
-        "source": "github",
-        "repo": "jaykaycodes/codebase-analyzer-mcp"
-      }
-    }
-  ]
-}

package/.claude-plugin/plugin.json

@@ -1,32 +0,0 @@
-{
-  "name": "codebase-analyzer",
-  "version": "2.1.2",
-  "description": "Multi-layer codebase analysis with Gemini AI. 4 agents, 1 command, 1 skill for architecture analysis, pattern detection, and dataflow tracing.",
-  "author": {
-    "name": "Jake Correa",
-    "url": "https://github.com/jaykaycodes"
-  },
-  "homepage": "https://github.com/jaykaycodes/codebase-analyzer-mcp",
-  "license": "MIT",
-  "keywords": [
-    "codebase-analysis",
-    "architecture",
-    "patterns",
-    "gemini",
-    "mcp",
-    "progressive-disclosure",
-    "tree-sitter"
-  ],
-  "mcpServers": {
-    "codebase-analyzer": {
-      "type": "stdio",
-      "command": "node",
-      "args": [
-        "${CLAUDE_PLUGIN_ROOT}/dist/mcp/server.js"
-      ],
-      "env": {
-        "GEMINI_API_KEY": "${GEMINI_API_KEY}"
-      }
-    }
-  }
-}

package/AGENTS.md

@@ -1,112 +0,0 @@
-# Agent Instructions
-
-This repository is both an MCP server and a Claude plugin for multi-layer codebase analysis.
-
-## Working Agreement
-
-- **Branching:** Feature branches for non-trivial changes
-- **Safety:** No destructive git commands, no deleting user data
-- **Testing:** Run `pnpm build` after changes - TypeScript errors break everything
-- **Architecture:** Respect layer separation (surface → structural → semantic)
-- **Counts:** When adding agents/commands/skills, update plugin.json description
-
-## Repository Structure
-
-```
-codebase-analyzer-mcp/
-├── .claude-plugin/
-│   └── plugin.json           # Plugin metadata
-├── agents/
-│   ├── analysis/             # Analysis agents
-│   └── research/             # Research agents
-├── commands/                 # Slash commands
-├── skills/                   # Context-loaded skills
-├── src/
-│   ├── mcp/                  # MCP server + tools
-│   ├── cli/                  # CLI interface
-│   └── core/                 # Analysis engine
-│       └── layers/           # Surface, structural, semantic
-└── docs/                     # Documentation
-```
-
-## Key Decisions
-
-| Decision | Rationale |
-|----------|-----------|
-| Gemini for semantic | Keep Claude context clean |
-| Tree-sitter for parsing | Fast AST without LLM |
-| Progressive disclosure | Minimize initial context cost |
-| Plugin + MCP | Both distribution paths |
-
-## Layer Responsibilities
-
-**Surface Layer** (`src/core/layers/surface.ts`)
-- File enumeration, language detection
-- Entry points, module identification
-- NO LLM calls
-
-**Structural Layer** (`src/core/layers/structural.ts`)
-- Tree-sitter parsing
-- Symbol extraction
-- Import/export mapping
-- NO LLM calls
-
-**Semantic Layer** (`src/core/layers/semantic.ts`)
-- Gemini API calls
-- Architecture detection
-- Pattern recognition
-- EXPENSIVE - opt-in only
-
-## Code Patterns
-
-**Partial failures:** Capture in `warnings[]` or `partialFailures[]`, don't throw
-
-**Token budget:** Check before expensive operations, warn if exceeded
-
-**Logging:** Use `logger` from `src/core/logger.ts`
-
-## Plugin Component Guidelines
-
-### Agents
-
-- Place in `agents/[category]/` by purpose
-- YAML frontmatter: `name`, `description` with examples
-- Description explains when to use the agent
-- Use haiku model for efficiency
-
-### Commands
-
-- Place in `commands/`
-- Set `user-invocable: true`
-- Document usage, options, examples
-- Show workflow and implementation
-
-### Skills
-
-- Directory in `skills/[name]/`
-- SKILL.md is entry point (<500 lines)
-- references/ for detailed docs
-- Description in third person
-
-## Updating Plugin Counts
-
-After adding/removing components:
-
-```bash
-# Count components
-ls agents/**/*.md | wc -l    # agents
-ls commands/*.md | wc -l      # commands
-ls -d skills/*/ | wc -l       # skills
-
-# Update description in .claude-plugin/plugin.json
-```
-
-Format: `"X agents, Y commands, Z skills"`
-
-## Testing Checklist
-
-- [ ] `pnpm build` succeeds
-- [ ] `pnpm cba capabilities` returns JSON
-- [ ] `pnpm cba analyze . -d surface -q` works
-- [ ] New agent/command/skill follows patterns
-- [ ] plugin.json counts match actual files