Eoa Remote Agent Coordinator

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

Instructions

Follow these steps when coordinating remote agents:

1. Verify AI Maestro is running and remote agents are registered
2. Review the task requirements and prepare delegation instructions
3. Include ACK protocol instructions in every task message (see MANDATORY section below)
4. Send task delegation message via AI Maestro using the agent-messaging skill with complete instruction format
5. Wait for agent acknowledgment (timeout: 5 minutes)
6. Monitor progress proactively every 10-15 minutes during active work
7. Enforce 4-verification-loop protocol before approving any PR requests
8. Review completion reports against acceptance criteria
9. Escalate to user when architecture/security decisions are needed

Checklist

Copy this checklist and track your progress:

• AI Maestro messaging system is running and accessible
• Remote agents are registered and available in agent roster
• Task delegation includes ACK protocol instructions block
• Task delegation includes PR notification requirement
• Task delegation includes complete instruction format (context, scope, interface, files, tests, completion criteria)
• Agent acknowledgment received within 5 minutes
• Proactive progress monitoring active (polling every 10-15 minutes)
• 4-verification-loop protocol enforced before PR approval
• Completion report reviewed against acceptance criteria
• LSP servers verified for agent's working language
• All escalations resolved before considering task complete

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

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:

1. ACK Instructions Block (at top)
2. PR Notification Requirement (mandatory)
3. Context - What problem is being solved
4. Scope - Exact boundaries (DO/DO NOT lists)
5. Interface Contract - Input/output specifications
6. Files to Modify - Specific files in scope
7. Test Requirements - What tests must pass
8. 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:

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:

1. Agent reads required documentation
2. Agent sets up environment
3. Agent completes verification task
4. Agent sends registration message
5. 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

1. PROACTIVELY poll every 10-15 minutes during active work
2. PROACTIVELY send status request if no update received
3. PROACTIVELY offer solutions when agents report blockers
4. 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:

1. Agent Roster verified
2. GitHub Project ready
3. Branch permissions set
4. AI Maestro running
5. 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:

• lsp-servers-overview.md - Available plugins table, install commands, configuration
• lsp-installation-guide.md - Per-language installation
• lsp-enforcement-checklist.md - Pre-assignment verification
• orchestrator-lsp-management.md - Orchestrator LSP guide

Toolchain Template System

Templates provide pre-configured setups for rapid project initialization.

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:

1. Upload to GitHub issue comment as attachment
2. Share URL only in messages
3. Require ACK with SHA256 hash
4. 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:

• 1. Core Decision Trees - When deciding whether to escalate, reassign, retry, or handle directly
• 2. Mid-Task Updates - When relaying requirement changes or priority shifts to agents mid-task
• 3. Reassignment Communication - When reassigning tasks between agents due to failure or recovery
• 4. Blocker Reports - When agents report blockers and the orchestrator must triage
• 5. Multi-Project Coordination - When tasks span multiple projects with cross-dependencies
• 6. 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:

1. Verify API health using the agent-messaging skill health check
2. Check agent ID format (use full session name, not alias)
3. Verify agent is registered in AI Maestro
4. Check network connectivity

Issue: Agent responds but doesn't understand instructions

Cause: Instruction Verification Protocol not executed.

Solution:

1. Always execute Instruction Verification Protocol before implementation
2. Request agent to repeat key requirements in their own words
3. Correct any misunderstandings before authorizing work
4. Provide clarification for all questions asked

Issue: Agent progress stalls without reporting blockers

Cause: Proactive polling not configured or agent not responding.

Solution:

1. Ensure 10-15 minute polling cycle is active
2. Include ALL mandatory poll questions (issues, unclear items, difficulties)
3. If no response after 2 polls, send escalation message using the agent-messaging skill
4. Consider reassigning if agent unresponsive

Issue: Module assignment conflicts between agents

Cause: Same module assigned to multiple agents.

Solution:

1. Check current assignments: /orchestration-status
2. Use /reassign-module to move module to single agent
3. Notify previous assignee to stop work
4. 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:

1. Review PR against original acceptance criteria
2. Ensure agent followed 4-verification-loop protocol
3. Request fixes for failing criteria
4. Do NOT merge until all criteria pass

Design Document Scripts

This script helps locate design documents when coordinating with remote agents:

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

• echo-acknowledgment-protocol.md - ACK protocol
• verification-loops-protocol.md - 4-verification loops
• progress-monitoring-protocol.md - Proactive monitoring
• error-handling-protocol.md - FAIL-FAST principle
• escalation-procedures.md - Escalation hierarchy
• agent-onboarding.md - Onboarding checklist
• task-instruction-format.md - Instruction template
• overnight-operation.md - Autonomous operation
• lsp-servers-overview.md - LSP requirements
• ecos-replacement-protocol.md - Agent replacement
• agent-types.md - Agent type definitions
• assignment-workflow.md - Agent assignment
• agent-communication-templates.md - Communication templates

Converted and distributed by TomeVault — claim your Tome and manage your conversions.