Agent Teams on Grok (ADR-402)
Claude SendMessage / TeammateTool are not available. Prefer Ruflo MCP team_* tools; CLI bus is the fallback.
Preferred: MCP tools
| Tool | Purpose |
|---|
team_create | Create team + topology |
team_plan | Ordered pipeline steps |
team_spawn | Register agent; returns spawn plan for spawn_subagent |
team_send / team_broadcast | Handoff messages |
team_inbox | Drain/peek mailbox |
team_status / team_on_stop / team_shutdown | Lifecycle |
Discover: search_tool query team_create. Call via use_tool as ruflo__team_create etc.
Quick start (CLI fallback)
# 1. Create team
node scripts/grok-team-bus.mjs create --name feature-x --topology hierarchical
# 2. Register plan
node scripts/grok-team-bus.mjs plan --team feature-x \
--steps '["architect","developer","tester","reviewer"]'
# 3. Register agents (prints spawnPlan JSON for spawn_subagent)
node scripts/grok-team-bus.mjs spawn --team feature-x --agent architect --role architect \
--prompt "Design <feature>. Handoff to developer." --next developer
node scripts/grok-team-bus.mjs spawn --team feature-x --agent developer --role developer \
--prompt "Implement from architect design." --next tester
node scripts/grok-team-bus.mjs spawn --team feature-x --agent tester --role tester \
--prompt "Test implementation." --next reviewer
node scripts/grok-team-bus.mjs spawn --team feature-x --agent reviewer --role reviewer \
--prompt "Review code and tests."
Lead (you) then
Checked against Grok Build 1.0.41. Pass only the live spawn arguments:
spawn_subagent({
prompt: spawnPlan.prompt,
description: spawnPlan.host.grok.spawn.description,
background: spawnPlan.host.grok.spawn.background,
isolation: spawnPlan.host.grok.spawn.isolation,
})
- Parse
spawnPlan.host.grok.spawn (and prompt). Call spawn_subagent in one message for every agent (background: true).
- Leave
host.grok.advisory on the plan. capability_mode and subagent_type are not spawn arguments on this Grok. The prompt carries the read-only or worktree constraint. isolation is the knob Grok enforces.
.grok/agents/ruflo-* are session profiles (grok --agent-profile ruflo-coder or /agents). spawn_subagent does not select them. An omitted type is general-purpose.- Children must not call
spawn_subagent. Nesting depth is 1. The lead spawns the whole pipeline.
- Pass
description unchanged (<role>:<agent>@<team>): the SubagentStop hook reads it to run on-stop for that team. Then spawn or resume the next step if needed.
- Synthesize results;
shutdown the team. A shut-down team refuses spawn and send; team_create --force reopens the name.
Every call names its team: mail is per team, and several teams can run at once. team_spawn stops at the team's maxAgents.
If grok --version is newer than 1.0.41, re-read ~/.grok/docs/user-guide/16-subagents.md (Spawning Subagents) before forwarding extra keys. A key the schema dropped fails the spawn.
Defaults
| Role | Prompt constraint (advisory.capability_mode) | isolation (passed through) |
|---|
| architect / reviewer | read-only | none |
| developer / tester | full tools | worktree |
Messaging
node scripts/grok-team-bus.mjs send --team feature-x --to developer \
--from architect --summary "design" --message "..."
node scripts/grok-team-bus.mjs inbox --team feature-x --agent developer
node scripts/grok-team-bus.mjs status --team feature-x
Also use Ruflo MCP when live
memory_search / memory_store with namespace team:feature-xswarm_init for coordination records (then you still execute)
Anti-patterns
- Waiting for
swarm start to write code
- Inventing SendMessage
- Passing
capability_mode or subagent_type into spawn_subagent (they are advisory on Grok Build 1.0.41)
- Parallel coders on the same tree without worktrees
- A child calling
spawn_subagent (depth limit is 1)