emasoft/amcos-agent-coordination

Agent Coordination

Overview

Manages team registry, messaging, role boundaries, and delegation.

Prerequisites

• AI Maestro running with agent-messaging skill
• Registry via REST API (GET /api/teams/{id}/agents)
• Script: uv run python scripts/amcos_team_registry.py

Instructions

1. Identify the coordination action needed (registry, messaging, delegation)
2. Execute the action using the appropriate procedure below
3. Verify the result and update team registry
4. Log the operation and notify affected agents

Team Registry

Commands: create, add-agent, remove-agent, update-status, list, publish

Steps: Identify type -> Execute -> Verify via list -> Optionally publish -> Backup

Inter-Agent Messaging

Use agent-messaging skill. Always use FULL session names (e.g., amoa-svgbbox-orchestrator).

Message types: role-assignment, project-assignment, task-delegation, status-request, status-report, team-notification, hibernation-warning, wake-notification, registry-update

Standards: Include from field. Acknowledge role assignments. Retry 3x before escalating.

Role Boundaries (CRITICAL)

• AMCOS is TEAM-SCOPED (one per team)
• AMCOS CREATES agents and ASSIGNS to teams
• AMCOS does NOT assign tasks (AMOA's job)
• AMCOS does NOT manage kanban (AMOA's job)
• AMCOS does NOT create projects (AMAMA's job)
• AMCOS NEVER spawns a copy of itself

Agent vs Sub-Agent

| Term | Definition | |------|------------| | Agent | Separate process in own tmux session. Own context, hibernates/terminates independently. | | Sub-agent | Spawned via Task tool inside parent. Shares context, terminates with parent. |

Cross-Host Awareness

Remote ops require GovernanceRequest + ConfigOperationType. Messages route via API.

Workflow Checklists

See the workflow checklists in Resources for agent lifecycle procedures.

Output

Registry update -> state reflected. Message -> delivery confirmed. Role assignment -> acknowledged.

Error Handling

| Issue | Resolution | |-------|-----------| | Maestro unavailable | File-based fallback, retry 30s | | Delivery fails | Retry 3x/10s, escalate to AMAMA | | Registry fails | Retry 3x, fallback POST /api/teams/{id}/agents | | Boundary violation | Log, reject, notify AMAMA | | Not in registry | Verify FULL name, check if terminated |

Examples

Update Registry After Spawn

uv run python scripts/amcos_team_registry.py add-agent \
  --team svgbbox-team --name ampa-svgbbox-impl --role programmer --status running
uv run python scripts/amcos_team_registry.py list --team svgbbox-team

Send Team Notification

# Via agent-messaging: To: amoa-svgbbox-orchestrator
# Content: { "type": "team-notification", "message": "Agent online" }

Checklist

Copy this checklist and track your progress:

• [ ] Identify registry update type (add, remove, or status change)
• [ ] Execute registry command and verify via list
• [ ] Send inter-agent message using FULL session name
• [ ] Log operation and notify affected agents

Resources

• op-update-team-registry — Team registry update procedures and examples
  • When to Use
  • Prerequisites
  • Procedure
    • Step 1: Identify Update Type
    • Step 2: Execute Registry Update
    • Step 3: Verify Update
    • Step 4: Publish Update to Team (Optional)
    • Step 5: Backup Registry (Recommended)
  • Checklist
  • Examples
    • Example: Complete Agent Addition Flow
    • Example: Status Change After Hibernation
  • Error Handling
  • Related Operations
• workflow-checklists — Agent lifecycle checklists
  • 1.1 Spawning New Agent Checklist
  • 2.1 Terminating Agent Checklist
  • 3.1 Hibernating Agent Checklist
  • 4.1 Waking Agent Checklist
  • 5.1 Forming Team Checklist
  • 6.1 Updating Team Registry Checklist