ecos-notification-protocols

Emasoft Chief of Staff - Notification Protocols Skill

Overview

Notification protocols ensure agents are properly informed about operations that affect them. Before performing operations like skill installation, agent restart, or configuration changes, the Chief of Staff must notify affected agents, wait for acknowledgment, and then proceed. This skill teaches you how to send pre-operation notifications, handle acknowledgment workflows, and report failures.

Prerequisites

Before using this skill, ensure:

1. AI Maestro messaging system is running
2. Target agents are registered and reachable
3. Notification templates are available

Instructions

1. Identify the notification type needed
2. Select appropriate notification template
3. Send notification using the agent-messaging skill
4. Verify delivery and acknowledgment

Output

Notification Type	Output
Status update	Notification sent, delivery confirmed
Alert	Alert sent, escalation tracked
Broadcast	Message sent to all agents, receipt logged

What Are Notification Protocols?

Notification protocols are the standardized communication patterns the Chief of Staff uses to coordinate with other agents during operations. The protocols ensure:

• No surprise interruptions: Agents know when operations will affect them
• Graceful state preservation: Agents have time to save work before operations
• Acknowledgment tracking: Operations proceed only when agents are ready
• Failure transparency: Agents are informed when operations fail

Protocol Types

┌───────────────────────────────────────────────────────────────────┐
│                    NOTIFICATION PROTOCOLS                          │
├───────────────────┬───────────────────┬───────────────────────────┤
│  PRE-OPERATION    │  POST-OPERATION   │  FAILURE                   │
│  Notifications    │  Notifications    │  Notifications             │
├───────────────────┼───────────────────┼───────────────────────────┤
│  - Warn agents    │  - Confirm done   │  - Report failures         │
│  - Request ack    │  - Ask verify     │  - Provide diagnostics     │
│  - Wait for ok    │  - Resume work    │  - Suggest recovery        │
└───────────────────┴───────────────────┴───────────────────────────┘

Protocol Flow:

1. PRE-OPERATION -> Send warning, wait for acknowledgment
2. EXECUTE -> Perform the operation
3. POST-OPERATION or FAILURE -> Send confirmation or failure notification

Core Procedures

PROCEDURE 1: Pre-Operation Notification

When to use: Before skill installation, plugin installation, agent restart, configuration changes, or any operation that will interrupt an agent.

Steps: Identify affected agents, compose notification message, send via AI Maestro, track acknowledgments, handle timeouts.

Related documentation:

Pre-Operation Notifications (references/pre-operation-notifications.md)

• 1.1 What are pre-operation notifications - Understanding warning messages
• 1.2 When to send pre-operation notifications - Notification triggers
  • 1.2.1 Skill installation - Agent will be hibernated and woken
  • 1.2.2 Plugin installation - Agent restart required
  • 1.2.3 Configuration changes - Settings will change
  • 1.2.4 System maintenance - Temporary disruption expected
• 1.3 Pre-operation notification procedure - Step-by-step process
  • 1.3.1 Identify affected agents - Who needs to know
  • 1.3.2 Compose notification - What to tell them
  • 1.3.3 Send notification - Using AI Maestro API
  • 1.3.4 Track acknowledgments - Monitor responses
  • 1.3.5 Handle timeouts - When agents don't respond
• 1.4 Notification message format - Standard message structure
• 1.5 Priority levels - When to use each priority
• 1.6 Examples - Pre-operation scenarios
• 1.7 Troubleshooting - Notification delivery issues

PROCEDURE 2: Post-Operation Notification

When to use: After skill installation completes, after agent restart, after configuration changes apply, or after any operation that affected an agent.

Steps: Confirm operation completed, compose success message, send confirmation, request verification, log outcome.

Related documentation:

Post-Operation Notifications (references/post-operation-notifications.md)

