Skip to content

Commit 6cd422e

Browse files
khaliqgantkhaliqgant
committed
version bump
1 parent 0822463 commit 6cd422e

3 files changed

Lines changed: 169 additions & 114 deletions

File tree

‎CLAUDE.md‎

Lines changed: 150 additions & 112 deletions
Original file line numberDiff line numberDiff line change
@@ -1,171 +1,209 @@
1-
<!-- prpm:snippet:start @agent-relay/agent-relay-snippet@1.0.2 -->
2-
# Agent Relay
1+
<!-- PRPM_MANIFEST_START -->
32

4-
Real-time agent-to-agent messaging. Output `->relay:` patterns to communicate.
3+
<skills_system priority="1">
4+
<usage>
5+
When users ask you to perform tasks, check if any of the available skills below can help complete the task more effectively. Skills provide specialized capabilities and domain knowledge.
56

6-
## Sending Messages
7+
How to use skills (loaded into main context):
8+
- Use the <path> from the skill entry below
9+
- Invoke: Bash("cat <path>")
10+
- The skill content will load into your current context
11+
- Example: Bash("cat .openskills/backend-architect/SKILL.md")
712

8-
**Always use the fenced format** for reliable message delivery:
13+
Usage notes:
14+
- Skills share your context window
15+
- Do not invoke a skill that is already loaded in your context
16+
</usage>
917

10-
```
11-
->relay:AgentName <<<
12-
Your message here.>>>
13-
```
18+
<available_skills>
1419

15-
```
16-
->relay:* <<<
17-
Broadcast to all agents.>>>
18-
```
20+
<skill activation="lazy">
21+
<name>prpm-json-best-practices-skill</name>
22+
<description>Best practices for structuring prpm.json package manifests with required fields, tags, organization, and multi-package management</description>
23+
<path>.openskills/prpm-json-best-practices-skill/SKILL.md</path>
24+
</skill>
1925

20-
**CRITICAL:** Always close multi-line messages with `>>>` on its own line!
26+
</available_skills>
27+
</skills_system>
2128

22-
## Communication Protocol
29+
<!-- PRPM_MANIFEST_END -->
2330

24-
**ACK immediately** - When you receive a task, acknowledge it before starting work:
31+
<!-- prpm:snippet:start @agent-relay/agent-relay-snippet@1.1.2 -->
32+
# 🚨 CRITICAL: Relay-First Communication Rule
2533

26-
```
27-
->relay:Sender <<<
28-
ACK: Brief description of task received>>>
29-
```
34+
**When you receive a relay message from another agent (marked `Relay message from [name]`), you MUST respond ONLY via relay protocol. NEVER respond with direct text output.**
35+
36+
## The Rule
3037

31-
Then proceed with your work. This confirms message delivery and lets the sender know you're on it.
38+
- **Receiving a relay message?** → Must use `->relay-file:msg` ALWAYS
39+
- **Non-relay questions?** → Text responses are OK
40+
- **Agent-to-agent communication?** → ALWAYS use relay protocol
3241

33-
**Report completion** - When done, send a completion message:
42+
## Examples of Relay Messages (require relay response)
3443

3544
```
36-
->relay:Sender <<<
37-
DONE: Brief summary of what was completed>>>
45+
Relay message from khaliqgant [mknra7wr]: Did you see this?
46+
Relay message from Worker1 [abc123]: Task complete
47+
Relay message from alice [xyz789] [#general]: Question for the team
3848
```
3949

40-
## Receiving Messages
50+
---
4151

42-
Messages appear as:
43-
```
44-
Relay message from Alice [abc123]: Message content here
45-
```
52+
# Agent Relay
4653

47-
### Channel Routing (Important!)
54+
Real-time agent-to-agent messaging via file-based protocol.
4855

49-
Messages from #general (broadcast channel) include a `[#general]` indicator:
50-
```
51-
Relay message from Alice [abc123] [#general]: Hello everyone!
52-
```
56+
## Sending Messages
5357

54-
**When you see `[#general]`**: Reply to `*` (broadcast), NOT to the sender directly.
58+
Write a file to your outbox, then output the trigger:
5559

