Skip to content

Update relay skills for v8 CLI surface + agent-relay MCP #69

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
willwashburn wants to merge 4 commits into
base: main
Choose a base branch
from
Open

Update relay skills for v8 CLI surface + agent-relay MCP #69

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
7fc3d4e
orchestrating-agent-relay: update for v8 CLI surface
willwashburn Jun 3, 2026
9de0cfe
Update relay skills for v8 CLI surface + agent-relay MCP
willwashburn Jun 3, 2026
5a3d199
chore: apply pr-reviewer fixes for #69
agent-relay-code[bot] Jun 3, 2026
9b2d767
chore: apply pr-reviewer fixes for #69
agent-relay-code[bot] Jun 3, 2026
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
10 changes: 5 additions & 5 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,26 +8,26 @@ Package metadata lives in [prpm.json](prpm.json). The repo currently publishes `

| Skill | Version | Description |
|-------|---------|-------------|
| [choosing-swarm-patterns](skills/choosing-swarm-patterns/SKILL.md) | 1.1.3 | Pick the right Agent Relay orchestration pattern across the 10 core swarm patterns plus specialized patterns. |
| [choosing-swarm-patterns](skills/choosing-swarm-patterns/SKILL.md) | 1.1.4 | Pick the right Agent Relay orchestration pattern across the 10 core swarm patterns plus specialized patterns. |
| [writing-agent-relay-workflows](skills/writing-agent-relay-workflows/SKILL.md) | 1.6.17 | Build multi-agent workflows with WorkflowBuilder, DAG dependencies, verification gates, review-depth review/fix loops with test hardening, channels, and chat-native coordination recipes. |
| [setting-up-relayfile](skills/setting-up-relayfile/SKILL.md) | 1.1.0 | Set up Relayfile mounts and writeback for provider files through local filesystem access. |
| [using-agent-relay](skills/using-agent-relay/SKILL.md) | 1.3.0 | Participant-side MCP reference for a **registered** relay agent (spawned worker / registered lead): messaging, channels, threads, reactions, search, webhooks. Counterpart to `orchestrating-agent-relay`. |
| [orchestrating-agent-relay](skills/orchestrating-agent-relay/SKILL.md) | 2.1.2 | The canonical way to run agent-relay: self-bootstrap the broker and autonomously spawn, monitor, and coordinate a worker team without human intervention. |
| [using-agent-relay](skills/using-agent-relay/SKILL.md) | 1.4.0 | Participant-side MCP reference for a **registered** relay agent (spawned worker / registered lead): messaging, channels, threads, reactions, and search. Counterpart to `orchestrating-agent-relay`. |
| [orchestrating-agent-relay](skills/orchestrating-agent-relay/SKILL.md) | 2.2.0 | The canonical way to run agent-relay: self-bootstrap the broker and autonomously spawn, monitor, and coordinate a worker team without human intervention. |
| [relay-80-100-workflow](skills/relay-80-100-workflow/SKILL.md) | 1.0.8 | Author workflows that close the 80-to-100 validation gap with repair-aware test, verify, review-depth review/fix with test hardening, and commit gates. |
| [review-fix-signoff-loop](skills/review-fix-signoff-loop/SKILL.md) | 1.0.2 | Loop review, repair, validation, and fresh-context dual-agent signoff until independent reviewers both satisfy the verdict contract. |
| [activity-summary](skills/activity-summary/SKILL.md) | 1.0.0 | Answer "what did I work on yesterday" questions by reading `digests/yesterday.md` first instead of crawling provider directories. |
| [daily-digest](skills/daily-digest/SKILL.md) | 1.0.0 | Authoring contract for `<mount>/digests/` files — windows, per-provider sections, adapter `digest()` exports, regeneration rules. |
| [writeback-as-files](skills/writeback-as-files/SKILL.md) | 1.0.0 | File-creation writeback contract — drop a JSON file at the canonical path and relayfile delivers the mutation, with dead-letter recovery. |
| [workspace-layout](skills/workspace-layout/SKILL.md) | 1.0.0 | Navigate a relayfile mount via root and per-provider `LAYOUT.md` files plus `by-*` alias indexes instead of `find`/`grep -r`. |
| [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. |
| [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) | 1.1.0 | Run headless multi-agent orchestration sessions via Agent Relay — spawn teams across Claude/Codex/Gemini/Pi/Droid, create channels, and manage agent lifecycle. |

## 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`. |
| [/spawn](commands/spawn.md) | 1.0.1 | Bootstrap the broker 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
Expand Down
14 changes: 7 additions & 7 deletions commands/spawn.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -21,26 +21,26 @@ Bootstrap the agent-relay broker (if not already running) and spawn a worker on
- Optional `--task "<text>"` — 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`.
- Run `agent-relay local status` first. If broker is up, skip startup.
- If down, ensure a workspace key is available (`$RELAYCAST_WORKSPACE_KEY` or `$AGENT_RELAY_WORKSPACE_KEY`, or prompt the user). Then `agent-relay local up --workspace-key $KEY --background --no-spawn`.
- Verify broker came up cleanly 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.
4. **Ensure a coordination channel exists.** Default to `orchestrator` unless the user specified one. Create it via `mcporter call agent-relay create_channel` if missing, then join it with `mcporter call agent-relay join_channel`.

5. **Spawn the worker.** Construct the spawn command from parsed args:
```text
agent-relay spawn <auto-name> $1 [--model <model>] [--team orchestrator] "<task>"
agent-relay local agent spawn $1 --name <auto-name> [--model <model>] --channels orchestrator --task "<task>"
Copy link
Copy Markdown

