# Epa Orchestrator Communication

> Communication with EOA Orchestrator via AI Maestro. Use when sending clarifications, status updates, blockers, or completions. Trigger with /epa-orchestrator-comm. Use when this capability is needed.

- Skill: `tomevault-io/epa-orchestrator-communication` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add tomevault-io/epa-orchestrator-communication`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/epa-orchestrator-communication/raw
- Safety review: pending (external: skill-scanner PASS, skillspector CAUTION)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: tomevault-io (https://skillmd.com/u/tomevault-io)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tomevault-io/epa-orchestrator-communication

---


# EPA Orchestrator Communication Skill

This skill defines all communication protocols between the Emasoft Programmer Agent (EPA) and the Emasoft Orchestrator Agent (EOA). Use this skill whenever you need to interact with the orchestrator for clarifications, status updates, blocking issues, improvement proposals, or task completion notifications.

## Overview

The EPA-EOA communication channel uses asynchronous inter-agent messaging provided by the globally installed `agent-messaging` skill. That skill defines the current commands and syntax for sending, receiving, reading, replying to, and checking the status of messages. Always read the `agent-messaging` skill at runtime to determine the exact commands -- never hardcode messaging command names in your workflow.

## When to Use This Skill

Use this skill in the following situations:

| Situation | Operation | Reference File |
|-----------|-----------|----------------|
| Task requirements are unclear or ambiguous | Request Clarification | [op-request-clarification.md](references/op-request-clarification.md) |
| Need to report current development status | Report Status | [op-report-status.md](references/op-report-status.md) |
| Encountered a blocking issue that prevents progress | Report Blocker | [op-report-blocker.md](references/op-report-blocker.md) |
| Have suggestions for design or task improvements | Propose Improvement | [op-propose-improvement.md](references/op-propose-improvement.md) |
| Task implementation is complete and ready for review | Notify Completion | [op-notify-completion.md](references/op-notify-completion.md) |
| Received feedback from EOA after PR review | Receive Feedback | [op-receive-feedback.md](references/op-receive-feedback.md) |

## Communication Architecture

```
EPA (Programmer Agent)          AI Maestro           EOA (Orchestrator Agent)
        |                           |                           |
        |--- Send Message --------->|                           |
        |                           |--- Deliver Message ------>|
        |                           |                           |
        |                           |<-- Response Message ------|
        |<--- Deliver Response -----|                           |
        |                           |                           |