• 2.1 What are post-operation notifications - Understanding confirmation messages
• 2.2 When to send post-operation notifications - Confirmation triggers
  • 2.2.1 Skill installation complete - Skill is now active
  • 2.2.2 Agent restart complete - Agent is back online
  • 2.2.3 Configuration applied - Settings now active
  • 2.2.4 Maintenance complete - Normal operations resume
• 2.3 Post-operation notification procedure - Step-by-step process
  • 2.3.1 Confirm operation success - Verify completion
  • 2.3.2 Compose confirmation - What to tell agents
  • 2.3.3 Send notification - Using AI Maestro API
  • 2.3.4 Request verification - Ask agent to confirm
  • 2.3.5 Log outcome - Record the result
• 2.4 Verification request format - Asking agents to confirm
• 2.5 Examples - Post-operation scenarios
• 2.6 Troubleshooting - Verification issues

PROCEDURE 3: Acknowledgment Protocol

When to use: When you need agent confirmation before proceeding, when operations require agent readiness, or when coordinating multi-agent operations.

Steps: Send acknowledgment request, start timeout timer, send reminders, process response, proceed or handle timeout.

Related documentation:

Acknowledgment Protocol (references/acknowledgment-protocol.md)

• 3.1 What is the acknowledgment protocol - Understanding coordination
• 3.2 When to require acknowledgments - Acknowledgment triggers
  • 3.2.1 Disruptive operations - Agent will be interrupted
  • 3.2.2 State-changing operations - Agent context affected
  • 3.2.3 Multi-agent coordination - Synchronized actions needed
• 3.3 Acknowledgment procedure - Step-by-step process
  • 3.3.1 Send acknowledgment request - Ask for "ok"
  • 3.3.2 Start timeout timer - See standardized timeouts below
  • 3.3.3 Send reminders - At 15s, 30s, 45s intervals for pre-operation ACK
  • 3.3.4 Process response - Handle "ok" or other responses
  • 3.3.5 Proceed or timeout - Continue or handle no response
• 3.4 Acknowledgment message format - Standard request structure
• 3.5 Reminder message format - Standard reminder structure
• 3.6 Response handling - What agents can send back
• 3.7 Timeout behavior - What happens without response
• 3.8 Examples - Acknowledgment scenarios
• 3.9 Troubleshooting - Acknowledgment issues

Standardized ACK Timeout Policy

CRITICAL: All ECOS components MUST use these standardized timeout values:

ACK Type	Timeout	Reminders	Use Case
Pre-operation ACK	60 seconds	15s, 30s, 45s	Before disruptive operations (hibernate, restart, etc.)
Approval request	2 minutes	60s, 90s	Requesting manager approval for operations
Emergency handoff ACK	30 seconds	10s, 20s	Time-critical emergency situations
Health check response	30 seconds	None	Verifying agent is alive

Important: These timeouts are SEQUENTIAL, not parallel. Total wait time calculation:

Example: Skill installation with approval

1. Pre-operation ACK request to agent    → Wait up to 60 seconds
2. Approval request to EAMA              → Wait up to 2 minutes
3. Post-operation verification           → Wait up to 30 seconds
                                           ─────────────────────
Total maximum wait time                  = 3 minutes 30 seconds

Timeout behavior:

• Pre-operation ACK timeout: Send final notice, then proceed with operation
• Approval request timeout: Log timeout, proceed if autonomous mode enabled, otherwise abort
• Emergency handoff ACK timeout: Proceed immediately (cannot wait in emergencies)

PROCEDURE 4: Failure Notification

When to use: When skill installation fails, when agent restart fails, when configuration change fails, or when any operation error occurs.

Steps: Capture error details, compose failure message, send to affected agents, provide recovery guidance, log failure.

Related documentation:

Failure Notifications (references/failure-notifications.md)

• 4.1 What are failure notifications - Understanding error messages
• 4.2 When to send failure notifications - Failure triggers
  • 4.2.1 Installation failures - Skill or plugin not installed
  • 4.2.2 Restart failures - Agent did not come back online
  • 4.2.3 Configuration failures - Settings not applied
  • 4.2.4 Timeout failures - Operation did not complete in time
