Agent Messaging

Agent Messaging

Overview

Defective inter-agent communication is the root cause of most multi-agent breakdowns: bloated context drowns focus, imprecise prompts yield incorrect results, and sloppy handoffs lose critical data.

Core principle: Supply agents with exactly the context they require — nothing more, nothing less. Structure every message for the recipient, not the sender.

The Prime Directive

NO AGENT DISPATCH WITHOUT A STRUCTURED BRIEF

If you have not organized the context, the agent will burn tokens deciphering your intent.

When to Use

Apply to:

• Composing prompts for subagents (Agent tool dispatches)
• Sending messages to team members (SendMessage)
• Structuring reports back to callers or team leads
• Handing off work between agents (implementer to reviewer, researcher to lead)
• Deciding what context to include or exclude

Complements:

• godmode:delegated-execution — Prompt design for implementer/reviewer subagents
• godmode:parallel-execution — Prompt design for concurrent investigations
• godmode:team-orchestration — Message design for team coordination

The Entry Protocol

BEFORE dispatching any agent or sending any message:

1. RECIPIENT: Who receives this? (subagent, teammate, team lead)
2. OBJECTIVE: What must they DO? (implement, investigate, review, report)
3. CONTEXT: What must they KNOW? (only what is relevant to their task)
4. DELIVERABLE: What must they RETURN? (format, content, detail level)
5. CONSTRAINTS: What must they NOT do? (scope limits, file restrictions)

Skip any step = unfocused agent, wasted tokens

Subagent Prompt Design

The Lean Context Principle

Subagents get distracted by irrelevant context. More context is not better context.

digraph context_decision {
    "Task follows existing pattern?" [shape=diamond];
    "Task depends on other tasks?" [shape=diamond];
    "Lean context" [shape=box style=filled fillcolor=lightgreen];
    "Full context" [shape=box];

    "Task follows existing pattern?" -> "Lean context" [label="yes - supply pattern ref"];
    "Task follows existing pattern?" -> "Task depends on other tasks?" [label="no"];
    "Task depends on other tasks?" -> "Full context" [label="yes"];
    "Task depends on other tasks?" -> "Lean context" [label="no - standalone"];
}

Lean context (default for independent tasks):

You are implementing: [1-2 sentence description]

File to modify: [exact path]
Pattern to follow: [reference to existing function/test]
What to implement: [specific requirement]
Verification: [exact command to run]

Full context (for dependent or complex tasks):

You are implementing Task N: [task name]

## Task Description
[FULL TEXT of task - paste it, do not make the subagent read a file]

## Context
[Where this fits, what preceded it, architectural decisions]

Never make a subagent read a plan file. Paste the relevant content directly. Reading files wastes tokens and attention on irrelevant sections.

Subagent Brief Template

Every subagent brief should contain these sections:

Effective vs Ineffective Briefs

Ineffective — too vague, no structure:

Fix the tests in the auth module. They're failing.

Ineffective — too much context:

[Paste entire 500-line plan file]
Your task is Task 7, which is about auth tests.

Effective — structured and focused:

You are resolving 3 failing tests in src/auth/session.test.ts.

Failures:
1. "should reject expired sessions" - expects 401, gets 200
2. "should renew valid sessions" - timeout after 5s
3. "should handle concurrent sessions" - race condition

Context: Session management was refactored in commit def456.
The validateSession() function now returns a Promise instead of sync.

Files:
- Fix: src/auth/session.test.ts
- Reference: src/auth/session-manager.ts (the refactored code)
- Do NOT modify: src/auth/session.ts (production code is correct)

Verification: npm test -- --testPathPattern=session.test

Report: Root cause per test, what you changed, test results.

Team Message Design

Peer-to-Peer Messages

Use SendMessage with type "message" for direct coordination.

Structure messages as:

[WHAT] - One line summary of the point
[DETAIL] - Supporting information (if needed)
[ACTION] - What you need from the recipient (if anything)

Effective:

SendMessage -> backend teammate:
"The profile API needs a PUT /profile/preferences endpoint.
Frontend needs to update preferences without replacing the full profile.
Can you add this to the contract before implementing?"

Ineffective:

SendMessage -> backend teammate:
"Hey, I was working on the frontend and I noticed we need
some changes. The profile page has this preferences feature where
users can update without replacing everything and I think we need
a new endpoint for that. What do you think? Also I noticed..."

Broadcast vs Direct Message

