agent-zero/plugins/_orchestrator/AGENTS.md

Orchestrator Plugin - AGENTS.md

Purpose

• Provide a bundled Agent Zero plugin for delegating repository and coding work to external terminal/headless agents.
• Keep heavy delegation instructions out of the always-loaded prompt by exposing the orchestrator skill instead of a terminal_agent tool.
• Own adapter status metadata, settings UI, Codex device login APIs, and skill instructions for Agent Zero headless, Codex CLI, Claude Code, Cursor CLI, Grok Build, Hermes Agent, OpenCode, and future terminal agents.

Ownership

• Source-owned files are .gitignore, plugin.yaml, default_config.yaml, LICENSE, README.md, thumbnail.png, api/, helpers/, skills/, tests/, and webui/.
• Runtime/user-state files such as config.json, data/, __pycache__/, credential stores, and generated screenshots are not source contracts.

Local Contracts

• Plugin imports must use plugins._orchestrator....
• The plugin must remain toolless: no tools/terminal_agent.py, no subprocess runner, and no agent.system.tool.terminal_agent.md prompt.
• External agents are orchestrated through the ordinary Agent Zero shell/code execution tool after the orchestrator skill is loaded.
• Adapters report installation, binary resolution, auth state, safe disconnect capability, and optional device-login capability. They do not build or run task commands.
• Settings UI is for status and command defaults. It must not offer generic install buttons; install/login belongs to the skill-guided human-in-the-loop shell workflow.
• Credentials must never be hardcoded or printed. Plugin-owned state belongs under data/<adapter>/ and external CLI state stays in the CLI's own home/config paths.
• Agent Zero headless is the first adapter. Its setup flow is the exception: ask whether to use this same Agent Zero instance or another/spun-up instance when the target is not specified.

Work Guidance

• Keep source docs, UI labels, adapter metadata, tests, skills/orchestrator/SKILL.md, and per-agent references aligned whenever adding or changing an adapter.
• Prefer direct, discoverable adapter metadata over a second abstraction layer. Keep generic behavior in the skill and per-agent command details in reference files.
• For CLI login flows, show provider/menu choices in chat and send the user's selected option back to the active shell session. Do not send users to a Docker shell only to choose a menu.
• After changing the skill, tell testers to start a fresh chat or reload orchestrator; previously loaded skill text can remain attached to old conversations.
• Codex device login is the only settings-screen OAuth flow currently owned here. Add another only when the credential store and revocation/disconnect path are known.
• Avoid recursive Agent Zero delegation loops. A0 headless prompts must tell the target instance to answer directly and not delegate back through terminal agents.

Verification

• Framework-runtime adapter self-check:

  docker exec 8dc967046cda bash -lc 'cd /a0 && /opt/venv-a0/bin/python plugins/_orchestrator/tests/test_status_adapters.py'
  

• Frontend syntax check when editing WebUI JavaScript:

  node --check plugins/_orchestrator/webui/orchestrator-store.js
  

• After Python checks, remove generated bytecode before packaging:

  find plugins/_orchestrator -type d -name __pycache__ -prune -exec rm -rf {} +
  

Child DOX Index

Child	Scope
api/AGENTS.md	Plugin HTTP API handlers for status, device login polling, and disconnect.
helpers/AGENTS.md	Adapter registry, base contracts, and shared helper behavior.
skills/AGENTS.md	Plugin skill collection and agent-facing delegation instructions.
tests/AGENTS.md	Direct regression checks for plugin contracts and skill text.
webui/AGENTS.md	Settings UI markup, Alpine store, status display, and device-login UI.

Intentionally unindexed local/generated paths:

Path	Reason
config.json	Local plugin settings state.
data/	Plugin-owned credential/state directory.
__pycache__/	Generated Python bytecode.