@tencent-ai/codebuddy-code 2.95.0-next.fefce1e.20260503 → 2.95.1-next.bd7ff53.20260508

package/dist/web-ui/docs/en/cli/plugins-reference.md

@@ -1,125 +1,109 @@
 # CodeBuddy Plugin Reference
 
-## Overview
+> A complete technical reference for the CodeBuddy plugin system, covering component specifications, CLI commands, and development tools.
 
-The CodeBuddy plugin system allows you to extend the AI assistant's functionality through a standardized plugin mechanism. Plugins can provide custom commands, agents, skills, hooks, MCP servers, and LSP servers.
+A **plugin** is a self-contained component directory that extends CodeBuddy with custom functionality. Plugin components include Skills, Agents, Hooks, MCP servers, and LSP servers.
 
-description: Command description
-allowed-tools: Read,Write,Bash
-argument-hint: Argument hint
-model: Model ID or name to use
+name: agent-name
+description: The agent's expertise and when to invoke it
+model: sonnet
+effort: medium
+maxTurns: 20
+disallowedTools: Write, Edit
 ---
 
-Command prompt content
+Detailed system prompt for the agent, describing its role, expertise, and behavior.
 ```
 
-**Command File Organization**:
-- Supports nested subdirectory organization
-- Subdirectory paths are converted to command names using colon separators
-- Example: `commands/deploy/production.md` → command name `deploy:production`
+Plugin agents support the following frontmatter fields: `name`, `description`, `model`, `effort`, `maxTurns`, `tools`, `disallowedTools`, `skills`, `memory`, `background`, and `isolation`. The only valid value for `isolation` is `"worktree"`. For security reasons, plugin agents do not support the `hooks`, `mcpServers`, or `permissionMode` fields.
 
-### 2. Agents
+**Integration**:
 
-**Location**: `agents/` directory in the plugin root
-**Format**: Markdown files with frontmatter
+- Agents appear in the `/agents` UI.
+- The AI assistant can auto-invoke agents based on task context.
+- Users can also invoke agents manually.
+- Plugin agents cooperate with built-in agents.
 
-**Frontmatter Configuration**:
-```markdown
----
-name: Agent name (optional, defaults to filename)
-description: Agent description
-model: Model ID or name to use
-tools: Read,Write,Bash (comma-separated list of available tools)
-color: #FF5733 (agent display color, optional)
----
-
-Agent instruction content
-```
-
-**Features**:
-- Agents can be invoked as tools by the main agent
-- Support custom tool lists
-- Automatically generate source tags to identify origin
-
-### 3. Skills
-
-**Location**: `skills/` directory in the plugin root
-**Format**: Each skill is a subdirectory containing a `SKILL.md` file
-
-**Directory Structure**:
-```
-skills/
-├── pdf-processor/
-│   ├── SKILL.md
-│   ├── reference.md (optional)
-│   └── scripts/ (optional)
-└── code-reviewer/
-    └── SKILL.md
-```
+See [Subagents](sub-agents.md) for details.
 
-**SKILL.md Frontmatter Configuration**:
-```markdown
----
-name: Skill name (optional, defaults to directory name)
-description: Skill description
-allowed-tools: Read,Write,Bash (list of allowed tools)
----
+### 3. Hooks
 
