diff --git a/README.md b/README.md index 5d385fb..3e4699b 100644 --- a/README.md +++ b/README.md @@ -23,14 +23,14 @@ Package metadata lives in [prpm.json](prpm.json). The repo currently publishes ` | [adding-swarm-patterns](skills/adding-swarm-patterns/SKILL.md) | 1.0.0 | Checklist for extending agent-relay with a new swarm pattern — TypeScript types, JSON schema, YAML template, and pattern/template docs. | | [creating-cloud-persona](skills/creating-cloud-persona/SKILL.md) | 1.0.6 | Create or update a Workforce cloud persona with `persona.json`/`persona.ts`, `agent.ts`, integration scope and adapter config guidance, vendored examples, and production-correctness checks. | | [factory-config](skills/factory-config/SKILL.md) | 1.0.2 | Create and validate Agent Relay Factory configs for repo routing, Linear states, GitHub issue ingestion, Slack, babysitter mode, and Relayflows dispatch wiring boundaries. | -| [openclaw-orchestrator](skills/openclaw-orchestrator/SKILL.md) | 1.0.0 | Run headless multi-agent orchestration sessions via Agent Relay — spawn teams across Claude/Codex/Gemini/Pi/Droid, create channels, and manage agent lifecycle. | +| [openclaw-orchestrator](skills/openclaw-orchestrator/SKILL.md) | 2.0.0 | OpenClaw-specific setup and completion reporting for a headless Agent Relay team; defers to `orchestrating-agent-relay` for broker, spawn, and coordination mechanics. | ## Slash Commands | Command | Version | Description | |---------|---------|-------------| -| [/create-workflow](commands/create-workflow.md) | 1.0.4 | Scaffold a model-agnostic Agent Relay workflow using the workflow and swarm-pattern skills, including selected review-depth review/fix loops with test hardening. | -| [/spawn](commands/spawn.md) | 1.0.0 | Bootstrap the broker and spawn a worker for `claude`, `codex`, `opencode`, `droid`, `gemini`, or `pi`. | +| [/create-workflow](commands/create-workflow.md) | 1.0.5 | Scaffold a model-agnostic Agent Relay workflow using the workflow and swarm-pattern skills, including selected review-depth review/fix loops with test hardening. | +| [/spawn](commands/spawn.md) | 1.1.0 | Bootstrap the broker (`agent-relay node up`) and spawn a worker for `claude`, `codex`, `opencode`, `droid`, `gemini`, or `pi`. | | [/review-loop](commands/review-loop.md) | 1.0.1 | Run a dual-reviewer code-review loop with repair and fresh-context signoff. | ## Claude Relay Plugin diff --git a/commands/create-workflow.md b/commands/create-workflow.md index b2a97d4..929fea1 100644 --- a/commands/create-workflow.md +++ b/commands/create-workflow.md @@ -24,7 +24,7 @@ Scaffold a new multi-agent workflow that runs on the agent-relay broker. This co - Keep prompts model-agnostic — never hardcode a specific model name into a step's instructions. - Size steps so a single agent can complete them in one focused pass. -4. **Wire the team.** Define the lead + worker agents, the channel(s) they share, and the team name. Reuse names from `agent-relay agents` only after checking for collisions. +4. **Wire the team.** Define the lead + worker agents, the channel(s) they share, and the team name. Reuse names from `agent-relay node agent list` only after checking for collisions. 5. **Provide a runnable example.** Output one minimal end-to-end example that demonstrates feeding `$ARGUMENTS` into the workflow and shows the expected `{{steps.*.output}}` shape at each stage. diff --git a/commands/spawn.md b/commands/spawn.md index ac90b47..95e5c13 100644 --- a/commands/spawn.md +++ b/commands/spawn.md @@ -13,7 +13,7 @@ Bootstrap the agent-relay broker (if not already running) and spawn a worker on ## Instructions -1. **Load the orchestrator skill.** Read the `orchestrating-agent-relay` skill. After installation with `npx prpm install @agent-relay/orchestrating-agent-relay`, look in the harness-managed skill locations first: `.claude/skills/orchestrating-agent-relay/SKILL.md` or `.agents/skills/orchestrating-agent-relay/SKILL.md`. When developing inside this repo, the same source lives at `skills/orchestrating-agent-relay/SKILL.md`. All broker startup, workspace key handling, channel creation, and spawn semantics come from that skill — do not improvise. +1. **Load the orchestrator skill.** Read the `orchestrating-agent-relay` skill. After installation with `npx prpm install @agent-relay/orchestrating-agent-relay`, look in the harness-managed skill locations first: `.claude/skills/orchestrating-agent-relay/SKILL.md` or `.agents/skills/orchestrating-agent-relay/SKILL.md`. When developing inside this repo, the same source lives at `skills/orchestrating-agent-relay/SKILL.md`. All broker startup, workspace handling, channel creation, and spawn semantics come from that skill — do not improvise. 2. **Parse arguments from `$ARGUMENTS`:** - Required positional: `$1` — the harness (`claude`, `codex`, `opencode`, `droid`, `gemini`, `pi`). @@ -21,29 +21,35 @@ Bootstrap the agent-relay broker (if not already running) and spawn a worker on - Optional `--task ""` — the task prompt for the spawned worker. If omitted, prompt the user for the task before spawning. 3. **Bootstrap the broker (idempotent).** Per the orchestrator skill: - - Run `agent-relay status` first. If broker is up, skip startup. - - If down, ensure a workspace key is available (`$RELAYCAST_WORKSPACE_KEY` or prompt the user). Then `agent-relay up --workspace-key $KEY --background --no-spawn`. - - Verify broker came up cleanly before spawning. + - Run `agent-relay node status` first. If the broker is already running, skip startup. + - If it is down, run `agent-relay node up --background --verbose`. A workspace is auto-created when none is set — do not prompt the user for a key. + - Confirm readiness with `agent-relay node status --wait-for 10` before spawning. -4. **Ensure a coordination channel exists.** Default to `#orchestrator` unless the user specified one. Create it via `mcporter call relaycast create_channel` if missing, then join it. - -5. **Spawn the worker.** Construct the spawn command from parsed args: - ```text - agent-relay spawn $1 [--model ] [--team orchestrator] "" +4. **Spawn the worker.** + ```bash + agent-relay node agent spawn $1 --name --channels orchestrator [--model ] --task "" ``` - - `` should be unique per run (e.g., `worker-`) to avoid 409 conflicts. - - Inject the standard task-prompt template from the orchestrator skill (channel posting, inbox checks, completion event) so the worker can communicate. + - `` should be unique per run (e.g. `worker-`) to avoid 409 conflicts. + - `--channels` creates and joins the channel; there is no separate create step and no `--team` flag. + - Include the worker protocol from the orchestrator skill in the task text: ACK on receipt, DONE with evidence, report to `orchestrator` or the channel (never to `broker`), and do not self-release. + +5. **Offer a follow-along link.** Run `agent-relay observer` and print the URL it returns. It is backed by a scoped, read-only, expiring token. Never build an observer URL from a workspace key. -6. **Report back.** Print the spawned agent name, the channel it joined, and the tail command (`agent-relay agents:logs `) so the user can monitor it. +6. **Report back.** Print the spawned agent name, the channel it joined, and the monitoring commands below. ## Output Contract - One-line confirmation: broker state, agent name, harness, model, channel. -- Monitoring commands (logs, channel messages, kill). -- If something failed (workspace key missing, harness unsupported, broker won't start), surface the exact error and the orchestrator-skill fix from its "Gotchas" table — do not silently continue. +- Monitoring commands: + - `agent-relay node agent list` — liveness (pid, status, uptime) + - `agent-relay node agent attach --mode view` — watch its output + - `agent-relay message inbox check` — read what it sent you + - `agent-relay node agent release ` — stop it +- If something failed (harness unsupported, broker won't start), surface the exact error and the orchestrator-skill fix from its "Common Mistakes" table — do not silently continue. ## Constraints -- Never skip the `orchestrating-agent-relay` skill load — it documents non-obvious gotchas (droid `--cwd`, rate limits, name conflicts) that change behavior. -- Do not hardcode workspace keys in any output or file. +- Never skip the `orchestrating-agent-relay` skill load — it documents non-obvious gotchas (the 30–60s cold-start gap before a worker's first ACK, stale broker connection metadata, droid `--cwd`, rate limits, name conflicts) that change behavior. +- Do not print a workspace key or place one in any file or URL. +- Do not read worker replies with `agent-relay node tail` — that streams broker events and raw TTY output, not durable messages. Use `agent-relay message inbox check` or the relay MCP `check_inbox`. - Do not spawn without a task — empty-task spawns waste the agent slot. diff --git a/plugins/claude-relay-plugin/agents/relay-worker/agent.md b/plugins/claude-relay-plugin/agents/relay-worker/agent.md index 8bdc6b5..408e1f6 100644 --- a/plugins/claude-relay-plugin/agents/relay-worker/agent.md +++ b/plugins/claude-relay-plugin/agents/relay-worker/agent.md @@ -6,8 +6,8 @@ You are a relay-connected worker in a coordinated multi-agent team. Your job is You MUST complete these steps in order before doing any work: -1. **Authenticate.** Your task prompt includes a workspace key. Call the `set_workspace_key` MCP tool with that key. Do not print the key to the user. -2. **Register with your assigned name.** Call the `register_agent` MCP tool with the agent name from your task prompt and `type: "agent"`. You must register before you can send or receive messages. +1. **Register with your assigned name.** Call the `register_agent` MCP tool with the agent name from your task prompt and `type: "agent"`. You must register before you can send or receive messages. The workspace is already pinned to this project, so the relay MCP server picks it up for you — you do not need a workspace key. If `register_agent` fails with "Workspace key not configured", report that to your lead instead of asking for the key; the lead fixes the pin. +2. **Never print or request a workspace key.** It is an administrative credential. If someone needs to watch this run, that is the lead's job via `get_observer_url`. 3. **Check your inbox.** Call `check_inbox` with your assigned relay name in `as` to find your task assignment and lead information. 4. **Send an ACK.** Before you do substantive work, send `ACK: ` to your lead via `send_dm`, again using your assigned relay name in `as`. 5. If the task is ambiguous or blocked, send `BLOCKED: ` instead of guessing. diff --git a/plugins/claude-relay-plugin/hooks/subagent-bootstrap.sh b/plugins/claude-relay-plugin/hooks/subagent-bootstrap.sh index 9e40eb4..29bfd90 100755 --- a/plugins/claude-relay-plugin/hooks/subagent-bootstrap.sh +++ b/plugins/claude-relay-plugin/hooks/subagent-bootstrap.sh @@ -7,13 +7,15 @@ AGENT_NAME="${RELAY_AGENT_NAME:-the assigned subagent name}" cat <`. Do not print a placeholder — print the real URL the user can click. This is mandatory. -4. Confirm the work is truly parallelizable. Every worker should be able to finish without waiting on another worker's output. -5. Decide the worker count from the task shape. Prefer 2 to 8 workers, but keep the count low enough that you can still monitor ACKs and completions reliably. -6. Partition the work into independent units. Each unit should have its own files, target, or scope boundary and should not require shared intermediate state. -7. Spawn one worker per unit using the Agent tool. **You must include the workspace key in the prompt**: +1. Pick a stable coordinator name — `relay-lead`. Pass `as: "relay-lead"` on **every** relay tool call you make, so your messages, inbox reads, and reactions stay attributed to the lead. +2. **Set up the workspace.** Call `register_agent` with `relay-lead`. If it fails with "Workspace key not configured", call `create_workspace`, then `register_agent` again. Both `create_workspace` and `set_workspace_key` pin the workspace to this project, which is how workers pick it up. +3. **Give the user a link to follow along.** Call `get_observer_url` and print the URL it returns. It is backed by a read-only token that expires, so it is safe to share. Never build an observer URL from the workspace key, and never print the key. +4. Confirm the work is genuinely parallelizable. Every worker must be able to finish without waiting on another worker's output. If that is not true, use the pipeline pattern instead. +5. Pick the worker count from the task shape. Prefer 2–8, and stay low enough that you can still track every ACK and DONE. +6. Partition the work into independent units — each with its own files, target, or scope boundary, and no shared intermediate state. +7. Spawn one worker per unit with the Agent tool: ``` Agent( subagent_type: "relay-worker", run_in_background: true, prompt: "You are relay-worker-N. Your lead is relay-lead. - Workspace key: . - CRITICAL: On every relay tool call, include as: \"relay-worker-N\". Without as, your messages can be attributed to another agent. + CRITICAL: pass as: \"relay-worker-N\" on every relay tool call, or your messages + can be attributed to another agent. Your unit: [specific target/scope]. Files: [list of files/directories]. - Deliver: [concrete output]." + Deliver: [concrete output]. + Do NOT release yourself when done — report DONE and stay idle for review." ) ``` -8. Each worker's prompt must include: - - the workspace key - - the unit it owns - - the exact files, directories, or target it should handle - - its assigned relay name and who its lead is - - a reminder to use `as: ""` on every relay tool call -9. Wait for ACK from every worker via relay inbox with `check_inbox(as: "relay-lead")`. Missing ACK means the worker is not ready. -10. Let workers run independently. Only send follow-up DMs for blockers, missing ACKs, or a global decision that changes all units, always using `as: "relay-lead"` for coordinator messages. -11. Collect all DONE messages, verify the outputs, and merge the final summary. Call out any units that finished partially or encountered blockers. +8. Wait for an ACK from every worker with `check_inbox(as: "relay-lead")`. A missing ACK means that worker is not working — re-DM it. +9. Keep a live worker table in your notes: name, unit, ACK, blocked, DONE. +10. Let workers run independently. Only DM them for blockers, missing ACKs, or a global decision that changes every unit. +11. Collect every DONE, verify the outputs yourself, and merge the summary. Call out units that finished partially or hit blockers. ## Rules - Do not use this pattern when stage N depends on stage N-1. That is a pipeline. -- Do not give multiple workers the same files unless duplicate review is intentional. -- Keep the task wording uniform so worker outputs are easy to compare and merge. -- Workers cannot spawn their own subagents — only the lead can spawn workers. +- Do not give two workers the same files unless duplicate review is the point. +- Keep the task wording uniform across units so the outputs are easy to compare and merge. +- Workers cannot spawn their own subagents — only the lead spawns. diff --git a/plugins/claude-relay-plugin/skills/relay-pipeline/SKILL.md b/plugins/claude-relay-plugin/skills/relay-pipeline/SKILL.md index dac0a0b..85df127 100644 --- a/plugins/claude-relay-plugin/skills/relay-pipeline/SKILL.md +++ b/plugins/claude-relay-plugin/skills/relay-pipeline/SKILL.md @@ -11,57 +11,55 @@ $ARGUMENTS ## How spawning works -Workers are spawned using Claude Code's built-in **Agent tool**, not the relay MCP tools. The relay is only used for communication between agents. +Workers are spawned with Claude Code's built-in **Agent tool**. The relay is only used for communication between agents. -- You **must** use `subagent_type: "relay-worker"` when spawning workers. Only `relay-worker` subagents get the Agent Relay MCP server, inbox-polling hooks, and the worker protocol. Regular subagent types (e.g. `researcher`, `general-purpose`) cannot communicate via relay. -- Run pipeline stages in **foreground mode** (default) so you wait for each stage to complete before starting the next. -- Each worker's prompt **must include the workspace key** so the worker can authenticate. See the spawn example below. -- The `SubagentStart` hook automatically injects relay bootstrap instructions into every spawned worker. -- Do not introduce extra setup scripts or dependencies in this workflow. Use the existing plugin hooks, Agent Relay MCP tools, and `relay-worker` agent definition only. -- Use relay MCP tools (`send_dm`, `check_inbox`) to receive handoff artifacts from each stage. +- Use `subagent_type: "relay-worker"`. Only `relay-worker` subagents get the Agent Relay MCP server, the inbox-polling hooks, and the worker protocol. Other subagent types (`researcher`, `general-purpose`, …) cannot talk over the relay. +- Run pipeline stages in **foreground mode** (the default) so each stage finishes before the next starts. +- Workers inherit the workspace automatically — the relay MCP server resolves the workspace pinned to this project. **Do not put the workspace key in a worker prompt.** It is an administrative credential, and copying it into N prompts puts it in N transcripts. If a worker reports no workspace, fix the pin (step 2) rather than pasting the key. +- The `SubagentStart` hook injects the relay bootstrap (register, check inbox, ACK, DONE) into every worker. +- Use the relay MCP tools (`send_dm`, `check_inbox`) to receive each stage's handoff. +- Do not add setup scripts or dependencies. Use the plugin's existing hooks, MCP tools, and `relay-worker` agent definition. ## Protocol -1. Pick a stable coordinator name such as `relay-lead`. On every relay tool call you make as the coordinator, include `as: "relay-lead"` so your messages, inbox checks, and reactions stay attributed to the lead. -2. **Set up the workspace.** Try calling `register_agent` with a coordinator name like `relay-lead`. If it fails with "Workspace key not configured", call `create_workspace` to generate one, then call `set_workspace_key` with the returned key, then `register_agent`. Save the workspace key — you will pass it to every worker. -3. **Tell the user they can follow along with the conversation.** Print the full observer URL with the real key value: `https://agentrelay.com/observer?key=`. Do not print a placeholder — print the real URL the user can click. This is mandatory. -4. Break the task into ordered stages. Each stage must have a clear handoff artifact for the next stage: a summary, decision, file path, diff, or verified output. -5. Keep the number of stages low and explicit. Prefer 2 to 5 stages with distinct responsibilities. -6. Start stage 1. Spawn its worker using the Agent tool in foreground mode. **Include the workspace key**: +1. Pick a stable coordinator name — `relay-lead`. Pass `as: "relay-lead"` on **every** relay tool call you make, so your messages, inbox reads, and reactions stay attributed to the lead. +2. **Set up the workspace.** Call `register_agent` with `relay-lead`. If it fails with "Workspace key not configured", call `create_workspace`, then `register_agent` again. Both `create_workspace` and `set_workspace_key` pin the workspace to this project, which is how workers pick it up. +3. **Give the user a link to follow along.** Call `get_observer_url` and print the URL it returns. It is backed by a read-only token that expires, so it is safe to share. Never build an observer URL from the workspace key, and never print the key. +4. Break the task into ordered stages. Every stage needs a concrete handoff artifact for the next one: a summary, a decision, a file path, a diff, or a verified output. +5. Keep the stage count low and explicit — prefer 2–5 with distinct responsibilities. +6. Start stage 1. Spawn its worker with the Agent tool in foreground mode: ``` Agent( subagent_type: "relay-worker", prompt: "You are relay-stage-1. Your lead is relay-lead. - Workspace key: . - CRITICAL: On every relay tool call, include as: \"relay-stage-1\". Without as, your messages can be attributed to another agent. + CRITICAL: pass as: \"relay-stage-1\" on every relay tool call, or your messages + can be attributed to another agent. Your task: [stage 1 scope]. Files: [relevant files]. - When done, send your lead a DONE message with: [handoff artifact description]." + When done, DM your lead a DONE message containing: [handoff artifact description]. + Do NOT release yourself when done — stay idle in case the stage needs a fix." ) ``` -7. Wait for the stage 1 DONE message via relay inbox with `check_inbox(as: "relay-lead")`. Do not start downstream work on assumptions. -8. For each later stage, spawn a new worker with: - - the workspace key - - the original task context - - the upstream DONE summary and handoff artifact - - any produced files, decisions, or constraints from previous stages +7. Wait for stage 1's DONE with `check_inbox(as: "relay-lead")`. Never start downstream work on an assumption about what the stage produced. +8. For each later stage, spawn a worker carrying the original task context, the upstream DONE summary and handoff artifact, and any files, decisions, or constraints the earlier stages produced: ``` Agent( subagent_type: "relay-worker", prompt: "You are relay-stage-2. Your lead is relay-lead. - Workspace key: . - CRITICAL: On every relay tool call, include as: \"relay-stage-2\". Without as, your messages can be attributed to another agent. + CRITICAL: pass as: \"relay-stage-2\" on every relay tool call. Previous stage completed: [DONE summary from stage 1]. - Your task: [stage 2 scope using stage 1 output]. - Files: [relevant files]." + Your task: [stage 2 scope, using stage 1's output]. + Files: [relevant files]. + Do NOT release yourself when done — stay idle in case the stage needs a fix." ) ``` -9. After each stage finishes, validate that the handoff is sufficient. If the output is ambiguous, ask the user for clarification before starting the next stage. -10. Continue until the final stage completes, then synthesize the end-to-end result and highlight where each handoff happened. +9. Keep a live stage table in your notes: stage, scope, ACK, blocked, DONE, handoff artifact. +10. After each stage, check the handoff is sufficient. If it is ambiguous, ask the user before starting the next stage. +11. When the last stage finishes, synthesize the end-to-end result and show where each handoff happened. ## Rules -- Use pipeline only for genuine dependencies. If stages can run independently, switch to fan-out. -- Handoffs must be explicit. A downstream worker should never need to guess what mattered from the previous stage. -- If a stage fails or is blocked, stop the pipeline, resolve the blocker, and then resume from the blocked stage. -- Workers cannot spawn their own subagents — only the lead can spawn workers. +- Use a pipeline only for genuine dependencies. If the stages can run independently, switch to fan-out. +- Handoffs must be explicit. A downstream worker should never have to guess what mattered upstream. +- If a stage fails or is blocked, stop the pipeline, resolve the blocker, and resume from that stage. +- Workers cannot spawn their own subagents — only the lead spawns. diff --git a/plugins/claude-relay-plugin/skills/relay-team/SKILL.md b/plugins/claude-relay-plugin/skills/relay-team/SKILL.md index a0c4691..a3d86ce 100644 --- a/plugins/claude-relay-plugin/skills/relay-team/SKILL.md +++ b/plugins/claude-relay-plugin/skills/relay-team/SKILL.md @@ -11,45 +11,46 @@ $ARGUMENTS ## How spawning works -Workers are spawned using Claude Code's built-in **Agent tool**, not the relay MCP tools. The relay is only used for communication between agents. +Workers are spawned with Claude Code's built-in **Agent tool**. The relay is only used for communication between agents. -- You **must** use `subagent_type: "relay-worker"` when spawning workers. Only `relay-worker` subagents get the Agent Relay MCP server, inbox-polling hooks, and the worker protocol. Regular subagent types (e.g. `researcher`, `general-purpose`) cannot communicate via relay. -- Run workers in **background mode** (`run_in_background: true`) so they execute concurrently. -- Each worker's prompt **must include the workspace key** so the worker can authenticate. See the spawn example below. -- The `SubagentStart` hook automatically injects relay bootstrap instructions (register, check inbox, ACK, DONE protocol) into every spawned worker. -- Do not introduce extra setup scripts or dependencies in this workflow. Use the existing plugin hooks, Agent Relay MCP tools, and `relay-worker` agent definition only. -- Use relay MCP tools (`send_dm`, `post_message`, `check_inbox`) to communicate with workers after they're running. +- Use `subagent_type: "relay-worker"`. Only `relay-worker` subagents get the Agent Relay MCP server, the inbox-polling hooks, and the worker protocol. Other subagent types (`researcher`, `general-purpose`, …) cannot talk over the relay. +- Run workers in **background mode** (`run_in_background: true`) so they work concurrently. +- Workers inherit the workspace automatically — the relay MCP server resolves the workspace pinned to this project. **Do not put the workspace key in a worker prompt.** It is an administrative credential, and copying it into N prompts puts it in N transcripts. If a worker reports no workspace, fix the pin (step 2) rather than pasting the key. +- The `SubagentStart` hook injects the relay bootstrap (register, check inbox, ACK, DONE) into every worker. +- Use the relay MCP tools (`send_dm`, `post_message`, `check_inbox`) to talk to workers once they are running. +- Do not add setup scripts or dependencies. Use the plugin's existing hooks, MCP tools, and `relay-worker` agent definition. ## Protocol -1. Pick a stable coordinator name such as `relay-lead`. On every relay tool call you make as the coordinator, include `as: "relay-lead"` so your messages, inbox checks, and reactions stay attributed to the lead. -2. **Set up the workspace.** Try calling `register_agent` with a coordinator name like `relay-lead`. If it fails with "Workspace key not configured", call `create_workspace` to generate one, then call `set_workspace_key` with the returned key, then `register_agent`. Save the workspace key — you will pass it to every worker. -3. **Tell the user they can follow along with the conversation.** Print the full observer URL with the real key value: `https://agentrelay.com/observer?key=`. Do not print a placeholder — print the real URL the user can click. This is mandatory. -4. Read the task, inspect the relevant code or files, and decide whether parallel work is justified. Prefer 1 worker for tightly coupled work and 2 to 5 workers for genuinely separable work. -5. Break the task into clear, non-overlapping worker scopes. Each worker needs a concrete deliverable, the relevant files or directories, and an explicit success condition. -6. Spawn each worker using the Agent tool. **You must include the workspace key in the prompt** so the worker can call `set_workspace_key`: +1. Pick a stable coordinator name — `relay-lead`. Pass `as: "relay-lead"` on **every** relay tool call you make, so your messages, inbox reads, and reactions stay attributed to the lead. +2. **Set up the workspace.** Call `register_agent` with `relay-lead`. If it fails with "Workspace key not configured", call `create_workspace`, then `register_agent` again. Both `create_workspace` and `set_workspace_key` pin the workspace to this project, which is how workers pick it up. +3. **Give the user a link to follow along.** Call `get_observer_url` and print the URL it returns. It is backed by a read-only token that expires, so it is safe to share. Never build an observer URL from the workspace key, and never print the key. +4. Read the task, inspect the relevant code, and decide whether parallel work is justified. Prefer 1 worker for tightly coupled work, 2–5 for genuinely separable work. +5. Break the task into non-overlapping scopes. Each worker needs a concrete deliverable, the relevant files, and an explicit success condition. +6. Spawn each worker with the Agent tool: ``` Agent( subagent_type: "relay-worker", run_in_background: true, prompt: "You are relay-worker-1. Your lead is relay-lead. - Workspace key: . - CRITICAL: On every relay tool call, include as: \"relay-worker-1\". Without as, your messages can be attributed to another agent. + CRITICAL: pass as: \"relay-worker-1\" on every relay tool call, or your messages + can be attributed to another agent. Your task: [specific scope and deliverables]. Files: [list of files/directories]. - Success condition: [what done looks like]." + Success condition: [what done looks like]. + Do NOT release yourself when done — report DONE and stay idle for review." ) ``` -7. After spawning, send each worker a DM via relay with any additional context they need. Include `as: "relay-lead"` on those coordinator messages. -8. Monitor the relay inbox for ACKs with `check_inbox(as: "relay-lead")`. Do not assume a worker is active until it ACKs. Send a follow-up DM if an ACK does not arrive. -9. Maintain a live worker table in your own notes with: worker name, scope, ACK status, blocker status, and DONE status. -10. Coordinate dependencies explicitly. Relay only the minimum context each worker needs, and keep workers independent whenever possible. -11. Collect every DONE message, verify the results, and synthesize the final output. Include what each worker finished and any remaining gaps or risks. +7. After spawning, DM each worker any extra context it needs. +8. Watch for ACKs with `check_inbox(as: "relay-lead")`. A worker is not working until it ACKs — expect a cold-start delay, and re-DM if an ACK never arrives. +9. Keep a live worker table in your notes: name, scope, ACK, blocked, DONE. +10. Coordinate dependencies explicitly. Send each worker the minimum context it needs and keep workers independent where you can. +11. Collect every DONE, verify the results yourself, and synthesize the final answer — what each worker finished, plus remaining gaps and risks. ## Rules -- Prefer fewer well-scoped workers over many vague workers. -- Do not let workers infer coordination details. Send explicit follow-up instructions when assumptions change. -- If the task turns out to be independent across targets, switch to the fan-out pattern instead of keeping a central coordinator busy. -- If the task turns out to be sequential, switch to the pipeline pattern instead of forcing parallelism. -- Workers cannot spawn their own subagents — only the lead can spawn workers. +- Prefer fewer well-scoped workers over many vague ones. +- Do not let workers infer coordination details. Send explicit follow-ups when assumptions change. +- If the work turns out to be independent across targets, switch to fan-out instead of keeping a coordinator busy. +- If it turns out to be sequential, switch to pipeline instead of forcing parallelism. +- Workers cannot spawn their own subagents — only the lead spawns. diff --git a/prpm.json b/prpm.json index 0339e99..2d62eec 100644 --- a/prpm.json +++ b/prpm.json @@ -249,7 +249,7 @@ }, { "name": "create-workflow", - "version": "1.0.4", + "version": "1.0.5", "description": "Slash command to scaffold a new agent-relay multi-agent workflow using the writing-agent-relay-workflows skill - harness-agnostic, model-agnostic prompts, picks the right swarm pattern, and emits a runnable WorkflowBuilder file with verify gates, selected review-depth review/fix loops with test hardening, and integration notes", "format": "claude", "subtype": "slash-command", @@ -267,7 +267,7 @@ }, { "name": "spawn", - "version": "1.0.0", + "version": "1.1.0", "description": "Slash command for relay-orchestrator that bootstraps the agent-relay broker and spawns a worker on the chosen harness (claude, codex, opencode, droid, gemini, pi) with optional --model and --task - loads the orchestrator skill so infrastructure, channels, and lifecycle just work", "format": "claude", "subtype": "slash-command", @@ -395,8 +395,8 @@ }, { "name": "openclaw-orchestrator", - "version": "1.0.0", - "description": "Run headless multi-agent orchestration sessions via Agent Relay. Use when spawning teams of agents, creating channels for coordination, managing agent lifecycle, and running parallel workloads across Claude/Codex/Gemini/Pi/Droid agents.", + "version": "2.0.0", + "description": "Run headless multi-agent Agent Relay sessions from OpenClaw. Use when spawning teams of agents, coordinating them over channels, and managing agent lifecycle from an OpenClaw session. Covers only the OpenClaw-specific setup and event reporting; the broker, spawn, and coordination mechanics come from the orchestrating-agent-relay skill.", "format": "claude", "subtype": "skill", "files": [ diff --git a/skills/openclaw-orchestrator/SKILL.md b/skills/openclaw-orchestrator/SKILL.md index 76c267d..c2e256f 100644 --- a/skills/openclaw-orchestrator/SKILL.md +++ b/skills/openclaw-orchestrator/SKILL.md @@ -1,185 +1,96 @@ --- -name: agent-relay-orchestrator -version: 1.0.0 -description: Run headless multi-agent orchestration sessions via Agent Relay. Use when spawning teams of agents, creating channels for coordination, managing agent lifecycle, and running parallel workloads across Claude/Codex/Gemini/Pi/Droid agents. -homepage: https://agentrelay.com/openclaw -metadata: { 'category': 'orchestration', 'requires': 'agent-relay' } +name: openclaw-orchestrator +description: Run headless multi-agent Agent Relay sessions from OpenClaw. Use when spawning teams of agents, coordinating them over channels, and managing agent lifecycle from an OpenClaw session. Covers only the OpenClaw-specific setup and event reporting; the broker, spawn, and coordination mechanics come from the orchestrating-agent-relay skill. --- -# Agent Relay Orchestrator +# OpenClaw Orchestrator -Run headless multi-agent sessions: start infrastructure, join a workspace, create channels, spawn teams, coordinate via messaging, and manage lifecycle. +Run a headless Agent Relay team from an OpenClaw session. -## Prerequisites - -- `agent-relay` CLI installed (`npm i -g agent-relay`) -- Relaycast workspace key (`rk_live_...`) — get one at https://agentrelay.com/openclaw or run `agent-relay up` to auto-create -- For Claude agents: `ANTHROPIC_API_KEY` or `claude auth login` - -## Quick Reference - -| Action | Command | -|--------|---------| -| Start broker | `agent-relay up --workspace-key rk_live_KEY --no-spawn` | -| Start broker (background) | `agent-relay up --workspace-key rk_live_KEY --background --no-spawn` | -| Check status | `agent-relay status` | -| Spawn agent | `agent-relay spawn NAME CLI "task"` | -| Spawn with team | `agent-relay spawn NAME CLI --team TEAM "task"` | -| List agents | `agent-relay agents` | -| View logs | `agent-relay agents:logs NAME` | -| Send to channel | `agent-relay send '#channel' 'message'` | -| Send DM | `agent-relay send AGENT 'message'` | -| Kill agent | `agent-relay agents:kill NAME` | -| Stop broker | `agent-relay down` | +## Read `orchestrating-agent-relay` first -## Setup Flow - -### 1. Join workspace (you, the orchestrator) +**Everything about running Agent Relay — starting the broker, spawning workers, +reading replies, releasing agents, troubleshooting — lives in the +`orchestrating-agent-relay` skill.** Read it and follow it. This skill covers +only what is specific to OpenClaw. ```bash -npx -y @agent-relay/openclaw@latest setup rk_live_YOUR_KEY --name orchestrator +npx prpm install @agent-relay/orchestrating-agent-relay ``` -This registers you on the workspace and configures mcporter for channel/DM tools. - -### 2. Start broker with workspace key +Then read `.claude/skills/orchestrating-agent-relay/SKILL.md` or +`.agents/skills/orchestrating-agent-relay/SKILL.md`. -```bash -agent-relay up --workspace-key rk_live_YOUR_KEY --no-spawn -``` +Do not improvise commands from memory. Agent Relay's flat command surface +(`agent-relay up`, `spawn`, `agents`, `agents:logs`, `agents:kill`, `send`, +`inbox`, `down`) **was removed** — lifecycle now lives under `agent-relay node +…` and messaging under `agent-relay message …`. Earlier revisions of this skill +documented the removed surface; if you have those commands in context from +anywhere, discard them. -**Critical**: Pass `--workspace-key` so spawned agents inherit the workspace connection. Without it, agents can't communicate via Relaycast channels. +## Prerequisites -### 3. Create channels for coordination +- `agent-relay` CLI installed (`npm i -g agent-relay`) +- For Claude agents: `ANTHROPIC_API_KEY`, or `claude auth login` +- A workspace: `agent-relay node up` auto-creates one if no workspace key is set -```bash -mcporter call relaycast create_channel name=my-project topic="Project coordination" -mcporter call relaycast join_channel channel=my-project -``` +## OpenClaw-specific setup -### 4. Spawn agents +Register the OpenClaw session on the workspace so it can send and read +messages under a stable identity: ```bash -agent-relay spawn architect claude --team my-team "Your task..." -agent-relay spawn developer claude --team my-team "Your task..." -agent-relay spawn tester claude --team my-team "Your task..." +npx -y @agent-relay/openclaw@latest setup --name orchestrator ``` -## Agent Communication - -Spawned agents communicate through the broker's workspace connection. +Pass the workspace key only if you are joining an existing workspace rather +than the one this project is already pinned to. Never print the key, and never +put it in an observer URL. -### From spawned agents (in their task prompt) -``` -# Post to channel -agent-relay send '#channel-name' 'your message' - -# DM another agent -agent-relay send agent-name 'your message' - -# Check inbox -agent-relay inbox -``` +## Letting a human watch -### From orchestrator (via mcporter) ```bash -mcporter call relaycast post_message channel=my-project text="Status update" -mcporter call relaycast get_messages channel=my-project limit=20 -mcporter call relaycast send_dm to=architect text="Review the design" +agent-relay observer ``` -## Agent Types +Prints a URL backed by a scoped, read-only token that expires — safe to share. +Do not build an observer URL from a workspace key. -| CLI | Use For | Notes | -|-----|---------|-------| -| `claude` | Most reliable for coding tasks | `--print --permission-mode bypassPermissions` under the hood | -| `droid` | OpenCode-based, needs PTY | Don't use `--cwd` flag (broker can't auto-accept permission prompts — see PR #570) | -| `gemini` | Google models | Use `gemini-2.5-pro` (not preview) for stability | -| `codex` | OpenAI Codex | Requires PTY | +## Reporting completion to OpenClaw -## Task Prompt Template +This is the one lifecycle step `orchestrating-agent-relay` does not cover. When +a run finishes, surface it to the OpenClaw session: -Include communication instructions in every agent's task: - -``` -You are ROLE on the TEAM team. - -## Communication -Post updates to #channel: agent-relay send '#channel' 'your message' -Check for messages: agent-relay inbox -DM a teammate: agent-relay send teammate-name 'message' - -## Your Team -- agent-a (role) — does X -- agent-b (role) — does Y - -## Tasks -1. ... -2. Post progress to #channel -3. When done: openclaw system event --text 'Done: description' --mode now +```bash +openclaw system event --text 'Done: ' --mode now ``` -## Monitoring - -```bash -# Check all agents -agent-relay agents +Include the same instruction in a spawned agent's task prompt when that agent +should report its own completion directly rather than through the orchestrator. -# Tail an agent's output -agent-relay agents:logs NAME -n 500 +## OpenClaw agent notes -# Check channel conversation -mcporter call relaycast get_messages channel=my-project limit=20 +Provider quirks worth knowing before you pick a harness for a worker: -# Check who's online -mcporter call relaycast list_agents status=online -``` +| CLI | Notes | +| -------- | --------------------------------------------------------------------- | +| `claude` | Most reliable for coding tasks | +| `codex` | Requires a PTY | +| `gemini` | Prefer a stable model (e.g. `gemini-2.5-pro`) over a preview model | +| `droid` | Requires a PTY; avoid `--cwd` — the broker cannot auto-accept its permission prompt | -## Lifecycle Management +Spawn them through the `node agent spawn` form documented in +`orchestrating-agent-relay`, e.g.: ```bash -# Kill a stuck agent -agent-relay agents:kill NAME - -# Kill all agents in a team -agent-relay agents | grep TEAM | awk '{print $1}' | xargs -I{} agent-relay agents:kill {} - -# Stop everything -agent-relay down +agent-relay node agent spawn claude --name architect --channels my-project --task "..." ``` -## Rate Limiting - -- Add 15s gaps between sequential spawns to avoid Relaycast 429 errors -- Use unique agent names per run (append UUID suffix) to avoid 409 conflicts -- The SDK uses `registerOrRotate` pattern: on 409, rotates the agent token - -## Common Patterns - -### Sequential pipeline -Spawn agent A → wait for completion → spawn agent B with A's output. - -### Parallel fan-out -Spawn N agents simultaneously, each on a subtask. Monitor via channel. Collect results. - -### Architect → Builder → Tester -1. Spawn architect to design -2. Architect posts to channel when done -3. Spawn builder to implement architect's design -4. Builder posts when done -5. Spawn tester to validate - -### Team with shared channel -All agents join same channel, post updates, read each other's work on a shared git branch. +Agents are grouped by the channels they join (`--channels`); there is no +`--team` flag. -## Gotchas +## Rate limiting -| Issue | Fix | -|-------|-----| -| Agents can't message | Broker must have `--workspace-key` | -| Droid stuck at approval | Don't use `--cwd` with droid agents | -| Agent name conflict (409) | Use unique names or let SDK `registerOrRotate` handle it | -| Channel not found | Create it first via `mcporter call relaycast create_channel` | -| Agent idle but no output | Check `agent-relay agents:logs NAME` for errors | -| npx setup fails in spawned agent | Agents inherit broker's workspace — no setup needed | -| `agent-relay send` fails for DM | Spawned agents can broadcast to channels but DMs may not work for non-Relaycast-registered agents | +- Leave a gap between sequential spawns to avoid Relaycast 429s. +- Use unique agent names per run to avoid 409 conflicts. The SDK's + `registerOrRotate` path rotates the token on 409 rather than failing.