AI Maestro Orchestrator Agent (amoa-)
June 20, 2026 · View on GitHub
Version: 1.9.0
A Claude Code plugin that turns one Claude session into a multi-agent orchestrator: it breaks a plan into GitHub-Issue-backed modules, assigns them to sub-agents and remote agents over AI Maestro inter-agent messaging, tracks progress on a GitHub Projects V2 kanban board, and enforces a verification gate before the session is allowed to exit.
Overview
The Orchestrator Agent handles task distribution, agent coordination, and progress monitoring for multi-agent projects. It receives plans and coordinates subagents to implement them via AI Maestro inter-agent messaging.
Requirements
- Python 3.8+ with PyYAML (
pip install pyyaml) - GitHub CLI (
gh) for issue and project management - AI Maestro messaging system for inter-agent communication
Core Responsibilities
- Task Distribution: Break plans into assignable tasks with dependency ordering
- Agent Coordination: Manage subagents and remote agents via AI Maestro
- Progress Monitoring: Track task completion via polling hooks
- Module Management: Organize work into GitHub Issue-backed modules
- Verification: Ensure instructions are followed correctly before exit
- Kanban Management: GitHub Projects V2 board and column management
Components
Agents (6)
| Agent | Description |
|---|---|
ai-maestro-orchestrator-agent-main-agent | Main orchestrator — delegates to sub-agents |
amoa-team-orchestrator | Coordinates team of remote agents |
amoa-task-summarizer | Summarizes task progress and state |
amoa-checklist-compiler | Creates verification checklists |
amoa-docker-container-expert | Docker and container expertise |
amoa-experimenter | Experimentation and prototyping |
Commands (15)
| Command | Description |
|---|---|
/amoa-start-orchestration | Start orchestration phase |
/amoa-orchestrator-loop | Start orchestration loop |
/amoa-orchestration-status | Show orchestration phase status (modules/agents) |
/amoa-orchestrator-status | Show orchestrator loop status (iterations/tasks) |
/amoa-cancel-orchestrator | Cancel orchestration |
/amoa-register-agent | Register remote agent |
/amoa-check-agents | Check agent status and poll progress |
/amoa-assign-module | Assign module to agent |
/amoa-reassign-module | Reassign module to different agent |
/amoa-add-module | Add new module |
/amoa-modify-module | Modify existing module |
/amoa-remove-module | Remove module |
/amoa-prioritize-module | Change module priority |
/amoa-reassign-kanban-tasks | Reassign kanban board tasks |
/amoa-generate-replacement-handoff | Generate agent replacement handoff document |
Skills (16)
| Skill | Description |
|---|---|
amoa-two-phase-mode | Plan-then-Execute workflows with formal approval |
amoa-orchestration-commands | Orchestration command reference and loop mechanics |
amoa-orchestration-patterns | Task breakdown patterns for human developers |
amoa-remote-agent-coordinator | Remote AI agent coordination via AI Maestro |
amoa-module-management | Module CRUD operations (1:1 with GitHub Issues) |
amoa-verification-patterns | Implementation verification and evidence collection |
amoa-developer-communication | Developer communication patterns and templates |
amoa-checklist-compilation-patterns | Verification checklist generation |
amoa-agent-replacement | Agent replacement and handoff protocols |
amoa-task-distribution | Task breakdown, assignment, and load balancing |
amoa-progress-monitoring | Progress tracking via state-based polling |
amoa-messaging-templates | AI Maestro message format templates |
amoa-label-taxonomy | GitHub label system for multi-agent coordination |
amoa-implementer-interview-protocol | Interview-based task verification |
amoa-github-action-integration | GitHub Actions CI/CD patterns |
amoa-kanban-management | GitHub Projects V2 kanban board management |
Hooks (4)
| Hook | Event | Description |
|---|---|---|
amoa-orchestrator-stop | Stop | Blocks exit until all tasks complete (120s timeout) |
amoa-instruction-verification-check | PreToolUse | Blocks agent work if verification incomplete |
amoa-polling-reminder | UserPromptSubmit | Reminds to poll agent progress |
amoa-file-tracker | PostToolUse | Tracks Edit/Write file modifications |
Project Structure
ai-maestro-orchestrator-agent/
├── .claude-plugin/ # Plugin manifest (plugin.json)
├── agents/ # Agent definitions (6 agents)
├── commands/ # Slash command definitions (15 commands)
├── docs/ # Architecture docs (role boundaries, workflow, registry)
├── git-hooks/ # Git hooks (pre-push validation)
├── hooks/ # Plugin hooks (hooks.json + 4 hook scripts)
├── scripts/ # Python scripts (56 scripts + validation suite)
│ └── amoa_stop_check/ # Stop hook package (lock, tasks, phase checks)
├── shared/ # Shared resources across skills
├── skills/ # Skill definitions (16 skills with references)
├── tests/ # Test suite
└── requirements.txt # Python dependencies (PyYAML)
Workflow
- Plan Phase: Define modules and requirements (two-phase mode)
- Assignment: Assign modules to agents via kanban board
- Execution: Agents implement modules, report via AI Maestro
- Monitoring: Poll agent progress, detect stalls, handle failures
- Verification: 4-loop verification ensures all tasks complete
- Completion: Stop hook enforces completion before session exit
Usage
Drive the orchestrator from its slash commands once the plugin is installed
(run /help to list the full amoa- command set). The common entry points:
/amoa-start-orchestration # begin a new orchestration run from a plan
/amoa-orchestration-status # show the live module/kanban/agent state
/amoa-cancel-orchestrator # stop the active orchestrator loop
Underlying tooling is also runnable directly for scripting:
uv run python scripts/amoa_kanban_manager.py <command> # kanban board ops
uv run python scripts/amoa_orchestration_status.py # status snapshot
Installation
Install using --plugin-dir for local development:
claude --plugin-dir /path/to/ai-maestro-orchestrator-agent
Start a session with the main orchestrator agent:
claude --agent ai-maestro-orchestrator-agent-main-agent
After modifying plugin files, reload without restarting:
/reload-plugins
Validation
Run the CPV (Claude Plugins Validation) suite. Validation is delegated entirely to CPV — this plugin ships no local validators:
cd ai-maestro-orchestrator-agent
uvx --from git+https://github.com/Emasoft/claude-plugins-validation --with pyyaml \
cpv-remote-validate plugin . --strict --verbose
scripts/publish.py re-runs this exact --strict gate (plus lint and the
test suite) immediately before every push. The pre-push hook only enforces
that pushes go through publish.py (a process-ancestry check); it runs no
validation of its own.
Development
- Kanban management:
uv run python scripts/amoa_kanban_manager.py <command> - GitHub project columns:
uv run python scripts/gh-project-add-columns.py
License
MIT