Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
80 changes: 50 additions & 30 deletions .beads/issues.jsonl

Large diffs are not rendered by default.

37 changes: 24 additions & 13 deletions .claude/agents/lead.md
Original file line number Diff line number Diff line change
Expand Up @@ -40,48 +40,56 @@ When delegating, match tasks to roles:

## Communication Patterns

**Always use the fenced format** for reliable message delivery.

### Assigning Work
```
->relay:Implementer **TASK:** [Clear task name]
->relay:Implementer <<<
**TASK:** [Clear task name]

**Files:** [Specific files to modify]
**Requirements:** [Bullet points of what's needed]
**Acceptance:** [How to know it's done]

**Claim:** `bd update <issue-id> --status=in_progress`
**Claim:** `bd update <issue-id> --status=in_progress`>>>
```

### Status Checks
```
->relay:Implementer Status check - how's [task] coming?
->relay:Implementer <<<
Status check - how's [task] coming?>>>
```

### Priority Changes
```
->relay:* **PRIORITY CHANGE:** [New priority]
->relay:* <<<
**PRIORITY CHANGE:** [New priority]

Previous task: [What they were doing]
New task: [What they should do now]
Reason: [Why the change]
Reason: [Why the change]>>>
```

### Acknowledging Completion
```
->relay:Implementer Confirmed. [Brief feedback]. Next task: [or "stand by"]
->relay:Implementer <<<
Confirmed. [Brief feedback]. Next task: [or "stand by"]>>>
```

## Anti-Patterns (What NOT To Do)

### Don't Get Deep
```
❌ BAD: "Let me read through this 500-line file and understand the architecture..."
✅ GOOD: "->relay:Implementer Read src/complex.ts and summarize the key functions."
✅ GOOD: "->relay:Implementer <<<
Read src/complex.ts and summarize the key functions.>>>"
```

### Don't Implement
```
❌ BAD: Writing code, editing files, running tests yourself
✅ GOOD: "->relay:Implementer Fix the failing test in parser.test.ts"
✅ GOOD: "->relay:Implementer <<<
Fix the failing test in parser.test.ts>>>"
```

### Don't Over-Explain
Expand Down Expand Up @@ -115,11 +123,12 @@ bd create --title="Add feature X" --type=feature --priority=P2

### 4. Delegate
```
->relay:Implementer **TASK:** Add feature X
->relay:Implementer <<<
**TASK:** Add feature X

**Issue:** agent-relay-xxx
**Requirements:** [2-3 bullet points]
**Claim:** `bd update agent-relay-xxx --status=in_progress`
**Claim:** `bd update agent-relay-xxx --status=in_progress`>>>
```

### 5. Monitor & Unblock
Expand All @@ -132,7 +141,8 @@ bd create --title="Add feature X" --type=feature --priority=P2
bd close agent-relay-xxx --reason "Feature complete"
```
```
->relay:Implementer Task closed. Next: [next task or "stand by"]
->relay:Implementer <<<
Task closed. Next: [next task or "stand by"]>>>
```

## Decision Framework
Expand All @@ -149,15 +159,16 @@ When facing a decision:
Periodically broadcast status:

```
->relay:* **STATUS UPDATE:**
->relay:* <<<
**STATUS UPDATE:**

| Agent | Task | Status |
|-------|------|--------|
| Implementer | Feature X | 🔄 In Progress |
| Designer | Dashboard UI | ✅ Complete |

