ai-maestro-agent-messaging

What this skill does

# AI Maestro Agent Messaging

## Purpose
Enable communication between AI coding agents using AI Maestro's dual-channel messaging system. Agents are identified by their agent ID or alias, with tmux session names as a fallback. Supports both SENDING and RECEIVING messages.

## CRITICAL: Inter-Agent Communication

**YOU ARE AN AGENT** - This skill is for **agent-to-agent** communication, NOT human-agent communication.

### IMPORTANT: Understanding "Your Messages"

When the human operator says "check your messages" or "read your messages":
- **YOUR inbox** = Messages addressed TO YOUR AGENT (from anyone - operator, other agents, etc.)
- **NOT the operator's inbox** = You check YOUR inbox, not the operator's

**Example:**
- Human says: "Check your messages"
- You are agent: `backend-api`
- You check: `~/.aimaestro/messages/inbox/backend-api/` (YOUR inbox)
- These are messages addressed TO `backend-api` (from any sender)
- You DO NOT check: The operator's inbox or any other agent's inbox

### Agent Identity

- **Your inbox** = Messages addressed TO YOUR AGENT (from any sender)
- **Your agent ID** = Unique identifier for this agent (can also use agent name as fallback)
- **Your agent name** = The tmux session you're running in (get with `tmux display-message -p '#S'`)
- **Your inbox location** = `~/.aimaestro/messages/inbox/YOUR-AGENT-ID/` or `~/.aimaestro/messages/inbox/YOUR-AGENT-NAME/`

**You do NOT read:**
- ❌ The operator's inbox
- ❌ Other agents' inboxes
- ❌ Messages not addressed to your agent

**You DO read:**
- ✅ Messages addressed TO YOUR AGENT
- ✅ YOUR OWN inbox only
- ✅ Your agent's inbox: `~/.aimaestro/messages/inbox/YOUR-AGENT-ID/`

## When to Use This Skill

**Sending (Agent-to-Agent):**
- User (operator) says "send a message to [another-agent]"
- User says "notify [another-agent]" or "alert [another-agent]"
- User wants YOU to communicate with ANOTHER agent
- You need to send urgent alerts or requests to OTHER AGENTS

**Receiving (Check YOUR OWN Inbox):**
- User says "check my inbox" or "check my messages" = Use `check-aimaestro-messages.sh`
- User says "read my messages" or "read message X" = Use `read-aimaestro-message.sh <id>`
- User asks "any new messages?" = Use `check-aimaestro-messages.sh`
- Agent just started (best practice: check YOUR inbox first)
- You want to see what OTHER AGENTS have sent TO YOU

**RECOMMENDED WORKFLOW:**
1. First check for unread messages: `check-aimaestro-messages.sh`
2. Then read specific message: `read-aimaestro-message.sh <message-id>`
3. Message is automatically marked as read after reading

## Available Tools

## PART 1: RECEIVING MESSAGES (YOUR OWN INBOX)

**📖 QUICK START - Check and Read Messages:**
```bash
# Step 1: Check what unread messages you have
check-aimaestro-messages.sh

# Output shows:
# [msg-1234...] 🔴 From: backend-api | 2025-10-29 14:30
#     Subject: Authentication endpoint ready
#     Preview: The /api/auth/login endpoint is now...

# Step 2: Read the specific message (automatically marks as read)
read-aimaestro-message.sh msg-1234...

# Step 3: Check again - that message is now gone from unread
check-aimaestro-messages.sh
# Output: "📭 No unread messages"
```

**⚠️ CRITICAL: What "YOUR inbox" means:**
- YOU = The AI agent running in this tmux session
- YOUR inbox = `~/.aimaestro/messages/inbox/YOUR-AGENT-ID/` (or agent name as fallback)
- Messages in YOUR inbox = Messages OTHER AGENTS sent TO YOU
- NOT the operator's messages, NOT other agents' private messages

**IMPORTANT:** These commands check YOUR AGENT'S inbox only. They automatically:
1. Detect your current agent ID or agent name
2. Read from `~/.aimaestro/messages/inbox/YOUR-AGENT-ID/`
3. Show messages that OTHER AGENTS sent TO YOU
4. Do NOT access anyone else's inbox