digraph message_type {
    "Who needs this information?" [shape=diamond];
    "Entire team?" [shape=diamond];
    "broadcast (expensive)" [shape=box];
    "SendMessage to specific teammate" [shape=box style=filled fillcolor=lightgreen];

    "Who needs this information?" -> "Entire team?";
    "Entire team?" -> "broadcast (expensive)" [label="yes - convention change, critical blocker"];
    "Entire team?" -> "SendMessage to specific teammate" [label="no - most cases"];
}

Broadcast only when:

• Convention or pattern change that affects every teammate
• Critical blocker that halts all progress
• Shared resource conflict

Direct message for everything else (status reports, questions, findings, coordination).

Reporting to Team Lead

When completing a task, report:

COMPLETED: [task name]
RESULT: [one-line summary]
FILES CHANGED: [list]
FINDINGS: [anything the lead or other teammates should know]
CONCERNS: [anything that might affect other tasks]

Handoff Formats

Implementer to Reviewer

## What Was Built
[Summary - what changed and why]

## Files Changed
[Exact paths, one per line]

## Test Results
[Pass/fail counts, any notable results]

## Self-Review Notes
[Issues found and resolved during self-review]
[Remaining concerns]

## Verification Command
[Exact command to run]

Reviewer to Implementer (Fix Request)

## Issues Identified
[List each issue with file:line reference]

## Priority
- Blocking: [must resolve before approval]
- Important: [should resolve]
- Suggestion: [consider for improvement]

## Scope Boundaries
[Do not refactor while fixing — stay focused]

Investigator to Lead (Debug/Research)

## Hypothesis Under Test
[What was being investigated]

## Evidence
- Supporting: [evidence favoring the hypothesis]
- Contradicting: [evidence against the hypothesis]

## Confidence
[High/Medium/Low with reasoning]

## Recommendation
[Next steps based on findings]

## Cross-Cutting Discoveries
[Anything that affects other investigations]

Context Management

What to Include

• Exact file paths (always absolute, never approximate)
• Error messages verbatim (do not paraphrase)
• Relevant code snippets (not entire files)
• Specific line numbers for references
• Verification commands ready to copy-paste
• Dependencies and prerequisites

What to Exclude

• Complete plan files (paste only the relevant task)
• Completed task details (unless they are dependencies)
• Project history irrelevant to the task
• Alternative approaches that were rejected
• Verbose explanations of obvious patterns

The Context Budget Guideline

Error Escalation

When an agent encounters an unresolvable problem:

digraph escalation {
    "Agent hits obstacle" [shape=box];
    "Can resolve independently?" [shape=diamond];
    "Resolve it" [shape=box];
    "Affects only own task?" [shape=diamond];
    "Report to lead at task completion" [shape=box];
    "Message lead immediately" [shape=box];
    "Affects other teammates?" [shape=diamond];
    "Message affected teammates" [shape=box];

    "Agent hits obstacle" -> "Can resolve independently?";
    "Can resolve independently?" -> "Resolve it" [label="yes"];
    "Can resolve independently?" -> "Affects only own task?" [label="no"];
    "Affects only own task?" -> "Report to lead at task completion" [label="yes"];
    "Affects only own task?" -> "Affects other teammates?" [label="no - blocks others"];
    "Affects other teammates?" -> "Message affected teammates" [label="yes"];
    "Affects other teammates?" -> "Message lead immediately" [label="no - requires lead decision"];
}

Escalation message format:

BLOCKED: [what is blocked]
CAUSE: [why it is blocked]
ATTEMPTED: [what was tried]
NEED: [what would unblock - decision, information, or fix]

Cognitive Traps

Guardrails

Prohibited:

• Making subagents read plan files (paste content instead)
• Sending unstructured prompts ("fix the tests")
• Including irrelevant context ("here's the full history...")
• Using broadcast for routine updates
• Omitting the deliverable format section (agents will not know what to report)
• Escalating without stating what was already attempted

Mandatory:

• Structure every prompt with role, task, context, constraints, deliverable
• Paste content directly instead of referencing files
• Include verification commands in implementation prompts
• Use direct messages over broadcast
• Include file paths in every handoff
• Report cross-cutting discoveries to affected parties

Integration

Consumed by:

• godmode:delegated-execution — Implementer and reviewer prompts
• godmode:parallel-execution — Concurrent agent prompts
• godmode:team-orchestration — Team communication patterns

Complements:

• godmode:fault-diagnosis — Structure for debug investigation reports
• godmode:quality-gate — Structure for review requests
• godmode:completion-gate — Structure for completion reports