@cubic-dev-ai cubic-dev-ai Bot Jun 3, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2: Spawn command hardcodes --channels orchestrator, so the documented user-specified channel path is ignored.

Prompt for AI agents 
Check if this issue is valid — if so, understand the root cause and fix it. At commands/spawn.md, line 32:

<comment>Spawn command hardcodes `--channels orchestrator`, so the documented user-specified channel path is ignored.</comment>

<file context>
@@ -21,26 +21,26 @@ Bootstrap the agent-relay broker (if not already running) and spawn a worker on
 5. **Spawn the worker.** Construct the spawn command from parsed args:
    ```text
-   agent-relay spawn <auto-name> $1 [--model <model>] [--team orchestrator] "<task>"
+   agent-relay local agent spawn $1 --name <auto-name> [--model <model>] --channels orchestrator --task "<task>"
    ```
    - `<auto-name>` should be unique per run (e.g., `worker-<short-uuid>`) to avoid 409 conflicts.
</file context>
Suggested change
agent-relay local agent spawn $1 --name <auto-name> [--model <model>] --channels orchestrator --task "<task>"
agent-relay local agent spawn $1 --name <auto-name> [--model <model>] --channels <channel> --task "<task>"

```
- `<auto-name>` should be unique per run (e.g., `worker-<short-uuid>`) 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.

6. **Report back.** Print the spawned agent name, the channel it joined, and the tail command (`agent-relay agents:logs <name>`) so the user can monitor it.
6. **Report back.** Print the spawned agent name, the channel it joined, the relay message commands for coordination, and the debug tail command (`agent-relay local tail --agent <name>`).

## 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 (relay messages, liveness, debug tail, release).
- If something failed (workspace key missing, 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

Expand Down
14 changes: 7 additions & 7 deletions prpm.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@
"packages": [
{
"name": "choosing-swarm-patterns",
"version": "1.1.3",
"version": "1.1.4",
"description": "Use when coordinating multiple AI agents with Agent Relay's workflow engine and need to pick the right orchestration pattern - covers the 10 core patterns (fan-out, pipeline, hub-spoke, consensus, mesh, handoff, cascade, dag, debate, hierarchical) plus 14 specialized ones, with decision framework and accurate SDK/YAML examples.",
"format": "claude",
"subtype": "skill",
Expand Down Expand Up @@ -71,8 +71,8 @@
},
{
"name": "using-agent-relay",
"version": "1.3.0",
"description": "Use when you are a registered relay agent (a spawned worker, or a lead that called agent_register) coordinating with peers in real time over Relaycast MCP tools - messaging, channels, threads, reactions, search, webhooks. Participant-side reference; the counterpart for driving a team from outside is orchestrating-agent-relay.",
"version": "1.4.0",
"description": "Use when you are a registered relay agent (a spawned worker, or a lead that called register_agent) coordinating with peers in real time over Agent Relay MCP tools - messaging, channels, threads, reactions, and search. Participant-side reference; the counterpart for driving a team from outside is orchestrating-agent-relay.",
"format": "claude",
"subtype": "skill",
"tags": [
Expand All @@ -89,8 +89,8 @@
},
{
"name": "orchestrating-agent-relay",
"version": "2.1.2",
"description": "The canonical way to run agent-relay - self-bootstrap the broker and autonomously spawn, monitor, and coordinate a team of worker agents without human intervention. Covers infrastructure startup, agent spawning, lifecycle monitoring, CLI-first reading, and team coordination.",
"version": "2.2.0",
Copy link
Copy Markdown

@cubic-dev-ai cubic-dev-ai Bot Jun 3, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2: Version metadata is now inconsistent: prpm.json says 2.2.0 while README still lists orchestrating-agent-relay as 2.1.2.

Prompt for AI agents 
Check if this issue is valid — if so, understand the root cause and fix it. At prpm.json, line 92:

<comment>Version metadata is now inconsistent: `prpm.json` says 2.2.0 while README still lists orchestrating-agent-relay as 2.1.2.</comment>

<file context>
@@ -89,7 +89,7 @@
     {
       "name": "orchestrating-agent-relay",
-      "version": "2.1.2",
+      "version": "2.2.0",
       "description": "The canonical way to run agent-relay - self-bootstrap the broker and autonomously spawn, monitor, and coordinate a team of worker agents without human intervention. Covers infrastructure startup, agent spawning, lifecycle monitoring, CLI-first reading, and team coordination.",
       "format": "claude",
</file context>

"description": "The canonical way to run agent-relay - self-bootstrap the broker and autonomously spawn, monitor, and coordinate a team of worker agents without human intervention. Covers infrastructure startup, agent spawning, lifecycle monitoring, relay-mediated messaging, and team coordination.",
"format": "claude",
"subtype": "skill",
"tags": [
Expand Down Expand Up @@ -249,7 +249,7 @@
},
{
"name": "spawn",
"version": "1.0.0",
"version": "1.0.1",
"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",
Expand Down Expand Up @@ -309,7 +309,7 @@
},
{
"name": "openclaw-orchestrator",
"version": "1.0.0",
"version": "1.1.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.",
"format": "claude",
"subtype": "skill",
Expand Down
26 changes: 13 additions & 13 deletions skills/choosing-swarm-patterns/SKILL.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -186,7 +186,7 @@ await workflow("api-build")
.step("review", { agent: "lead", task: "Review everything", dependsOn: ["routes"] })
.run();
```
Hub (picked via `role: lead` or first agent) stays on the channel and direct-messages interactive workers via `mcp__relaycast__message_dm_send`.
Hub (picked via `role: lead` or first agent) stays on the channel and direct-messages interactive workers via `mcp__agent-relay__send_dm`.

