| 1 | # Plugins And Development Workflow |
| 2 | |
| 3 | ## Source Anchors |
| 4 | |
| 5 | - Plugin contract: `/a0/plugins/AGENTS.md` |
| 6 | - Plugin helper code: `/a0/helpers/plugins.py` |
| 7 | - Plugin specialist skills: `/a0/skills/a0-plugin-router/SKILL.md`, `/a0/skills/a0-create-plugin/SKILL.md`, `/a0/skills/a0-debug-plugin/SKILL.md`, `/a0/skills/a0-review-plugin/SKILL.md` |
| 8 | - Root development contract: `/a0/AGENTS.md` |
| 9 | |
| 10 | ## Plugin-First Rule |
| 11 | |
| 12 | Plugins are the primary way to extend Agent Zero. A plugin can bundle: |
| 13 | |
| 14 | - `plugin.yaml` |
| 15 | - `default_config.yaml` |
| 16 | - `hooks.py` |
| 17 | - `execute.py` |
| 18 | - `tools/` |
| 19 | - `api/` |
| 20 | - `helpers/` |
| 21 | - `prompts/` |
| 22 | - `skills/` |
| 23 | - `extensions/python/` |
| 24 | - `extensions/webui/` |
| 25 | - `webui/` |
| 26 | - plugin-local docs and assets |
| 27 | |
| 28 | Use root framework directories only when changing bundled framework behavior itself. For custom or experimental work, use `usr/plugins/<plugin>/` unless the task is explicitly to change a bundled plugin. |
| 29 | |
| 30 | ## Imports And Runtime |
| 31 | |
| 32 | - Bundled plugins under `plugins/` may use `plugins.<plugin_name>...` imports. |
| 33 | - User plugins under `usr/plugins/` should use `usr.plugins.<plugin_name>...` imports. |
| 34 | - Avoid `sys.path` hacks and symlink-dependent imports. |
| 35 | - `hooks.py` runs inside the framework runtime (`/opt/venv-a0` in Docker). |
| 36 | - If a plugin must prepare the agent execution runtime or system packages, it must explicitly target that environment in a subprocess. |
| 37 | |
| 38 | ## Manifest And Configuration |
| 39 | |
| 40 | Every plugin needs `plugin.yaml`. Runtime fields include: |
| 41 | |
| 42 | - `name` |
| 43 | - `title` |
| 44 | - `description` |
| 45 | - `version` |
| 46 | - `settings_sections` |
| 47 | - `per_project_config` |
| 48 | - `per_agent_config` |
| 49 | - `always_enabled` |
| 50 | |
| 51 | Defaults belong in `default_config.yaml`. Runtime user settings belong under `usr/`. |
| 52 | |
| 53 | Settings resolution order is project/profile, project, user/profile, user plugin config, then bundled `default_config.yaml`. |
| 54 | |
| 55 | ## Activation And Cleanup |
| 56 | |
| 57 | - Global and scoped activation are independent. |
| 58 | - Activation files use `.toggle-1` for ON and `.toggle-0` for OFF. |
| 59 | - `always_enabled: true` forces ON and disables UI toggles. |
| 60 | - Plugin deletion or disablement should not leave unmanaged services, symlinks, or files outside plugin-owned paths unless explicitly documented with cleanup. |
| 61 | |
| 62 | ## Routes And UI |
| 63 | |
| 64 | Plugin routes: |
| 65 | |
| 66 | | Route | Purpose | |
| 67 | |---|---| |
| 68 | | `GET /plugins/<name>/<path>` | Static/plugin web assets. | |
| 69 | | `POST /api/plugins/<name>/<handler>` | Plugin API handler. | |
| 70 | | `POST /api/plugins` | Plugin management actions. | |
| 71 | |
| 72 | Plugin settings UIs should bind saved values to `config.*` and modal-only state/actions to `context.*` through `$store.pluginSettingsPrototype`. |
| 73 | |
| 74 | Plugin UI errors, warnings, success, and info should use the A0 notification system. |
| 75 | |
| 76 | ## Workflow |
| 77 | |
| 78 | 1. Decide whether the request is plugin-specific. If yes, load `a0-plugin-router`. |
| 79 | 2. If creating a plugin, load `a0-create-plugin`. |
| 80 | 3. If debugging a plugin, load `a0-debug-plugin`. |
| 81 | 4. If reviewing or publishing a plugin, load `a0-review-plugin` or `a0-contribute-plugin`. |
| 82 | 5. Read `plugins/AGENTS.md` and any plugin-local `AGENTS.md`. |
| 83 | 6. Keep changes inside the plugin boundary unless shared framework behavior truly belongs in `helpers/` or root code. |
| 84 | 7. Update plugin docs/DOX when user-visible behavior, configuration, routes, hooks, or cleanup changes. |
| 85 | |
| 86 | ## Verification |
| 87 | |
| 88 | - Run plugin-specific tests after changing a bundled plugin. |
| 89 | - Run framework tests for touched tools, API handlers, extension points, settings, or WebUI surfaces. |
| 90 | - Smoke-test external-service, browser, desktop, or connector integrations when practical. |
| 91 | - For discovery banners/cards, verify rendering, dismiss behavior, ordering, and CTA behavior. |