AgentSkillsCN

eoa-remote-agent-coordinator

当需要协调远程 AI 代理时使用。可通过任务委派或多智能体协同请求触发相关操作。

SKILL.md
--- frontmatter
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 (configurable via AIMAESTRO_API env var, default http://localhost:23000). Python 3.9+ for LSP management scripts. Requires AI Maestro installed.
metadata:
  author: Anthropic
  version: 1.2.0
context: fork
agent: eoa-main

Remote Agent Coordinator

Overview

The Remote Agent Coordinator enables the ATLAS-ORCHESTRATOR 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 running (default: http://localhost:23000)
  • •Python 3.9+ for LSP management scripts
  • •Remote agents registered and available
  • •GitHub CLI (gh) for issue management

Output

Output TypeFormatLocation
Agent rosterJSON fileagent_roster.json
Task delegation messagesAI Maestro messageSent via API
Progress reportsAI Maestro messageReceived via API
Verification loop stateJSON trackingIn-memory or file
Escalation messagesAI Maestro messageSent to orchestrator-master

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 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

ProtocolReferenceUse When
Acknowledgmentecho-acknowledgment-protocol.mdTask requires confirmation of receipt
4-Verification Loopsverification-loops-protocol.mdAgent requests PR permission
Progress Monitoringprogress-monitoring-protocol.mdTracking agent progress
Error Handlingerror-handling-protocol.mdAgent reports being blocked
Escalationescalation-procedures.mdIssue requires user decision

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

TypePurposeWhen to Use
taskAssign new coding taskStarting work on feature/fix
fix-requestRequest code fixAfter PR review finds issues
status-requestCheck on progressNo update received
approvalApprove completed workAfter successful review
escalationEscalate to userArchitecture/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:

  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:

TemplatePathPurpose
ACK Responsetemplates/ack-response.mdHow to acknowledge task receipt
Completion Reporttemplates/completion-report.mdHow to report task completion
Status Updatetemplates/status-update.mdHow 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:

  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:

Toolchain Template System

Templates provide pre-configured setups for rapid project initialization.

CategoryPurpose
ToolchainLanguage-specific dev configs
HandoffTask delegation formats
ReportStatus reporting formats
GitHubKanban 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

ATLAS 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-atlas.md

  • •1.0 Storage architecture
  • •2.0 Document delivery rules
  • •3.0 Orchestrator scripts
  • •4.0 Remote agent storage skill

Configuration References

DocumentUse When
central-configuration.mdSetting up design/ directory structure
change-notification-protocol.mdNotifying agents of config changes
artifact-sharing-protocol.mdSharing build artifacts between agents
bug-reporting-protocol.mdReceiving and handling bug reports

RULE 15: No Implementation by Orchestrator

The orchestrator NEVER:

  • •Writes code
  • •Runs builds
  • •Edits source files
  • •Sets up infrastructure

Full rule: rule-15-no-implementation.md

  • •1.0 What orchestrator never does
  • •2.0 Task delegation self-check
  • •3.0 Correct vs incorrect usage examples

RULE 14: User Requirements Are Immutable

Every task delegation MUST include:

  1. •Requirement Reference - Exact user quotes
  2. •Forbidden Actions - What agents cannot change
  3. •Escalation Protocol - What to do if requirements have issues

Full rule: rule-14-immutable-requirements.md

  • •1.0 Mandatory delegation elements
  • •2.0 Violation handling
  • •3.0 User decision workflow

Skill Authoring References

DocumentUse When
skill-format-comparison.mdComparing Open Spec vs Claude Code Skills
skill-authoring-best-practices.mdWriting new skills

Skill Files

Full directory structure: skill-directory-structure.md

  • •1.0 Top-Level Structure
  • •2.0 References Directory (30+ files)
  • •3.0 Scripts Directory
  • •4.0 Templates Directory

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: curl ${AIMAESTRO_API:-http://localhost:23000}/api/health
  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
  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

Resources