> **Don't set `interactive: false` on a hub-spoke worker** if you want it to receive coordination DMs — `resolveTopology` strips non-interactive agents from the message graph (`coordinator.ts:218-237`). Use `interactive: false` only when the worker is a one-shot subprocess whose stdout you collect via `{{steps.X.output}}` without any mid-run coordination.

Expand Down Expand Up @@ -333,21 +333,21 @@ Conventional signals baked into the adapter (`relay-adapter.ts:29-36`):

The runner captures PTY chunks as step output and also records channel posts + file changes as `StepCompletionEvidence`. Legacy fallback: a file at `.relay/summaries/{stepName}.md` is read if PTY output is empty (`runner.ts:6607`).

## Relaycast MCP — Correct Tool Names
## Agent Relay MCP — Correct Tool Names

The skill previously referenced `mcp__relaycast__send` / `mcp__relaycast__dm` — those names are wrong. The real tools (the first three are cited in the workflow convention-injection at `relay-adapter.ts:31-35`; the rest are exposed by the live `relaycast` MCP server):
The skill previously referenced `mcp__agent-relay__send` / `mcp__agent-relay__dm` — those names are wrong. The real tools (the first three are cited in the workflow convention-injection at `relay-adapter.ts:31-35`; the rest are exposed by the live `agent-relay` MCP server):