**Blockers:** None
**Next:** [What's coming next]
**Next:** [What's coming next]>>>
```

## Session Summary Pattern
Expand Down
42 changes: 25 additions & 17 deletions .claude/skills/using-agent-relay/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -22,9 +22,8 @@ Real-time agent-to-agent messaging. Two modes: **tmux wrapper** (real-time, sub-

| Pattern | Description |
|---------|-------------|
| `->relay:Name message` | Direct message (output as text) |
| `->relay:Name <<<`...`>>>` | Multi-line message with blank lines/code |
| `->relay:* message` | Broadcast to all |
| `->relay:Name <<<`...`>>>` | **Default format** - always use fenced format |
| `->relay:* <<<`...`>>>` | Broadcast to all agents |
| `[[RELAY]]{"to":"Name","body":"msg"}[[/RELAY]]` | Structured JSON |
| `\->relay:` | Escape (literal output) |
| `relay read <id>` | Read truncated message |
Expand All @@ -51,16 +50,19 @@ relay team status # Show team

## Sending Messages (Tmux Mode)

**Output the pattern directly** - don't use bash commands:
**Output the pattern directly** - don't use bash commands. Always use the fenced format:

```
->relay:BlueLake I've finished the API refactor.
->relay:* STATUS: Starting auth module.
->relay:BlueLake <<<
I've finished the API refactor.>>>

->relay:* <<<
STATUS: Starting auth module.>>>
```

### Multi-line Messages (Fenced Format)
### Fenced Format (Default)

For messages with blank lines, code blocks, or complex content:
The fenced format is the default for all messages:

```
->relay:Reviewer <<<
Expand All @@ -72,11 +74,10 @@ Please check:

Key changes:
1. Added JWT validation
2. Fixed session expiry
>>>
2. Fixed session expiry>>>
```

**CRITICAL:** Always end with `>>>` on its own line! The `<<<` opens, `>>>` closes.
**CRITICAL:** Always end with `>>>` at the end of the last line of content! The `<<<` opens, `>>>` closes.

**Limits:** Fenced messages max 200 lines. For longer content, send summary with reference ID.

Expand Down Expand Up @@ -113,20 +114,27 @@ relay read abc123

```
# Task assignment
->relay:Developer TASK: Implement /api/register
->relay:Developer <<<
TASK: Implement /api/register>>>

# Status broadcast
->relay:* STATUS: Starting auth module
->relay:* DONE: Auth complete
->relay:* <<<
STATUS: Starting auth module>>>

->relay:* <<<
DONE: Auth complete>>>

# Review request
->relay:Reviewer REVIEW: src/auth/*.ts
->relay:Reviewer <<<
REVIEW: src/auth/*.ts>>>

# Question
->relay:Architect QUESTION: JWT or sessions?
->relay:Architect <<<
QUESTION: JWT or sessions?>>>

# Blocked
->relay:* BLOCKED: Need DB credentials
->relay:* <<<
BLOCKED: Need DB credentials>>>
```

## Spawning Agents
Expand Down
2 changes: 2 additions & 0 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -37,3 +37,5 @@ coverage/
.tmp-agent-relay-data

.next

src/dashboard/out
38 changes: 21 additions & 17 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -73,24 +73,19 @@ Real-time agent-to-agent messaging. Output `->relay:` patterns to communicate.

## Sending Messages

```
->relay:AgentName Your message here
->relay:* Broadcast to all agents
```

### Multi-line Messages

For messages with blank lines or code:
**Always use the fenced format** for reliable message delivery:

```
->relay:AgentName <<<
Your multi-line message here.
Your message here.>>>
```

Can include blank lines and code.
>>>
```
->relay:* <<<
Broadcast to all agents.>>>
```

**CRITICAL:** Always end with `>>>` on its own line!
**CRITICAL:** Always end with `>>>` at the end of the last line of content!

## Receiving Messages

Expand All @@ -116,11 +111,20 @@ Spawn workers to delegate tasks:
## Common Patterns

```
->relay:* STATUS: Starting work on auth module
->relay:* DONE: Auth module complete
->relay:Developer TASK: Implement /api/register
->relay:Reviewer REVIEW: Please check src/auth/*.ts
->relay:Architect QUESTION: JWT or sessions?
->relay:* <<<
STATUS: Starting work on auth module>>>

->relay:* <<<
DONE: Auth module complete>>>

->relay:Developer <<<
TASK: Implement /api/register>>>

->relay:Reviewer <<<
REVIEW: Please check src/auth/*.ts>>>

->relay:Architect <<<
QUESTION: JWT or sessions?>>>
```

## Rules
Expand Down
22 changes: 15 additions & 7 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -23,11 +23,14 @@ agent-relay -n Alice claude
agent-relay -n Bob codex
```

Agents communicate by outputting `->relay:` patterns:
Agents communicate by outputting `->relay:` patterns. Always use the fenced format:

```
->relay:Bob Hey, can you review my changes?
->relay:* Broadcasting to everyone
->relay:Bob <<<
Hey, can you review my changes?>>>

->relay:* <<<
Broadcasting to everyone>>>
```

## CLI
Expand Down Expand Up @@ -68,13 +71,15 @@ Agents communicate by outputting `->relay:` patterns:
### Send Message

```
->relay:AgentName Your message here
->relay:AgentName <<<
Your message here>>>
```

### Broadcast

```
->relay:* Message to all agents
->relay:* <<<
Message to all agents>>>
```

### Receive
Expand Down Expand Up @@ -136,8 +141,11 @@ agent-relay bridge ~/auth ~/frontend ~/api
### Cross-Project Messaging

```
->relay:projectId:agent Message to specific agent
->relay:*:lead Broadcast to all project leads
->relay:projectId:agent <<<
Message to specific agent>>>

->relay:*:lead <<<
Broadcast to all project leads>>>
```

### Spawn Agents
Expand Down
16 changes: 13 additions & 3 deletions TESTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -35,6 +35,13 @@ Inside Alice's terminal, output these patterns:
->relay:spawn Dev1 claude "Write unit tests for the auth module"
```

Or using the fenced format for messages:

```
->relay:Dev1 <<<
Write unit tests for the auth module>>>
```

**Expected:**
- New tmux window created in `relay-workers` session
- Dev1 agent starts with the task injected
Expand Down Expand Up @@ -122,14 +129,16 @@ agent-relay -n Bob claude

From Alice (Project A):
```
->relay:project-b:Bob Hey Bob, can you review my changes?
->relay:project-b:Bob <<<
Hey Bob, can you review my changes?>>>
```

**Expected:** Bob receives the message in Project B.

From Bob (Project B):
```
->relay:project-a:Alice Sure, sending review now.
->relay:project-a:Alice <<<
Sure, sending review now.>>>
```

**Expected:** Alice receives the message in Project A.
Expand All @@ -138,7 +147,8 @@ From Bob (Project B):

From the bridge/architect:
```
->relay:*:lead Standup time - report your status
->relay:*:lead <<<
Standup time - report your status>>>
```

**Expected:** Both Alice and Bob receive the message.
Expand Down
Loading