emasoft/amcos-agent-replacement
skills/amcos-agent-replacement/SKILL.md
Use when replacing a failed agent with a new instance. Trigger with agent replacement or failover events. Loaded by ai-maestro-chief-of-staff-main-agent
testing
Updated Apr 26, 2026
$ install --global
skillsauthnpx skillsauth add emasoft/ai-maestro-chief-of-staff amcos-agent-replacementInstall this skill globally with one command. Works with Claude Code, Cursor, and Windsurf.
Security Scan Results
3 of 9 scanners reported clean
Some scanners were skipped, did not run, or reported a non-clean status. Review each row below.
3
Scanners Passed
9
Scanners in report
Clean
TrivyContainer and dependency vulnerability scanner
95%
Clean
SemgrepStatic code analysis for vulnerabilities
95%
Clean
mcp-scan (Snyk)Model Context Protocol security validation
95%
Skipped
Snyk (dep)Open source security scanning
50%
Skipped
Socket.devSupply chain security analysis
50%
Skipped
VirusTotalMulti-engine malware detection
50%
Skipped
CrowdStrikeAdvanced threat intelligence
50%
Skipped
OSV-ScannerOpen Source Vulnerability database check
50%
Skipped
OWASP Dep-Check
50%
Last scanned: Apr 26, 2026, 4:28 AM82.5s7 files scanned
SKILL.md
- name:
- amcos-agent-replacement
- description:
- Use when replacing a failed agent with a new instance. Trigger with agent replacement or failover events. Loaded by ai-maestro-chief-of-staff-main-agent
- user-invocable:
- false
- license:
- Apache-2.0
- compatibility:
- Requires AI Maestro installed.
- author:
- Emasoft
- version:
- 1.0.0
- context:
- fork
- agent:
- ai-maestro-chief-of-staff-main-agent
AMCOS Agent Replacement
Overview
Replace a failed agent when recovery has failed or failure is terminal. Covers failure confirmation, artifact preservation, manager approval, agent creation, orchestrator notification, and work handoff.
Prerequisites
- Failure classified as Terminal, or all recovery strategies exhausted
- AI Maestro running locally with agent registry accessible
- Handoff directory at
$CLAUDE_PROJECT_DIR/thoughts/shared/handoffs/
Instructions
Phase 4: Agent Replacement Protocol
- Confirm failure -- verify all recovery strategies attempted or failure is terminal
- Preserve artifacts -- save recoverable work to
thoughts/shared/handoffs/AGENT_NAME/ - Request approval -- send
urgentreplacement request to AMAMA; wait for approval - Create replacement -- use
ai-maestro-agents-managementskill - Notify AMOA -- so it can generate handoff docs and update kanban
- Send handoff docs to new agent (validate with checklist below)
- Verify acknowledgment -- confirm new agent received handoff and began work
- Close incident -- log resolution, notify AMAMA
Replacement Protocol Summary
Terminal failure -> AMCOS notifies AMAMA -> AMAMA approves
-> Create new agent -> Notify AMOA (handoff + kanban)
-> Send handoff to new agent -> Agent acknowledges
Key Consideration: Memory Loss
CRITICAL: The replacement agent has NO MEMORY of the old agent. Therefore:
- AMOA must generate handoff documentation
- AMOA must reassign tasks in GitHub Project kanban
- AMCOS must send handoff docs to new agent
ROLE BOUNDARY: AMCOS creates agents and sends context. AMOA owns task assignment.
Handoff Validation Checklist
Copy this checklist and track your progress:
- [ ] Required fields present (from/to/type/UUID/task/failed_agent/failure_reason)
- [ ] UUID is unique
- [ ] Target agent exists and is alive
- [ ] All referenced files exist
- [ ] No [TBD] placeholders
- [ ] Acceptance criteria defined
Output
| Phase | Output | |-------|--------| | Artifact preservation | Files saved to handoff directory | | Manager approval | Approval message from AMAMA | | Agent creation | New agent online and registered | | Work handoff | Docs sent and acknowledged |
Error Handling
| Issue | Resolution | |-------|------------| | Manager does not respond | Wait 15 min, reminder, escalate to user | | New agent fails to register | Verify AI Maestro health and hooks | | Handoff rejected | Queue and retry in 5 minutes | | No artifacts recoverable | Document loss, notify AMOA to recreate |
Examples
# Request replacement approval from manager
amp-send.sh amama-assistant-manager "Replace failed agent" urgent \
'{"type":"replacement-request","failed_agent":"ampa-svgbbox-impl","reason":"terminal crash"}'
Expected: AMAMA approves; proceed to create replacement agent and send handoff.
Checklist
Copy this checklist and track your progress:
- [ ] Confirm failure is terminal or all recovery exhausted
- [ ] Preserve recoverable artifacts to handoff directory
- [ ] Request and receive manager approval
- [ ] Create replacement agent and send handoff docs
Resources
Related Skills
emasoft/amcos-context-management
data-ai
VerifiedTrustedCommunity
Use when managing context or patterns. Trigger with context update or compaction needs. Loaded by ai-maestro-chief-of-staff-main-agent
SKILL.mdUpdated Apr 26, 2026
emasoft/amcos-context-management-ref
data-ai
VerifiedTrustedCommunity
Use when consulting detailed context management references. Trigger with context management lookups. Loaded by ai-maestro-chief-of-staff-main-agent
SKILL.mdUpdated Apr 26, 2026
emasoft/amcos-config-snapshot
data-ai
VerifiedTrustedCommunity
Use when capturing config snapshots, detecting config changes, or resolving config version conflicts. Trigger with config management or snapshot needs. Loaded by ai-maestro-chief-of-staff-main-agent
SKILL.mdUpdated Apr 26, 2026
emasoft/amcos-config-snapshot-ref
data-ai
VerifiedTrustedCommunity
Use when consulting detailed config snapshot references. Trigger with config snapshot lookups. Loaded by ai-maestro-chief-of-staff-main-agent
SKILL.mdUpdated Apr 26, 2026