### 1. Check YOUR Inbox for UNREAD Messages (Recommended)
**Command:**
```bash
check-aimaestro-messages.sh [--mark-read]
```

**What it does:**
- Shows ONLY UNREAD messages in YOUR inbox (messages sent TO YOUR AGENT)
- Automatically detects YOUR agent's session
- Displays: priority indicator, sender, subject, preview, timestamp
- Optional `--mark-read` flag to mark all messages as read after viewing
- **This is the recommended way to check messages** - avoids re-reading old messages

**Example:**
```bash
# Check unread messages without marking as read
check-aimaestro-messages.sh

# Check and mark all as read
check-aimaestro-messages.sh --mark-read
```

**Output format:**
```
📬 You have 3 unread message(s)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

[msg-167...] 🔴 From: backend-architect | 2025-10-29 13:45
    Subject: API endpoint ready
    Preview: The POST /api/auth/login endpoint is now...

[msg-168...] 🔵 From: frontend-dev | 2025-10-29 14:20
    Subject: Need help with styling
    Preview: Can you review the CSS for the navigation...
```

### 2. Read Specific Message and Mark as Read
**Command:**
```bash
read-aimaestro-message.sh <message-id> [--no-mark-read]
```

**What it does:**
- Retrieves and displays the full message content
- **Automatically marks the message as read** (unless `--no-mark-read` flag)
- Shows all message details: content, context, forwarding info
- Perfect for reading a specific message after checking the list

**Example:**
```bash
# Read message (automatically marks as read)
read-aimaestro-message.sh msg-1234567890-abc

# Peek at message without marking as read
read-aimaestro-message.sh msg-1234567890-abc --no-mark-read
```

**Output format:**
```
═══════════════════════════════════════════════════════════════
📧 Message: API endpoint ready
═══════════════════════════════════════════════════════════════

From:     backend-architect
To:       frontend-dev
Date:     2025-10-29 13:45:00
Priority: 🔴 urgent
Type:     response

───────────────────────────────────────────────────────────────

The POST /api/auth/login endpoint is now deployed and ready...

───────────────────────────────────────────────────────────────
📎 Context:
{
  "endpoint": "/api/auth/login"
}

✅ Message marked as read
═══════════════════════════════════════════════════════════════
```

### 3. Auto-Display on Agent Start (Legacy - DO NOT USE MANUALLY)
**Command:**
```bash
check-and-show-messages.sh
```

**What it does:**
- Automatically runs when you attach to a tmux session
- Shows a summary of unread messages
- **DO NOT run this command manually** - it's for auto-display only
- **For manual checking, use `check-aimaestro-messages.sh` instead**

**Why not use this manually?**
- It's designed for auto-display (runs on tmux attach)
- Output format is optimized for quick glance, not interactive reading
- Use the new commands (#1 and #2 above) for better experience

**Output format:**
```
Message: msg_1234567890_abcde
From: backend-architect          ← Another agent sent this TO YOU
To: frontend-dev                 ← YOUR session name
Subject: Need API endpoint
Priority: high
Type: request
Status: unread
Timestamp: 2025-01-17 14:23:45
Content: Please implement POST /api/users with pagination...
```

### 4. Check for New Messages Count (Quick)
**Command:**
```bash
check-new-messages-arrived.sh
```

**What it does:**
- Shows count of unread messages in YOUR inbox
- Automatically checks YOUR session's inbox
- Quick check without full details
- Returns "No new messages" or "You have X new message(s)"

**Example:**
```bash
check-new-messages-arrived.sh
# Output: "You have 3 new message(s)"  ← Messages sent TO YOU
```

### 5. Read Specific Message FROM YOUR Inbox (Direct File Access - Advanced)
**Command:**
```bash
cat ~/.aimaestro/messages/inbox/$(tmux display-message -p '#S')/<message-id>.json | jq
```

**What it does:**
- Read a specific message file from YOUR inbox
- `$(tmux display-message -p '#S')` = YOUR session name (auto-detected)
- Use `jq` for pretty formatting
- Useful when you know the message ID

**Directory structure:**
```
~/.aimaestro/messages/
├── inbox/YOUR-SESSION-NAME/     # Messages TO YOU from other agents
│   └── msg_*.json
├── sent/YOUR-SESSION-NAME/