claude-flow 3.58.1 → 3.59.1

package/v3/@claude-flow/cli/templates/grok/scripts/grok-team-store.mjs

@@ -0,0 +1,287 @@
+/**
+ * Storage layer for the host-agnostic Agent Teams bus (ADR-402).
+ * Imported by grok-team-bus.mjs; not a CLI.
+ *
+ * Layout (all under <project>/.claude-flow/teams/<team>/):
+ *   team.json                 roster, plan, status   (lock + atomic rename)
+ *   team.lock                 cross-process lock (O_EXCL file + token)
+ *   mailbox/<agent>/*.json    pending messages, named <priority>_<id>.json
+ *   mailbox/<agent>/archive/  drained messages
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+export const NAME_RE = /^[a-zA-Z0-9][a-zA-Z0-9_-]{0,63}$/;
+// A waiter must never give up before the lock it's waiting on can even be
+// considered stale — otherwise every spawn attempted in the gap between
+// "waiter gives up" and "lock is stale" fails outright even though nothing
+// is actually stuck (ADR-402 round-2 review, N3). So LOCK_WAIT_MS >=
+// LOCK_STALE_MS, always.
+//
+// Both are also sized to fit inside the SubagentStop hook's own 5s command
+// timeout (templates/grok/hooks/subagent-stop-team.json): worst case, the
+// hook waits out the full stale window, breaks the lock, and runs its (tiny,
+// sub-millisecond) critical section — that must land comfortably under 5s
+// including node startup. 4s stale / 4.5s wait leaves ~0.5s of margin for
+// process startup and the break-then-acquire dance, while still being far
+// longer than any legitimate holder ever needs (team.json read-modify-write
+// is the only thing done under this lock).
+const LOCK_WAIT_MS = 4_500;
+const LOCK_STALE_MS = 4_000;
+
+// ---------------------------------------------------------------------------
+// Names, paths, and filesystem safety
+// ---------------------------------------------------------------------------
+
+export function safeName(name, field = 'name') {
+  if (typeof name !== 'string' || !NAME_RE.test(name)) {
+    throw new Error(`Invalid ${field} "${name}" — use 1-64 alphanumeric, dash, underscore (must start alphanumeric)`);
+  }
+  return name;
+}
+
+export function teamsRoot(projectRoot) {
+  return path.join(projectRoot, '.claude-flow', 'teams');
+}
+
+export function teamDir(projectRoot, team) {
+  return path.join(teamsRoot(projectRoot), safeName(team, 'team'));
+}
+
+export function teamFile(projectRoot, team) {
+  return path.join(teamDir(projectRoot, team), 'team.json');
+}
+
+export function mailboxDir(projectRoot, team, agent) {
+  return path.join(teamDir(projectRoot, team), 'mailbox', safeName(agent, 'agent'));
+}
+
+/**
+ * Create `dir` and every missing parent below `base`, refusing to pass through
+ * a symlink. A planted symlink would otherwise redirect writes outside the
+ * project.
+ */
+export function ensureRealDir(base, dir) {
+  const rel = path.relative(base, dir);
+  if (rel.startsWith('..') || path.isAbsolute(rel)) {
+    throw new Error(`Refusing path outside ${base}: ${dir}`);
+  }
+  let cur = base;
+  fs.mkdirSync(base, { recursive: true, mode: 0o700 });
+  assertRealDir(cur);
+  for (const part of rel.split(path.sep).filter(Boolean)) {
+    cur = path.join(cur, part);
+    try {
+      fs.mkdirSync(cur, { mode: 0o700 });
+    } catch (err) {
+      if (err.code !== 'EEXIST') throw err;
+    }
+    assertRealDir(cur);
+  }
+}
+
+export function assertRealDir(dir) {
+  const st = fs.lstatSync(dir);
+  if (st.isSymbolicLink() || !st.isDirectory()) {
+    throw new Error(`Refusing to use ${dir}: not a real directory (symlink?)`);
+  }
+}
+
+/** Existing real directory → true; missing → false; symlink/file → throws. */
+export function realDirExists(dir) {
+  try {
+    assertRealDir(dir);
+    return true;
+  } catch (err) {
+    if (err.code === 'ENOENT') return false;
+    throw err;
+  }
+}
+
+export function readJson(file) {
+  try {
+    return JSON.parse(fs.readFileSync(file, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+/** Write via a unique temp file + rename so readers never see a torn file. */
+export function writeJsonAtomic(file, data) {
+  const tmp = `${file}.${process.pid}.${Math.random().toString(36).slice(2, 10)}.tmp`;
+  fs.writeFileSync(tmp, JSON.stringify(data, null, 2) + '\n', { encoding: 'utf8', flag: 'wx', mode: 0o600 });
+  for (let attempt = 0; ; attempt++) {
+    try {
+      fs.renameSync(tmp, file);
+      return;
+    } catch (err) {
+      // Windows can refuse a rename over a file another process has open.
+      if (attempt >= 20 || (err.code !== 'EPERM' && err.code !== 'EBUSY' && err.code !== 'EACCES')) {
+        try { fs.rmSync(tmp, { force: true }); } catch { /* ignore */ }
+        throw err;
+      }
+      sleepMs(10);
+    }
+  }
+}
+
+/**
+ * Synchronous sleep via Atomics.wait — blocks this thread (and, in an MCP
+ * server, every other in-flight request on it) for `ms`. Kept only for the
+ * tiny (<=200ms worst case, ~20 attempts x 10ms), bounded Windows
+ * rename-retry in writeJsonAtomic, which is a rare edge case and not worth
+ * threading a Promise through every atomic write for. Anything that can
+ * block for the length of a lock wait — potentially seconds — must use
+ * sleepMsAsync instead (ADR-402 round-2 review, N3).
+ */
+export function sleepMs(ms) {
+  Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
+
+/** Non-blocking sleep: yields to the event loop instead of the whole thread. */
+export function sleepMsAsync(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+export function nowIso() {
+  return new Date().toISOString();
+}
+
+// ---------------------------------------------------------------------------
+// Lock: one team.json writer at a time, across processes
+// ---------------------------------------------------------------------------
+
+/**
+ * Run `fn` holding the team lock: a `team.lock` file created with O_EXCL and
+ * holding a random token. A lock older than LOCK_STALE_MS (a crashed holder)
+ * is broken by renaming it aside and checking the token: if a live holder
+ * re-took the lock in between, the rename caught theirs, so it is linked back
+ * (link fails rather than overwrite) and this waiter keeps waiting. Release
+ * removes the file only while it still holds our token.
+ *
+ * Async: the wait loop yields via sleepMsAsync (setTimeout), not a blocking
+ * Atomics.wait, so an MCP server (or any other caller) keeps serving other
+ * requests while this call waits for the lock (ADR-402 round-2 review, N3).
+ * `fn` itself still runs synchronously once the lock is held — team.json
+ * read-modify-write is fast enough that yielding mid-critical-section isn't
+ * worth the added complexity.
+ */
+export async function withTeamLock(projectRoot, team, fn) {
+  const dir = teamDir(projectRoot, team);
+  if (!realDirExists(dir)) throw new Error(`Team "${team}" not found — run create first`);
+  const lock = path.join(dir, 'team.lock');
+  const token = `${process.pid}.${Date.now()}.${Math.random().toString(36).slice(2, 10)}`;
+  const deadline = Date.now() + LOCK_WAIT_MS;
+  for (let wait = 2; ; wait = Math.min(wait * 2, 50)) {
+    try {
+      fs.writeFileSync(lock, token, { flag: 'wx', mode: 0o600 });
+      break;
+    } catch (err) {
+      if (err.code !== 'EEXIST') throw err;
+    }
+    breakStaleLock(lock, token);
+    if (Date.now() > deadline) throw new Error(`Timed out waiting for the lock on team "${team}"`);
+    await sleepMsAsync(wait + Math.floor(Math.random() * wait));
+  }
+  try {
+    return fn();
+  } finally {
+    try {
+      if (fs.readFileSync(lock, 'utf8') === token) fs.rmSync(lock, { force: true });
+    } catch {
+      /* already gone */
+    }
+  }
+}
+
+/** True when the lock token names a pid that still exists on this host. */
+function lockHolderAlive(token) {
+  const pid = Number(String(token).split('.')[0]);
+  if (!Number.isInteger(pid) || pid <= 0) return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (err) {
+    // EPERM: the process exists and we cannot signal it. ESRCH: it is gone.
+    return err.code === 'EPERM';
+  }
+}
+
+/**
+ * Break `lock` if it's still stale. Re-verifies the token and mtime we
+ * observed as stale immediately before renaming anything: without this, a
+ * waiter that read a stale token, then got preempted while another waiter
+ * broke the same lock and a fresh holder re-acquired it, would rename that
+ * LIVE lock out from under its holder — and the window that opens between
+ * the rename and the "put it back" recovery lets a fourth party grab the
+ * vacated slot, leaving two holders at once (ADR-402 round-2 review, N2).
+ * If anything has changed since our first observation, someone else already
+ * handled it: back off without touching the file and let the caller's own
+ * wait loop retry. A token whose pid is still alive is left alone even when
+ * the file is older than LOCK_STALE_MS (round-3 review).
+ */
+export function breakStaleLock(lock, token) {
+  let seen, mtime;
+  try {
+    mtime = fs.statSync(lock).mtimeMs;
+    if (Date.now() - mtime <= LOCK_STALE_MS) return;
+    seen = fs.readFileSync(lock, 'utf8');
+  } catch {
+    return; // released meanwhile
+  }
+  let mtime2, seen2;
+  try {
+    mtime2 = fs.statSync(lock).mtimeMs;
+    seen2 = fs.readFileSync(lock, 'utf8');
+  } catch {
+    return; // released meanwhile
+  }
+  if (mtime2 !== mtime || seen2 !== seen) return; // changed underneath us — back off
+  // A live holder is not stale, however old the file is. The lock is not
+  // refreshed while held, so a stall longer than LOCK_STALE_MS (SIGSTOP,
+  // sleep, a hook killed mid-update) used to let the next writer break it
+  // and drop one of the two updates. The token starts with the holder's
+  // pid; if that pid is still alive on this host, leave the lock alone
+  // (ADR-402 round-3 review). A dead or unparsable pid keeps the mtime rule.
+  if (lockHolderAlive(seen2)) return;
+
+  const aside = `${lock}.stale.${token}`;
+  try {
+    fs.renameSync(lock, aside);
+  } catch {
+    return; // another waiter broke it first
+  }
+  try {
+    if (fs.readFileSync(aside, 'utf8') !== seen) {
+      // Same-millisecond collision the re-verify above couldn't rule out:
+      // put the live lock back if the slot is still free.
+      try { fs.linkSync(aside, lock); } catch { /* slot taken; that holder's release is a no-op */ }
+    }
+  } finally {
+    fs.rmSync(aside, { force: true });
+  }
+}
+
+export function loadTeam(projectRoot, team) {
+  const t = readJson(teamFile(projectRoot, team));
+  if (!t) throw new Error(`Team "${team}" not found — run create first`);
+  return t;
+}
+
+/** Read-modify-write team.json under the lock. `mutate` returns the result. */
+export function updateTeam(projectRoot, team, mutate) {
+  return withTeamLock(projectRoot, team, () => {
+    const t = loadTeam(projectRoot, team);
+    const result = mutate(t);
+    writeJsonAtomic(teamFile(projectRoot, team), t);
+    return result;
+  });
+}
+
+export function assertActive(t) {
+  if (t.status !== 'active') {
+    throw new Error(`Team "${t.name}" is ${t.status}; create it again (force) to reuse the name`);
+  }
+}
+

package/v3/@claude-flow/cli/templates/grok/scripts/host-statusline.mjs

@@ -0,0 +1,281 @@
+#!/usr/bin/env node
+/**
+ * One "what is loaded" line for every host.
+ *
+ *   grok    ~/.grok/config.toml [ui.status_line] command. Project config
+ *           cannot set this (Grok 1.0.41 reads [ui] from the user file only).
+ *           SessionStart stdout is ignored, so a hook cannot print the line.
+ *           `ruflo init --grok --grok-statusline` installs a copy of this
+ *           script at ~/.grok/ruflo/host-statusline.mjs and points the row at
+ *           that absolute path; it reports on whichever repo Grok is in.
+ *   claude  .claude/settings.json statusLine → .claude/helpers/statusline.cjs
+ *           (the rich row). This script is the same facts, not a replacement.
+ *   codex   no status row. `node scripts/host-statusline.mjs --host codex`
+ *           prints the line; nothing in Codex displays it for you.
+ *
+ * Grok pipes a JSON payload on stdin. A tty (a manual run) is left alone.
+ *   node scripts/host-statusline.mjs
+ *   node scripts/host-statusline.mjs --json
+ *   node scripts/host-statusline.mjs --host claude
+ */
+
+import { existsSync, readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join, resolve } from 'node:path';
+
+const args = process.argv.slice(2);
+const JSON_OUT = args.includes('--json');
+const hostFlag = args.indexOf('--host');
+const HOST = (hostFlag >= 0 ? args[hostFlag + 1] : 'grok').toLowerCase();
+const ROOT = resolve(process.env.RUFLO_HOST_ROOT || process.cwd());
+
+export const HOST_STATUS = {
+  grok: {
+    surface: 'ui.status_line',
+    scope: 'user',
+    command: 'node "<home>/.grok/ruflo/host-statusline.mjs"',
+  },
+  claude: {
+    surface: 'statusLine',
+    scope: 'project',
+    command: 'node .claude/helpers/statusline.cjs',
+  },
+  codex: {
+    surface: null,
+    scope: null,
+    command: 'node scripts/host-statusline.mjs --host codex',
+  },
+};
+
+function has(rel) {
+  return existsSync(join(ROOT, rel));
+}
+
+// ---------------------------------------------------------------------------
+// Minimal, comment-aware TOML table reader.
+//
+// This script is a zero-dependency copy: `init --grok --grok-statusline`
+// writes it to ~/.grok/ruflo/host-statusline.mjs, and `init --grok` also
+// copies it to <project>/scripts/host-statusline.mjs — both live outside any
+// node_modules tree, so (unlike grok-generator.ts, which is part of the
+// installed @claude-flow/cli package) it can't `import '@iarna/toml'`
+// without risking "Cannot find package" at the exact moment Grok tries to
+// render the status line. The previous version matched `trusted = true` /
+// `[mcp_servers.name]` via substring/regex on the raw file text, which
+// happily matched inside a `#` comment and never noticed a sibling
+// `enabled = false` key. This walks real `[section]` boundaries and strips
+// comments outside of string literals first, instead (ADR-402 round-2
+// review, minor item 3). It is not a general TOML parser — only enough of
+// one for the two shapes this file actually reads: table headers (with
+// quoted or bare dotted keys) and simple `key = true|false` booleans.
+// ---------------------------------------------------------------------------
+
+function stripComment(line) {
+  let quote = null;
+  for (let i = 0; i < line.length; i++) {
+    const c = line[i];
+    if (quote) {
+      if (c === '\\' && quote === '"') { i++; continue; }
+      if (c === quote) quote = null;
+      continue;
+    }
+    if (c === '"' || c === "'") { quote = c; continue; }
+    if (c === '#') return line.slice(0, i);
+  }
+  return line;
+}
+
+/** Splits a dotted TOML key on top-level dots only (not dots inside quotes), then dequotes each part. */
+function splitDottedKey(raw) {
+  const parts = [];
+  let cur = '';
+  let quote = null;
+  for (const c of raw) {
+    if (quote) {
+      cur += c;
+      if (c === quote) quote = null;
+      continue;
+    }
+    if (c === '"' || c === "'") { quote = c; cur += c; continue; }
+    if (c === '.') { parts.push(cur.trim()); cur = ''; continue; }
+    cur += c;
+  }
+  parts.push(cur.trim());
+  return parts.map((p) => p.replace(/^["']|["']$/g, ''));
+}
+
+/**
+ * '[a."b.c"]' or '[a.b]' → normalized key 'a.b.c' (dequoted parts joined by '.'),
+ * or null if not a table header. A `]` inside a quoted key is part of the key
+ * (`[folders."/x/a]b"]`), not the end of the header.
+ */
+function sectionHeaderKey(line) {
+  const trimmed = line.trim();
+  if (!trimmed.startsWith('[') || trimmed.startsWith('[[')) return null; // array-of-tables: not modeled
+  let quote = null;
+  let end = -1;
+  for (let i = 1; i < trimmed.length; i++) {
+    const c = trimmed[i];
+    if (quote) {
+      if (c === '\\' && quote === '"') { i++; continue; }
+      if (c === quote) quote = null;
+      continue;
+    }
+    if (c === '"' || c === "'") { quote = c; continue; }
+    if (c === ']') { end = i; break; }
+  }
+  if (end < 0 || trimmed.slice(end + 1).trim() !== '') return null;
+  const inner = trimmed.slice(1, end).trim();
+  if (!inner) return null;
+  return splitDottedKey(inner).join('.');
+}
+
+/** { normalizedSectionPath -> { key -> rawValueText } } for every `[table]` in the file. */
+function parseTomlTables(text) {
+  const tables = new Map([['', {}]]);
+  let current = '';
+  for (const rawLine of text.split('\n')) {
+    const line = stripComment(rawLine).trim();
+    if (!line) continue;
+    const header = sectionHeaderKey(line);
+    if (header !== null) {
+      current = header;
+      if (!tables.has(current)) tables.set(current, {});
+      continue;
+    }
+    const kv = /^([^=]+?)\s*=\s*(.+)$/.exec(line);
+    if (!kv) continue;
+    tables.get(current)[kv[1].trim().replace(/^["']|["']$/g, '')] = kv[2].trim();
+  }
+  return tables;
+}
+
+function tomlBool(raw) {
+  if (raw === 'true') return true;
+  if (raw === 'false') return false;
+  return undefined;
+}
+
+function sectionTrusted(text, folder) {
+  const tables = parseTomlTables(text);
+  const table = tables.get(sectionHeaderKey(`[folders."${folder}"]`));
+  return table ? tomlBool(table.trusted) === true : false;
+}
+
+function grokTrusted() {
+  const file = join(homedir(), '.grok', 'trusted_folders.toml');
+  if (!existsSync(file)) return false;
+  try {
+    return sectionTrusted(readFileSync(file, 'utf8'), ROOT);
+  } catch {
+    return false;
+  }
+}
+
+/** A `[mcp_servers.<name>]` table exists and is not explicitly `enabled = false`. */
+function configHasServer(file, name) {
+  if (!existsSync(file)) return false;
+  let tables;
+  try {
+    tables = parseTomlTables(readFileSync(file, 'utf8'));
+  } catch {
+    return false;
+  }
+  const table = tables.get(sectionHeaderKey(`[mcp_servers.${name}]`));
+  if (!table) return false;
+  return tomlBool(table.enabled) !== false;
+}
+
+function readStdinPayload() {
+  if (process.stdin.isTTY) return null;
+  try {
+    const raw = readFileSync(0, 'utf8');
+    if (!raw.trim().startsWith('{')) return null;
+    return JSON.parse(raw);
+  } catch {
+    return null;
+  }
+}
+
+function snapshot(host) {
+  if (host === 'claude') {
+    const settings = join(ROOT, '.claude', 'settings.json');
+    let wired = false;
+    if (existsSync(settings)) {
+      try {
+        wired = Boolean(JSON.parse(readFileSync(settings, 'utf8')).statusLine?.command);
+      } catch {
+        wired = false;
+      }
+    }
+    return {
+      host,
+      surface: HOST_STATUS.claude.surface,
+      loaded: {
+        statusLine: wired,
+        helper: has('.claude/helpers/statusline.cjs'),
+      },
+    };
+  }
+  if (host === 'codex') {
+    const homeCfg = join(homedir(), '.codex', 'config.toml');
+    return {
+      host,
+      surface: null,
+      loaded: {
+        mcp: configHasServer(homeCfg, 'ruflo') || configHasServer(homeCfg, 'claude-flow'),
+      },
+    };
+  }
+  const agents = ['ruflo-architect', 'ruflo-coder', 'ruflo-tester', 'ruflo-reviewer'].filter((name) =>
+    has(join('.grok', 'agents', `${name}.md`)),
+  );
+  const skills = ['agent-teams-grok'].filter((name) =>
+    has(join('.grok', 'skills', name, 'SKILL.md')),
+  );
+  const projectCfg = join(ROOT, '.grok', 'config.toml');
+  const userCfg = join(homedir(), '.grok', 'config.toml');
+  return {
+    host: 'grok',
+    surface: HOST_STATUS.grok.surface,
+    loaded: {
+      mcp: configHasServer(projectCfg, 'ruflo') || configHasServer(projectCfg, 'claude-flow') || configHasServer(userCfg, 'ruflo'),
+      rules: has('.grok/rules/ruflo-grok.md'),
+      agents: agents.length,
+      skills: skills.length,
+      hook: has('.grok/hooks/subagent-stop-team.json'),
+      trusted: grokTrusted(),
+    },
+  };
+}
+
+function lineFor(snap, stdin) {
+  if (snap.host === 'claude') {
+    const ok = snap.loaded.statusLine && snap.loaded.helper;
+    return ok ? 'RuFlo loaded │ claude statusLine' : 'RuFlo │ claude statusLine missing';
+  }
+  if (snap.host === 'codex') {
+    return snap.loaded.mcp ? 'RuFlo │ codex mcp configured (no status row)' : 'RuFlo │ codex mcp not configured';
+  }
+  const L = snap.loaded;
+  const gaps = [];
+  if (!L.mcp) gaps.push('mcp');
+  if (!L.rules) gaps.push('rules');
+  if (L.agents < 4) gaps.push(`agents ${L.agents}/4`);
+  if (L.skills < 1) gaps.push('skill agent-teams-grok');
+  if (!L.hook) gaps.push('hook');
+  if (!L.trusted) gaps.push('untrusted');
+  const head = gaps.length ? `RuFlo │ missing ${gaps.join(', ')}` : 'RuFlo loaded │ ruflo │ rules │ 4 agents │ skill │ hook │ trusted';
+  const model = stdin?.model?.display_name;
+  const pct = stdin?.context_window?.used_percentage;
+  const tail = [model, pct == null ? '' : `${pct}% ctx`].filter(Boolean).join(' │ ');
+  return tail ? `${head} │ ${tail}` : head;
+}
+
+const snap = snapshot(HOST);
+const text = lineFor(snap, readStdinPayload());
+if (JSON_OUT) {
+  process.stdout.write(JSON.stringify({ ...snap, line: text, map: HOST_STATUS }, null, 2) + '\n');
+} else if (text) {
+  process.stdout.write(`${text}\n`);
+}

package/v3/@claude-flow/cli/templates/grok/skills/agent-teams-grok/SKILL.md

@@ -0,0 +1,98 @@
+---
+name: agent-teams-grok
+description: >
+  Run Ruflo-style named Agent Teams on Grok Build using the host-agnostic team bus
+  (scripts/grok-team-bus.mjs). Use when coordinating multi-agent pipelines, feature
+  development with architect→coder→tester→reviewer, or replacing Claude SendMessage.
+---
+
+# 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)
+
+```bash
+# 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,
+})
+```
+
+1. Parse `spawnPlan.host.grok.spawn` (and `prompt`). Call **`spawn_subagent`** in **one message** for every agent (`background: true`).
+2. 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.
+3. `.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`.
+4. Children must not call `spawn_subagent`. Nesting depth is 1. The lead spawns the whole pipeline.
+5. 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.
+6. 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
+
+```bash
+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-x`
+- `swarm_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)