| name | eoa-remote-agent-coordinator |
| description | Use when coordinating remote AI agents. Trigger with task delegation or multi-agent coordination requests. |
| license | Apache-2.0 |
| compatibility | Requires AI Maestro messaging system (AMP, handles routing automatically). Python 3.9+ for LSP management scripts. Requires AI Maestro installed. |
| metadata | {"author":"Emasoft","version":"1.2.0"} |
| context | fork |
| user-invocable | false |
| agent | eoa-main |
| workflow-instruction | Step 17 |
| procedure | proc-execute-task |
Remote Agent Coordinator
Overview
The Remote Agent Coordinator enables the EOA (Emasoft Orchestrator Agent) to delegate coding tasks to remote AI agents and human developers via the AI Maestro messaging system. This is the ONLY mechanism through which actual code is written.
Critical Principle: The orchestrator NEVER writes code. It creates precise instructions and sends them to remote agents who execute the coding work.
Prerequisites
- AI Maestro messaging system (AMP) running
- Python 3.9+ for LSP management scripts
- Remote agents registered and available
- GitHub CLI (gh) for issue management
Output
| Output Type | Format | Location |
|---|
| Agent roster | JSON file | agent_roster.json |
| Task delegation messages | AI Maestro message | Sent via API |
| Progress reports | AI Maestro message | Received via API |
| Verification loop state | JSON tracking | In-memory or file |
| Escalation messages | AI Maestro message | Sent to orchestrator-master |
Instructions
Follow these steps when coordinating remote agents:
- Verify AI Maestro is running and remote agents are registered
- Review the task requirements and prepare delegation instructions
- Include ACK protocol instructions in every task message (see MANDATORY section below)
- Send task delegation message via AI Maestro using the
agent-messaging skill with complete instruction format
- Wait for agent acknowledgment (timeout: 5 minutes)
- Monitor progress proactively every 10-15 minutes during active work
- Enforce 4-verification-loop protocol before approving any PR requests
- Review completion reports against acceptance criteria
- Escalate to user when architecture/security decisions are needed
Checklist
Copy this checklist and track your progress:
Quick Reference: Core Protocols
MANDATORY: Acknowledgment Protocol
CRITICAL: Remote agents DO NOT have this skill. The orchestrator MUST teach them the ACK protocol BY INCLUDING IT IN EVERY TASK DELEGATION MESSAGE.
ACK template to copy-paste: See echo-acknowledgment-protocol.md section 2.3 for the exact template block.
Full protocol details: echo-acknowledgment-protocol.md
- 1.0 Purpose and triggers
- 2.0 Message Types: Instructions vs Conversations
- 3.0 ACK Format and Examples (includes template block)
- 4.0 Timeout handling (5 min wait, reminder, reassign)
- 5.0 Proactive enforcement by orchestrator
AI Maestro Messaging
For messaging, use the official AI Maestro skill: ~/.claude/skills/agent-messaging/SKILL.md
Message Types
| Type | Purpose | When to Use |
|---|
task | Assign new coding task | Starting work on feature/fix |
fix-request | Request code fix | After PR review finds issues |
status-request | Check on progress | No update received |
approval | Approve completed work | After successful review |
escalation | Escalate to user | Architecture/security decision |
Full protocol details: messaging-protocol.md
- 1.0 Sending Messages
- 2.0 Message priorities and timeouts
- 3.0 Task Management messages
- 4.0 Status and Progress messages
- 5.0 Approvals and Rejections
- 6.0 Error Handling
Task Instruction Format
Every task instruction MUST include:
- ACK Instructions Block (at top)
- PR Notification Requirement (mandatory)
- Context - What problem is being solved
- Scope - Exact boundaries (DO/DO NOT lists)
- Interface Contract - Input/output specifications
- Files to Modify - Specific files in scope
- Test Requirements - What tests must pass
- Completion Criteria - How to know when done
Full template and examples: task-instruction-format.md
- 1.0 Complete instruction template
- 2.0 Example filled-in instruction
- 3.0 Config reference patterns
- 4.0 Error states and escalation
Agent Response Templates
Include template references in EVERY task delegation:
| Template | Path | Purpose |
|---|
| ACK Response | templates/ack-response.md | How to acknowledge task receipt |
| Completion Report | templates/completion-report.md | How to report task completion |
| Status Update | templates/status-update.md | How to send progress updates |
Full details: agent-response-templates.md
- 1.0 Available templates
- 2.0 Including templates in delegations
- 3.0 Generating ad-hoc skills for complex tasks
Agent Onboarding
Before any agent can receive real tasks, they must complete onboarding.
Quick flow:
- Agent reads required documentation
- Agent sets up environment
- Agent completes verification task
- Agent sends registration message
- Orchestrator approves registration
Full onboarding guide: agent-onboarding.md
- 1.0 Onboarding Checklist
- 2.0 Environment Setup
- 3.0 Verification Task
- 4.0 Required Reading List
- 5.0 Roster Registration
Agent registration format: agent-registration.md
- 1.0 Registration fields
- 2.0 Agent Roster management
- 3.0 Availability states
MANDATORY: 4-Verification-Loops Before PR
CRITICAL: For EACH TASK, require 4 verification loops BEFORE allowing PR creation. The agent will make 5 PR requests total - respond to the first 4 with "Check your changes for errors", then approve or reject on the 5th.
Full protocol with table: verification-loops-protocol.md
- 1.0 Understanding the 5 PR requests cycle
- 2.0 Verification message templates
- 3.0 Tracking verification state per task
- 4.0 Summary table: The 5 PR Requests (orchestrator responses)
- 5.0 Enforcement rules (MUST/MUST NOT)
Progress Monitoring (PROACTIVE)
CRITICAL: Do not wait passively for updates - actively reach out.
Proactive Monitoring Principles
- PROACTIVELY poll every 10-15 minutes during active work
- PROACTIVELY send status request if no update received
- PROACTIVELY offer solutions when agents report blockers
- PROACTIVELY verify agents don't stop until ALL tasks complete
Full protocol: progress-monitoring-protocol.md
- 1.0 Polling intervals by task type
- 2.0 Status request messages
- 3.0 Unblocking protocol
- 4.0 No-update escalation timeline
Error Handling
Remote agents must follow FAIL-FAST:
- NO workarounds
- NO fallbacks
- If blocked, REPORT and WAIT
Full protocol: error-handling-protocol.md
- 1.0 FAIL-FAST principle
- 2.0 Error report message format
- 3.0 Orchestrator response procedures
Overnight Autonomous Operation
Prerequisites before leaving:
- Agent Roster verified
- GitHub Project ready
- Branch permissions set
- AI Maestro running
- Tasks queued
Full guide: overnight-operation.md
- 1.0 Prerequisites Checklist
- 2.0 User Handoff Protocol
- 3.0 Operation Flow
- 4.0 Escalation rules during autonomous operation
- 5.0 Recovery procedures
Escalation Protocol
Escalate to user when:
- Architecture decisions not covered by methodology
- Security vulnerabilities discovered
- Dependency conflicts requiring user choice
- Test failures suggesting spec issues
Full procedures: escalation-procedures.md
- 1.0 Escalation hierarchy (Level 0-2)
- 2.0 Escalation message formats
- 3.0 Escalation categories
- 4.0 Queue management
LSP Server Requirements
Remote agents MUST have LSP servers installed for working languages. Verify LSP availability before assigning tasks.
LSP References:
Toolchain Template System
Templates provide pre-configured setups for rapid project initialization.
| Category | Purpose |
|---|
| Toolchain | Language-specific dev configs |
| Handoff | Task delegation formats |
| Report | Status reporting formats |
| GitHub | Kanban and project tracking |
Full guide: toolchain-template-system.md
- 1.0 Template categories
- 2.0 Using compile_template.py
- 3.0 Including templates in delegations
Template index: templates/TEMPLATE_INDEX.md
Document Storage Protocol
Documents are NEVER embedded in AI Maestro messages - only GitHub issue comment URLs.
Rules:
- Upload to GitHub issue comment as attachment
- Share URL only in messages
- Require ACK with SHA256 hash
- Lock files read-only after download
Full protocol: document-storage-protocol.md
- 1.0 Storage architecture
- 2.0 Document delivery rules
- 3.0 Orchestrator scripts
- 4.0 Remote agent storage skill
Orchestrator Rules
RULE 15 - No Implementation: The orchestrator NEVER writes code, runs builds, edits source files, or sets up infrastructure. See rule-15-no-implementation.md.
RULE 14 - Immutable Requirements: Every task delegation MUST include requirement references, forbidden actions, and escalation protocol. See rule-14-immutable-requirements.md.
Additional References
Extended Coordination Protocols
For decision trees, mid-task updates, reassignment, blockers, multi-project coordination, and verification feedback, see extended-coordination-protocols.md:
-
- Core Decision Trees - When deciding whether to escalate, reassign, retry, or handle directly
-
- Mid-Task Updates - When relaying requirement changes or priority shifts to agents mid-task
-
- Reassignment Communication - When reassigning tasks between agents due to failure or recovery
-
- Blocker Reports - When agents report blockers and the orchestrator must triage
-
- Multi-Project Coordination - When tasks span multiple projects with cross-dependencies
-
- Verification Feedback (Loops 2-4) - When providing progressive feedback during the 4-verification-loop cycle
Examples
Complete examples with code: examples-remote-coordination.md
- 1.0 Example: Onboard and Assign Task to New Agent (with curl commands)
- 2.0 Example: 4-Verification Loop Sequence (complete conversation flow, tracking table)
- 3.0 Example: Progress Monitoring Flow (polling commands, timeline, no-response handling)
Error Handling
Issue: AI Maestro messages not being delivered
Cause: API endpoint unreachable or agent identifier incorrect.
Solution:
- Verify API health using the
agent-messaging skill health check
- Check agent ID format (use full session name, not alias)
- Verify agent is registered in AI Maestro
- Check network connectivity
Issue: Agent responds but doesn't understand instructions
Cause: Instruction Verification Protocol not executed.
Solution:
- Always execute Instruction Verification Protocol before implementation
- Request agent to repeat key requirements in their own words
- Correct any misunderstandings before authorizing work
- Provide clarification for all questions asked
Issue: Agent progress stalls without reporting blockers
Cause: Proactive polling not configured or agent not responding.
Solution:
- Ensure 10-15 minute polling cycle is active
- Include ALL mandatory poll questions (issues, unclear items, difficulties)
- If no response after 2 polls, send escalation message using the
agent-messaging skill
- Consider reassigning if agent unresponsive
Issue: Module assignment conflicts between agents
Cause: Same module assigned to multiple agents.
Solution:
- Check current assignments:
/orchestration-status
- Use
/reassign-module to move module to single agent
- Notify previous assignee to stop work
- Never assign same module to multiple agents simultaneously
Issue: Agent completes work but PR fails verification
Cause: Acceptance criteria not met or 4-verification-loop not followed.
Solution:
- Review PR against original acceptance criteria
- Ensure agent followed 4-verification-loop protocol
- Request fixes for failing criteria
- Do NOT merge until all criteria pass
Design Document Scripts
This script helps locate design documents when coordinating with remote agents:
| Script | Purpose | Usage |
|---|
eoa_design_search.py | Search design documents for task delegation | python scripts/eoa_design_search.py --type <TYPE> --status <STATUS> |
Use eoa_design_search.py when:
- Looking up design specifications to include in task delegations
- Finding related designs for context when assigning work
- Verifying design status before creating implementation tasks
Script Location
The script is located at ../../scripts/eoa_design_search.py relative to this skill.
Resources