```

## Message Priority Levels

| Priority | Use Case | Expected Response Time |
|----------|----------|------------------------|
| `urgent` | Blocking issues, critical failures | Immediate (within minutes) |
| `high` | Clarifications needed to continue, completion notifications | Within 30 minutes |
| `normal` | Status updates, improvement proposals | Within 2 hours |

## Message Types

All messages to EOA must include a `type` field in the content object:

| Type | Description |
|------|-------------|
| `clarification-request` | Asking for task clarification |
| `status-update` | Reporting development progress |
| `blocker-report` | Reporting blocking issues |
| `improvement-proposal` | Suggesting design improvements |
| `completion-notification` | Task is done, ready for review |
| `feedback-acknowledgment` | Acknowledging received feedback |

## Prerequisites

Before using any operation in this skill:

1. **Messaging identity is initialized**: Read the `agent-messaging` skill and follow its initialization instructions. Verify your identity is set up before sending any messages.
2. **Messaging service is operational**: Use the `agent-messaging` skill's status check operation to confirm connectivity.
3. **EOA is active**: The orchestrator agent session must be available.

## Operations Reference

### 1. Request Clarification (Step 14)

Use when task requirements are unclear or need additional information.

**Reference**: [op-request-clarification.md](references/op-request-clarification.md)

**Contents**:
- 1.1 When to Request Clarification
- 1.2 Clarification Request Format
- 1.3 Sending the Request
- 1.4 Handling the Response
- 1.5 Examples

### 2. Report Status (Step 17)

Use to send "in development" status updates to keep EOA informed.

**Reference**: [op-report-status.md](references/op-report-status.md)

**Contents**:
- 2.1 When to Report Status
- 2.2 Status Message Format
- 2.3 Progress Indicators
- 2.4 Sending Status Updates
- 2.5 Examples

### 3. Report Blocker

Use when you encounter issues that prevent task progress.

**Reference**: [op-report-blocker.md](references/op-report-blocker.md)

**Contents**:
- 3.1 Identifying Blockers
- 3.2 Blocker Report Format
- 3.3 Severity Levels
- 3.4 Escalation Procedure
- 3.5 Examples

### 4. Propose Improvement (Step 15)

Use to suggest design or implementation improvements.

**Reference**: [op-propose-improvement.md](references/op-propose-improvement.md)

**Contents**:
- 4.1 When to Propose Improvements
- 4.2 Improvement Proposal Format
- 4.3 Justification Requirements
- 4.4 Awaiting Approval
- 4.5 Examples

### 5. Notify Completion (Step 19)

Use when task implementation is complete and ready for review.

**Reference**: [op-notify-completion.md](references/op-notify-completion.md)

**Contents**:
- 5.1 Completion Criteria
- 5.2 Completion Notification Format
- 5.3 Deliverables Summary
- 5.4 Sending Notification
- 5.5 Examples

### 6. Receive Feedback

Use to handle feedback from EOA after PR review.

**Reference**: [op-receive-feedback.md](references/op-receive-feedback.md)

**Contents**:
- 6.1 Monitoring for Feedback
- 6.2 Feedback Message Types
- 6.3 Processing Feedback
- 6.4 Acknowledgment Protocol
- 6.5 Examples

## Messaging Quick Reference

All messaging operations below are performed using the `agent-messaging` skill. Read that skill to learn the current command syntax.

### Send Message to EOA

Send a message to the orchestrator using the `agent-messaging` skill:
- **Recipient**: your assigned orchestrator agent
- **Subject**: the subject line for this message
- **Content**: the message body text
- **Type**: the message type (see Message Types table above)
- **Priority**: the priority level (see Message Priority Levels table above)

**Verify**: confirm the message appears in your sent messages.

### Check for Messages from EOA

Check your inbox using the `agent-messaging` skill. Process all unread messages before proceeding.

### Read a Specific Message

Read the message by its ID using the `agent-messaging` skill to see its full content.

### Reply to a Message (Acknowledge)

Reply to the message using the `agent-messaging` skill, confirming receipt and stating your next action.

### Check Messaging Status

Use the `agent-messaging` skill's status check operation to verify the messaging service is running and your identity is configured.

### Verify Messaging Identity

Use the `agent-messaging` skill's identity check operation to confirm your session name is registered as your messaging identity.

## Error Handling

| Error | Cause | Resolution |
|-------|-------|------------|
| Identity not found | Messaging not initialized | Read the `agent-messaging` skill and follow its initialization instructions |
| Recipient not found | EOA session not registered | Wait for EOA to start or notify user |
| Message delivery failed | Network or service issue | Retry the send operation using the `agent-messaging` skill |
| Messaging service offline | Service not running | Use the `agent-messaging` skill's status check, restart AI Maestro service |

## Checklist

Copy this checklist and track your progress:

- [ ] Initialize messaging identity via agent-messaging skill
- [ ] Verify messaging service status
- [ ] Confirm EOA is active and reachable
- [ ] Determine communication type (clarification, status, blocker, improvement, completion, feedback)
- [ ] Read the operation reference file for the chosen type
- [ ] Compose and send the message with correct type, priority, and content
- [ ] Verify delivery in sent messages list
- [ ] Monitor for and process EOA response
- [ ] Acknowledge receipt of any EOA reply

## Troubleshooting

### Messaging Connection Issues

If messaging operations fail:

1. Use the `agent-messaging` skill's status check operation to verify connectivity
2. Use the `agent-messaging` skill's identity check operation to verify your identity is set up
3. Re-initialize your identity following the `agent-messaging` skill's initialization instructions

### EOA Not Responding

If EOA does not respond within expected time:

1. Check the messaging service status using the `agent-messaging` skill
2. Escalate to user if EOA is unavailable
3. Document the delay in status update

### Message Delivery Failures

If message delivery fails:

1. Verify recipient name is correct
2. Check messaging service status using the `agent-messaging` skill
3. Retry up to 3 times with 5-second delays
4. Report to user if all retries fail

## Instructions

Follow these numbered steps whenever you need to communicate with the Emasoft Orchestrator Agent (EOA):

1. **Initialize messaging identity**: Read the `agent-messaging` skill and follow its initialization instructions. Verify your session name is registered before proceeding.
2. **Verify messaging service status**: Use the `agent-messaging` skill's status check operation to confirm the service is running and reachable.
3. **Confirm EOA is active**: Check that the orchestrator agent session is registered and available to receive messages.
4. **Determine the communication type**: Identify which operation applies to your situation using the "When to Use This Skill" table above (clarification request, status update, blocker report, improvement proposal, completion notification, or feedback acknowledgment).
5. **Read the operation reference file**: Open the corresponding reference file listed in the Operations Reference section to learn the exact message format and required fields for that operation type.
6. **Compose the message**: Build the message with the correct `type` field, appropriate `priority` level, descriptive `subject` line, and structured `content` body as specified in the reference file.
7. **Send the message**: Use the `agent-messaging` skill's send operation to deliver the message to your assigned EOA session name.
8. **Verify delivery**: Confirm the message appears in your sent messages list using the `agent-messaging` skill.
9. **Monitor for response**: Periodically check your inbox for replies from EOA. Process all unread messages before continuing other work.
10. **Acknowledge receipt**: When you receive a response from EOA, reply using the `agent-messaging` skill to confirm you received it and state your next planned action.

## Output

This skill produces the following artifacts and outcomes:

- **Outbound AI Maestro messages**: Structured JSON messages sent from EPA to EOA, each containing a `type` field (one of the six message types), a `priority` level, a `subject` line, and a formatted `content` body.
- **Delivery confirmations**: Verification that each sent message was accepted by the AI Maestro messaging service and appears in the sent messages list.
- **Acknowledgment replies**: Reply messages sent back to EOA confirming receipt of feedback or instructions, stating the EPA's next action.
- **Communication audit trail**: A chronological record of all EPA-EOA exchanges visible in both agents' message histories, providing traceability for task progress and decisions.

## Examples

### Example 1: Requesting Clarification on Ambiguous Task Requirements

The EPA receives a task to "implement data validation" but the acceptance criteria do not specify which fields require validation or what validation rules to apply.

**Action**: Send a clarification request message to EOA:
- **Type**: `clarification-request`
- **Priority**: `high`
- **Subject**: "Clarification needed: data validation scope for task PROJ-42"
- **Content**: "Task PROJ-42 says 'implement data validation' but does not specify which fields need validation or what rules apply. Questions: (1) Which input fields require validation? (2) Should validation be schema-based or custom rule-based? (3) Are there existing validation patterns in the codebase to follow?"

**Expected outcome**: EOA replies with specific field names, validation rules, and a pointer to existing patterns.

### Example 2: Reporting a Blocking Issue

The EPA discovers that a required dependency package is not available in the project environment and cannot proceed with implementation.

**Action**: Send a blocker report message to EOA:
- **Type**: `blocker-report`
- **Priority**: `urgent`
- **Subject**: "BLOCKER: Missing dependency 'pydantic-settings' for task PROJ-42"
- **Content**: "Cannot proceed with task PROJ-42. The package 'pydantic-settings>=2.0' is required for config validation but is not listed in pyproject.toml and is not installed in the project environment. Attempted workarounds: none (adding dependencies is outside EPA scope). Requesting EOA to authorize adding this dependency or provide an alternative approach."

**Expected outcome**: EOA authorizes the dependency addition or reassigns the task with updated instructions.

### Example 3: Notifying Task Completion

The EPA finishes implementing the feature, all tests pass, and the code is committed and pushed to a feature branch.

**Action**: Send a completion notification message to EOA:
- **Type**: `completion-notification`
- **Priority**: `high`
- **Subject**: "Task PROJ-42 complete: data validation implemented"
- **Content**: "Task PROJ-42 is complete and ready for review. Branch: feature/proj-42-data-validation. Commit: abc1234. Deliverables: (1) src/validators/data_validator.py - new validation module, (2) tests/test_data_validator.py - 12 passing tests, (3) Updated pyproject.toml with pydantic-settings dependency. All tests pass locally. PR created: #87."

**Expected outcome**: EOA acknowledges receipt and routes the PR to the Emasoft Integrator Agent (EIA) for code review.

## Resources

- [op-request-clarification.md](references/op-request-clarification.md) - Detailed format and procedure for sending clarification requests to EOA
- [op-report-status.md](references/op-report-status.md) - Format and timing guidelines for development status updates
- [op-report-blocker.md](references/op-report-blocker.md) - Blocker report format, severity levels, and escalation procedure
- [op-propose-improvement.md](references/op-propose-improvement.md) - Format for design and implementation improvement proposals
- [op-notify-completion.md](references/op-notify-completion.md) - Completion notification format and deliverables summary requirements
- [op-receive-feedback.md](references/op-receive-feedback.md) - How to monitor, process, and acknowledge feedback from EOA
- `agent-messaging` skill (globally installed) - Provides the actual messaging commands and syntax used by all operations in this skill

---
> Converted and distributed by [TomeVault](https://tomevault.io/claim/emasoft) — claim your Tome and manage your conversions.
<!-- tomevault:4.0:skill_md:2026-04-14 -->