• 4.3 Failure notification procedure - Step-by-step process
  • 4.3.1 Capture error details - What went wrong
  • 4.3.2 Compose failure message - What to tell agents
  • 4.3.3 Send notification - Using AI Maestro API
  • 4.3.4 Provide recovery guidance - How to proceed
  • 4.3.5 Log failure - Record for analysis
• 4.4 Failure message format - Standard error structure
• 4.5 Error severity levels - Critical, error, warning
• 4.6 Recovery guidance patterns - Common recovery steps
• 4.7 Examples - Failure scenarios
• 4.8 Troubleshooting - Notification delivery during failures

Task Checklist

Copy this checklist and track your progress:

• Understand the four notification protocol types
• Learn PROCEDURE 1: Pre-operation notification
• Learn PROCEDURE 2: Post-operation notification
• Learn PROCEDURE 3: Acknowledgment protocol
• Learn PROCEDURE 4: Failure notification
• Practice sending pre-operation notification with acknowledgment
• Practice sending post-operation confirmation
• Practice handling acknowledgment timeout
• Practice sending failure notification
• Verify message delivery via AI Maestro

Examples

Example 1: Skill Installation Notification Flow (Complete)

This example shows the full notification flow for installing a skill on an agent.

Step 1: Send Pre-Operation Notification

Use the agent-messaging skill to send a message:

• Recipient: code-impl-auth
• Subject: Skill Installation Pending
• Priority: high
• Content: type pre-operation, message explaining the upcoming skill installation, expected downtime of 30 seconds, and that acknowledgment is required

Verify: confirm message delivery.

Step 2: Wait for Acknowledgment (with reminders)

Use the agent-messaging skill to check for unread messages from code-impl-auth with type acknowledgment.

If no response after 30 seconds, use the agent-messaging skill to send a reminder:

• Recipient: code-impl-auth
• Subject: Reminder: Skill Installation Pending
• Priority: high
• Content: type reminder, noting 90 seconds remaining

Verify: check for acknowledgment response.

Step 3: Receive Acknowledgment

Note: Use the agent-messaging skill to send messages. The JSON structure below shows the message content.

{
  "from": "code-impl-auth",
  "to": "chief-of-staff",
  "subject": "RE: Skill Installation Pending",
  "content": {
    "type": "acknowledgment",
    "message": "ok",
    "ready": true
  }
}

Step 4: Perform Installation

Use the ai-maestro-agents-management skill to hibernate agent code-impl-auth, install the skill, then wake agent code-impl-auth.

Verify: agent is back online after wake.

Step 5: Send Post-Operation Notification

Use the agent-messaging skill to send a message:

• Recipient: code-impl-auth
• Subject: Skill Installation Complete
• Priority: normal
• Content: type post-operation, confirming that the security-audit skill has been installed, requesting the agent to verify the skill is active

Verify: confirm message delivery and await agent verification response.

Example 2: Handling Acknowledgment Timeout

After 2 minutes with no response, proceed anyway:

1. Log the timeout: WARNING: No acknowledgment from code-impl-auth after 2 minutes.

2. Use the agent-messaging skill to send a final notice:

   • Recipient: code-impl-auth
   • Subject: Proceeding Without Acknowledgment
   • Priority: high
   • Content: type timeout-notice, explaining that no response was received and the operation will proceed

3. Use the ai-maestro-agents-management skill to hibernate agent code-impl-auth and proceed with installation.

Verify: confirm final notice was delivered.

Example 3: Failure Notification

When a skill installation fails, use the agent-messaging skill to send a failure notification:

• Recipient: code-impl-auth
• Subject: Skill Installation Failed
• Priority: high
• Content: type failure, explaining the error (e.g., "Skill validation failed - missing required SKILL.md file"), advising the agent to continue previous work, and noting the recovery action (skill package will be fixed and installation retried)

Verify: confirm message delivery.

Example 4: Broadcast Notification to Multiple Agents

