vrr/agent-zero
2
0
Fork 0
mirror of https://github.com/agent0ai/agent-zero.git synced 2026-07-09 17:08:29 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 4
agent-zero/plugins/_commands/AGENTS.md
Alessandro 84c13dab01 Add built-in goal management plugin 
Adds the always-enabled _goal plugin with per-chat goal storage, WebUI goal strip, /goal slash command, and agent-facing goal tools.

Includes command-picker integration, focused plugin tests, and the generated 256x256 thumbnail asset.
2026-07-09 17:09:08 +02:00

3.1 KiB
Raw Blame History

Commands Plugin DOX

Purpose

  • Own the built-in slash command manager and chat composer slash picker.
  • Keep file-backed /command discovery consistent across project, global, and plugin-provided scopes.

Ownership

  • plugin.yaml owns the built-in _commands plugin metadata.
  • helpers/commands.py owns command name sanitization, argument parsing, scope resolution, file persistence, plugin command discovery, and command invocation resolution.
  • api/commands.py owns the Commands API actions used by the WebUI.
  • webui/ owns the manager/editor modal stores, HTML surfaces, and thumbnail asset.
  • commands/ owns bundled read-only slash command definitions shipped by _commands.
  • extensions/ owns the chat composer picker and sidebar quick-action entry.
  • extensions/python/startup_migration/ owns one-time migration from the legacy community commands plugin namespace.
  • skills/commands-create-slash-command/ owns the agent-facing authoring workflow for reusable slash commands.
  • tests/ owns regression coverage for parsing, CRUD, scope precedence, plugin-distributed commands, legacy migration, and skill discovery.

Local Contracts

  • The plugin identity is _commands; user-created command files live under usr/plugins/_commands/commands/ or usr/projects/<project>/.a0proj/plugins/_commands/commands/.
  • Each command is one .command.yaml config plus one same-directory .txt text template or .py script hook.
  • Project commands override global commands, global commands override bundled _commands/commands/ defaults, and bundled defaults override other plugin-distributed commands with the same name.
  • Bundled _commands/commands/ definitions and commands contributed by other plugins are read-only from this manager.
  • Bundled command files use canonical command names only; do not ship alias-only built-ins such as /img for /attach.
  • Command configs may set webui_hidden: true to stay resolvable but be omitted from the chat composer picker.
  • Commands contributed by enabled plugins live in their commands/ directory and must not be rediscovered through the generic plugin-distributed path from _commands itself.
  • On startup, _commands copies legacy usr/plugins/commands command and skill files into usr/plugins/_commands without overwriting existing files, copies scoped legacy command folders to _commands, and disables the legacy commands plugin roots to prevent duplicate WebUI popovers.
  • Script commands must expose run(payload) and return a string or a dict with text and optional effects; show_markdown effects render as auto-dismissing toast notifications.
  • Script commands may emit send_message with text to submit the rendered composer text immediately after command resolution.

Work Guidance

  • Keep the command storage and route namespace aligned with _commands.
  • Preserve unknown command config keys when editing commands.
  • Keep WebUI paths pointed at /plugins/_commands/....

Verification

  • Run conda run -n a0 pytest plugins/_commands/tests after backend or command contract changes.

Child DOX Index

No child DOX files.