-Skill instruction content
-```
+Plugins can provide event handlers that respond to CodeBuddy events automatically.
 
-**Features**:
-- Skills can include auxiliary files and scripts
-- The skill's `baseDirectory` points to the skill directory, allowing access to resource files in the same directory
+**Location**: `hooks/hooks.json` under the plugin root, or inline configuration in `plugin.json`.
 
-### 4. Hooks
+**Format**: JSON configuration containing event matchers and actions.
 
-**Location**: `hooks/hooks.json` in the plugin root, or configured via PluginInfo extension fields in `plugin.json`
-**Format**: JSON configuration containing event matchers and actions
+**Configuration example**:
 
-**Configuration Example**:
 ```json
 {
-  "PostToolUse": [
-    {
-      "matcher": "Write|Edit",
-      "hooks": [
-        {
-          "type": "command",
-          "command": "${CODEBUDDY_PLUGIN_ROOT}/scripts/format-code.sh",
-          "timeout": 30000
-        }
-      ]
-    }
-  ]
+  "hooks": {
+    "PostToolUse": [
+      {
+        "matcher": "Write|Edit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CODEBUDDY_PLUGIN_ROOT}/scripts/format-code.sh"
+          }
+        ]
+      }
+    ]
+  }
 }
 ```
 
-**Available Events**:
-- `PreToolUse`: Triggered before tool use
-- `PostToolUse`: Triggered after tool use
-- `UserPromptSubmit`: Triggered when user submits a prompt
-- `Notification`: Triggered when sending a notification
-- `Stop`: Triggered when attempting to stop
-- `SubagentStop`: Triggered when sub-agent attempts to stop
-- `SessionStart`: Triggered at session start
-- `SessionEnd`: Triggered at session end
-- `PreCompact`: Triggered before conversation history compression
-
-**Hook Types**:
-- `command`: Execute a shell command or script
+**Available events**:
+
+Plugin hooks respond to the same lifecycle events as user-defined hooks:
+
+| Event | Trigger |
+|------|---------|
+| `SessionStart` | Session starts or resumes |
+| `UserPromptSubmit` | User submits a prompt, before AI processing |
+| `PreToolUse` | Before tool execution; can block |
+| `PermissionRequest` | When the permission dialog appears |
+| `PermissionDenied` | When a tool call is denied by the auto-mode classifier. Return `{retry: true}` to tell the model it can retry |
+| `PostToolUse` | After a tool call succeeds |
+| `PostToolUseFailure` | After a tool call fails |
+| `Notification` | When CodeBuddy sends a notification |
+| `SubagentStart` | When a sub-agent starts |
+| `SubagentStop` | When a sub-agent finishes |
+| `TaskCreated` | When a task is created via `TaskCreate` |
+| `TaskCompleted` | When a task is marked completed |
+| `Stop` | When the AI finishes its response |
+| `StopFailure` | When the turn ends due to an API error. Output and exit code are ignored |
+| `TeammateIdle` | When a teammate is about to go idle |
+| `InstructionsLoaded` | When CODEBUDDY.md or `.codebuddy/rules/*.md` files are loaded into context |
+| `ConfigChange` | When a configuration file changes during the session |
+| `CwdChanged` | When the working directory changes (e.g., the AI runs `cd`) |
+| `FileChanged` | When a watched file changes on disk. The `matcher` field specifies the filename to watch |
+| `WorktreeCreate` | When a worktree is created via `--worktree` or `isolation: "worktree"` |
+| `WorktreeRemove` | When a worktree is removed (session exit or sub-agent completion) |
+| `PreCompact` | Before context compaction |
+| `PostCompact` | After context compaction completes |
+| `Elicitation` | When an MCP server requests user input during a tool call |
+| `ElicitationResult` | After the user responds to an MCP elicitation, before the response is sent back to the server |
+| `SessionEnd` | When the session terminates |
+
+**Hook types**:
+
+- `command`: Executes a shell command or script.
+- `http`: Sends the event JSON as a POST request to a URL.
+- `prompt`: Uses an LLM to evaluate a prompt (use the `$ARGUMENTS` placeholder for context).
+- `agent`: Runs an agent validator with tools, for complex validation tasks.
+
+### 4. MCP Servers
+
+Plugins can bundle Model Context Protocol (MCP) servers to connect CodeBuddy with external tools and services.
+
+**Location**: `.mcp.json` under the plugin root, or inline configuration in `plugin.json`.
+
+**Format**: Standard MCP server configuration.
+
+**Configuration example**:
 
-**Matcher Rules**:
-- Supports regex matching for tool names
-- Example: `"Write|Edit"` matches Write or Edit tools
-
-### 5. MCP Servers
-
-**Location**:
-- `.mcp.json` configuration file in the plugin root
-- Or configured via PluginInfo extension fields in `plugin.json`
-
-**Configuration Example** (.mcp.json):
 ```json
 {
   "mcpServers": {
@@ -139,28 +123,30 @@ Skill instruction content
 }
 ```
 
-**Integration Behavior**:
-- MCP servers automatically start when the plugin is enabled
-- Servers appear as standard MCP tools in the toolkit
-- Server functionality seamlessly integrates with existing tools
+**Integration behavior**:
+
+- MCP servers start automatically when the plugin is enabled.
+- Servers appear as standard MCP tools in the toolkit.
+- Server functionality integrates seamlessly with existing tools.
+- Plugin servers can be configured independently of user-level MCP servers.
 
-### 6. LSP Servers
+### 5. LSP Servers
 
-> **Tip**: Need to use an LSP plugin? Install from the official marketplace—search for "lsp" in the `/plugin` Discover tab. This section describes how to create LSP plugins for languages not covered by the official marketplace.
+> **Tip**: Need an LSP plugin? You can install one from the official marketplace — search for "lsp" in the `/plugin` Discover tab. This section covers how to create LSP plugins for languages not provided by the official marketplace.
 
-Plugins can provide [Language Server Protocol](https://microsoft.github.io/language-server-protocol/) (LSP) servers to give the AI assistant real-time code intelligence support when working on codebases.
+Plugins can provide [Language Server Protocol](https://microsoft.github.io/language-server-protocol/) (LSP) servers to give the AI assistant real-time code intelligence while working on a codebase.
 
 LSP integration provides:
 
-* **Instant diagnostics**: AI assistant sees errors and warnings immediately after each edit
-* **Code navigation**: Jump to definition, find references, and hover information
-* **Language awareness**: Type information and documentation for code symbols
+* **Instant diagnostics**: The AI assistant sees errors and warnings immediately after each edit.
+* **Code navigation**: Go to definition, find references, and hover information.
+* **Language awareness**: Type information and documentation for code symbols.
 
-**Location**: `.lsp.json` file in the plugin root, or inline configuration in `plugin.json`
+**Location**: An `.lsp.json` file under the plugin root, or inline configuration in `plugin.json`.
 
-**Format**: JSON configuration mapping language server names to their configurations
+**Format**: JSON configuration mapping language server names to their configurations.
 
-**`.lsp.json` File Format**:
+**`.lsp.json` file format**:
 
 ```json
 {
@@ -174,7 +160,7 @@ LSP integration provides:
 }
 ```
 
-**Inline Configuration in `plugin.json`**:
+**Inline configuration in `plugin.json`**:
 
 ```json
 {
@@ -191,14 +177,14 @@ LSP integration provides:
 }
 ```
 
-**Required Fields**:
+**Required fields**:
 
 | Field | Description |
 | :--- | :--- |
-| `command` | The LSP binary to execute (must be in PATH) |
+| `command` | LSP binary to execute (must be on PATH) |
 | `extensionToLanguage` | Maps file extensions to language identifiers |
 
-**Optional Fields**:
+**Optional fields**:
 
 | Field | Description |
 | :--- | :--- |
@@ -208,17 +194,16 @@ LSP integration provides:
 | `initializationOptions` | Options passed to the server during initialization |
 | `settings` | Settings passed via `workspace/didChangeConfiguration` |
 | `workspaceFolder` | Workspace folder path for the server |
-| `startupTimeout` | Maximum time to wait for server startup (milliseconds) |
-| `shutdownTimeout` | Maximum time to wait for graceful shutdown (milliseconds) |
-| `restartOnCrash` | Whether to automatically restart when the server crashes |
+| `startupTimeout` | Maximum time (ms) to wait for server startup |
+| `shutdownTimeout` | Maximum time (ms) to wait for graceful shutdown |
+| `restartOnCrash` | Whether to automatically restart after a crash |
 | `maxRestarts` | Maximum restart attempts before giving up |
-| `loggingConfig` | Debug logging configuration (see below) |
 
-> **Warning**: **You must install the language server binary separately.** LSP plugins configure how CodeBuddy connects to a language server but do not include the server itself. If you see `Executable not found in $PATH` errors in the `/plugin` Errors tab, install the required binary for your language.
+> **Warning**: **You must install the language server binary separately.** LSP plugins configure how CodeBuddy connects to a language server but do not include the server itself. If you see an `Executable not found in $PATH` error in the `/plugin` Errors tab, install the binary for your language.
 
-**Available LSP Plugins**:
+**Available LSP plugins**:
 
-| Plugin | Language Server | Installation Command |
+| Plugin | Language Server | Install Command |
 | :--- | :--- | :--- |
 | `pyright-lsp` | Pyright (Python) | `pip install pyright` or `npm install -g pyright` |
 | `typescript-lsp` | TypeScript Language Server | `npm install -g typescript-language-server typescript` |
@@ -228,7 +213,26 @@ Install the language server first, then install the plugin from the marketplace.
 
 ---
 
-## II. Plugin Manifest Schema (plugin.json)
+## II. Plugin Installation Scopes
+
+When installing a plugin, choose a **scope** that determines where the plugin is available:
+
+| Scope | Settings file | Use case |
+| :--- | :--- | :--- |
+| `user` | `~/.codebuddy/settings.json` | Personal plugin, available in all projects (default) |
+| `project` | `.codebuddy/settings.json` | Team plugin, shared via version control |
+| `local` | `.codebuddy/settings.local.json` | Project-specific plugin, gitignored |
+| `managed` | Managed settings | Managed plugins (read-only; updates only) |
+
+Plugins use the same scoping system as other CodeBuddy configuration. See [Settings](settings.md) for details.
+
+---
+
+## III. Plugin Manifest Schema (plugin.json)
+
+The `.codebuddy-plugin/plugin.json` file (or `.workbuddy-plugin/plugin.json`, `.claude-plugin/plugin.json`) defines plugin metadata and configuration. This section documents all supported fields and options.
+
+The manifest is optional. If omitted, CodeBuddy auto-discovers components in the [default locations](#file-location-reference) and derives the plugin name from the directory name. Use a manifest when you need to provide metadata or customize component paths.
 
 ### Complete Schema Example
 
@@ -238,7 +242,7 @@ Install the language server first, then install the plugin from the marketplace.
   "version": "1.2.0",
   "description": "Brief plugin description",
   "author": {
-    "name": "Author Name",
+    "name": "Author name",
     "email": "[email protected]",
     "url": "https://github.com/author"
   },
@@ -246,107 +250,130 @@ Install the language server first, then install the plugin from the marketplace.
   "repository": "https://github.com/author/plugin",
   "license": "MIT",
   "keywords": ["keyword1", "keyword2"],
-  "category": "Development Tools",
-  "features": ["Feature 1", "Feature 2"],
-  "requirements": {
-    "node": ">=16.0.0"
-  },
   "commands": ["./custom/commands/special.md"],
   "agents": "./custom/agents/",
+  "skills": "./custom/skills/",
   "hooks": "./config/hooks.json",
-  "mcpServers": [
-    {
-      "name": "custom-server",
-      "command": "node",
-      "args": ["./servers/custom.js"],
-      "env": {
-        "SERVER_PORT": "3000"
-      }
-    }
-  ],
+  "mcpServers": "./mcp-config.json",
+  "outputStyles": "./styles/",
   "lspServers": "./.lsp.json"
 }
 ```
 
 ### Required Fields
 
+If a manifest is included, `name` is the only required field.
+
 | Field | Type | Description | Example |
 |------|------|------|------|
-| name | string | Unique identifier (kebab-case, no spaces) | "deployment-tools" |
-| description | string | Brief plugin purpose | "Deployment automation tools" |
+| `name` | string | Unique identifier (kebab-case, no spaces) | `"deployment-tools"` |
+
+This name is used for component namespacing. For example, in the UI, the agent `agent-creator` from plugin `plugin-dev` will appear as `plugin-dev:agent-creator`.
 
 ### Metadata Fields
 
 | Field | Type | Description | Example |
 |------|------|------|------|
-| version | string | Semantic version | "2.1.0" |
-| author | object | Author information | `{"name": "Dev Team", "email": "[email protected]"}` |
-| homepage | string | Documentation URL | "https://docs.example.com" |
-| repository | string | Source code URL | "https://github.com/user/plugin" |
-| license | string | License identifier | "MIT", "Apache-2.0" |
-| keywords | array | Discovery tags | `["deployment", "ci-cd"]` |
-| category | string | Plugin category | "Development Tools" |
-| features | array | Feature list | `["Auto-deployment", "Log analysis"]` |
+| `version` | string | Semantic version. If set in both the marketplace entry and `plugin.json`, `plugin.json` wins. Set in only one place. | `"2.1.0"` |
+| `description` | string | Short description of the plugin's purpose | `"Deployment automation tools"` |
+| `author` | object | Author information | `{"name": "Dev Team", "email": "[email protected]"}` |
+| `homepage` | string | Documentation URL | `"https://docs.example.com"` |
+| `repository` | string | Source code URL | `"https://github.com/user/plugin"` |
+| `license` | string | License identifier | `"MIT"`, `"Apache-2.0"` |
+| `keywords` | array | Discovery tags | `["deployment", "ci-cd"]` |
 
-### Component Path Fields (PluginManifest)
+### Component Path Fields
 
 | Field | Type | Description | Example |
 |------|------|------|------|
-| commands | string / string[] | Additional command file path array | `["./custom/cmd.md"]` |
-| agents | string / string[] | Additional agent file directory path | "./custom/agents/" |
-| hooks | string / object | Additional hook file or configuration | "./custom/hooks.json" |
-| mcpServers | string / `Record<string,MCPServerConfig>` | MCP server config file path or config object | See MCPServerConfig below |
-| lspServers | string / object | [Language Server Protocol](https://microsoft.github.io/language-server-protocol/) configuration for code intelligence (jump to definition, find references, etc.) | `"./.lsp.json"` |
+| `commands` | string \| array | Custom command file/directory (replaces default `commands/`) | `"./custom/cmd.md"` or `["./cmd1.md"]` |
+| `agents` | string \| array | Custom agent files (replaces default `agents/`) | `"./custom/agents/reviewer.md"` |
+| `skills` | string \| array | Custom skill directories (replaces default `skills/`) | `"./custom/skills/"` |
+| `hooks` | string \| array \| object | Hook configuration path or inline configuration | `"./my-extra-hooks.json"` |
+| `mcpServers` | string \| array \| object | MCP configuration path or inline configuration | `"./my-extra-mcp-config.json"` |
+| `outputStyles` | string \| array | Custom output style files/directories (replaces default `output-styles/`) | `"./styles/"` |
+| `lspServers` | string \| array \| object | LSP configuration path or inline configuration | `"./.lsp.json"` |
+| `userConfig` | object | Values CodeBuddy prompts the user to provide when enabling the plugin. See [User Configuration](#user-configuration) | See below |
+| `channels` | array | Channel declarations for message injection. See [Channels](#channels) | See below |
 
-### MCPServerConfig Structure
+### User Configuration
 
-```typescript
+The `userConfig` field declares values that CodeBuddy prompts the user to provide when the plugin is enabled. Use this instead of asking users to edit `settings.json` manually.
+
+```json
 {
-  "name": "Server name",
-  "command": "Execution command",
-  "args": ["Array of command arguments"],
-  "env": {
-    "ENVIRONMENT_VARIABLE": "value"
+  "userConfig": {
+    "api_endpoint": {
+      "description": "Your team's API endpoint",
+      "sensitive": false
+    },
+    "api_token": {
+      "description": "API authentication token",
+      "sensitive": true
+    }
   }
 }
 ```
 
-### Runtime Extension Fields (PluginInfo)
+Keys must be valid identifiers. Each value can be substituted as `${user_config.KEY}` in MCP and LSP server configs and hook commands, and (for non-sensitive values only) inside skill and agent content. Values are also exported as `CODEBUDDY_PLUGIN_OPTION_<KEY>` environment variables to plugin child processes.
 
-Plugins extend the following fields at runtime, supporting more flexible configuration:
+Non-sensitive values are stored in `pluginConfigs[<plugin-id>].options` in `settings.json`. Sensitive values are stored in the system keychain (or in `~/.codebuddy/.credentials.json` if the keychain is unavailable). Keychain storage is shared with OAuth tokens and has a total limit of around 2 KB, so sensitive values should be kept small.
 
-| Field | Type | Description | Example |
-|------|------|------|------|
-| agents | string[] | Agent file or directory paths | `["./custom/agents/"]` |
-| commands | string[] | Command file or directory paths | `["./custom/commands/"]` |
-| skills | string[] | Skill file or directory paths | `["./custom/skills/"]` |
-| hooks | `Record<string, any>` \| string | Hook configuration object or file path | "./hooks/custom.json" |
-| mcpServers | `Record<string, McpConfig>` \| string | MCP configuration object or file path | "./mcp-config.json" |
-| lspServers | `Record<string, LspConfig>` \| string | LSP configuration object or file path | "./.lsp.json" |
-
-**Note**:
-- These extension fields are used in marketplace.json to configure how plugins are loaded
-- Support for direct configuration objects or file path strings
-- The loader intelligently merges configured paths with default directory scanning results
+### Channels
+
+The `channels` field lets a plugin declare one or more message channels used to inject content into the conversation. Each channel binds to an MCP server provided by the plugin.
+
+```json
+{
+  "channels": [
+    {
+      "server": "telegram",
+      "userConfig": {
+        "bot_token": { "description": "Telegram bot token", "sensitive": true },
+        "owner_id": { "description": "Your Telegram user ID", "sensitive": false }
+      }
+    }
+  ]
+}
+```
+
+The `server` field is required and must match a key in the plugin's `mcpServers`. The optional per-channel `userConfig` uses the same schema as the top-level one, letting you prompt for a bot token or owner ID when the plugin is enabled.
 
 ### Path Behavior Rules
 
-**Important**: Custom paths are **supplementary** to default directories, not replacements.
+For `commands`, `agents`, `skills`, and `outputStyles`, a custom path **replaces** the default directory. If the manifest specifies `commands`, the default `commands/` directory is not scanned. Hooks, MCP servers, and LSP servers have different semantics for handling multiple sources.
+
+- All paths must be relative to the plugin root and start with `./`.
+- Components under custom paths follow the same naming and namespacing rules.
+- Multiple paths can be specified as an array.
+- To keep the default directory and add more paths, include the default in the array: `"commands": ["./commands/", "./extras/deploy.md"]`.
 
-- If the `commands/` directory exists, it will be loaded along with custom command paths
-- All paths must be relative to the plugin root and begin with `./`
-- Multiple paths can be specified as arrays for flexibility
-- Paths can point to individual files or directories
+**Path examples**:
 
-**Path Resolution Rules**:
-- File paths: Must end with `.md` (for commands/agents) or be `SKILL.md` (for skills)
-- Directory paths: Recursively scans the directory for all qualifying files
+```json
+{
+  "commands": [
+    "./specialized/deploy.md",
+    "./utilities/batch-process.md"
+  ],
+  "agents": [
+    "./custom-agents/reviewer.md",
+    "./custom-agents/tester.md"
+  ]
+}
+```
 
 ### Environment Variables
 
-**`${CODEBUDDY_PLUGIN_ROOT}`**: Contains the absolute path to the plugin directory. Use this variable in hooks, MCP servers, and scripts to ensure correct paths regardless of installation location.
+CodeBuddy provides two variables for referencing plugin paths. Both are substituted inline anywhere in skill content, agent content, hook commands, and MCP or LSP server configuration. Both are also exported as environment variables to hook processes and MCP/LSP server child processes.
+
+**`${CODEBUDDY_PLUGIN_ROOT}`**: Absolute path to the plugin installation directory. Use it to reference scripts, binaries, and configuration files bundled with the plugin. This path changes when the plugin is updated, so files written here do not persist across updates.
+
+**Compatibility**: The `${CLAUDE_PLUGIN_ROOT}` variable name is also supported for compatibility with Claude Code plugins.
 
-**Compatibility**: Also supports the `${CLAUDE_PLUGIN_ROOT}` variable name for compatibility with Claude Code plugins.
+**`${CODEBUDDY_PLUGIN_DATA}`**: A persistent directory for plugin state that survives updates. Use it for installed dependencies (such as `node_modules` or Python virtual environments), generated code, caches, and any files that need to persist across plugin versions. The directory is created automatically on first reference.
+
+**Compatibility**: The `${CLAUDE_PLUGIN_DATA}` variable name is also supported.
 
 ```json
 {
@@ -365,355 +392,414 @@ Plugins extend the following fields at runtime, supporting more flexible configu
 }
 ```
 
+#### Persistent Data Directory
+
+The `${CODEBUDDY_PLUGIN_DATA}` directory resolves to `~/.codebuddy/plugins/data/{id}/`, where `{id}` is the plugin identifier with characters outside `a-z`, `A-Z`, `0-9`, `_`, and `-` replaced by `-`. For example, a plugin installed as `formatter@my-marketplace` uses the directory `~/.codebuddy/plugins/data/formatter-my-marketplace/`.
+
+A common use is to install language dependencies once and reuse them across sessions and plugin updates. Because the data directory's lifetime outlasts any single plugin version, simply checking for directory existence does not detect when an update has changed the plugin's dependency manifest. The recommended pattern is to compare the bundled manifest with a copy in the data directory and reinstall when they differ.
+
+The following `SessionStart` hook installs `node_modules` on first run, and reinstalls them whenever a plugin update includes a changed `package.json`:
+
+```json
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "diff -q \"${CODEBUDDY_PLUGIN_ROOT}/package.json\" \"${CODEBUDDY_PLUGIN_DATA}/package.json\" >/dev/null 2>&1 || (cd \"${CODEBUDDY_PLUGIN_DATA}\" && cp \"${CODEBUDDY_PLUGIN_ROOT}/package.json\" . && npm install) || rm -f \"${CODEBUDDY_PLUGIN_DATA}/package.json\""
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+`diff` exits non-zero whenever the stored copy is missing or differs from the bundled copy, covering both the first run and dependency-changing updates. If `npm install` fails, the trailing `rm` removes the copied manifest so the next session retries.
+
+Scripts bundled under `${CODEBUDDY_PLUGIN_ROOT}` can run against the persisted `node_modules`:
+
+```json
+{
+  "mcpServers": {
+    "routines": {
+      "command": "node",
+      "args": ["${CODEBUDDY_PLUGIN_ROOT}/server.js"],
+      "env": {
+        "NODE_PATH": "${CODEBUDDY_PLUGIN_DATA}/node_modules"
+      }
+    }
+  }
+}
+```
+
+When a plugin is uninstalled (from its last installation scope), the data directory is deleted automatically. The `/plugin` UI shows the directory size and prompts before deletion. The CLI deletes it by default; pass `--keep-data` to retain it.
+
+---
+
+## IV. Plugin Cache and File Resolution
+
+Plugins can be specified in two ways:
+
+- Via `codebuddy --plugin-dir`, valid for the current session only.
+- Via marketplace installation, valid for future sessions.
+
+For security and validation, CodeBuddy copies **marketplace** plugins to the user's local **plugin cache** (`~/.codebuddy/plugins/cache`) rather than using them in place. Understanding this behavior is important when developing plugins that reference external files.
+
+### Path Traversal Restrictions
+
+Installed plugins cannot reference files outside their own directory. Paths that traverse outside the plugin root (like `../shared-utils`) do not work after installation because those external files are not copied into the cache.
+
+### Using External Dependencies
+
+If a plugin needs access to files outside its directory, you can create symlinks inside the plugin directory that point to external files. Symlinks are preserved during the copy:
+
+```bash
+# Inside the plugin directory
+ln -s /path/to/shared-utils ./shared-utils
+```
+
+The contents of the symlink are copied into the plugin cache. This provides flexibility while preserving the security benefits of the cache system.
+
 ---
 
-## III. Plugin Directory Structure
+## V. Plugin Directory Structure
 
 ### Standard Plugin Layout
 
+A complete plugin follows this structure:
+
 ```
 enterprise-plugin/
-├── .codebuddy-plugin/       # Metadata directory
-│   └── plugin.json          # Required: Plugin manifest
-├── commands/                # Default commands location
+├── .codebuddy-plugin/        # Metadata directory (optional)
+│   └── plugin.json             # Plugin manifest
+├── commands/                 # Default commands location
 │   ├── status.md
 │   └── logs.md
-├── agents/                  # Default agents location
+├── agents/                   # Default agents location
 │   ├── security-reviewer.md
 │   ├── performance-tester.md
 │   └── compliance-checker.md
-├── skills/                  # Agent skills
+├── skills/                   # Agent skills
 │   ├── code-reviewer/
 │   │   └── SKILL.md
 │   └── pdf-processor/
 │       ├── SKILL.md
 │       └── scripts/
-├── hooks/                   # Hook configuration
-│   └── hooks.json           # Hook configuration file
-├── .mcp.json               # MCP server definitions
-├── .lsp.json               # LSP server configuration
-├── scripts/                # Hooks and utility scripts
+├── output-styles/            # Output style definitions
+│   └── terse.md
+├── hooks/                    # Hook configuration
+│   ├── hooks.json            # Primary hook configuration
+│   └── security-hooks.json   # Additional hooks
+├── bin/                      # Plugin executables, added to PATH
+│   └── my-tool               # Callable as a bare command in the Bash tool
+├── settings.json             # Plugin default settings
+├── .mcp.json                 # MCP server definitions
+├── .lsp.json                 # LSP server configuration
+├── scripts/                  # Hook and utility scripts
 │   ├── security-scan.sh
 │   ├── format-code.py
 │   └── deploy.js
-├── LICENSE                 # License file
-└── README.md               # Plugin documentation
+├── LICENSE                   # License file
+└── CHANGELOG.md              # Version history
 ```
 
-**Important**:
-- The `.codebuddy-plugin/` or `.claude-plugin/` directory contains the `plugin.json` file
-- All other directories (`commands/`, `agents/`, `skills/`, `hooks/`) must be located in the plugin root
-- The system prioritizes `.codebuddy-plugin/` while also supporting `.claude-plugin/` for compatibility
+> **Important**: The `.codebuddy-plugin/` directory contains the `plugin.json` file. All other directories (`commands/`, `agents/`, `skills/`, `output-styles/`, `hooks/`) must live at the plugin root, not inside `.codebuddy-plugin/`. The `.workbuddy-plugin/` and `.claude-plugin/` directories are also supported for compatibility.
 
 ### File Location Reference
 
-| Component | Default Location | Purpose |
+| Component | Default location | Purpose |
 |------|----------|------|
-| Manifest | .codebuddy-plugin/plugin.json | Required metadata file |
-| Commands | commands/ | Slash command markdown files |
-| Agents | agents/ | Sub-agent markdown files |
-| Skills | skills/ | Agent skills with SKILL.md files |
-| Hooks | hooks/hooks.json | Hook configuration |
-| MCP servers | .mcp.json | MCP server definitions |
-| LSP servers | .lsp.json | Language server configuration |
+| **Manifest** | `.codebuddy-plugin/plugin.json` | Plugin metadata and configuration (optional) |
+| **Commands** | `commands/` | Skill Markdown files (legacy; new skills use `skills/`) |
+| **Agents** | `agents/` | Sub-agent Markdown files |
+| **Skills** | `skills/` | Skills following the `<name>/SKILL.md` structure |
+| **Output styles** | `output-styles/` | Output style definitions |
+| **Hooks** | `hooks/hooks.json` | Hook configuration |
+| **MCP servers** | `.mcp.json` | MCP server definitions |
+| **LSP servers** | `.lsp.json` | Language server configuration |
+| **Executables** | `bin/` | Executables added to the Bash tool PATH. When the plugin is enabled, files in this directory can be invoked as bare commands in any Bash tool call |
+| **Settings** | `settings.json` | Default configuration applied when the plugin is enabled. Currently only [agent](sub-agents.md) settings are supported |
 
 ---
 
-## IV. Marketplace Manifest Schema (marketplace.json)
+## VI. CLI Command Reference
 
-### Complete Schema Example
+CodeBuddy provides CLI commands for non-interactive plugin management, suitable for scripting and automation.
 
-```json
-{
-  "name": "Enterprise Plugin Marketplace",
-  "description": "Internal enterprise plugin collection",
-  "version": "1.0.0",
-  "owner": {
-    "name": "Enterprise Development Team",
-    "email": "[email protected]"
-  },
-  "plugins": [
-    {
-      "name": "deployment-tool",
-      "description": "Automated deployment tools",
-      "version": "1.0.0",
-      "source": "plugins/deployment-tool"
-    },
-    {
-      "name": "code-review-bot",
-      "description": "Code review bot",
-      "version": "2.1.0",
-      "source": {
-        "source": "github",
-        "repo": "company/code-review-bot"
-      }
-    },
-    {
-      "name": "security-scanner",
-      "description": "Security scanning tool",
-      "version": "1.5.0",
-      "source": {
-        "source": "url",
-        "url": "https://github.com/company/security-scanner.git"
-      }
-    }
-  ]
-}
-```
+### plugin install
 
-### Required Fields
+Install a plugin from an available marketplace.
 
-| Field | Type | Description | Example |
-|------|------|------|------|
-| name | string | Marketplace name | "Enterprise Plugin Marketplace" |
-| plugins | array | Plugin list | See below |
+```bash
+codebuddy plugin install <plugin> [options]
+```
 
-### Metadata Fields
+**Arguments**:
 
-| Field | Type | Description | Example |
-|------|------|------|------|
-| description | string | Marketplace description | "Internal enterprise plugin collection" |
-| version | string | Marketplace version | "1.0.0" |
-| owner | object | Owner information | `{"name": "Team", "email": "..."}` |
+- `<plugin>`: Plugin name, or `plugin-name@marketplace-name` to specify a particular marketplace.
 
-### Plugin Entry (MarketplacePluginEntry)
+**Options**:
 
-Each plugin entry contains the following fields:
+| Option | Description | Default |
+|------|------|------|
+| `-s, --scope <scope>` | Install scope: `user`, `project`, or `local` | `user` |
+| `-h, --help` | Show command help | |
 
-| Field | Type | Required | Description |
-|------|------|------|------|
-| name | string | ✓ | Plugin unique identifier |
-| description | string | ✓ | Plugin description |
-| version | string | | Plugin version number |
-| source | string \| PluginSource | ✓ | Plugin source configuration |
-| strict | boolean | | Strict mode (compatible with superpowers-marketplace) |
+The scope determines which settings file the installed plugin is added to. For example, `--scope project` writes to `enabledPlugins` in `.codebuddy/settings.json`, making the plugin available to everyone who clones the project repository.
 
-### PluginSource Configuration
+**Examples**:
 
-Plugin sources support three types:
+```bash
+# Install at user scope (default)
+codebuddy plugin install formatter@my-marketplace
 
-#### 1. Local Relative Path (string)
-```json
-{
-  "source": "plugins/my-plugin"
-}
-```
+# Install at project scope (shared with team)
+codebuddy plugin install formatter@my-marketplace --scope project
 
-#### 2. Local Path (object)
-```json
-{
-  "source": {
-    "source": "local",
-    "path": "plugins/my-plugin"
-  }
-}
+# Install at local scope (gitignored)
+codebuddy plugin install formatter@my-marketplace --scope local
 ```
 
-#### 3. GitHub Repository
-```json
-{
-  "source": {
-    "source": "github",
-    "repo": "owner/repo-name"
-  }
-}
+### plugin uninstall
+
+Remove an installed plugin.
+
+```bash
+codebuddy plugin uninstall <plugin> [options]
 ```
 
-#### 4. Git URL
-```json
-{
-  "source": {
-    "source": "url",
-    "url": "https://github.com/owner/repo.git"
-  }
-}
+**Arguments**:
+
+- `<plugin>`: Plugin name, or `plugin-name@marketplace-name`.
+
+**Options**:
+
+| Option | Description | Default |
+|------|------|------|
+| `-s, --scope <scope>` | Uninstall from scope: `user`, `project`, or `local` | `user` |
+| `--keep-data` | Preserve the plugin's [persistent data directory](#persistent-data-directory) | |
+| `-h, --help` | Show command help | |
+
+**Aliases**: `remove`, `rm`
+
+By default, uninstalling from the last remaining scope also deletes the plugin's `${CODEBUDDY_PLUGIN_DATA}` directory. Use `--keep-data` to preserve it — for example, when reinstalling after testing a new version.
+
+### plugin enable
+
+Enable a disabled plugin.
+
+```bash
+codebuddy plugin enable <plugin> [options]
 ```
 
-### Marketplace Types
+**Arguments**:
 
-CodeBuddy supports four marketplace types:
+- `<plugin>`: Plugin name, or `plugin-name@marketplace-name`.
 
-| Type | Description | source Field |
-|------|------|-------------|
-| Directory | Local filesystem directory | path: Absolute local directory path |
-| Github | GitHub repository | repo: owner/repo format |
-| Git | Git repository | url: Git repository URL |
-| URL | HTTP/HTTPS remote | url: URL to marketplace.json |
+**Options**:
 
----
+| Option | Description | Default |
+|------|------|------|
+| `-s, --scope <scope>` | Enable scope: `user`, `project`, or `local` | `user` |
+| `-h, --help` | Show command help | |
 
-## V. Plugin Loading Mechanism
+### plugin disable
 
-### Loading Flow
+Disable a plugin without uninstalling it.
 
-1. **Marketplace Installation**:
-   - Install marketplace from configured source
-   - Read `marketplace.json` to get plugin list
+```bash
+codebuddy plugin disable <plugin> [options]
+```
 
-2. **Plugin Installation**:
-   - Select appropriate installer (Local/Git) based on `source` configuration
-   - Install plugin content to target location
+**Arguments**:
 
-3. **Plugin Activation**:
-   - Read the plugin's `plugin.json` manifest
-   - Load components based on manifest configuration
+- `<plugin>`: Plugin name, or `plugin-name@marketplace-name`.
 
-4. **Component Loading**:
-   - Concurrently load all types of extension components
-   - Merge configured paths with default directory scanning results
-   - Cache loaded components for performance
+**Options**:
 
-### Loader Intelligent Merging
+| Option | Description | Default |
+|------|------|------|
+| `-s, --scope <scope>` | Disable scope: `user`, `project`, or `local` | `user` |
+| `-h, --help` | Show command help | |
 
-Each extension loader intelligently merges content from two sources:
+### plugin update
 
-1. **Configured Paths**: Paths specified in `plugin.json` or runtime configuration
-2. **Default Scanning**: Files in default directories (e.g., `commands/`, `agents/`)
+Update a plugin to the latest version.
 
-**Example**:
-```json
-{
-  "commands": ["./custom/deploy.md"],
-  // Actually loads:
-  // - ./custom/deploy.md (configured path)
-  // - All .md files in commands/ directory (default scanning)
-}
+```bash
+codebuddy plugin update <plugin> [options]
 ```
 
-### Command Name Generation Rules
+**Arguments**:
 
-- Filename: `command.md` → command name: `command`
-- Subdirectory: `deploy/prod.md` → command name: `deploy:prod`
-- Plugin prefix: Automatically adds plugin name as prefix, e.g., `plugin-name:command`
+- `<plugin>`: Plugin name, or `plugin-name@marketplace-name`.
 
-### Agent and Skill Tags
+**Options**:
 
-All agents and skills loaded from plugins automatically receive the following tags:
-- Source tag: `(plugin-name@marketplace-name)`
-- Type tag: `plugin`
-- Custom tags: `custom-agent` or `custom-command`
+| Option | Description | Default |
+|------|------|------|
+| `-s, --scope <scope>` | Update scope: `user`, `project`, `local`, or `managed` | `user` |
+| `-h, --help` | Show command help | |
 
----
+### Marketplace Management
+
+```bash
+# Add a marketplace
+codebuddy plugin marketplace add <source> [--name <name>]
+
+# List marketplaces
+codebuddy plugin marketplace list
 
-## VI. Debugging and Development Tools
+# Update a marketplace
+codebuddy plugin marketplace update <name>
 
-### View Plugin Loading Logs
+# Remove a marketplace
+codebuddy plugin marketplace remove <name>
+```
 
-Use the `--verbose` parameter to view detailed plugin loading information:
+**Marketplace source formats**:
 
 ```bash
-codebuddy --verbose
+# Local directory
+codebuddy plugin marketplace add /path/to/marketplace
+
+# GitHub shorthand
+codebuddy plugin marketplace add owner/repo
+
+# Git URL
+codebuddy plugin marketplace add https://github.com/owner/repo.git
+
+# HTTP URL (marketplace.json)
+codebuddy plugin marketplace add https://example.com/marketplace.json
 ```
 
-**Display Content**:
-- Which plugins are being loaded
-- Any errors in plugin manifests
-- Command, agent, and skill registration
-- MCP server initialization
-- Hook configuration loading
+---
+
+## VII. Debugging and Development Tools
+
+### Debug Commands
+
+Use `codebuddy --debug` to see plugin loading details:
+
+**What it shows**:
+
+- Which plugins are being loaded.
+- Any errors in plugin manifests.
+- Command, agent, and hook registration.
+- MCP server initialization.
 
 ### Common Troubleshooting
 
 | Issue | Cause | Solution |
 |------|------|----------|
-| Plugin not loaded | Invalid plugin.json | Validate JSON syntax, check required fields |
-| Command not appearing | Incorrect directory structure | Ensure commands/ is in plugin root |
-| Hook not triggering | Script not executable | Run `chmod +x script.sh` |
-| MCP server fails | Missing environment variables | Use `${CODEBUDDY_PLUGIN_ROOT}` |
+| Plugin not loaded | Invalid `plugin.json` | Run `codebuddy plugin validate` or `/plugin validate` to check `plugin.json`, skill/agent/command frontmatter, and `hooks/hooks.json` for syntax and schema errors |
+| Command not appearing | Wrong directory structure | Ensure `commands/` is at the plugin root, not inside `.codebuddy-plugin/` |
+| Hook not firing | Script not executable | Run `chmod +x script.sh` |
+| MCP server fails | Missing `${CODEBUDDY_PLUGIN_ROOT}` | Use this variable for all plugin paths |
 | Path errors | Using absolute paths | All paths must be relative and start with `./` |
-| Metadata directory not recognized | Using incorrect directory name | Use `.codebuddy-plugin/` or `.claude-plugin/` |
 | LSP `Executable not found in $PATH` | Language server not installed | Install the binary (e.g., `npm install -g typescript-language-server typescript`) |
 
-### Plugin Development Best Practices
+### Common Error Messages
 
-1. **Use Relative Paths**: All file references use relative paths to ensure cross-environment compatibility
-2. **Environment Variables**: Use `${CODEBUDDY_PLUGIN_ROOT}` in scripts to reference the plugin directory
-3. **Error Handling**: Add appropriate error handling and timeout settings for hook scripts
-4. **Complete Documentation**: Provide clear installation and usage instructions in README.md
-5. **Semantic Versioning**: Follow semantic versioning conventions to manage plugin versions
-6. **Test Coverage**: Test plugin installation and functionality across different environments
+**Manifest validation errors**:
 
----
+- `Invalid JSON syntax: Unexpected token } in JSON at position 142`: Check for missing commas, trailing commas, or unquoted strings.
+- `Plugin has an invalid manifest file at .codebuddy-plugin/plugin.json. Validation errors: name: Required`: Missing required field.
+- `Plugin has a corrupt manifest file at .codebuddy-plugin/plugin.json. JSON parse error: ...`: JSON syntax error.
 
-## VII. Version Management Reference
+**Plugin loading errors**:
 
-### Semantic Versioning
+- `Warning: No commands found in plugin my-plugin custom directory: ./cmds. Expected .md files or SKILL.md in subdirectories.`: The command path exists but contains no valid command files.
+- `Plugin directory not found at path: ./plugins/my-plugin. Check that the marketplace entry has the correct path.`: The `source` path in `marketplace.json` points to a non-existent directory.
+- `Plugin my-plugin has conflicting manifests: both plugin.json and marketplace entry specify components.`: Remove duplicate component definitions, or remove `strict: false` from the marketplace entry.
 
-Follow semantic versioning for plugin releases:
+### Hook Troubleshooting
 
-- **MAJOR version**: Incompatible API changes
-- **MINOR version**: Backwards-compatible feature additions
-- **PATCH version**: Backwards-compatible bug fixes
+**Hook script not executing**:
 
-Example: `1.2.0` → `1.2.1` (fix) → `1.3.0` (new feature) → `2.0.0` (breaking change)
+1. Verify the script is executable: `chmod +x ./scripts/your-script.sh`.
+2. Check the shebang line: the first line should be `#!/bin/bash` or `#!/usr/bin/env bash`.
+3. Confirm the path uses `${CODEBUDDY_PLUGIN_ROOT}`: `"command": "${CODEBUDDY_PLUGIN_ROOT}/scripts/your-script.sh"`.
+4. Test the script manually: `./scripts/your-script.sh`.
 
-### Plugin Update Process
+**Hook not firing on the expected event**:
 
-1. Modify plugin code and resources
-2. Update the version field in `plugin.json`
-3. Record changes in CHANGELOG.md
-4. Commit to version control system
-5. Users update plugin through marketplace
+1. Verify the event name (case-sensitive): `PostToolUse`, not `postToolUse`.
+2. Check the matcher pattern matches the target tool: `"matcher": "Write|Edit"` for file operations.
+3. Confirm the hook type is valid: `command`, `http`, `prompt`, or `agent`.
 
----
+### MCP Server Troubleshooting
 
-## VIII. CLI Command Reference
+**Server does not start**:
 
-### Marketplace Management
+1. Check that the command exists and is executable.
+2. Verify all paths use the `${CODEBUDDY_PLUGIN_ROOT}` variable.
+3. Check MCP server logs: `codebuddy --debug` shows initialization errors.
+4. Test the server manually outside of CodeBuddy.
 
-```bash
-# Add marketplace
-codebuddy plugin marketplace add <source> [--name <name>]
+**Server tools do not appear**:
 
-# List marketplaces
-codebuddy plugin marketplace list
+1. Ensure the server is correctly configured in `.mcp.json` or `plugin.json`.
+2. Verify that the server correctly implements the MCP protocol.
+3. Check for connection timeouts in the debug output.
 
-# Update marketplace
-codebuddy plugin marketplace update <name>
+### Directory Structure Errors
+
+**Symptom**: The plugin loads but components (commands, agents, hooks) are missing.
+
+**Correct structure**: Components must be at the plugin root, not inside `.codebuddy-plugin/`. Only `plugin.json` belongs in `.codebuddy-plugin/`.
 
-# Remove marketplace
-codebuddy plugin marketplace remove <name>
+```
+my-plugin/
+├── .codebuddy-plugin/
+│   └── plugin.json      <- Only the manifest lives here
+├── commands/             <- At root level
+├── agents/               <- At root level
+└── hooks/                <- At root level
 ```
 
-### Plugin Management
+If components are inside `.codebuddy-plugin/`, move them up to the plugin root.
 
-```bash
-# Install plugin
-codebuddy plugin install <plugin-name> <marketplace-name>
+**Debug checklist**:
 
-# List installed plugins
-codebuddy plugin list [--marketplace <name>]
+1. Run `codebuddy --debug` and look for "loading plugin" messages.
+2. Verify that each component directory is listed in the debug output.
+3. Confirm that file permissions allow reading the plugin files.
 
-# Enable plugin
-codebuddy plugin enable <plugin-name> <marketplace-name>
+---
 
-# Disable plugin
-codebuddy plugin disable <plugin-name> <marketplace-name>
+## VIII. Version Management Reference
 
-# Uninstall plugin
-codebuddy plugin uninstall <plugin-name> <marketplace-name>
+### Semantic Versioning
 
-# Update plugin
-codebuddy plugin update <plugin-name> <marketplace-name>
-```
+Follow semantic versioning for plugin releases:
 
-### Marketplace Source Formats
+```json
+{
+  "name": "my-plugin",
+  "version": "2.1.0"
+}
+```
 
-Supports the following formats for adding marketplaces:
+**Version format**: `MAJOR.MINOR.PATCH`
 
-```bash
-# Local directory
-codebuddy plugin marketplace add /path/to/marketplace
+- **MAJOR**: Incompatible API changes.
+- **MINOR**: Backwards-compatible feature additions.
+- **PATCH**: Backwards-compatible bug fixes.
 
-# GitHub shorthand
-codebuddy plugin marketplace add owner/repo
+**Best practices**:
 
-# Git URL
-codebuddy plugin marketplace add https://github.com/owner/repo.git
+- Start the first stable release at `1.0.0`.
+- Update the version in `plugin.json` before distributing changes.
+- Record changes in a `CHANGELOG.md` file.
+- Use pre-release versions (e.g., `2.0.0-beta.1`) for testing.
 
-# HTTP URL (marketplace.json)
-codebuddy plugin marketplace add https://example.com/marketplace.json
-```
+> **Note**: CodeBuddy uses the version to decide whether a plugin needs updating. If you change plugin code without bumping the version in `plugin.json`, existing users will not see the change due to caching.
+>
+> If the plugin is in a [marketplace](plugin-marketplaces.md) directory, you can manage versions via `marketplace.json` and omit the `version` field from `plugin.json`.
 
 ---
 
@@ -725,50 +811,28 @@ The CodeBuddy plugin system is designed to be compatible with the Claude Code pl
 
 | Concept | Claude Code | CodeBuddy |
 |------|-------------|-----------|
-| Metadata Directory | `.claude-plugin/` | `.codebuddy-plugin/` (priority) or `.claude-plugin/` (compatible) |
-| Environment Variable | `${CLAUDE_PLUGIN_ROOT}` | `${CODEBUDDY_PLUGIN_ROOT}` (priority) or `${CLAUDE_PLUGIN_ROOT}` (compatible) |
-
-### Extended Features
-
-CodeBuddy provides the following extensions over Claude Code:
-
-1. **Runtime Configuration**: PluginInfo supports runtime extension field configuration
-2. **Multiple Metadata Directories**: Supports both `.codebuddy-plugin/` and `.claude-plugin/`
-3. **Flexible Configuration**: Supports both configuration objects and file path configuration methods
+| Metadata directory | `.claude-plugin/` | `.codebuddy-plugin/` (priority), `.workbuddy-plugin/`, or `.claude-plugin/` (compatible) |
+| Environment variable | `${CLAUDE_PLUGIN_ROOT}` | `${CODEBUDDY_PLUGIN_ROOT}` (priority) or `${CLAUDE_PLUGIN_ROOT}` (compatible) |
+| Data directory variable | `${CLAUDE_PLUGIN_DATA}` | `${CODEBUDDY_PLUGIN_DATA}` (priority) or `${CLAUDE_PLUGIN_DATA}` (compatible) |
 
 ### Migration Guide
 
 Migrating from Claude Code to CodeBuddy:
 
-1. Optionally rename `.claude-plugin/` to `.codebuddy-plugin/`
-2. Optionally replace `${CLAUDE_PLUGIN_ROOT}` with `${CODEBUDDY_PLUGIN_ROOT}` in scripts
-3. If using the `mcpServers` field, no changes needed (already uses `mcpServers`)
+1. Optionally rename `.claude-plugin/` to `.codebuddy-plugin/`.
+2. Optionally replace `${CLAUDE_PLUGIN_ROOT}` with `${CODEBUDDY_PLUGIN_ROOT}` in scripts.
+3. Optionally replace `${CLAUDE_PLUGIN_DATA}` with `${CODEBUDDY_PLUGIN_DATA}`.
 
-**Note**: Keeping the original naming is fully compatible; CodeBuddy will automatically recognize it.
+**Note**: Keeping the original names is fully compatible — CodeBuddy recognizes them automatically.
 
 ---
 
 ## Related Resources
 
-- **Plugin Development Tutorial** - How to create custom plugins
-- **Marketplace Creation Guide** - Creating and managing plugin marketplaces
-- **Hooks Deep Dive** - Event handling and automation
-- **MCP Integration Documentation** - External tool integration
-- **Settings Configuration** - Plugin configuration options
-
----
-
-## Summary
-
-This document provides the complete technical specification for the CodeBuddy plugin system, covering:
-
-1. Six plugin component types (Commands, Agents, Skills, Hooks, MCP Servers, LSP Servers)
-2. Complete plugin.json manifest schema and field descriptions
-3. marketplace.json marketplace manifest schema
-4. Standard directory structure and file locations
-5. Plugin loading mechanism and intelligent merging rules
-6. CLI commands and debugging tools
-7. Version management best practices
-8. Compatibility notes with Claude Code
-
-Developers can use this reference document to create fully-featured, well-structured CodeBuddy plugins.
+- [Plugins](plugins.md) – Tutorial and practical guide
+- [Plugin Marketplaces](plugin-marketplaces.md) – Creating and managing marketplaces
+- [Skills](skills.md) – Skill development details
+- [Subagents](sub-agents.md) – Agent configuration and capabilities
+- [Hooks](hooks.md) – Event handling and automation
+- [MCP](mcp.md) – External tool integration
+- [Settings](settings.md) – Plugin configuration options