Rename to orchestrating-agent-relay + CLI-first/--json guidance#48
Merged
Merged
Conversation
The spawning orchestrator is not a registered relaycast agent, so mcp__relaycast__message_* / agent_list fail with 'Not registered. Call agent.register first.' Make the CLI the documented path and recommend --json for full, untruncated, parseable output: - replies <agent> is the canonical DM-read; --json gives full text + direction - channel evidence via history --to '#channel' --json is untruncated/chronological - who --json exposes structured lifecycle (pid, uptimeSecs, memoryBytes, status) for health polling instead of scraping the worker TTY - drop legacy inbox --agent / MCP-primary framing Mirrors the relay repo skill change on PR #861. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
📝 WalkthroughWalkthroughDocs and manifest updated to rename the headless orchestrator skill to orchestrating-agent-relay, canonicalize agent-relay CLI workflows (replies/send/history/who) for spawning/monitoring/troubleshooting, add a new orchestrating-agent-relay SKILL.md, and revise using-agent-relay guidance for registered agents. ChangesHeadless Orchestrator CLI Standardization
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~20 minutes Possibly related PRs
Poem
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Comment |
![devin-ai-integration[bot]](https://avatars.githubusercontent.com/in/811515?s=60&v=4){kind=small}
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 2
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@skills/running-headless-orchestrator/SKILL.md`:
- Around line 121-126: Update the sentence listing which read commands should
include --json by removing "inbox" so it only mentions "replies", "history", and
"who"; edit the paragraph containing the `mcp__relaycast__message_*` /
`agent_list` guidance in SKILL.md and delete the word "inbox" from the list
after "Add `--json` to any read command" to avoid reintroducing legacy framing
while keeping the rest of the sentence and the advice about `agent-relay`
unchanged.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro Plus
Run ID: 9eaf90bc-922a-45f4-a6ec-995fc746342d
📒 Files selected for processing (1)
skills/running-headless-orchestrator/SKILL.md
…g-agent-relay This skill is the canonical "how to run agent-relay" entrypoint, so it gets a canonical, gerund-form name consistent with the skill family (using-agent-relay, writing-agent-relay-workflows). - Rename skills/running-headless-orchestrator -> skills/orchestrating-agent-relay - Update SKILL.md frontmatter name + title + description - prpm.json: rename package, bump skill 1.0.5 -> 2.0.0 (breaking: package name change), bump bundle 1.0.10 -> 1.1.0 - Update README.md and commands/spawn.md references and install command Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
khaliqgant
changed the title
There was a problem hiding this comment.
Actionable comments posted: 2
♻️ Duplicate comments (3)
skills/orchestrating-agent-relay/SKILL.md (3)
312-330:⚠️ Potential issue | 🟠 Major | ⚡ Quick winUpdate Common Mistakes table to use canonical
repliescommand.The Common Mistakes table references
agent-relay inbox --agent <name>in multiple entries (lines 325, 326, 328), perpetuating the same contradiction with the canonicalrepliesguidance established earlier in the document. These should be updated to useagent-relay replies <name> --jsonfor consistency.📝 Proposed fix
-| Messages not delivered | Check `agent-relay history --to '`#general`'` for channel messages; use `agent-relay inbox --agent <name>` for DMs | -| Worker replies not showing in history | Expected — `history` only shows channel posts. Use `agent-relay inbox --agent <name>` (unread only) or `agent-relay history --to <name>` (full thread) to read DM replies | +| Messages not delivered | Check `agent-relay history --to '`#general`' --json` for channel messages; use `agent-relay replies <name> --json` for DMs | +| Worker replies not showing in history | Expected — `history` only shows channel posts. Use `agent-relay replies <name>` (canonical DM read) or `agent-relay history --to <name>` (full thread) to read DM replies | | `inbox_check` shows unread but can't see content | `inbox_check` only returns counts. Use `mcp__relaycast__message_dm_list(as: "<name>")` to list conversations, or `agent-relay inbox --agent <name>` via CLI | -| `inbox --agent` showed messages once but now shows nothing | `inbox` only shows **unread** — already-read messages won't reappear. Use `agent-relay history --to <name>` to re-read the full conversation | +| `inbox --agent` showed messages once but now shows nothing | This is legacy unread-only behavior. Use `agent-relay replies <name>` for the canonical persistent view or `agent-relay history --to <name>` to re-read the full conversation |🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@skills/orchestrating-agent-relay/SKILL.md` around lines 312 - 330, Update the Common Mistakes table entries that reference the inbox command to use the canonical replies command: replace all occurrences of the string "agent-relay inbox --agent <name>" (and similar inbox examples in the same rows) with "agent-relay replies <name> --json" so the table is consistent with the earlier guidance; ensure related sentences mentioning unread vs read behavior still make sense with replies output and update the examples in the rows that previously pointed to inbox (rows referencing inbox_check, inbox behavior, and worker DM reading) to use the replies command.
283-296:⚠️ Potential issue | 🟠 Major | ⚡ Quick winReplace
inbox --agentwith canonicalrepliesin the template.This template instructs orchestrators to use
agent-relay inbox --agent Worker1(line 284) and referencesinbox --agent <name>in the protocol section (lines 293, 295). This contradicts the canonical guidance established at lines 160-166, which explicitly states thatreplies <agent>is the canonical command and thatinbox --agentis "legacy unread-only behavior" where entries disappear after reading.Using
inboxin operational instructions can cause orchestrators to miss payloads and experience the truncation/unread-only issues this PR aims to solve.📝 Proposed fix to align with canonical guidance
Read worker replies (DMs are not visible in history): - agent-relay inbox --agent Worker1 + agent-relay replies Worker1 --json ## Protocol - Workers will ACK when they receive tasks - Workers will send DONE when complete - Use `agent-relay agents:logs <name>` to monitor progress -- Use `agent-relay inbox --agent <name>` to read **unread** DM replies from a worker (clears after reading) +- Use `agent-relay replies <name> --json` to read full, chronological DM replies safely in loops - Use `agent-relay history --to <name>` to re-read the full DM conversation (read + unread) -- Use `agent-relay history --to '`#general`'` to see channel message flow +- Use `agent-relay history --to '`#general`' --json` to see channel message flow - Do NOT use `agent-relay history` alone to check worker replies — it only shows channel posts, DM replies are invisible there🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@skills/orchestrating-agent-relay/SKILL.md` around lines 283 - 296, Replace the legacy "inbox --agent" usage with the canonical "replies <agent>" everywhere in the SKILL.md snippet: change the example command "agent-relay inbox --agent Worker1" to "agent-relay replies Worker1" and update the Protocol lines that reference "inbox --agent <name>" to "replies <agent>" (and similarly "inbox --agent <name>" occurrences) so instructions align with the canonical guidance in the template; preserve the note that "inbox" is legacy/unread-only behavior if you want to mention it, but ensure operational commands and examples use "replies <agent>" and any explanation about clearing/unread behavior is consistent with the canonical command semantics.
123-128:⚠️ Potential issue | 🟠 Major | ⚡ Quick winRemove
inboxfrom the--jsonrecommendation list.Line 127 includes
inboxin the list of read commands that should use--json, but this reintroduces legacy framing after establishing CLI canonical behavior withrepliesas the primary DM read command (lines 160-166). The list should focus onreplies,history, andwhoto maintain consistency with the canonical guidance.📝 Proposed fix
-> Add `--json` to any read command (`replies`, `history`, `inbox`, `who`) +> Add `--json` to any read command (`replies`, `history`, `who`) > when you need full, untruncated, parseable output.🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@skills/orchestrating-agent-relay/SKILL.md` around lines 123 - 128, Update the CLI recommendation sentence so `--json` is suggested only for the read commands that should produce canonical, unframed output: keep `replies`, `history`, and `who`, and remove `inbox` from that list; ensure the surrounding text still references using the `agent-relay` CLI and the `--json` flag for parseable output and that `replies` remains the primary DM read command.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@skills/orchestrating-agent-relay/SKILL.md`:
- Around line 90-96: The fenced code block containing the
mcp__relaycast__agent_add(...) call needs an explicit language tag for markdown
rendering; update that block in SKILL.md to start with a language specifier
(e.g., ```text or ```javascript) so the snippet is valid and highlights
correctly—locate the block containing mcp__relaycast__agent_add and add the
chosen language identifier immediately after the opening backticks.
- Line 256: The fenced code block that begins with "You are an autonomous
orchestrator. Bootstrap the relay infrastructure and manage a team of workers."
in SKILL.md lacks a language specifier; update the opening fence from ``` to
```text (or ```markdown) so the block is annotated (e.g., replace the opening
triple-backtick before that paragraph with ```text) to ensure proper syntax
highlighting and markdown compliance.
---
Duplicate comments:
In `@skills/orchestrating-agent-relay/SKILL.md`:
- Around line 312-330: Update the Common Mistakes table entries that reference
the inbox command to use the canonical replies command: replace all occurrences
of the string "agent-relay inbox --agent <name>" (and similar inbox examples in
the same rows) with "agent-relay replies <name> --json" so the table is
consistent with the earlier guidance; ensure related sentences mentioning unread
vs read behavior still make sense with replies output and update the examples in
the rows that previously pointed to inbox (rows referencing inbox_check, inbox
behavior, and worker DM reading) to use the replies command.
- Around line 283-296: Replace the legacy "inbox --agent" usage with the
canonical "replies <agent>" everywhere in the SKILL.md snippet: change the
example command "agent-relay inbox --agent Worker1" to "agent-relay replies
Worker1" and update the Protocol lines that reference "inbox --agent <name>" to
"replies <agent>" (and similarly "inbox --agent <name>" occurrences) so
instructions align with the canonical guidance in the template; preserve the
note that "inbox" is legacy/unread-only behavior if you want to mention it, but
ensure operational commands and examples use "replies <agent>" and any
explanation about clearing/unread behavior is consistent with the canonical
command semantics.
- Around line 123-128: Update the CLI recommendation sentence so `--json` is
suggested only for the read commands that should produce canonical, unframed
output: keep `replies`, `history`, and `who`, and remove `inbox` from that list;
ensure the surrounding text still references using the `agent-relay` CLI and the
`--json` flag for parseable output and that `replies` remains the primary DM
read command.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro Plus
Run ID: 25d50422-cd76-4d69-b928-a8d900afc69f
📒 Files selected for processing (4)
README.mdcommands/spawn.mdprpm.jsonskills/orchestrating-agent-relay/SKILL.md
✅ Files skipped from review due to trivial changes (1)
- README.md
![cubic-dev-ai[bot]](https://avatars.githubusercontent.com/in/1082092?s=60&v=4){kind=small}
There was a problem hiding this comment.
2 issues found across 4 files (changes from recent commits).
Prompt for AI agents (unresolved issues)
Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.
<file name="skills/orchestrating-agent-relay/SKILL.md">
<violation number="1" location="skills/orchestrating-agent-relay/SKILL.md:325">
P2: This row points users to legacy `inbox --agent` for DM reads, which conflicts with the doc’s canonical `replies` guidance and can hide already-read messages.</violation>
<violation number="2" location="skills/orchestrating-agent-relay/SKILL.md:327">
P2: Replace this MCP-based troubleshooting guidance with CLI-only read commands, since `message_dm_list` requires a registered agent identity and can fail for the spawning orchestrator.</violation>
</file>
Reply with feedback, questions, or to request a fix.
Fix all with cubic | Re-trigger cubic
… orchestrating-agent-relay using-agent-relay and orchestrating-agent-relay are complementary, not redundant — they sit on opposite sides of the registration boundary. Make that explicit so readers pick the right one: - using-agent-relay: add a 'which skill do you want?' callout, retitle to 'registered participant', sharpen frontmatter/description, replace the stale 'truncated message -> read <id>' mistake row with the not-registered case and the (now untruncated) CLI replies/--json fix; bump 1.2.0 -> 1.3.0 - orchestrating-agent-relay: add a reciprocal note that spawned workers are registered participants and use the using-agent-relay skill - README + prpm.json descriptions/versions updated; also fixed a prettier blockquote wrap artifact in both skills Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@skills/orchestrating-agent-relay/SKILL.md`:
- Around line 139-141: The fenced code block containing
mcp__relaycast__agent_remove(name: "Worker1") is missing a language identifier;
update the fence to include a language (e.g., add ```text) so the block becomes
```text ... ``` to satisfy markdown linting and consistency for the
mcp__relaycast__agent_remove example.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro Plus
Run ID: a56b1d31-798a-4ca5-b90a-97fadde958ab
📒 Files selected for processing (4)
README.mdprpm.jsonskills/orchestrating-agent-relay/SKILL.mdskills/using-agent-relay/SKILL.md
✅ Files skipped from review due to trivial changes (1)
- skills/using-agent-relay/SKILL.md
🚧 Files skipped from review as they are similar to previous changes (1)
- prpm.json
- Add 'text' language to the 3 bare fenced blocks (MD040): agent_add, agent_remove, orchestrator-instructions template - Drop 'inbox' from the 'add --json to any read command' list (replies, history, who) to avoid reintroducing legacy framing - Replace remaining legacy inbox --agent / message_dm_list DM-read guidance (orchestrator template + Common Mistakes rows) with canonical 'agent-relay replies <name>' / '--json'; keep history --to <name> as the full-thread alternative Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
There was a problem hiding this comment.
🧹 Nitpick comments (1)
skills/orchestrating-agent-relay/SKILL.md (1)
41-41: ⚡ Quick winAlign
whoexamples with your own--jsonmonitoring guidance.The doc repeatedly positions
agent-relay who --jsonas the reliable health-polling path, but these spots still show plainagent-relay who, which weakens consistency for automation-oriented readers.Suggested doc patch
-| List workers | `agent-relay who` | +| List workers | `agent-relay who --json` |-Monitor workers (do this frequently): - agent-relay who # List active workers +Monitor workers (do this frequently): + agent-relay who --json # List active workers (structured for polling) agent-relay agents:logs Worker1 # View worker output/progressAlso applies to: 281-282
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@skills/orchestrating-agent-relay/SKILL.md` at line 41, Update the examples that show the plain `agent-relay who` command to use the JSON-monitoring variant `agent-relay who --json` so they align with the guidance that `--json` is the reliable health-polling path; search for occurrences of `agent-relay who` in SKILL.md (including the example at the table row and the example around lines 281-282) and replace them with `agent-relay who --json`, keeping surrounding text intact to preserve context.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Nitpick comments:
In `@skills/orchestrating-agent-relay/SKILL.md`:
- Line 41: Update the examples that show the plain `agent-relay who` command to
use the JSON-monitoring variant `agent-relay who --json` so they align with the
guidance that `--json` is the reliable health-polling path; search for
occurrences of `agent-relay who` in SKILL.md (including the example at the table
row and the example around lines 281-282) and replace them with `agent-relay who
--json`, keeping surrounding text intact to preserve context.
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro Plus
Run ID: 4205ae72-aacd-4c5a-8ce5-af1d72fa687a
📒 Files selected for processing (1)
skills/orchestrating-agent-relay/SKILL.md
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Makes
running-headless-orchestratorthe canonical "how to run agent-relay" skill: renames it toorchestrating-agent-relayand updates its guidance to be accurate for a spawning orchestrator. Mirrors the relay-side changes in AgentWorkforce/relay#861.Rename
skills/running-headless-orchestrator/→skills/orchestrating-agent-relay/name, title, and description updatedprpm.json: package renamed; skill1.0.5→2.0.0(breaking: package name change); bundleagent-workforce-skills1.0.10→1.1.0README.md+commands/spawn.mdreferences andnpx prpm installcommand updatedGerund form is consistent with the rest of the skill family (
using-agent-relay,writing-agent-relay-workflows) and distinct from them: this is the imperative "drive agent-relay to run a team" entrypoint.Guidance changes (why)
mcp__relaycast__message_*/agent_listfail withNot registered. Call agent.register first.The CLI is now the documented path.--jsonfor full, untruncated, parseable output acrossreplies/history/inbox/who.replies <agent>is the canonical DM read;history --to '#channel' --jsonis untruncated/chronological channel evidence;who --jsonexposes structured lifecycle (pid,uptimeSecs,memoryBytes,status) for health polling instead of TTY scraping.inbox --agent/ MCP-primary framing.Related / follow-up
who --json, untruncated chronological channel history) and the.claude/.agentsskill mirrors. Those mirrors +relay/prpm.json+ the spec reference still use the old name and need the same rename for consistency (tracked alongside #861).🤖 Generated with Claude Code