agent-relay 1.0.8 → 1.0.9

package/docs/AGENTS.md

@@ -79,6 +79,60 @@ relay wrap -n PlayerO claude
 
 ---
 
+## Agent Role Auto-Detection
+
+When you start an agent with `-n`, the name is matched against agent definitions in your project. If a matching agent file exists, the agent automatically assumes that role.
+
+**Supported locations:**
+- `.claude/agents/<name>.md` - Claude Code agents
+- `.openagents/<name>.md` - OpenAgents format
+
+### Example
+
+```bash
+# If .claude/agents/lead.md exists:
+relay wrap -n lead claude
+# → Agent automatically assumes the Lead role defined in lead.md
+
+# If .claude/agents/implementer.md exists:
+relay wrap -n implementer claude
+# → Agent assumes the Implementer role
+
+# No matching file? Agent starts with default behavior
+relay wrap -n CustomName claude
+# → Standard agent, no role injection
+```
+
+### How It Works
+
+1. Agent name from `-n` flag is matched **case-insensitively**
+2. System checks for `<project>/.claude/agents/<name>.md` or `<project>/.openagents/<name>.md`
+3. If found, the agent definition is injected into the agent's initial context
+4. Agent assumes the persona, instructions, and behaviors defined in the file
+
+**Case insensitive matching:**
+```bash
+relay wrap -n Lead claude      # matches lead.md
+relay wrap -n LEAD claude      # matches lead.md
+relay wrap -n lead claude      # matches lead.md
+```
+
+### Creating Role Agents
+
+Create agent files for your team roles:
+
+```
+.claude/agents/
+├── lead.md          # Coordinator, delegates work
+├── implementer.md   # Writes code, fixes bugs
+├── designer.md      # UI/UX, frontend work
+└── reviewer.md      # Code review, quality checks
+```
+
+Each file follows the standard Claude agent format with frontmatter and instructions.
+
+---
+
 ## Team Communication
 
 If you have an INSTRUCTIONS.md file in `/tmp/agent-relay-team/{YourName}/`, use these commands:
@@ -111,6 +165,15 @@ relay team status
 ->relay:* Broadcast to all agents
 ```
 
+**Fenced format** (multi-line with blank lines/code):
+```
+->relay:AgentName <<<
+Multi-line message here.
+
+Can include blank lines and code.
+>>>
+```
+
 **Block format** (structured data):
 ```
 [[RELAY]]{"to":"AgentName","type":"message","body":"Your message"}[[/RELAY]]
@@ -355,6 +418,48 @@ Requirements:
 
 ---
 
+## Spawning Agents
+
+Any agent can spawn worker agents to delegate tasks. Workers run in separate tmux windows and can communicate via relay.
+
+### Spawn a Worker
+
+Output this pattern to spawn a new agent:
+```
+->relay:spawn WorkerName cli "task description"
+```
+
+**Examples:**
+```
+->relay:spawn Dev1 claude "Implement the login endpoint with JWT auth"
+->relay:spawn Reviewer claude "Review the auth module in src/auth/"
+->relay:spawn Tester claude "Write unit tests for the user service"
+```
+
+### Release a Worker
+
+When a worker is done, release it:
+```
+->relay:release WorkerName
+```
+
+### How It Works
+
+1. The spawn command creates a new tmux window
+2. Launches `agent-relay -n WorkerName cli --dangerously-skip-permissions`
+3. Waits for the agent to register with the daemon
+4. Injects the task as the initial prompt
+5. Worker can communicate back via `->relay:` patterns
+
+### Best Practices
+
+- Give workers specific, well-scoped tasks
+- Use descriptive names that indicate the worker's purpose
+- Release workers when they complete their tasks
+- Workers can spawn their own workers if needed (nested spawning)
+
+---
+
 ## Agent Naming
 
 Agent names follow the AdjectiveNoun format:

package/docs/ARCHITECTURE_DECISIONS.md