For each target agent (code-impl-auth, test-engineer-01, docs-writer), use the agent-messaging skill to send a message:

• Recipient: each agent in the list
• Subject: System Maintenance in 5 Minutes
• Priority: high
• Content: type broadcast, explaining that system maintenance will begin in 5 minutes, all agents will be hibernated, and they should save their work and reply with "ok" when ready. Include the total recipient count and a broadcast ID for tracking.

Verify: confirm delivery to all recipients and track acknowledgments.

Operational Procedures

Step-by-step runbooks for executing individual notification operations. Use these when performing a specific notification operation.

• op-pre-operation-notification.md - Pre-Operation Notification: Identify affected agents, compose notification message, send notification, track acknowledgments, and handle timeouts before disruptive operations
• op-post-operation-notification.md - Post-Operation Notification: Confirm operation completed, compose success message, send confirmation to affected agents, request verification, and log outcome
• op-acknowledgment-protocol.md - Acknowledgment Protocol: Send acknowledgment request, start timeout timer with standardized policy, send reminders at intervals, process response, and proceed or handle timeout
• op-failure-notification.md - Failure Notification: Capture error details, compose failure message with severity level, send notification to affected agents, provide recovery guidance, and log failure

Error Handling

Issue: Notification not delivered

Symptoms: Agent does not receive message, no response observed.

See references/pre-operation-notifications.md Section 1.7 Troubleshooting for resolution.

Issue: Acknowledgment timeout

Symptoms: Agent does not respond within 2 minutes.

See references/acknowledgment-protocol.md Section 3.9 Troubleshooting for resolution.

Issue: Agent sends unexpected response

Symptoms: Agent responds with something other than "ok".

See references/acknowledgment-protocol.md Section 3.6 Response handling for resolution.

Issue: Failure notification not received

Symptoms: Agent unaware of operation failure.

See references/failure-notifications.md Section 4.8 Troubleshooting for resolution.

Key Takeaways

1. Always notify before disruptive operations - Never surprise agents with interruptions
2. Use acknowledgment protocol for critical operations - Wait for "ok" before proceeding
3. Send reminders at 30s, 60s, 90s - Give agents multiple chances to respond
4. Proceed after 2 minute timeout - Do not wait indefinitely
5. Log timeout occurrences - Track agents that did not respond
6. Send post-operation confirmations - Let agents verify success
7. Request verification after installation - Ask agents to confirm skill is active
8. Provide recovery guidance in failures - Tell agents what happens next

Message Type Quick Reference

Message Type	When to Use	Requires Ack
pre-operation	Before any disruptive operation	Yes
post-operation	After successful operation	Optional
reminder	When awaiting acknowledgment	No
timeout-notice	When proceeding without ack	No
failure	When operation fails	No
broadcast	Notifying multiple agents	Yes
acknowledgment	Agent responding with "ok"	No

Next Steps

1. Read Pre-Operation Notifications

See references/pre-operation-notifications.md for complete pre-operation documentation.

2. Read Post-Operation Notifications

See references/post-operation-notifications.md for confirmation procedures.

3. Read Acknowledgment Protocol

See references/acknowledgment-protocol.md for detailed acknowledgment handling.

4. Read Failure Notifications

See references/failure-notifications.md for error notification procedures.

---

Resources

• Pre-Operation Notifications
• Post-Operation Notifications
• Acknowledgment Protocol
• Failure Notifications
• AI Maestro Message Templates - Standard message templates for inter-agent communication
• Message Response Decision Tree - Decision tree for routing AI Maestro messages by priority and type
• Design Document Protocol - Standards for design documents in the design/ folder
• Proactive Handoff Protocol - Automatic handoff triggers and inter-agent work transfer
• Task Completion Checklist - Pre-completion verification checklist for Chief of Staff operations
• Edge Case Protocols - Protocols for failure scenarios and edge cases in ECOS operations

---

Version: 1.0 Last Updated: 2025-02-02 Target Audience: Chief of Staff Agents Difficulty Level: Intermediate