{
  "version": 1,
  "registry": "https://clawhub.ai",
  "slug": "agent-team-orchestration",
  "installedVersion": "1.0.0",
  "installedAt": 1777595269345
}

# 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.

# Patterns

Proven multi-agent workflows. Copy and adapt.

## Spec → Review → Build → Test

The full quality loop. Use for any non-trivial feature.

```
1. Orchestrator creates task, assigns to Spec Writer
2. Spec Writer produces spec at /shared/specs/[task]-spec.md
3. Orchestrator assigns spec review to Builder (feasibility check)
4. Builder reviews: "feasible" / "change X because Y"
5. If changes needed → back to Spec Writer → re-review
6. Orchestrator assigns build to Builder
7. Builder produces artifacts at /shared/artifacts/[task]/
8. Orchestrator assigns review to Reviewer
9. Reviewer approves or returns with feedback
10. If returned → Builder fixes → re-review
11. Orchestrator marks Done, reports to stakeholders
```

**Key:** The person who writes the spec doesn't review the build. The person who builds doesn't approve their own work. Cross-role verification is the whole point.

### Minimal version (2 agents):
```
1. Orchestrator writes brief spec
2. Builder implements
3. Orchestrator reviews output
4. Done or return for fixes
```

## Parallel Research

Multiple agents research independently, then merge. Use for broad investigation.

```
1. Orchestrator defines research question + splits into angles
2. Spawn Agent A: "Research [angle 1], write findings to /shared/specs/research-[topic]-a.md"
3. Spawn Agent B: "Research [angle 2], write findings to /shared/specs/research-[topic]-b.md"
4. Wait for both to complete
5. Orchestrator (or designated agent) merges into /shared/specs/research-[topic]-final.md
6. Use merged research to inform next decision
```

**Rules:**
- Define non-overlapping angles to avoid duplicate work
- Set a time/scope limit per agent — research expands to fill available time
- The merge step is mandatory — raw research without synthesis is useless

## Escalation

Agent hits a blocker it can't resolve. Structured escalation prevents stalling.

```
1. Agent comments on task: "Blocked: [specific problem]"
2. Agent continues with other work if possible (don't idle)
3. Orchestrator sees blocker, decides:
   a. Resolve directly (answer the question, provide access)
   b. Reassign to a more capable agent
   c. Escalate to human stakeholder
   d. Deprioritize/defer the task
4. Orchestrator comments decision and unblocks or reassigns
```

**Escalation triggers:**
- Missing access or credentials
- Ambiguous requirements that need product decisions
- Technical blocker outside agent's expertise
- Task exceeds estimated scope by 2x+

**Anti-pattern:** Agent silently struggling for 30 minutes instead of escalating after 10. Set the expectation: escalate early, escalate with context.

## Cron-Based Ops

Scheduled tasks for team health. Assign to the cheapest reliable agent.

### Daily Standup
```
Schedule: Every morning
Agent: Ops

1. Read all open tasks
2. Check for stale tasks (no comment in 24h+)
3. Check for overdue tasks
4. Produce standup summary:
   - What completed yesterday
   - What's in progress
   - What's blocked
   - What's stale
5. Post to orchestrator or team channel
```

### Task Dispatch
```
Schedule: Every few hours (or on trigger)
Agent: Orchestrator

1. Check inbox for new tasks
2. Prioritize by urgency/importance
3. Match to available agents (check capabilities)
4. Assign and spawn
```

### Health Check
```
Schedule: Periodic
Agent: Ops

1. Verify shared directories exist and are writable
2. Check for orphaned tasks (assigned but no agent session)
3. Check for artifact path conflicts
4. Report anomalies to orchestrator
```

## Batch Processing

Multiple similar tasks that can run in parallel.

```
1. Orchestrator creates N tasks from a list
2. Spawn up to M agents in parallel (M ≤ concurrency limit)
3. Each agent picks one task, completes it, writes output
4. Orchestrator collects results as agents finish
5. Spawn next batch if more tasks remain
6. Final aggregation once all tasks complete
```

**Sizing:** Start with 2-3 parallel agents. More isn't always faster — coordination overhead grows.

## Review Rotation

Prevent review fatigue and bias by rotating reviewers.

```
Task produced by Agent A → Reviewed by Agent B
Task produced by Agent B → Reviewed by Agent C
Task produced by Agent C → Reviewed by Agent A
```

**Why:** Same reviewer for the same builder creates blind spots. Rotation catches different things.

# Task Lifecycle

Task states, transitions, comment conventions, and decision logging.

## States

```
Inbox → Assigned → In Progress → Review → Done | Failed
```

| State | Meaning | Owner |
|-------|---------|-------|
| **Inbox** | New task, unassigned | Orchestrator |
| **Assigned** | Agent selected, not yet started | Orchestrator |
| **In Progress** | Agent actively working | Assigned agent |
| **Review** | Work complete, awaiting verification | Reviewer |
| **Done** | Verified and shipped | Orchestrator |
| **Failed** | Abandoned with documented reason | Orchestrator |

## Transition Rules

**Orchestrator transitions:**
- Inbox → Assigned (picks the agent)
- Assigned → In Progress (spawns the agent or sends the task)
- Review → Done (accepts the deliverable)
- Any state → Failed (with reason)

**Agents transition:**
- In Progress → Review (submits deliverable with handoff comment)

**Reviewers transition:**
- Review → In Progress (returns with feedback — agent must address it)
- Review → Done (approves — orchestrator confirms)

**Never skip Review.** The orchestrator may override for trivial tasks, but document it.

## Comment Conventions

Every state change gets a comment. Format:

```
[Agent] [Action]: [Details]
```