@@ -0,0 +1,175 @@
+# Multi-Agent Coordination: Architecture Decisions
+
+This document compares approaches to multi-agent coordination and explains when to use each.
+
+## Two Approaches
+
+### 1. Subagents (Hierarchical)
+
+Spawn child agents from a parent, collect results, continue.
+
+```
+       ┌─────────┐
+       │ Parent  │
+       └────┬────┘
+            │ spawn
+    ┌───────┼───────┐
+    ▼       ▼       ▼
+┌───────┐┌───────┐┌───────┐
+│ Child ││ Child ││ Child │
+└───────┘└───────┘└───────┘
+    │       │       │
+    └───────┼───────┘
+            ▼ return
+       ┌─────────┐
+       │ Parent  │
+       └─────────┘
+```
+
+**Characteristics:**
+- Tree topology (parent orchestrates)
+- Synchronous - parent waits for children
+- Ephemeral - children die after returning
+- State held by parent
+- No peer-to-peer communication
+
+### 2. Agent-Relay (Mesh)
+
+Persistent agents communicate via message passing.
+
+```
+┌───────┐     ┌───────┐
+│ Agent │◄───►│ Agent │
+└───┬───┘     └───┬───┘
+    │             │
+    └──────┬──────┘
+           ▼
+    ┌─────────────┐
+    │   Daemon    │ ← routes messages
+    │  (router)   │ ← persists history
+    └─────────────┘
+           │
+    ┌──────┴──────┐
+    ▼             ▼
+┌───────┐     ┌───────┐
+│ Agent │◄───►│ Agent │
+└───────┘     └───────┘
+```
+
+**Characteristics:**
+- Mesh topology (any-to-any)
+- Asynchronous - fire and respond
+- Persistent - agents live across tasks
+- Distributed state + message log
+- Direct peer communication
+
+## Decision Matrix
+
+| Requirement | Subagents | Agent-Relay |
+|-------------|:---------:|:-----------:|
+| Simple one-shot tasks | ✅ | ⚠️ overkill |
+| Clear parent/child hierarchy | ✅ | ✅ |
+| No infrastructure to manage | ✅ | ❌ |
+| Agents debate/negotiate | ❌ | ✅ |
+| Long-running agents | ❌ | ✅ |
+| Mix different AI providers | ⚠️ limited | ✅ |
+| Audit trail / replay | ❌ | ✅ |
+| External observability | ❌ | ✅ |
+| Horizontal scaling | ❌ | ✅ |
+| Resume after crash | ❌ | ✅ |
+
+## When to Use Subagents
+
+Choose subagents when:
+
+1. **Tasks are independent** - Fan out, collect, aggregate
+2. **Hierarchy is natural** - One coordinator, many workers
+3. **No persistence needed** - Results matter, not the conversation
+4. **Same provider** - All agents are Claude (or same SDK)
+5. **Simplicity wins** - Fewer moving parts
+
+**Example use cases:**
+- Parallel code analysis (security, perf, style)
+- Research tasks with multiple queries
+- Map-reduce style workloads
+- One-time batch processing
+
+```typescript
+// Subagent pattern
+const [security, perf, style] = await Promise.all([
+  analyzeSecurityAgent(code),
+  analyzePerfAgent(code),
+  analyzeStyleAgent(code),
+]);
+return summarize(security, perf, style);
+```
+
+## When to Use Agent-Relay
+
+Choose agent-relay when:
+
+1. **Agents need to discuss** - Back-and-forth negotiation
+2. **Persistence matters** - Audit, debug, replay conversations
+3. **Mixed ecosystem** - Claude + Codex + Gemini + custom bots
+4. **External integration** - Dashboard, Slack, webhooks
+5. **Long-running sessions** - Agents stay alive, handle multiple tasks
+6. **Decoupling** - Add/remove agents without code changes
+
+**Example use cases:**
+- Collaborative document editing
+- Multi-agent game playing
+- Continuous monitoring systems
+- Team simulations with distinct personas
+- Human-in-the-loop workflows
+
+```typescript
+// Agent-relay pattern
+const daemon = new Daemon({ socketPath, storagePath });
+await daemon.start();
+
+// Agents live independently, communicate async
+const architect = new RelayClient({ name: 'Architect', socketPath });
+const developer = new RelayClient({ name: 'Developer', socketPath });
+const reviewer = new RelayClient({ name: 'Reviewer', socketPath });
+
+// They message each other directly
+architect.send({ to: 'Developer', body: 'Implement auth module' });
+// Developer works, then...
+developer.send({ to: 'Reviewer', body: 'Ready for review' });
+// Reviewer responds to Developer directly
+```
+
+## Hybrid Approach
+
+You can combine both:
+
+```
+┌─────────────────────────────────────┐
+│           Orchestrator              │
+│         (agent-relay)               │
+└──────┬──────────────┬───────────────┘
+       │              │
+       ▼              ▼
+┌─────────────┐ ┌─────────────┐
+│  Team Lead  │ │  Team Lead  │
+│  (relay)    │ │  (relay)    │
+└──────┬──────┘ └──────┬──────┘
+       │               │
+   ┌───┴───┐       ┌───┴───┐
+   ▼       ▼       ▼       ▼
+┌─────┐ ┌─────┐ ┌─────┐ ┌─────┐
+│Sub 1│ │Sub 2│ │Sub 3│ │Sub 4│  ← subagents
+└─────┘ └─────┘ └─────┘ └─────┘
+```
+
+- **Agent-relay** for cross-team coordination
+- **Subagents** for parallelizable work within a team
+
+## Summary
+
+| Approach | Mental Model | Best For |
+|----------|--------------|----------|
+| Subagents | Function calls | Hierarchical, stateless, one-shot |
+| Agent-Relay | Microservices | Mesh, persistent, observable |
+
+**Rule of thumb:** Start with subagents. Move to agent-relay when you need persistence, observability, or peer-to-peer communication.