| Purpose | Tool | Source |
|---------|------|--------|
| Send DM to another agent | `mcp__relaycast__message_dm_send` | `relay-adapter.ts:31` |
| Check inbox | `mcp__relaycast__message_inbox_check` | `relay-adapter.ts:35` |
| List agents | `mcp__relaycast__agent_list` | `relay-adapter.ts:35` |
| Post to a channel | `mcp__relaycast__message_post` | relaycast MCP server |
| Reply in a thread | `mcp__relaycast__message_reply` | relaycast MCP server |
| Spawn sub-agent | `mcp__relaycast__agent_add` | relaycast MCP server |
| Remove sub-agent | `mcp__relaycast__agent_remove` | relaycast MCP server |
| Send DM to another agent | `mcp__agent-relay__send_dm` | `relay-adapter.ts:31` |
| Check inbox | `mcp__agent-relay__check_inbox` | `relay-adapter.ts:35` |
| List agents | `mcp__agent-relay__list_agents` | `relay-adapter.ts:35` |
| Post to a channel | `mcp__agent-relay__post_message` | agent-relay MCP server |
| Reply in a thread | `mcp__agent-relay__reply_to_thread` | agent-relay MCP server |
| Spawn sub-agent | `mcp__agent-relay__add_agent` | agent-relay MCP server |
| Remove sub-agent | `mcp__agent-relay__remove_agent` | agent-relay MCP server |

> `interactive: false` agents run as non-interactive subprocesses with no relay connection — they must NOT call any `mcp__relaycast__*` tool (validator warns on this at `validator.ts:138-150`, check `NONINTERACTIVE_RELAY`).
> `interactive: false` agents run as non-interactive subprocesses with no relay connection — they must NOT call any `mcp__agent-relay__*` tool (validator warns on this at `validator.ts:138-150`, check `NONINTERACTIVE_RELAY`).

## Reflection (Trajectories)

Expand Down Expand Up @@ -383,7 +383,7 @@ For a first-class critic loop, use the `reflection` **pattern** (agents with `ro
| Relying on `reflectOnBarriers` | Config flag exists but runner never calls it | Use `reflectOnConverge` for convergence reflection; use `reflection` pattern for critic loops |
| `interactive: false` agent calling MCP | Non-interactive subprocess has no relay | Use `interactive: true` (default) or emit output on stdout |
| Relying on multi-level `hierarchical` | Topology is single-level hub in current impl | Use pattern for naming; model levels via `dependsOn` graph |
| Writing `mcp__relaycast__send(...)` | Wrong tool name | Use `mcp__relaycast__message_post` or `message_dm_send` |
| Writing `mcp__agent-relay__send(...)` | Wrong tool name | Use `mcp__agent-relay__post_message` or `mcp__agent-relay__send_dm` |

## Resume & Re-run

Expand All @@ -397,7 +397,7 @@ await runWorkflow("feature-dev.yaml", {
previousRunId: "<runId>",
});
```
Cached outputs live in `.agent-relay/step-outputs/`; runs in `.agent-relay/workflow-runs.jsonl`. Env vars `RESUME_RUN_ID`, `START_FROM`, `PREVIOUS_RUN_ID` are auto-detected.
Cached outputs live in `.agentworkforce/relay/step-outputs/`; runs in `.agentworkforce/relay/workflow-runs.jsonl`. Env vars `RESUME_RUN_ID`, `START_FROM`, `PREVIOUS_RUN_ID` are auto-detected.

## Complete YAML Example

Expand Down
Loading