### Required comments:

**Starting work:**
```
[Builder] Starting: Picking up auth module. Questions: Should rate limiting be per-user or per-IP?
```

**Blocker found:**
```
[Builder] Blocked: Need API credentials for the payment gateway. Who has access?
```

**Submitting for review:**
```
[Builder] Handoff: Auth module complete at /shared/artifacts/auth/.
- Added JWT validation middleware
- Tests at /shared/artifacts/auth/tests/
- Run `npm test -- --grep auth` to verify
- Known issue: refresh token rotation not implemented (out of scope per spec)
- Next: Reviewer checks error handling paths
```

**Review feedback:**
```
[Reviewer] Feedback: Two issues found.
1. Missing input validation on email field — SQL injection risk
2. Error messages expose internal paths in production mode
Returning to builder. Fix both, then resubmit.
```

**Completion:**
```
[Reviewer] Approved: All issues addressed. Auth module ready to ship.
```

**Failure:**
```
[Orchestrator] Failed: Deprioritized — superseded by new auth provider integration. Preserving spec at /shared/specs/auth-v1.md for reference.
```

## Decision Logging

Architecture or product decisions made during task execution go in a shared decisions directory.

```markdown
# Decision: [Title]
**Date:** YYYY-MM-DD
**Author:** [Agent]
**Status:** Proposed | Accepted | Rejected
**Task:** [Task ID if applicable]

## Context
Why this decision came up.

## Options Considered
1. Option A — tradeoffs
2. Option B — tradeoffs

## Decision
What was chosen and why.

## Consequences
What changes as a result.
```

**When to log a decision:**
- Choosing between two valid architectural approaches
- Changing a spec during implementation
- Rejecting a requirement as infeasible
- Any choice that future agents will wonder "why did we do it this way?"

## Multi-Step Task Workflows

Complex tasks split into sub-tasks. Track the parent relationship:

```
Task #12: Build user dashboard
  ├── #12a: Write spec (Assigned: Spec writer)
  ├── #12b: Review spec (Assigned: Builder — feasibility check)
  ├── #12c: Build frontend (Assigned: Builder)
  ├── #12d: Build API endpoints (Assigned: Builder)
  └── #12e: Integration test (Assigned: Reviewer)
```

The orchestrator tracks the parent task and only marks it Done when all sub-tasks complete.

# Team Setup

How to define agents, assign roles, select models, and isolate workspaces.

## Define Roles First, Then Agents

Start with the work, not the agents. List the types of work, then create roles to cover them.

**Minimal team (2 agents):**
```
Orchestrator — routes tasks, tracks state
Builder      — executes work
```

**Standard team (3-4 agents):**
```
Orchestrator — routes, prioritizes, reports to stakeholders
Builder      — produces artifacts (code, docs, configs)
Reviewer     — verifies quality, catches gaps
Ops          — scheduled tasks, health checks, mechanical work
```

**Rule:** One agent, one primary role. An agent can do secondary work, but its role determines what it's optimized for.

## Model Selection Per Role

Match model cost to the cognitive demands of the role.

| Role | Needs | Model tier |
|------|-------|-----------|
| Orchestrator | Judgment, prioritization, multi-context reasoning | Top tier (e.g., Claude Opus, GPT-4.5) |
| Builder | Code generation, following specs, producing artifacts | Mid-to-top tier depending on complexity |
| Reviewer | Critical analysis, catching edge cases, feasibility | Top tier — reviewers catch what builders miss |
| Ops | Following templates, running scripts, dispatching | Cheapest reliable model (e.g., GPT-4o-mini, Haiku) |

**Don't waste expensive models on mechanical work.** Cron-based standups, file organization, and template-following tasks don't need frontier reasoning.

## Workspace Isolation

Each agent operates in its own workspace to prevent interference.

```
/workspace/
├── agents/
│   ├── builder/          — Builder's personal workspace
│   │   └── SOUL.md       — Builder's identity and instructions
│   ├── reviewer/         — Reviewer's personal workspace
│   │   └── SOUL.md
│   └── ops/
│       └── SOUL.md
├── shared/               — Shared across all agents
│   ├── specs/            — Requirements and specifications
│   ├── artifacts/        — Build outputs
│   ├── reviews/          — Review notes and feedback
│   └── decisions/        — Architecture and product decisions
```

**Rules:**
- Agents read/write their own workspace freely
- Agents write deliverables to `/shared/` — never to personal workspaces
- Agents can read any shared directory
- Orchestrator can read all workspaces for oversight

## Identity Files (SOUL.md)

Each agent gets a SOUL.md that defines:

1. **Role and scope** — What this agent does and doesn't do
2. **Communication style** — How it writes comments, reports, asks questions
3. **Boundaries** — What requires escalation vs. autonomous action
4. **Team context** — Who else is on the team and how to interact with them

Example SOUL.md for a builder agent:

```markdown
# SOUL.md — Builder

I build what the specs say. My job is execution, not product decisions.

## Scope
- Implement features per approved specs
- Write tests for what I build
- Document non-obvious decisions in code comments
- Hand off with clear verification steps

## Boundaries
- Spec unclear? Ask the orchestrator, don't guess
- Architecture change needed? Propose it, don't just do it
- Blocked for >10 minutes? Comment on the task and move on

## Handoff Format
Every completed task includes:
1. What I changed and why
2. File paths for all artifacts
3. How to test/verify
4. Known limitations
```

## Adding a New Agent

1. Create the workspace directory
2. Write its SOUL.md
3. Update the team protocol with its role
4. Verify it has the capabilities it needs (browser, tools, API access)
5. Start with a small task to validate the setup before loading it into the rotation