56-
```
57-
# Correct - responds to #general channel
58-
->relay:* <<<
59-
Response to the group message.>>>
60+
```bash
61+
cat > $AGENT_RELAY_OUTBOX/msg << 'EOF'
62+
TO: AgentName
6063
61-
# Wrong - sends as DM to sender instead of to the channel
62-
->relay:Alice <<<
63-
Response to the group message.>>>
64+
Your message here.
65+
EOF
6466
```
6567

66-
This ensures your response appears in the same channel as the original message.
68+
IMPORTANT: Output the trigger `->relay-file:msg` directly in your response text (not via echo in bash). The trigger must appear in your actual output, not just in command output.
6769

68-
If truncated, read full message:
69-
```bash
70-
agent-relay read abc123
71-
```
70+
> **Note**: `$AGENT_RELAY_OUTBOX` is automatically set by agent-relay when spawning agents. Data is stored in `.agent-relay/` within your project directory.
7271
73-
## Spawning Agents
72+
## Synchronous Messaging
7473

75-
Spawn workers to delegate tasks:
74+
By default, messages are fire-and-forget. Add `[await]` to block until the recipient ACKs:
7675

7776
```
78-
->relay:spawn WorkerName claude "task description"
79-
->relay:release WorkerName
77+
->relay:AgentB [await] Please confirm
8078
```
8179

82-
## Threads
83-
84-
Use threads to group related messages together. Thread syntax:
80+
Custom timeout (seconds or minutes):
8581

8682
```
87-
->relay:AgentName [thread:topic-name] <<<
88-
Your message here.>>>
83+
->relay:AgentB [await:30s] Please confirm
84+
->relay:AgentB [await:5m] Please confirm
8985
```
9086

91-
**When to use threads:**
92-
- Working on a specific issue (e.g., `[thread:agent-relay-299]`)
93-
- Back-and-forth discussions with another agent
94-
- Code review conversations
95-
- Any multi-message topic you want grouped
87+
Recipients auto-ACK after processing when a correlation ID is present.
88+
89+
## Message Format
9690

97-
**Examples:**
91+
```
92+
TO: Target
93+
THREAD: optional-thread
9894
95+
Message body (everything after blank line)
9996
```
100-
->relay:Protocol [thread:auth-feature] <<<
101-
How should we handle token refresh?>>>
10297

103-
->relay:Frontend [thread:auth-feature] <<<
104-
Use a 401 interceptor that auto-refreshes.>>>
98+
| TO Value | Behavior |
99+
|----------|----------|
100+
| `AgentName` | Direct message |
101+
| `*` | Broadcast to all |
102+
| `#channel` | Channel message |
105103

