| name | eoa-agent-replacement |
| description | Use when replacing agents. Trigger with agent replacement or handoff requests. |
| license | Apache-2.0 |
| compatibility | Requires Python 3.8+, PyYAML, GitHub CLI. Requires AI Maestro for inter-agent messaging. Requires ECOS notifications for replacement triggers. Requires AI Maestro installed. |
| metadata | {"author":"Emasoft","version":"1.0.0"} |
| user-invocable | false |
| context | fork |
| agent | eoa-main |
| workflow-instruction | support |
| procedure | support-skill |
Agent Replacement Skill
Overview
Handle agent replacement scenarios triggered by ECOS (Emergency Context-loss Operations System). When an agent fails, becomes unresponsive, or experiences context loss, compile all task context and generate handoff documents for the replacement agent.
Prerequisites
- Python 3.8+ with PyYAML installed
- GitHub CLI (gh) authenticated
- AI Maestro running for inter-agent messaging
- ECOS system operational for replacement notifications
- Active orchestration state with agent assignments
Output
| Output Type | Location | Format |
|---|
| Handoff Document | GitHub issue comment | Markdown with task context, progress, next steps |
| State File Update | Orchestrator state YAML | Updated agent assignment with replacement metadata |
| ECOS Confirmation | AI Maestro message | JSON confirmation with replacement status |
| Kanban Reassignment | GitHub Project board | Updated assignee on all task cards |
Instructions
- Receive and acknowledge the ECOS replacement notification via AI Maestro
- Compile all task context from the failed agent (assignments, progress, blockers, file changes)
- Generate a comprehensive handoff document with all necessary context
- Reassign GitHub Project kanban tasks to the replacement agent
- Send the handoff document to the new agent using the
agent-messaging skill and request acknowledgment
- Confirm replacement by verifying ACK, updating state, and notifying ECOS
Use this skill when: ECOS notifies you of agent failure, context loss, unresponsive behavior, or manual replacement is needed.
Checklist
Copy this checklist and track your progress:
Contents
Replacement Protocol Flow
ECOS → EOA: Agent X failed, replacement is Agent Y
↓
EOA: Compile all task context for Agent X
↓
EOA: Generate comprehensive handoff document
↓
EOA: Update GitHub Project kanban (reassign tasks)
↓
EOA: Send handoff to replacement agent
↓
EOA: Confirm reassignment complete
CRITICAL: Before any replacement action: SAVE all state, DOCUMENT progress, PRESERVE communication history, NEVER assume new agent has any context.
Step 1: Receive ECOS Notification
Acknowledge ECOS notification, pause new assignments, begin context compilation.
See: ecos-notification-handling.md - 1.1 Notification Types, 1.2 Urgency Levels, 1.3 Acknowledgment Protocol, 1.4 Error Handling
Step 2: Compile Task Context
Gather ALL information: task assignments, requirements, current progress, blockers, file changes, communication history, GitHub issues.
python3 "${CLAUDE_PLUGIN_ROOT}/scripts/eoa_compile_replacement_context.py" \
--failed-agent "implementer-1" --output "replacement-context.md"
See: context-compilation-workflow.md - 2.1 Information Sources, 2.2 State File Extraction, 2.3 GitHub Issue Collection, 2.4 Communication History, 2.5 Git Branch Analysis
Step 3: Generate Handoff Document
Create comprehensive handoff with: metadata, task context, user requirements, progress, technical context, communication history, next steps, verification requirements.
/eoa-generate-replacement-handoff --failed-agent implementer-1 --new-agent implementer-2 --include-tasks --include-context
See: handoff-document-format.md - 3.1 Required Sections, 3.2 Task Detail Format, 3.3 Progress Documentation, 3.4 Communication History Format, 3.5 Next Steps Clarity
Step 4: Reassign Kanban Tasks
Find all cards assigned to failed agent, update assignee, add reassignment comment, preserve labels/status, log for audit.
/eoa-reassign-kanban-tasks --from-agent implementer-1 --to-agent implementer-2 --project-id PROJECT_ID
See: kanban-reassignment-protocol.md - 4.1 Finding Assigned Cards, 4.2 Updating Assignee, 4.3 Audit Comments, 4.4 Preserving State, 4.5 Handling Partial Work
Step 5: Send Handoff to New Agent
Upload handoff to GitHub issue, send AI Maestro message using the agent-messaging skill with URL, include urgency level, request ACK within timeout.
See: handoff-delivery-protocol.md - 5.1 Document Upload, 5.2 AI Maestro Notification, 5.3 ACK Requirements, 5.4 Timeout Handling
Step 6: Confirm Reassignment
Verify: new agent ACKed, requirements understood, GitHub cards updated, state file updated, ECOS notified, failed agent removed from roster.
See: confirmation-protocol.md - 6.1 ACK Verification, 6.2 State File Updates, 6.3 ECOS Notification, 6.4 Audit Logging
Python Scripts
| Script | Purpose |
|---|
eoa_compile_replacement_context.py | Gather all context about failed agent's work |
eoa_generate_replacement_handoff.py | Generate handoff document from compiled context |
eoa_reassign_kanban_tasks.py | Reassign GitHub Project cards |
eoa_confirm_replacement.py | Verify replacement completion and notify ECOS |
Error Handling
| Error | Cause | Solution |
|---|
| ECOS notification not received | AI Maestro communication failure | Check AI Maestro service status |
| Context compilation failed | State file missing or git unavailable | See troubleshooting.md section 7.2 |
| Handoff generation failed | Template or incomplete data error | See troubleshooting.md section 7.3 |
| GitHub API rate limit | Too many API calls | Wait or use batch operations |
| New agent ACK timeout | Agent unresponsive | Retry or alert user |
See: troubleshooting.md for detailed troubleshooting procedures.
See: emergency-procedures.md for critical failure scenarios.
Examples
See: examples.md - Standard replacement flow, emergency replacement with partial context
Resources
Related Skills
eoa-remote-agent-coordinator - Agent registration and assignmenteoa-remote-agent-coordinator - Remote agent communicationeoa-orchestration-patterns - General orchestration patternseoa-agent-replacement - Shared handoff protocols
Version: 1.0.0 | Last Updated: 2026-02-03
