Skip to content

Agent Zero AI framework

update agents, human docs, plugin skill

Alessandro6f6348850d9f
diff --git a/AGENTS.md b/AGENTS.md
index 529362c2a..f81ad76a6 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -1,113 +1,216 @@
-# Agent Zero — Full-Stack Agent & Plugin Architecture
+# Agent Zero - AGENTS.md
-This document bridges the gap between the **Python Backend** (AgentContext, LLM loop) and the **Frontend Component System** (Alpine.js, Modals). Use this as the canonical reference for building deep integrations.
+[Generated using reconnaissance on 2026-02-22]
+
+## Quick Reference
+Tech Stack: Python 3.12+ | Flask | Alpine.js | LiteLLM | WebSocket (Socket.io)
+Dev Server: python run_ui.py (runs on http://localhost:50001 by default)
+Run Tests: pytest (standard) or pytest tests/test_name.py (file-scoped)
+Documentation: README.md | docs/
+Frontend Deep Dives: [Component System](docs/agents/AGENTS.components.md) | [Modal System](docs/agents/AGENTS.modals.md) | [Plugin Architecture](AGENTS.plugins.md)
---
-## 1. The Core Concept: `AgentContext`
+## Table of Contents
+1. [Project Overview](#project-overview)
+2. [Core Commands](#core-commands)
+3. [Docker Environment](#docker-environment)
+4. [Project Structure](#project-structure)
+5. [Development Patterns & Conventions](#development-patterns--conventions)
+6. [Safety and Permissions](#safety-and-permissions)
+7. [Code Examples](#code-examples)
+8. [Git Workflow](#git-workflow)
+9. [API Documentation](#api-documentation)
+10. [Troubleshooting](#troubleshooting)
+
+---
-Every conversation in Agent Zero is an `AgentContext`. It owns the message history, the LLM state, the tool definitions, and the log queue.
+## Project Overview
-### Backend: Managing Contexts
-When building a plugin, you must interact with the context system correctly:
+Agent Zero is a dynamic, organic agentic framework designed to grow and learn. It uses the operating system as a tool, featuring a multi-agent cooperation model where every agent can create subordinates to break down tasks.
-```python
-from agent import AgentContext, AgentContextType, initialize_agent
-from python.helpers.messages import UserMessage
+Type: Full-Stack Agentic Framework (Python Backend + Alpine.js Frontend)
+Status: Active Development
+Primary Language(s): Python, JavaScript (ES Modules)
-# 1. Access an existing context (e.g., from a stored ID)
-context = AgentContext.use(context_id)
+---
-# 2. Or create a new one
-config = {} # use defaults
-context = AgentContext(config=config, type=AgentContextType.USER)
-await initialize_agent(context)
+## Core Commands
-# 3. Communicate (send a message and wait for completion)
-task = context.communicate(UserMessage("Hello Agent!"))
-response_text = await task.result()
+### Setup
+Do not combine these commands; run them individually:
+```bash
+pip install -r requirements.txt
+pip install -r requirements2.txt
```
+- Start WebUI: python run_ui.py
-### The Glue: `MessageQueue` (mq)
-The frontend listens to a WebSocket. To make messages appear in the WebUI from your plugin, use the log helper:
+---
-```python
-# In your ApiHandler or bridge
-from python.helpers.messages import mq
+## Docker Environment
-# This makes the user message appear in the UI immediately
-mq.log_user_message(context.id, "Incoming message from WhatsApp", source="WhatsApp")
-```
+When running in Docker, Agent Zero uses two distinct Python runtimes to isolate the framework from the code being executed:
----
+### 1. Framework Runtime (/opt/venv-a0)
+- Version: Python 3.12.4
+- Purpose: Runs the Agent Zero backend, API, and core logic.
+- Packages: Contains all dependencies from requirements.txt.
+
+### 2. Execution Runtime (/opt/venv)
+- Version: Python 3.13
+- Purpose: Default environment for the interactive terminal and the agent's code execution tool.
+- Behavior: This is the environment active when you docker exec into the container. Packages installed by the agent via pip install during a task are stored here.
-## 2. The Frontend: Component System
+---
-Agent Zero uses a custom **Component Loader** that fetches HTML, extracts `<style>` and `<script type="module">`, and injects them into the DOM.
+## Project Structure
-### The "Golden Rules" of Frontend Components
+```
+/
+├── agent.py # Core Agent and AgentContext definitions
+├── initialize.py # Framework initialization logic
+├── models.py # LLM provider configurations
+├── run_ui.py # WebUI server entry point
+├── python/
+│ ├── api/ # API Handlers (ApiHandler subclasses)
+│ ├── extensions/ # Backend lifecycle extensions
+│ ├── helpers/ # Shared Python utilities (plugins, files, etc.)
+│ ├── tools/ # Agent tools (Tool subclasses)
+│ └── websocket_handlers/# WebSocket event handlers
+├── webui/
+│ ├── components/ # Alpine.js components
+│ ├── js/ # Core frontend logic (modals, stores, etc.)
+│ └── index.html # Main UI shell
+├── usr/ # User data directory (isolated from core)
+│ ├── plugins/ # Custom user plugins
+│ ├── settings.json # User-specific configuration
+│ └── workdir/ # Default agent workspace
+├── plugins/ # Core system plugins
+├── agents/ # Agent profiles (prompts and config)
+├── prompts/ # System and message prompt templates
+└── tests/ # Pytest suite
+```
-1. **Store Gating (Critical)**: Always wrap your component content in a template that waits for the store. This prevents "undefined" errors during the loading race.
- ```html
- <div x-data>
- <template x-if="$store.myStore">
- <div class="content">...</div>
- </template>
- </div>
- ```
-2. **Separate Store Files**: Never put store registration logic directly inside the HTML `alpine:init` block. Use a separate `*-store.js` file and import it via `<script type="module" src="...">`.
-3. **createStore Proxy**: Use `createStore` from `/js/AlpineStore.js`. It ensures the store is available to the module even before Alpine fully boots.
+Key Files:
+- agent.py: Defines AgentContext and the main Agent class.
+- python/helpers/plugins.py: Plugin discovery and configuration logic.
+- webui/js/AlpineStore.js: Store factory for reactive frontend state.
+- python/helpers/api.py: Base class for all API endpoints.
+- docs/agents/AGENTS.components.md: Deep dive into the frontend component architecture.
+- docs/agents/AGENTS.modals.md: Guide to the stacked modal system.
+- AGENTS.plugins.md: Comprehensive guide to the full-stack plugin system.
---
-## 3. The Modal System
+## Development Patterns & Conventions
+
+### Backend (Python)
+- Context Access: Use from agent import AgentContext, AgentContextType (not python.helpers.context).
+- Communication: Use mq from python.helpers.messages to log proactive UI messages:
+ mq.log_user_message(context.id, "Message", source="Plugin")
+- API Handlers: Derive from ApiHandler in python/helpers/api.py.
+- Extensions: Use the extension framework in python/helpers/extension.py for lifecycle hooks.
+- Error Handling: Use RepairableException for errors the LLM might be able to fix.
+
+### Frontend (Alpine.js)
+- Store Gating: Always wrap store-dependent content in a template:
+```html
+<div x-data>
+ <template x-if="$store.myStore">
+ <div x-init="$store.myStore.onOpen()">...</div>
+ </template>
+</div>
+```
+- Store Registration: Use createStore from /js/AlpineStore.js.
+- Modals: Use openModal(path) and closeModal() from /js/modals.js.
-Modals in A0 are "stacked" and loaded dynamically via `openModal(path)`.
+### Plugin Architecture
+- Location: Always develop new plugins in usr/plugins/.
+- Manifest: Every plugin requires a plugin.json with name, description, version, and optionally settings_sections.
+- Discovery: Conventions based on folder names (api/, tools/, webui/, extensions/).
+- Settings: Use get_plugin_config(plugin_name, agent=agent) to retrieve settings. Plugins can expose a UI for settings via webui/config.html. For plugins wrapping core settings, set $store.pluginSettings.saveMode = 'core' in x-init.
-### Directory Convention
-- `webui/components/modals/<feature>/<feature>.html`
-- `webui/components/modals/<feature>/<feature>-store.js`
+### Lifecycle Synchronization
+| Action | Backend Extension | Frontend Lifecycle |
+|---|---|---|
+| Initialization | agent_init | init() in Store |
+| Mounting | N/A | x-create directive |
+| Processing | monologue_start/end | UI loading state |
+| Cleanup | context_deleted | x-destroy directive |
-### Plugin Settings
+---
-Plugins get a dedicated settings modal with **Project** and **Agent profile** context selectors. To enable it:
+## Safety and Permissions
-1. Add `webui/config.html` to your plugin (auto-detected).
-2. Set `"settings_sections": ["agent"]` in `plugin.json` - this places a subsection with a Settings button in the chosen tab.
+### Allowed Without Asking
+- Read any file in the repository.
+- Update code files in usr/.
-Your `config.html` binds to `$store.pluginSettings.settings` (a plain object persisted as `config.json`). The modal's Save/Cancel footer handles persistence automatically. See `plugins/README.md` for the full contract and settings resolution priority chain.
+### Ask Before Executing
+- pip install (new dependencies).
+- Deleting core files outside of usr/ or tmp/.
+- Modifying agent.py or initialize.py.
+- Making git commits or pushes.
-For plugins that surface **existing core settings** (e.g. wrapping `settings/agent/memory.html`), set `$store.pluginSettings.saveMode = 'core'` in `x-init` to route Save through the core settings API instead.
+### Never Do
+- Commit, hardcode or leak secrets or .env files.
+- Bypass CSRF or authentication checks.
+- Hardcode API keys.
---
-## 4. Lifecycle Synchronization
+## Code Examples
-| Action | Backend Extension | Frontend Lifecycle |
-|---|---|---|
-| **Initialization** | `agent_init` | `init()` in Store |
-| **Mounting** | N/A | `x-create` directive |
-| **Processing** | `monologue_start/end` | UI loading state |
-| **Cleanup** | `context_deleted` | `x-destroy` directive |
+### API Handler (Good)
+```python
+from python.helpers.api import ApiHandler, Request, Response
+
+class MyHandler(ApiHandler):
+ async def process(self, input: dict, request: Request) -> dict | Response:
+ # Business logic here
+ return {"ok": True, "data": "result"}
+```
+
+### Alpine Store (Good)
+```javascript
+import { createStore } from "/js/AlpineStore.js";
+
+export const store = createStore("myStore", {
+ items: [],
+ init() { /* global setup */ },
+ onOpen() { /* mount setup */ },
+ cleanup() { /* unmount cleanup */ }
+});
+```
+
+### Tool Definition (Good)
+```python
+from python.helpers.tool import Tool, ToolResult
+
+class MyTool(Tool):
+ async def execute(self, arg1: str):
+ # Tool logic
+ return ToolResult("Success")
+```
---
-## 5. Directory Mapping (Plugin Layout)
-
-> [!IMPORTANT]
-> **Always create new plugins in `usr/plugins/`.** The root `/plugins/` folder is reserved for core Agent Zero plugins and may be overwritten during framework updates.
-
-```text
-usr/plugins/my-plugin/
-├── plugin.json # Required manifest (name, version, settings_sections)
-├── api/ # ApiHandler (python.helpers.api)
-├── extensions/
-│ ├── python/agent_init/ # Auto-start logic
-│ └── webui/ # sidebar-quick-actions-main-start/
-└── webui/
- ├── config.html # Optional: plugin settings UI
- └── my-modal.html # Full plugin pages + stores
+## Troubleshooting
+
+### Dependency Conflicts
+If pip install fails, try running in a clean virtual environment:
+```bash
+python -m venv .venv
+source .venv/bin/activate
+pip install -r requirements.txt
+pip install -r requirements2.txt
```
-Refer to `docs/agents/AGENTS.components.md` for deep UI technicals and `docs/agents/AGENTS.modals.md` for modal-specific CSS classes (`btn-ok`, `btn-cancel`).
+### WebSocket Connection Failures
+- Check if X-CSRF-Token is being sent.
+- Ensure the runtime ID in the session matches the current server instance.
+
+---
+*Last updated: 2026-02-22*
+*Maintained by: Agent Zero Core Team*
diff --git a/AGENTS.plugins.md b/AGENTS.plugins.md
new file mode 100644
index 000000000..cf3b9fd24
--- /dev/null
+++ b/AGENTS.plugins.md
@@ -0,0 +1,91 @@
+# Agent Zero - Plugins Guide
+
+This guide covers the Python Backend and Frontend WebUI plugin architecture. Use this as the definitive reference for building and extending Agent Zero.
+
+---
+
+## 1. Architecture Overview
+
+Agent Zero uses a convention-over-configuration plugin model where runtime capabilities are discovered from the directory structure.
+
+### Internal Components
+
+1. Backend discovery (python/helpers/plugins.py): Resolves roots (usr/plugins/ first, then plugins/) and builds the effective set of plugins.
+2. Path resolution (python/helpers/subagents.py): Injects plugin paths into the agent's search space for prompts, tools, and configurations.
+3. Python extensions (python/helpers/extension.py): Executes lifecycle hooks from extensions/python/<point>/.
+4. WebUI extensions (webui/js/extensions.js): Injects HTML/JS contributions into core UI breakpoints (x-extension).
+
+---
+
+## 2. File Structure
+
+Each plugin lives in usr/plugins/<plugin_name>/.
+
+```text
+usr/plugins/<plugin_name>/
+├── plugin.json # Required: Name, version, settings config
+├── api/ # API handlers (ApiHandler subclasses)
+├── tools/ # Agent tools (Tool subclasses)
+├── helpers/ # Shared Python logic
+├── prompts/ # Prompt templates
+├── agents/ # Agent profiles
+├── extensions/
+│ ├── python/<point>/ # Backend lifecycle hooks
+│ └── webui/<point>/ # UI HTML/JS contributions
+└── webui/
+ ├── config.html # Optional: Plugin settings UI
+ └── ... # Full plugin pages/components
+```
+
+### plugin.json format
+```json
+{
+ "name": "My Plugin",
+ "description": "What this plugin does.",
+ "version": "1.0.0",
+ "settings_sections": ["agent"]
+}
+```
+settings_sections values: agent, external, mcp, developer, backup.
+
+---
+
+## 3. Frontend Extensions
+
+### HTML Breakpoints
+Core UI defines insertion points like <x-extension id="sidebar-quick-actions-main-start"></x-extension>.
+To contribute:
+1. Place HTML files in extensions/webui/<extension_point>/.
+2. Include a root x-data scope.
+3. Include an x-move-* directive (e.g., x-move-to-start, x-move-after="#id").
+
+### JS Hooks
+Place *.js files in extensions/webui/<extension_point>/ and export a default async function. They are called via callJsExtensions("<point>", context).
+
+---
+
+## 4. Plugin Settings
+
+1. Add webui/config.html to your plugin.
+2. Bind fields to $store.pluginSettings.settings.
+3. Settings are scoped per-project and per-agent automatically.
+
+### Resolution Priority (Highest First)
+1. project/.a0proj/agents/<profile>/plugins/<name>/config.json
+2. project/.a0proj/plugins/<name>/config.json
+3. usr/agents/<profile>/plugins/<name>/config.json
+4. usr/plugins/<name>/config.json
+
+---
+
+## 5. Routes
+
+| Route | Purpose |
+|---|---|
+| GET /plugins/<name>/<path> | Serve static assets |
+| POST /api/plugins/<name>/<handler> | Call plugin API |
+| POST /api/plugins | Management (action: get_config, save_config) |
+
+---
+
+*Refer to AGENTS.md for the main framework guide.*
diff --git a/docs/agents/AGENTS.components.md b/docs/agents/AGENTS.components.md
index 7d7ed73f1..31d564609 100644
--- a/docs/agents/AGENTS.components.md
+++ b/docs/agents/AGENTS.components.md
@@ -7,11 +7,11 @@
| Aspect | Value |
|--------|-------|
-| **Tech Stack** | Alpine.js, ES Modules, CSS Variables |
-| **Component Tag** | `<x-component path="...">` |
-| **State Management** | `createStore(name, model)` from `/js/AlpineStore.js` |
-| **Modals** | `openModal(path)` / `closeModal()` from `/js/modals.js` |
-| **API Layer** | `callJsonApi()` / `fetchApi()` from `/js/api.js` |
+| Tech Stack | Alpine.js, ES Modules, CSS Variables |
+| Component Tag | `<x-component path="...">` |
+| State Management | `createStore(name, model)` from `/js/AlpineStore.js` |
+| Modals | `openModal(path)` / `closeModal()` from `/js/modals.js` |
+| API Layer | `callJsonApi()` / `fetchApi()` from `/js/api.js` |
---
@@ -182,7 +182,7 @@ This enables safe module-level initialization before Alpine loads.
| Module import | `import { store } from "./feature-store.js"; store.prop` |
| Global (avoid) | `Alpine.store("featureStore").prop` |
-**Prefer module imports over global lookups.**
+Prefer module imports over global lookups.
### Persistence Helpers
@@ -262,7 +262,7 @@ const model = {
};
```
-**Key distinction:**
+Key distinction:
- `init()` → once per app load (store registration)
- `onOpen()` → each time component mounts (modal opens, etc.)
- `cleanup()`/`destroy()` → teardown resources
@@ -360,7 +360,7 @@ Parent `x-component` attributes accessible via `globalThis.xAttrs(element)`:
</div>
```
-**Always gate components that depend on stores.** Prevents errors during initial load race.
+Always gate components that depend on stores. Prevents errors during initial load race.
---
@@ -422,7 +422,7 @@ When `x-component` wrapper would break flex layout:
### Common Mistakes
-**Race condition: store not ready**
+Race condition: store not ready
```html
<!-- ❌ BAD: No gate -->
<div x-data>
@@ -437,7 +437,7 @@ When `x-component` wrapper would break flex layout:
</div>
```
-**Duplicate initialization**
+Duplicate initialization
```javascript
// ❌ BAD: Runs every time store accessed
init() {
@@ -452,7 +452,7 @@ init() {
}
```
-**Leaking listeners**
+Leaking listeners
```javascript
// ❌ BAD: No cleanup
init() {
@@ -474,7 +474,7 @@ destroy() {
### Minimum Requirements for External Apps
-1. **Files to copy:**
+1. Files to copy:
```
/js/components.js # Component loader
/js/AlpineStore.js # Store factory
@@ -482,11 +482,11 @@ destroy() {
/js/initFw.js # Alpine bootstrap + directives
```
-2. **Dependencies:**
+2. Dependencies:
- Alpine.js (vendor or CDN)
- CSS variables (define your theme)
-3. **Bootstrap sequence:**
+3. Bootstrap sequence:
```javascript
// initFw.js pattern:
await import("path/to/alpine.min.js");
@@ -497,7 +497,7 @@ destroy() {
// etc.
```
-4. **HTML entry point:**
+4. HTML entry point:
```html
<script type="module" src="/js/initFw.js"></script>
<x-component path="app/root.html"></x-component>
@@ -516,10 +516,10 @@ destroy() {
| Framework | Consideration |
|-----------|--------------|
-| **Vanilla/Static** | Works directly, include initFw.js |
-| **Electron** | Works, may need CSP adjustments for Blob URLs |
-| **React/Vue** | Mount Alpine in specific container, avoid conflicts |
-| **SPA Routers** | MutationObserver handles dynamic inserts |
+| Vanilla/Static | Works directly, include initFw.js |
+| Electron | Works, may need CSP adjustments for Blob URLs |
+| React/Vue | Mount Alpine in specific container, avoid conflicts |
+| SPA Routers | MutationObserver handles dynamic inserts |
---
@@ -551,7 +551,7 @@ webui/components/
└── ...
```
-**Naming conventions:**
+Naming conventions:
- Components: `feature-name.html`
- Stores: `feature-store.js` or `feature-name-store.js`
- Modals: placed in `modals/` or feature folder
diff --git a/docs/agents/AGENTS.modals.md b/docs/agents/AGENTS.modals.md
index 86fd4a5fa..3b75f84bd 100644
--- a/docs/agents/AGENTS.modals.md
+++ b/docs/agents/AGENTS.modals.md
@@ -149,7 +149,7 @@ Use these standard button classes for modal actions:
| `btn btn-ok` | Positive/confirmatory actions (Save, Create, Confirm) | Solid blue background, white text |
| `btn btn-cancel` | Dismissive/negative actions (Cancel, Close, Delete) | Transparent with accent border |
-Footer button order convention: **positive action first** (left), **negative action second** (right).
+Footer button order convention: positive action first (left), negative action second (right).
Example footer markup:
diff --git a/plugins/README.md b/plugins/README.md
index 68772935e..b793a763d 100644
--- a/plugins/README.md
+++ b/plugins/README.md
@@ -1,199 +1,22 @@
-# Agent Zero Plugins
+# Agent Zero - Core Plugins
-This directory contains default plugins. For a full-stack development guide, see [docs/AGENTS.md](../docs/AGENTS.md).
+This directory contains the system-level plugins for Agent Zero.
-> [!TIP]
-> While Agent Zero looks for plugins in both `usr/plugins/` and `plugins/`, you should **always develop new plugins in `usr/plugins/`**. This ensures your work is isolated from core system files and persists through framework updates.
+## Directory Structure
-## Architecture
+- plugins/: Core system plugins (reserved for framework updates).
+- usr/plugins/: Recommended location for user-developed plugins.
-Agent Zero uses a convention-over-configuration plugin model:
+## Documentation
-- Runtime capabilities are discovered from directory structure.
-- Backend owns discovery, routing, and static asset serving.
-- Frontend uses explicit `x-extension` breakpoints plus the standard `x-component` loader.
+For detailed guides on how to create, extend, or configure plugins, please refer to:
-### Internal Components
+- AGENTS.plugins.md: Full-stack plugin architecture, manifest format, and extension points.
+- AGENTS.md: Main framework guide and backend context overview.
-1. **Backend plugin discovery** (`python/helpers/plugins.py`)
- - `get_plugin_roots()` resolves roots in priority order (`usr/plugins` first, then `plugins`).
- - `list_plugins()` builds the effective set (first root wins on ID conflicts).
- - `get_webui_extensions(extension_point, filters)` scans `extensions/webui/<extension_point>/`.
+## Usage
-2. **Path resolution** (`python/helpers/subagents.py`)
- - `get_paths(..., include_plugins=True)` includes plugin candidates for prompts/tools.
-
-3. **Python extension runtime** (`python/helpers/extension.py`)
- - `call_extensions(extension_point, agent, **kwargs)` executes extension classes.
- - Searches `python/extensions/<point>/` and `plugins/*/extensions/python/<point>/`.
- - Extension classes derive from `Extension` and implement `async execute()`.
-
-4. **API and static routes** (`run_ui.py`, `python/api/load_webui_extensions.py`)
- - `GET /plugins/<plugin_id>/<path>` serves plugin static assets.
- - Plugin APIs are mounted under `/api/plugins/<plugin_id>/<handler>`.
- - `POST /api/load_webui_extensions` returns extension files for a given extension point.
-
-5. **Frontend WebUI extension runtime** (`webui/js/extensions.js`)
- - HTML flow: discovers `<x-extension>` tags, calls backend API, injects `<x-component>` tags.
- - JS flow: `callJsExtensions("<extension_point>", contextObject)` loads and executes plugin JS modules.
- - Both HTML and JS lookups are cached per extension point.
-
-## File Structure
-
-```text
-usr/plugins/
- <plugin_name>/
- plugin.json # Required manifest (enables discovery)
- api/ # API handlers (ApiHandler subclasses)
- tools/ # Agent tools (Tool subclasses)
- helpers/ # Shared Python helpers
- prompts/ # Prompt templates
- agents/ # Agent profiles
- extensions/
- python/<extension_point>/ # Python lifecycle extensions
- webui/<extension_point>/ # WebUI HTML/JS hook contributions
- webui/
- config.html # Optional: plugin settings UI
- ... # Full plugin-owned UI pages/components
-```
-
-## Directory Conventions
-
-Each plugin lives in `usr/plugins/<plugin_name>/`.
-
-Capability discovery is based on these paths:
-
-- `plugin.json` - **required** manifest; a directory without it is not recognized as a plugin
-- `api/*.py` - API handlers (`ApiHandler` subclasses), exposed under `/api/plugins/<plugin_name>/<handler>`
-- `tools/*.py` - agent tools (`Tool` subclasses)
-- `helpers/*.py` - shared Python helpers
-- `extensions/python/<extension_point>/*.py` - backend lifecycle extensions
-- `extensions/webui/<extension_point>/*` - WebUI extension assets (HTML/JS)
-- `webui/**` - full plugin-owned UI pages/components (loaded directly by path)
-- `webui/config.html` - if present, a Settings button appears for this plugin in the relevant settings tabs
-- `prompts/**/*.md` - prompt templates
-- `agents/` - agent profiles
-
-### `plugin.json` format
-
-```json
-{
- "name": "My Plugin",
- "description": "What this plugin does.",
- "version": "1.0.0",
- "settings_sections": ["agent"]
-}
-```
-
-`settings_sections` controls which Settings tabs show a subsection for this plugin. Current valid values: `agent`, `external`, `mcp`, `developer`, `backup`. Leave empty (`[]`) for no subsection.
-
-## Frontend Extensions
-
-### HTML insertion via breakpoints
-
-Core UI defines insertion points like:
-
-```html
-<x-extension id="sidebar-quick-actions-main-start"></x-extension>
-```
-
-Resolution flow:
-
-1. `webui/js/extensions.js` finds `x-extension` nodes.
-2. It calls `/api/load_webui_extensions` with the extension point and HTML filters.
-3. Backend returns matching files from `plugins/*/extensions/webui/<extension_point>/`.
-4. `extensions.js` injects returned entries as `<x-component path="...">`.
-5. `components.js` loads each component using the standard component pipeline.
-
-Required baseline for HTML UI extensions in this repository:
-- include a root `x-data` scope
-- include one explicit `x-move-*` placement directive
-
-### JS hook extensions
-
-JS hooks are loaded from the same extension point structure:
-
-`plugins/<plugin_id>/extensions/webui/<extension_point>/*.js`
-
-Runtime code calls:
-
-`callJsExtensions("<extension_point>", contextObject)`
-
-### Fine placement helpers
-
-`initFw.js` provides Alpine move directives for plugin markup:
-
-- `x-move-to-start`
-- `x-move-to-end`
-- `x-move-to`
-- `x-move-before`
-- `x-move-after`
-
-## Plugin Settings
-
-If your plugin needs user-configurable settings:
-
-1. Add `webui/config.html` to your plugin. The system detects this file automatically.
-2. Declare which settings tabs should show a subsection for your plugin via `settings_sections` in `plugin.json`.
-3. The plugin settings modal provides **Project** and **Agent profile** context selectors (same as the Skills list). Settings are scoped per-project and per-agent.
-
-### Config HTML contract
-
-Your `config.html` receives context from `$store.pluginSettings`:
-
-```html
-<html>
-<head>
- <title>My Plugin Config</title>
- <script type="module">
- import { store } from "/components/plugins/plugin-settings-store.js";
- </script>
-</head>
-<body>
- <div x-data>
- <!-- bind fields to $store.pluginSettings.settings -->
- <input x-model="$store.pluginSettings.settings.my_key" />
- </div>
-</body>
-</html>
-```
-
-- `$store.pluginSettings.settings` - plain object loaded from `config.json`, save-scoped to the selected project/agent.
-- The modal's **Save** button calls `POST /plugins` (`action: save_config`) automatically.
-- For plugins that surface **core settings** (like memory), set `saveMode = 'core'` in `x-init` so Save delegates to the core settings API instead.
-
-### Settings resolution priority (highest first)
-
-```
-project/.a0proj/agents/<profile>/plugins/<name>/config.json
-project/.a0proj/plugins/<name>/config.json
-usr/agents/<profile>/plugins/<name>/config.json
-agents/<profile>/plugins/<name>/config.json
-usr/plugins/<name>/config.json
-plugins/<name>/config.json
-```
-
-## Plugin Author Flow
-
-1. Create `usr/plugins/<plugin_name>/`.
-2. Add `plugin.json` manifest (required for discovery).
-3. Add backend capabilities by convention (`api/`, `tools/`, `helpers/`, `extensions/python/`, `prompts/`, `agents/`).
-4. Pick a WebUI breakpoint or JS hook extension point.
-5. For HTML UI entries: place files under `extensions/webui/<extension_point>/`, use root `x-data` + one `x-move-*` directive.
-6. For JS hooks: place `*.js` files under `extensions/webui/<extension_point>/`, export a default async function.
-7. Place full plugin pages/components in `webui/` and open them directly by path.
-8. Optionally add `webui/config.html` and set `settings_sections` in `plugin.json` to expose settings in the UI.
-
-## Routes
-
-- Plugin static assets: `GET /plugins/<plugin_name>/<path>`
-- Plugin APIs: `POST /api/plugins/<plugin_name>/<handler>`
-- WebUI extension discovery: `POST /api/load_webui_extensions`
-- Plugin management (get/save config): `POST /plugins`
-
-## Notes
-
-- User plugins in `usr/plugins/` override repo plugins by plugin ID.
-- Runtime behavior is fully convention-driven from directory structure.
-- Extension point ordering between multiple plugins is currently implicit (filesystem order).
-- When you need a new extension point for your plugin, submit a PR - we are actively expanding coverage based on community needs.
+Plugins are automatically discovered based on the presence of a plugin.json file. Each plugin can contribute:
+- Backend: APIs, Tools, Helpers, and Lifecycle Extensions.
+- Frontend: HTML/JS UI contributions via core breakpoints.
+- Config: Isolated settings scoped per-project and per-agent profile.
diff --git a/skills/a0-create-plugin/SKILL.md b/skills/a0-create-plugin/SKILL.md
index 8a02d5adb..2d7e0df01 100644
--- a/skills/a0-create-plugin/SKILL.md
+++ b/skills/a0-create-plugin/SKILL.md
@@ -6,17 +6,17 @@ description: Create, extend, or modify Agent Zero plugins. Follows strict full-s
# Agent Zero Plugin Development
> [!IMPORTANT]
-> **Always create new plugins in `usr/plugins/<plugin_name>/`.** The root `/plugins` directory is reserved for core system plugins.
+> Always create new plugins in usr/plugins/<plugin_name>/. The root /plugins directory is reserved for core system plugins.
Primary references:
-- `/a0/AGENTS.md` (Full-stack architecture & AgentContext)
-- `/a0/docs/agents/AGENTS.components.md` (Component system deep dive)
-- `/a0/docs/agents/AGENTS.modals.md` (Modal system & CSS conventions)
-- `/a0/plugins/README.md` (Extension points, plugin.json, settings system)
+- /a0/AGENTS.md (Full-stack architecture & AgentContext)
+- /a0/docs/agents/AGENTS.components.md (Component system deep dive)
+- /a0/docs/agents/AGENTS.modals.md (Modal system & CSS conventions)
+- /a0/AGENTS.plugins.md (Extension points, plugin.json, settings system)
-## 📋 Plugin Manifest (`plugin.json`)
+## Plugin Manifest (plugin.json)
-Every plugin **must** have a `plugin.json` or it will not be discovered:
+Every plugin must have a plugin.json or it will not be discovered:
```json
{
@@ -27,12 +27,12 @@ Every plugin **must** have a `plugin.json` or it will not be discovered:
}
```
-`settings_sections` controls which Settings tabs show a subsection for this plugin. Valid values: `agent`, `external`, `mcp`, `developer`, `backup`. Use `[]` for no subsection.
+settings_sections controls which Settings tabs show a subsection for this plugin. Valid values: agent, external, mcp, developer, backup. Use [] for no subsection.
-## 🛠️ Mandatory Frontend Patterns
+## Mandatory Frontend Patterns
### 1. The "Store Gate" Template
-To avoid race conditions and "undefined" errors, every component must use this wrapper:
+To avoid race conditions and undefined errors, every component must use this wrapper:
```html
<div x-data>
<template x-if="$store.myPluginStore">
@@ -44,30 +44,31 @@ To avoid race conditions and "undefined" errors, every component must use this w
```
### 2. Separate Store Module
-Place store logic in a separate `.js` file. Do NOT use `alpine:init` listeners inside HTML.
+Place store logic in a separate .js file. Do NOT use alpine:init listeners inside HTML.
```javascript
// webui/my-store.js
import { createStore } from "/js/AlpineStore.js";
export const store = createStore("myPluginStore", {
status: 'idle',
init() { ... },
- onOpen() { ... }
+ onOpen() { ... },
+ cleanup() { ... }
});
```
-Import it in the HTML `<head>`:
+Import it in the HTML <head>:
```html
<head>
<script type="module" src="/plugins/<plugin_name>/webui/my-store.js"></script>
</head>
```
-## ⚙️ Plugin Settings
+## Plugin Settings
-If your plugin needs user-configurable settings, add `webui/config.html`. The system detects it automatically and shows a Settings button in the relevant tabs (per `settings_sections` in `plugin.json`).
+If your plugin needs user-configurable settings, add webui/config.html. The system detects it automatically and shows a Settings button in the relevant tabs (per settings_sections in plugin.json).
### Settings modal contract
-The modal provides Project + Agent profile context selectors. Your `config.html` binds to `$store.pluginSettings.settings`:
+The modal provides Project + Agent profile context selectors. Your config.html binds to $store.pluginSettings.settings:
```html
<html>
@@ -86,11 +87,11 @@ The modal provides Project + Agent profile context selectors. Your `config.html`
</html>
```
-The modal's Save button persists `$store.pluginSettings.settings` to `config.json` in the correct scope (project/agent/global).
+The modal's Save button persists $store.pluginSettings.settings to config.json in the correct scope (project/agent/global).
### Surfacing core settings (e.g. memory pattern)
-If your plugin exposes **existing core settings** rather than plugin-specific ones, set `saveMode = 'core'` so Save delegates to the core settings API:
+If your plugin exposes existing core settings rather than plugin-specific ones, set saveMode = 'core' so Save delegates to the core settings API:
```html
<div x-data x-init="
@@ -102,15 +103,16 @@ If your plugin exposes **existing core settings** rather than plugin-specific on
```
### Sidebar Button (sidebar entry point)
-- **Extension point**: `sidebar-quick-actions-main-start`
-- **Class**: `class="config-button"`
-- **Placement**: `x-move-after=".config-button#dashboard"`
-- **Action**: `@click="openModal('/plugins/<plugin_name>/webui/my-modal.html')"`
+- Extension point: sidebar-quick-actions-main-start
+- Class: class="config-button"
+- Placement: x-move-after=".config-button#dashboard"
+- Action: @click="openModal('/plugins/<plugin_name>/webui/my-modal.html')"
-## 🐍 Backend API & Context
+## Backend API & Context
### Import Paths
-- **Correct**: `from agent import AgentContext` (not python.helpers.agent)
+- Correct: from agent import AgentContext, AgentContextType
+- Correct: from initialize import initialize_agent
### Sending Messages Proactively
```python
@@ -138,7 +140,7 @@ save_plugin_config(
)
```
-## 📁 Directory Layout
+## Directory Layout
```
usr/plugins/<name>/
plugin.json # Required manifest