106-
->relay:Reviewer [thread:pr-123] <<<
107-
Please review src/auth/*.ts>>>
104+
## Agent Naming (Local vs Bridge)
108105

109-
->relay:Developer [thread:pr-123] <<<
110-
LGTM, approved!>>>
111-
```
106+
**Local communication** uses plain agent names. The `project:` prefix is **ONLY** for cross-project bridge mode.
107+
108+
| Context | Correct | Incorrect |
109+
|---------|---------|-----------|
110+
| Local (same project) | `TO: Lead` | `TO: project:lead` |
111+
| Local (same project) | `TO: Worker1` | `TO: myproject:Worker1` |
112+
| Bridge (cross-project) | `TO: frontend:Designer` | N/A |
113+
| Bridge (to another lead) | `TO: otherproject:lead` | N/A |
112114

113-
Thread messages appear grouped in the dashboard with reply counts.
115+
**Common mistake**: Using `project:lead` when communicating locally. This will fail because the relay looks for an agent literally named "project:lead".
114116

115-
## Common Patterns
117+
```bash
118+
# CORRECT - local communication to Lead agent
119+
cat > $AGENT_RELAY_OUTBOX/msg << 'EOF'
120+
TO: Lead
116121
122+
Status update here.
123+
EOF
117124
```
118-
->relay:Lead <<<
119-
ACK: Starting /api/register implementation>>>
120125

121-
->relay:* <<<
122-
STATUS: Working on auth module>>>
126+
```bash
127+
# WRONG - project: prefix is only for bridge mode
128+
cat > $AGENT_RELAY_OUTBOX/msg << 'EOF'
129+
TO: project:lead
130+
131+
This will fail locally!
132+
EOF
133+
```
123134

124-
->relay:Lead <<<
125-
DONE: Auth module complete>>>
135+
## Spawning & Releasing
126136

127-
->relay:Developer <<<
128-
TASK: Implement /api/register>>>
137+
**IMPORTANT**: The filename is always `spawn` (not `spawn-agentname`) and the trigger is always `->relay-file:spawn`. Spawn agents one at a time sequentially.
129138

130-
->relay:Reviewer [thread:code-review-auth] <<<
131-
REVIEW: Please check src/auth/*.ts>>>
139+
```bash
140+
# Spawn
141+
cat > $AGENT_RELAY_OUTBOX/spawn << 'EOF'
142+
KIND: spawn
143+
NAME: WorkerName
144+
CLI: claude
132145
133-
->relay:Architect <<<
134-
QUESTION: JWT or sessions?>>>
146+
Task description here.
147+
EOF
135148
```
149+
Then: `->relay-file:spawn`
136150

137-
## Rules
151+
```bash
152+
# Release
153+
cat > $AGENT_RELAY_OUTBOX/release << 'EOF'
154+
KIND: release
155+
NAME: WorkerName
156+
EOF
157+
```
158+
Then: `->relay-file:release`
138159

139-
- Pattern must be at line start (whitespace OK)
140-
- Escape with `\->relay:` to output literally
141-
- Check daemon status: `agent-relay status`
142-
<!-- prpm:snippet:end @agent-relay/agent-relay-snippet@1.0.2 -->
143-
<!-- PRPM_MANIFEST_START -->
160+
## When You Are Spawned
144161

145-
<skills_system priority="1">
146-
<usage>
147-
When users ask you to perform tasks, check if any of the available skills below can help complete the task more effectively. Skills provide specialized capabilities and domain knowledge.
162+
If you were spawned by another agent:
148163

149-
How to use skills (loaded into main context):
150-
- Use the <path> from the skill entry below
151-
- Invoke: Bash("cat <path>")
152-
- The skill content will load into your current context
153-
- Example: Bash("cat .openskills/backend-architect/SKILL.md")
164+
1. **Check who spawned you**: `echo $AGENT_RELAY_SPAWNER`
165+
2. **Your first message** is your task from your spawner - reply to THEM, not "spawner"
166+
3. **Report status** to your spawner (your lead), not broadcast
154167

155-
Usage notes:
156-
- Skills share your context window
157-
- Do not invoke a skill that is already loaded in your context
158-
</usage>
168+
```bash
169+
# Check your spawner
170+
echo "I was spawned by: $AGENT_RELAY_SPAWNER"
159171

160-
<available_skills>
172+
# Reply to your spawner
173+
cat > $AGENT_RELAY_OUTBOX/msg << 'EOF'
174+
TO: $AGENT_RELAY_SPAWNER
161175
162-
<skill activation="lazy">
163-
<name>prpm-json-best-practices-skill</name>
164-
<description>Best practices for structuring prpm.json package manifests with required fields, tags, organization, and multi-package management</description>
165-
<path>.openskills/prpm-json-best-practices-skill/SKILL.md</path>
166-
</skill>
176+
ACK: Starting on the task.
177+
EOF
178+
```
179+
Then: `->relay-file:msg`
167180

168-
</available_skills>
169-
</skills_system>
181+
## Receiving Messages
170182

171-
<!-- PRPM_MANIFEST_END -->
183+
Messages appear as:
184+
```
185+
Relay message from Alice [abc123]: Content here
186+
```
187+
188+
Channel messages include `[#channel]`:
189+
```
190+
Relay message from Alice [abc123] [#general]: Hello!
191+
```
192+
Reply to the channel shown, not the sender.
193+
194+
## Protocol
195+
196+
- **ACK** when you receive a task: `ACK: Brief description`
197+
- **DONE** when complete: `DONE: What was accomplished`
198+
- Send status to your **lead** (the agent in `$AGENT_RELAY_SPAWNER`), not broadcast
199+
200+
## Headers Reference
201+
202+
| Header | Required | Description |
203+
|--------|----------|-------------|
204+
| TO | Yes (messages) | Target agent/channel |
205+
| KIND | No | `message` (default), `spawn`, `release` |
206+
| NAME | Yes (spawn/release) | Agent name |
207+
| CLI | Yes (spawn) | CLI to use |
208+
| THREAD | No | Thread identifier |
209+
<!-- prpm:snippet:end @agent-relay/agent-relay-snippet@1.1.2 -->

‎package.json‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
{
22
"name": "agent-trajectories",
3-
"version": "0.2.3",
3+
"version": "0.3.0",
44
"description": "Capture the complete train of thought of agent work as first-class artifacts",
55
"type": "module",
66
"main": "dist/index.js",

‎prpm.lock‎

Lines changed: 18 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -85,7 +85,24 @@
8585
"position": "append"
8686
}
8787
}
88+
},
89+
"@agent-relay/agent-relay-snippet#agents.md:CLAUDE.md": {
90+
"version": "1.1.2",
91+
"resolved": "https://registry.prpm.dev/api/v1/packages/%40agent-relay%2Fagent-relay-snippet/1.1.2.tar.gz",
92+
"integrity": "sha256-1b575f52991910e379b7e1828ee4d593135e774e2a2cea139c76d683e831ad72",
93+
"format": "agents.md",
94+
"subtype": "snippet",
95+
"sourceFormat": "generic",
96+
"sourceSubtype": "snippet",
97+
"installedPath": "CLAUDE.md",
98+
"snippetMetadata": {
99+
"targetPath": "CLAUDE.md",
100+
"config": {
101+
"target": "CLAUDE.md",
102+
"position": "append"
103+
}
104+
}
88105
}
89106
},
90-
"generated": "2026-01-02T09:59:32.031Z"
107+
"generated": "2026-01-30T10:39:38.246Z"
91108
}

0 commit comments

Comments
 (0)