arminnaimi_agent-team-orchestration/references/communication.md

# Communication

How agents coordinate: sync vs async, spawning vs messaging, and artifact sharing.

## Communication Channels

### Shared Files (Primary — Async)

The default communication method. Persistent, auditable, no timing dependency.

```
/shared/
├── specs/          — Requirements, research, analysis
├── artifacts/      — Build outputs, deliverables
├── reviews/        — Review notes and feedback
├── decisions/      — Architecture and product decisions
```

**Use for:** Deliverables, specs, reviews, decisions — anything another agent needs to find later.

### Task Comments (Async)

Attached to specific tasks. Chronological record of progress.

**Use for:** Status updates, blockers, handoff messages, review feedback.

### sessions_send (Sync — Urgent)

Direct message to a running agent session. Interrupts their current work.

**Use for:**
- Urgent priority changes ("Drop everything, critical bug")
- Quick questions that block progress ("Is feature X in scope?")
- Coordination that can't wait for task comment review

**Don't use for:**
- Routine updates (use task comments)
- Delivering artifacts (use shared files)
- Anything the agent needs to reference later (messages are ephemeral)

## Spawn vs Send

### Spawn a new sub-agent when:
- The task is self-contained with clear inputs and outputs
- You want isolation — the work shouldn't affect other running sessions
- The task needs a different model or capability set
- You're parallelizing — multiple independent tasks at once

### Send to an existing session when:
- The agent is already working on related context
- You need a quick answer, not a full task execution
- The work is a small addition to something already in progress

**Default to spawn.** It's cleaner. Send is for exceptions.

## Spawn Prompt Template

Every spawn includes:

```markdown
## Task: [Title]
**Task ID:** [ID]
**Role:** [What this agent is]
**Priority:** [High/Medium/Low]

### Context
[What the agent needs to know]

### Deliverables
[Exactly what to produce]

### Output Path
[Exact directory/file path for artifacts]

### Handoff
When complete:
1. Write artifacts to [output path]
2. Comment on task with handoff summary
3. Include: what was done, how to verify, known issues
```

**Critical fields:**
- **Output Path** — Without this, you'll lose the work. Always specify.
- **Handoff instructions** — Tell the agent exactly how to signal completion.

## Artifact Conventions

### Naming
```
/shared/artifacts/[task-id]-[short-name]/
/shared/specs/[date]-[topic].md
/shared/decisions/[date]-[title].md
/shared/reviews/[task-id]-review.md
```

### Rules
- All deliverables go to `/shared/` — never to personal agent workspaces
- One directory per task for multi-file outputs
- Include a brief README or summary at the top of the artifact directory if it contains 3+ files
- Overwrite previous versions in place — don't create v2, v3 copies

## Avoiding Communication Failures

**Silent agents:** If an agent doesn't comment within its expected timeframe, assume it's stuck. Check on it or restart the task.

**Lost artifacts:** Always verify the output path exists after a task completes. Agents sometimes write to wrong directories.

**Context gaps:** When spawning, include all context the agent needs. Don't assume it can read other agent sessions or recent conversations. Shared files are the bridge.

**Message timing:** `sessions_send` only works if the target session is active. If unsure, spawn a new session instead.