Skip to content

armgit / ruflo

Public Imported from GitHub
0

🌊 The original agent harness. Deploy intelligent multi-player swarms, coordinate autonomous workflows, and build conversational AI systems. Features adaptive memory, self-learning intelligence, federation, vector RAG integration, and native Claude Code / Codex / Hermes and many more Integrated

feat: Grok Build host surface + host-agnostic team bus (ADR-402) (#3512)

Mathew Beane953d8d0018d4
diff --git a/README.md b/README.md
index b42093667a..f17904bd1a 100644
--- a/README.md
+++ b/README.md
@@ -118,6 +118,8 @@ User → Ruflo (CLI/MCP) → Router → Swarm → Agents → Memory → LLM prov
A harness is the workbench around the model: it organizes tasks, carries context between steps and helps check results. **This establishes Ruflo's lineage, not a universal first across every Claude Code tool.** [See the illustrated explainer, exact commits and earlier ecosystem context](docs/harness-origins.md).
+**Grok Build:** `npx ruflo init --grok` writes the project host surface (`.grok/`, the team bus, and the operator guide) and nothing outside the project; add `--dry-run` to preview. Setup, the `spawn_subagent` contract, the optional status row, and what to re-check when Grok updates: [the Grok operator guide](v3/@claude-flow/cli/templates/grok/docs/README.md).
+
<details>
<summary><strong>📖 Background — where the name comes from</strong></summary>
diff --git a/package.json b/package.json
index 63c4565167..c3d389141c 100644
--- a/package.json
+++ b/package.json
@@ -30,6 +30,7 @@
"!v3/@claude-flow/cli/dist/**/*.map",
"v3/@claude-flow/cli/package.json",
"v3/@claude-flow/cli/catalog-manifest.json",
+ "v3/@claude-flow/cli/templates/**",
"v3/@claude-flow/shared/dist/**/*.js",
"v3/@claude-flow/shared/dist/**/*.d.ts",
"!v3/@claude-flow/shared/dist/**/*.map",
diff --git a/scripts/probe-grok-host-live.mjs b/scripts/probe-grok-host-live.mjs
new file mode 100755
index 0000000000..64d1341a06
--- /dev/null
+++ b/scripts/probe-grok-host-live.mjs
@@ -0,0 +1,13 @@
+#!/usr/bin/env node
+/** Grok is the default host. The check itself is scripts/probe-host-live.mjs. */
+import { spawnSync } from 'node:child_process';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const here = dirname(fileURLToPath(import.meta.url));
+const extra = process.argv.slice(2);
+if (!extra.includes('--host')) extra.unshift('--host', 'grok');
+const r = spawnSync(process.execPath, [join(here, 'probe-host-live.mjs'), ...extra], {
+ stdio: 'inherit',
+});
+process.exit(r.status == null ? 1 : r.status);
diff --git a/scripts/probe-host-live.mjs b/scripts/probe-host-live.mjs
new file mode 100755
index 0000000000..0a6fbf774c
--- /dev/null
+++ b/scripts/probe-host-live.mjs
@@ -0,0 +1,474 @@
+#!/usr/bin/env node
+/**
+ * probe-host-live.mjs — one Ruflo host check, several CLIs.
+ *
+ * The contract is the same on every host:
+ * discover did this process load rules, agents, skills, hooks, and an MCP server?
+ * connect does the server that host is configured to start expose the Ruflo tools?
+ * execute does a headless turn run a SessionStart hook?
+ * live can that turn store and retrieve a memory value? (--live)
+ *
+ * What each CLI cannot answer is a SKIP, not a pass.
+ *
+ * node scripts/probe-host-live.mjs --host grok
+ * node scripts/probe-host-live.mjs --host claude
+ * node scripts/probe-host-live.mjs --host codex
+ * node scripts/probe-host-live.mjs --host all --no-execute
+ * node scripts/probe-host-live.mjs --host grok --live
+ *
+ * --host defaults to grok. probe-grok-host-live.mjs is that default.
+ * The Grok checks read this checkout's .grok/ — generate it with
+ * `node v3/@claude-flow/cli/bin/cli.js init --grok` (it is not committed).
+ * EXIT 0 no critical failures (skips and warnings allowed) 1 critical fail 2 runner error
+ */
+
+import { spawnSync } from 'node:child_process';
+import { existsSync, mkdirSync, readFileSync, writeFileSync, rmSync } from 'node:fs';
+import { join, dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { tmpdir } from 'node:os';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const REPO_ROOT = resolve(__dirname, '..');
+const args = process.argv.slice(2);
+const JSON_OUT = args.includes('--json');
+const LIVE = args.includes('--live');
+const NO_EXECUTE = args.includes('--no-execute');
+
+function flag(name) {
+ const i = args.indexOf(name);
+ if (i < 0 || i + 1 >= args.length) return null;
+ return args[i + 1];
+}
+
+const HOST_ARG = (flag('--host') || 'grok').toLowerCase();
+const RUN_ID = `probe-${Date.now().toString(36)}`;
+const MCP_NAMES = ['ruflo', 'claude-flow'];
+const REQUIRED_TOOLS = [
+ 'team_create',
+ 'memory_store',
+ 'memory_retrieve',
+ 'hooks_route',
+ 'swarm_init',
+ 'neural_status',
+];
+const GROK_AGENTS = ['ruflo-architect', 'ruflo-coder', 'ruflo-tester', 'ruflo-reviewer'];
+const GROK_SKILLS = ['agent-teams-grok'];
+
+/** @type {{ host: string, id: string, domain: string, level: 'critical'|'warn'|'skip', ok: boolean, ms: number, detail: string }[]} */
+const results = [];
+
+function record(host, id, domain, level, ok, ms, detail) {
+ results.push({ host, id, domain, level, ok, ms, detail });
+ if (JSON_OUT) return;
+ const mark = ok ? 'PASS' : level === 'skip' ? 'SKIP' : level === 'warn' ? 'WARN' : 'FAIL';
+ console.log(`${mark}\t${host}\t${domain}\t${id}\t${detail}`);
+}
+
+function run(cmd, cmdArgs, timeoutMs) {
+ const start = Date.now();
+ const r = spawnSync(cmd, cmdArgs, {
+ cwd: REPO_ROOT,
+ encoding: 'utf8',
+ timeout: timeoutMs,
+ maxBuffer: 20 * 1024 * 1024,
+ env: process.env,
+ });
+ return {
+ code: r.status,
+ stdout: r.stdout || '',
+ stderr: r.stderr || '',
+ error: r.error ? String(r.error.message || r.error) : '',
+ ms: Date.now() - start,
+ };
+}
+
+function which(bin) {
+ const direct = spawnSync('/bin/sh', ['-c', `command -v ${bin}`], { encoding: 'utf8' });
+ const path = (direct.stdout || '').trim();
+ return path || null;
+}
+
+function parseJson(text) {
+ const src = String(text || '');
+ for (const open of ['{', '[']) {
+ const start = src.indexOf(open);
+ if (start < 0) continue;
+ const close = open === '{' ? '}' : ']';
+ const end = src.lastIndexOf(close);
+ if (end <= start) continue;
+ try {
+ return JSON.parse(src.slice(start, end + 1));
+ } catch {
+ /* try the other bracket */
+ }
+ }
+ return null;
+}
+
+function toolNamesFromCli(cliPath) {
+ const listed = run(process.execPath, [cliPath, 'mcp', 'tools'], 60_000);
+ const names = new Set();
+ for (const line of `${listed.stdout}\n${listed.stderr}`.split('\n')) {
+ const m = line.match(/^\s{2}([a-z][a-z0-9_-]+)\s{2,}/);
+ if (m) names.add(m[1]);
+ }
+ return names;
+}
+
+function recordTools(host, names, filterNote) {
+ for (const tool of REQUIRED_TOOLS) {
+ if (names.has(tool)) {
+ record(host, `server-tool:${tool}`, 'connect', 'critical', true, 0, filterNote || 'exposed by the configured server command');
+ continue;
+ }
+ record(
+ host,
+ `server-tool:${tool}`,
+ 'connect',
+ 'critical',
+ false,
+ 0,
+ filterNote ? `${filterNote}; ${tool} not listed` : 'missing from mcp tools',
+ );
+ }
+}
+
+function hookCommand(receipt) {
+ return `${process.execPath} -e ${JSON.stringify(
+ `require('fs').writeFileSync(${JSON.stringify(receipt)}, 'fired\\n')`,
+ )}`;
+}
+
+function livePrompt(host, key) {
+ const task = [
+ `Store then retrieve one Ruflo memory value.`,
+ `key ${JSON.stringify(key)}, value "probe-ok", namespace "host-probe".`,
+ 'Do not edit files. Do not spawn a subagent.',
+ 'Reply with exactly: PROBE_OK probe-ok',
+ ];
+ if (host === 'grok') {
+ return [
+ 'Use the ruflo MCP server through search_tool and use_tool.',
+ `1. search_tool for memory_store.`,
+ `2. use_tool ruflo__memory_store with key ${JSON.stringify(key)}, value "probe-ok", namespace "host-probe".`,
+ '3. use_tool ruflo__memory_retrieve with the same key and namespace.',
+ 'Reply with exactly: PROBE_OK probe-ok',
+ 'Do not edit files. Do not spawn a subagent.',
+ ].join('\n');
+ }
+ return task.join('\n');
+}
+
+function finishHeadless(host, r, receipt) {
+ const fired = existsSync(receipt);
+ record(
+ host,
+ 'hook:session-start',
+ 'execute',
+ 'critical',
+ fired,
+ r.ms,
+ fired ? 'SessionStart hook wrote a receipt' : 'hook did not fire, or the session never started',
+ );
+ const out = parseJson(r.stdout);
+ const text = String(out?.text || out?.message || r.stdout || '');
+ if (!LIVE) {
+ record(
+ host,
+ 'session:ping',
+ 'execute',
+ 'critical',
+ r.code === 0 && /PING/.test(text),
+ 0,
+ r.code === 0 ? 'headless session answered' : `exit=${r.code} ${(r.error || r.stderr).slice(0, 200)}`,
+ );
+ } else {
+ record(
+ host,
+ 'live:memory-roundtrip',
+ 'execute',
+ 'critical',
+ r.code === 0 && /PROBE_OK probe-ok/.test(text),
+ 0,
+ r.code === 0 ? text.trim().slice(0, 240) : `exit=${r.code} ${(r.error || r.stderr).slice(0, 240)}`,
+ );
+ }
+}
+
+const adapters = {
+ grok: {
+ binary: 'grok',
+ discover() {
+ if (!existsSync(join(REPO_ROOT, '.grok', 'config.toml'))) {
+ record('grok', 'surface', 'discover', 'critical', false, 0, 'no .grok/ in this checkout — run `node v3/@claude-flow/cli/bin/cli.js init --grok` first');
+ return;
+ }
+ const r = run('grok', ['--cwd', REPO_ROOT, 'inspect', '--json'], 60_000);
+ const data = parseJson(r.stdout);
+ if (!data) {
+ record('grok', 'inspect', 'discover', 'critical', false, r.ms, r.error || `exit=${r.code} no json`);
+ return;
+ }
+ record('grok', 'inspect:version', 'discover', 'critical', Boolean(data.grokVersion), r.ms, data.grokVersion || 'missing');
+ record('grok', 'inspect:trusted', 'discover', 'critical', data.projectTrusted === true, 0, data.projectTrusted ? 'folder trusted' : 'folder not trusted');
+ const instructions = Array.isArray(data.projectInstructions) ? data.projectInstructions : [];
+ const rule = instructions.find((i) => String(i.path || '').endsWith('.grok/rules/ruflo-grok.md'));
+ record('grok', 'inspect:rules', 'discover', 'critical', Boolean(rule), 0, rule ? rule.path : 'ruflo-grok.md not loaded');
+ const agents = Array.isArray(data.agents) ? data.agents : [];
+ for (const name of GROK_AGENTS) {
+ const hit = agents.find((a) => a.name === name && String(a.source?.path || '').includes(`${join('.grok', 'agents', name)}.md`));
+ record('grok', `inspect:agent:${name}`, 'discover', 'critical', Boolean(hit), 0, hit ? hit.source.path : 'not a project agent');
+ }
+ const skills = Array.isArray(data.skills) ? data.skills : [];
+ for (const name of GROK_SKILLS) {
+ const hit = skills.find((s) => s.name === name && String(s.source?.path || '').includes(join('.grok', 'skills')));
+ record('grok', `inspect:skill:${name}`, 'discover', 'critical', Boolean(hit), 0, hit ? hit.source.path : 'not loaded from .grok/skills');
+ }
+ const hooks = Array.isArray(data.hooks) ? data.hooks : [];
+ const teamHook = hooks.find((h) => h.event === 'subagent_stop' && String(h.target || '').includes('grok-subagent-stop-hook.mjs'));
+ record('grok', 'inspect:hook:subagent-stop', 'discover', 'critical', Boolean(teamHook), 0, teamHook ? teamHook.target : 'team SubagentStop hook not loaded');
+ const servers = Array.isArray(data.mcpServers) ? data.mcpServers : [];
+ const found = MCP_NAMES.map((name) => servers.find((s) => s.name === name)).filter(Boolean);
+ const mcp = found[0];
+ record('grok', 'inspect:mcp', 'discover', 'critical', Boolean(mcp), 0, mcp ? `${mcp.name} via ${mcp.source?.path || 'unknown'}` : `no ${MCP_NAMES.join(' or ')}`);
+ if (found.length > 1) {
+ record('grok', 'inspect:mcp:extra', 'discover', 'warn', false, 0, `also loaded: ${found.slice(1).map((s) => `${s.name} via ${s.source?.path || 'unknown'}`).join('; ')}`);
+ }
+ },
+ connect() {
+ const r = run('grok', ['--cwd', REPO_ROOT, 'mcp', 'doctor', 'ruflo', '--json'], 180_000);
+ const data = parseJson(r.stdout);
+ const server = data?.servers?.find((s) => MCP_NAMES.includes(s.name));
+ if (!server) {
+ record('grok', 'doctor', 'connect', 'critical', false, r.ms, r.error || r.stderr.slice(0, 240) || 'no ruflo/claude-flow server');
+ return;
+ }
+ const failed = (server.checks || []).filter((c) => !c.passed);
+ const tools = (server.checks || []).find((c) => /tools discovered/i.test(c.label));
+ record('grok', 'doctor:handshake', 'connect', 'critical', server.healthy === true && failed.length === 0, r.ms, failed.length ? failed.map((c) => c.label).join(', ') : `${server.target}; ${tools?.label || 'healthy'}`);
+ const target = String(server.target || '');
+ const cli = target.startsWith('node ') ? target.split(/\s+/)[1] : '';
+ if (!cli || !existsSync(cli)) {
+ record('grok', 'doctor:tool-names', 'connect', 'skip', false, 0, `host did not give a local node entry: ${target}`);
+ return;
+ }
+ recordTools('grok', toolNamesFromCli(cli));
+ },
+ execute() {
+ const receipt = join(tmpdir(), `${RUN_ID}-grok.receipt`);
+ const dir = join(REPO_ROOT, '.grok', 'hooks');
+ mkdirSync(dir, { recursive: true });
+ const hookPath = join(dir, `${RUN_ID}.json`);
+ const promptPath = join(tmpdir(), `${RUN_ID}-grok.prompt.txt`);
+ writeFileSync(hookPath, JSON.stringify({ hooks: { SessionStart: [{ hooks: [{ type: 'command', command: hookCommand(receipt), timeout: 10 }] }] } }, null, 2) + '\n');
+ writeFileSync(promptPath, LIVE ? livePrompt('grok', `${RUN_ID}-memory`) : 'Reply with exactly: PING');
+ try {
+ const r = run('grok', ['--cwd', REPO_ROOT, '--prompt-file', promptPath, '--verbatim', '--output-format', 'json', '--max-turns', LIVE ? '8' : '1', '--always-approve'], LIVE ? 300_000 : 180_000);
+ finishHeadless('grok', r, receipt);
+ } finally {
+ rmSync(hookPath, { force: true });
+ rmSync(receipt, { force: true });
+ rmSync(promptPath, { force: true });
+ }
+ },
+ },
+
+ claude: {
+ binary: 'claude',
+ discover() {
+ record('claude', 'inspect', 'discover', 'skip', false, 0, 'Claude Code has no inspect --json. File presence is not evidence a session loaded rules, agents, skills, or hooks.');
+ },
+ connect() {
+ const r = run('claude', ['mcp', 'get', 'claude-flow'], 90_000);
+ const text = `${r.stdout}\n${r.stderr}`;
+ const missing = /No MCP server named/i.test(text);
+ if (missing || r.code !== 0) {
+ record('claude', 'mcp:claude-flow', 'connect', 'warn', false, r.ms, missing ? 'no server named claude-flow or ruflo in Claude MCP config' : text.slice(0, 240));
+ return;
+ }
+ record('claude', 'mcp:claude-flow', 'connect', 'critical', true, r.ms, text.replace(/\s+/g, ' ').slice(0, 240));
+ record('claude', 'server-tools', 'connect', 'skip', false, 0, 'claude mcp get does not report the tool list or the spawned command reliably enough to assert tool names');
+ },
+ execute() {
+ const receipt = join(tmpdir(), `${RUN_ID}-claude.receipt`);
+ const settingsPath = join(tmpdir(), `${RUN_ID}-claude-settings.json`);
+ const promptPath = join(tmpdir(), `${RUN_ID}-claude.prompt.txt`);
+ writeFileSync(settingsPath, JSON.stringify({ hooks: { SessionStart: [{ hooks: [{ type: 'command', command: hookCommand(receipt), timeout: 10 }] }] } }));
+ writeFileSync(promptPath, LIVE ? livePrompt('claude', `${RUN_ID}-memory`) : 'Reply with exactly: PING');
+ try {
+ const r = run('claude', ['-p', '--output-format', 'json', '--settings', settingsPath, '--dangerously-skip-permissions', '--', readPrompt(promptPath)], LIVE ? 300_000 : 180_000);
+ finishHeadless('claude', r, receipt);
+ } finally {
+ rmSync(settingsPath, { force: true });
+ rmSync(receipt, { force: true });
+ rmSync(promptPath, { force: true });
+ }
+ },
+ },
+
+ codex: {
+ binary: 'codex',
+ discover() {
+ record('codex', 'inspect', 'discover', 'skip', false, 0, 'Codex CLI has no inspect --json for rules, agents, skills, or hooks.');
+ },
+ connect() {
+ const r = run('codex', ['mcp', 'list', '--json'], 30_000);
+ const data = parseJson(r.stdout);
+ if (!Array.isArray(data)) {
+ record('codex', 'mcp:list', 'connect', 'critical', false, r.ms, r.error || `exit=${r.code} no json`);
+ return;
+ }
+ const server = data.find((s) => MCP_NAMES.includes(s.name) && s.enabled !== false);
+ if (!server) {
+ record('codex', 'mcp:ruflo', 'connect', 'warn', false, r.ms, `no enabled ${MCP_NAMES.join(' or ')} in Codex MCP config`);
+ return;
+ }
+ const cmd = server.transport?.command;
+ const argv = Array.isArray(server.transport?.args) ? server.transport.args : [];
+ const filter = server.transport?.env?.CLAUDE_FLOW_MCP_TOOLS || '';
+ record('codex', 'mcp:configured', 'connect', 'critical', true, r.ms, `${server.name}: ${cmd || server.transport?.type} ${argv[0] || ''}`.trim());
+ record('codex', 'mcp:handshake', 'connect', 'skip', false, 0, 'codex mcp list shows configuration, not a live handshake');
+ const cli = argv.find((a) => String(a).endsWith('cli.js'));
+ if (!cli || !existsSync(cli)) {
+ record('codex', 'server-tools', 'connect', 'skip', false, 0, 'configured command is not a local cli.js, so tool names were not listed');
+ return;
+ }
+ const names = toolNamesFromCli(cli);
+ const groups = new Set(String(filter).split(',').map((s) => s.trim()).filter(Boolean));
+ const groupOf = {
+ team_create: 'team',
+ memory_store: 'memory',
+ memory_retrieve: 'memory',
+ hooks_route: 'hooks',
+ swarm_init: 'swarm',
+ neural_status: 'neural',
+ };
+ for (const tool of REQUIRED_TOOLS) {
+ const group = groupOf[tool];
+ if (groups.size && !groups.has(group)) {
+ record('codex', `server-tool:${tool}`, 'connect', 'skip', false, 0, `host filter CLAUDE_FLOW_MCP_TOOLS=${filter} does not include ${group}`);
+ continue;
+ }
+ record('codex', `server-tool:${tool}`, 'connect', 'critical', names.has(tool), 0, names.has(tool) ? 'present on the configured CLI' : 'missing');
+ }
+ },
+ execute() {
+ record('codex', 'hook:session-start', 'execute', 'skip', false, 0, 'Codex can bypass hook trust, but this adapter does not yet know a safe temp hook file Codex will load. Not counted as a pass.');
+ record('codex', 'session:ping', 'execute', 'skip', false, 0, 'Headless codex exec is implemented only once a hook install path is confirmed. Run is not faked.');
+ },
+ },
+};
+
+function readPrompt(path) {
+ return spawnSync('/bin/cat', [path], { encoding: 'utf8' }).stdout || '';
+}
+
+function runHost(id) {
+ const adapter = adapters[id];
+ const bin = which(adapter.binary);
+ if (!bin) {
+ record(id, 'binary', 'discover', 'skip', false, 0, `${adapter.binary} is not on PATH`);
+ return;
+ }
+ record(id, 'binary', 'discover', 'critical', true, 0, bin);
+ adapter.discover();
+ adapter.connect();
+ statusCheck(id);
+ if (!NO_EXECUTE) adapter.execute();
+}
+
+function statusCheck(id) {
+ const script = join(REPO_ROOT, 'scripts', 'host-statusline.mjs');
+ if (!existsSync(script)) {
+ record(id, 'statusline', 'status', 'skip', false, 0, 'scripts/host-statusline.mjs is not in this checkout');
+ return;
+ }
+ const r = run(process.execPath, [script, '--host', id, '--json'], 15_000);
+ const data = parseJson(r.stdout);
+ if (!data?.line) {
+ record(id, 'statusline', 'status', 'warn', false, r.ms, 'status snapshot produced no line');
+ return;
+ }
+ if (id === 'codex' || data.surface == null) {
+ record(id, 'statusline', 'status', 'skip', false, r.ms, `${data.line} — this host has no status row`);
+ return;
+ }
+ const loaded = String(data.line).startsWith('RuFlo loaded');
+ record(id, 'statusline', 'status', loaded ? 'critical' : 'warn', loaded, r.ms, data.line);
+ if (id === 'grok') {
+ const homeCfg = join(process.env.HOME || '', '.grok', 'config.toml');
+ let wired = false;
+ try {
+ // Header, [ ui."status_line" ], dotted key, or inline table.
+ wired = existsSync(homeCfg)
+ && /^\s*\[\s*ui\s*\.\s*["']?status_line["']?\s*\]|^\s*(ui\s*\.\s*)?status_line\s*[.=]/m.test(readFileSync(homeCfg, 'utf8'));
+ } catch {
+ wired = false;
+ }
+ record(
+ id,
+ 'statusline:wired',
+ 'status',
+ wired ? 'critical' : 'warn',
+ wired,
+ 0,
+ wired
+ ? 'user ~/.grok/config.toml has [ui.status_line] (project config cannot set this)'
+ : 'row stays hidden until ~/.grok/config.toml has [ui.status_line]; project .grok/config.toml cannot enable it',
+ );
+ }
+}
+
+function main() {
+ const known = Object.keys(adapters);
+ if (HOST_ARG !== 'all' && !known.includes(HOST_ARG)) {
+ console.error(`Unknown --host ${HOST_ARG}. Use ${known.join(', ')}, or all.`);
+ process.exit(2);
+ }
+ const hosts = HOST_ARG === 'all' ? known : [HOST_ARG];
+ if (!JSON_OUT) console.log(`Host probe run=${RUN_ID} hosts=${hosts.join(',')} live=${LIVE} execute=${!NO_EXECUTE}`);
+ for (const id of hosts) runHost(id);
+ const critical = results.filter((r) => r.level === 'critical' && !r.ok);
+ const skips = results.filter((r) => r.level === 'skip');
+ const warns = results.filter((r) => r.level === 'warn' && !r.ok);
+ const report = {
+ id: RUN_ID,
+ when: new Date().toISOString(),
+ hosts,
+ live: LIVE,
+ execute: !NO_EXECUTE,
+ pass: results.filter((r) => r.ok).length,
+ fail: critical.length,
+ skip: skips.length,
+ warn: warns.length,
+ results,
+ };
+ const outDir = join(REPO_ROOT, 'docs', 'benchmarks');
+ mkdirSync(outDir, { recursive: true });
+ writeFileSync(join(outDir, 'host-live-latest.json'), JSON.stringify(report, null, 2) + '\n');
+ const lines = [
+ `# Host probe — ${RUN_ID}`,
+ '',
+ `**When:** ${report.when}`,
+ `**Hosts:** ${hosts.join(', ')}`,
+ `**Live model turn:** ${LIVE}`,
+ `**Result:** ${critical.length ? 'FAIL' : 'PASS'} — ${report.pass} passed, ${critical.length} failed, ${warns.length} warnings, ${skips.length} skipped`,
+ '',
+ 'Skips are surfaces that host does not expose. They are not passes.',
+ '',
+ '| Status | Host | Domain | Id | Detail |',
+ '|--------|------|--------|----|--------|',
+ ];
+ for (const r of results) {
+ const status = r.ok ? 'PASS' : r.level === 'skip' ? 'SKIP' : r.level === 'warn' ? 'WARN' : 'FAIL';
+ lines.push(`| ${status} | ${r.host} | ${r.domain} | \`${r.id}\` | ${r.detail.replace(/\|/g, '/')} |`);
+ }
+ lines.push('');
+ writeFileSync(join(outDir, 'host-live-latest.md'), lines.join('\n'));
+ if (JSON_OUT) console.log(JSON.stringify(report, null, 2));
+ else console.log(`\n${critical.length ? 'FAIL' : 'PASS'} ${report.pass} passed, ${critical.length} failed, ${warns.length} warnings, ${skips.length} skipped`);
+ process.exit(critical.length ? 1 : 0);
+}
+
+main();
diff --git a/scripts/use-local-ruflo.sh b/scripts/use-local-ruflo.sh
new file mode 100755
index 0000000000..27b6039da6
--- /dev/null
+++ b/scripts/use-local-ruflo.sh
@@ -0,0 +1,63 @@
+#!/usr/bin/env bash
+# Build the monorepo CLI and make the shell `ruflo` command use it.
+#
+# Usage (from repo root or anywhere):
+# ./scripts/use-local-ruflo.sh
+# ./scripts/use-local-ruflo.sh --skip-build # only re-link
+#
+# After this:
+# which ruflo → …/node_modules/ruflo → this repo's ruflo/bin/ruflo.js
+# ruflo --version
+# ruflo mcp tools | grep team_
+set -euo pipefail
+
+ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+SKIP_BUILD=0
+for a in "$@"; do
+ case "$a" in
+ --skip-build) SKIP_BUILD=1 ;;
+ -h|--help)
+ sed -n '2,12p' "$0"
+ exit 0
+ ;;
+ esac
+done
+
+if [[ "$SKIP_BUILD" -eq 0 ]]; then
+ echo "==> Building @claude-flow/cli (+ workspace deps)…"
+ (cd "$ROOT/v3" && pnpm --filter @claude-flow/cli... build)
+else
+ echo "==> Skipping build (--skip-build)"
+fi
+
+if [[ ! -f "$ROOT/v3/@claude-flow/cli/dist/src/index.js" ]]; then
+ echo "error: CLI dist missing — build failed or was skipped without dist" >&2
+ exit 1
+fi
+
+echo "==> npm link ruflo wrapper → global PATH"
+(cd "$ROOT/ruflo" && npm link)
+
+# Prefer nvm/global node bin over older pnpm global ruflo if both exist
+RUFL0_BIN="$(command -v ruflo || true)"
+echo ""
+echo "ruflo → ${RUFL0_BIN:-not found}"
+if [[ -n "$RUFL0_BIN" ]]; then
+ # Resolve symlink chain target when possible
+ if command -v realpath >/dev/null 2>&1; then
+ echo "target → $(realpath "$RUFL0_BIN" 2>/dev/null || true)"
+ fi
+ ruflo --version
+ if ruflo mcp tools 2>/dev/null | grep -q 'team_create'; then
+ echo "OK: team_* tools present (local ADR-402 surface)"
+ else
+ echo "warn: team_create not listed — check CLI dist / mcp tools" >&2
+ fi
+fi
+
+echo ""
+echo "Grok MCP: \`node $ROOT/v3/@claude-flow/cli/bin/cli.js init --grok\` in a project writes this for you."
+echo "To point an existing project .grok/config.toml [mcp_servers.ruflo] at this build:"
+echo " command = \"node\""
+echo " args = [\"$ROOT/v3/@claude-flow/cli/bin/cli.js\", \"mcp\", \"start\"]"
+echo "Then restart Grok."
diff --git a/v3/@claude-flow/cli/__tests__/grok-init.test.ts b/v3/@claude-flow/cli/__tests__/grok-init.test.ts
new file mode 100644
index 0000000000..c6ac172ab8
--- /dev/null
+++ b/v3/@claude-flow/cli/__tests__/grok-init.test.ts
@@ -0,0 +1,351 @@
+/**
+ * `init --grok` (ADR-402) — regression coverage for the #3512 review:
+ * user-config merge safety, opt-in home writes, dry run, pinned MCP launch,
+ * Windows escaping, and the shipped status row.
+ */
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import {
+ mkdtempSync,
+ rmSync,
+ existsSync,
+ readFileSync,
+ writeFileSync,
+ mkdirSync,
+ readdirSync,
+ symlinkSync,
+ lstatSync,
+ realpathSync,
+} from 'node:fs';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+import { spawnSync } from 'node:child_process';
+import * as TOML from '@iarna/toml';
+import {
+ executeGrokInit,
+ grokStatusLineCommand,
+ grokTemplatesRoot,
+ materializeGrokConfig,
+ mergeGrokStatusLine,
+ rufloMcpLaunch,
+} from '../src/init/grok-generator.js';
+
+const HOME = '/home/tester';
+
+/** Existing, valid user configs that already set ui.status_line some other way. */
+const ALREADY_SET: Record<string, string> = {
+ header: '[ui.status_line]\ntype = "command"\ncommand = "mine"\n',
+ spacedHeader: '[ ui.status_line ]\ntype = "command"\ncommand = "mine"\n',
+ quotedHeader: '[ui."status_line"]\ntype = "command"\ncommand = "mine"\n',
+ inlineTable: '[ui]\nstatus_line = { type = "command", command = "mine" }\n',
+ dottedKeys: '[ui]\nstatus_line.type = "command"\nstatus_line.command = "mine"\n',
+ rootDotted: 'ui.status_line.type = "command"\nui.status_line.command = "mine"\n',
+};
+
+describe('mergeGrokStatusLine (review #1)', () => {
+ for (const [name, text] of Object.entries(ALREADY_SET)) {
+ it(`leaves an existing status row alone: ${name}`, () => {
+ expect(TOML.parse(text)).toBeTruthy();
+ expect(mergeGrokStatusLine(text, HOME)).toEqual({ kind: 'already-set', ours: false });
+ });
+ }
+
+ it('appends to an unrelated config and keeps every other value and comment', () => {
+ const text = '# my settings\nmodel = "grok-4"\n\n[ui]\ntheme = "dark"\n\n[mcp_servers.x]\ncommand = "x"\nargs = ["a"]';
+ const out = mergeGrokStatusLine(text, HOME);
+ expect(out.kind).toBe('write');
+ if (out.kind !== 'write') return;
+ expect(out.text.startsWith(text)).toBe(true);
+ const parsed = TOML.parse(out.text) as any;
+ expect(parsed.model).toBe('grok-4');
+ expect(parsed.ui.theme).toBe('dark');
+ expect(parsed.mcp_servers.x.args).toEqual(['a']);
+ expect(parsed.ui.status_line).toEqual({ type: 'command', command: grokStatusLineCommand(HOME) });
+ });
+
+ it('falls back to the snippet when ui is an inline table (cannot be extended)', () => {
+ const out = mergeGrokStatusLine('ui = { theme = "dark" }\n', HOME);
+ expect(out.kind).toBe('unsafe');
+ });
+
+ it('falls back to the snippet when the file is not valid TOML', () => {
+ const out = mergeGrokStatusLine('[ui\nbroken = ', HOME);
+ expect(out.kind).toBe('unsafe');
+ if (out.kind === 'unsafe') expect(out.reason).toMatch(/could not parse/);
+ });
+
+ it('produces TOML that Python tomllib also accepts (when python3 is present)', () => {
+ const out = mergeGrokStatusLine('[ui]\ntheme = "dark"\n', 'C:\\Users\\Bob');
+ expect(out.kind).toBe('write');
+ if (out.kind !== 'write') return;
+ const py = spawnSync('python3', ['-c', 'import sys,tomllib,json; print(json.dumps(tomllib.loads(sys.stdin.read())))'], {
+ input: out.text,
+ encoding: 'utf-8',
+ });
+ if (py.error || py.status === null) return; // no python3 on this runner
+ if (py.stderr.includes('No module named')) return; // python < 3.11
+ expect(py.status, py.stderr).toBe(0);
+ expect(JSON.parse(py.stdout).ui.status_line.command).toBe(grokStatusLineCommand('C:\\Users\\Bob'));
+ });
+});
+
+describe('status row command (reviews #7, #10)', () => {
+ it('runs node on an absolute path, with no shell and no repo-relative script', () => {
+ const cmd = grokStatusLineCommand(HOME);
+ expect(cmd).toBe(`node "${join(HOME, '.grok', 'ruflo', 'host-statusline.mjs')}"`);
+ expect(cmd).not.toMatch(/\bsh\b|test -f|scripts\//);
+ });
+});
+
+describe('materializeGrokConfig (reviews #9, #10)', () => {
+ const template = readFileSync(join(grokTemplatesRoot(), 'config.toml'), 'utf-8');
+
+ it('never launches ruflo@latest', () => {
+ expect(template).not.toMatch(/ruflo@latest/);
+ const launch = rufloMcpLaunch();
+ const text = materializeGrokConfig(template, launch, HOME);
+ const parsed = TOML.parse(text) as any;
+ expect(parsed.mcp_servers.ruflo.command).toBe(launch.command);
+ expect(parsed.mcp_servers.ruflo.args).toEqual(launch.args);
+ expect(JSON.stringify(parsed)).not.toMatch(/@latest/);
+ });
+
+ it('pins a published install to its own version', () => {
+ const root = join(tmpdir(), 'x', 'node_modules', '@claude-flow', 'cli');
+ const launch = rufloMcpLaunch(root);
+ expect(launch.source).toBe('published');
+ expect(launch.args).toContain('[email protected]');
+ expect(launch.args.some((a) => a.includes('latest'))).toBe(false);
+ });
+
+ it('escapes Windows paths into valid TOML strings', () => {
+ const winHome = 'C:\\Users\\Bob';
+ const launch = {
+ command: 'node',
+ args: ['C:\\src\\ruflo\\v3\\@claude-flow\\cli\\bin\\cli.js', 'mcp', 'start'],
+ source: 'checkout' as const,
+ version: '1.0.0',
+ };
+ // Uncomment the optional brain block so its {{HOME}} paths are parsed too.
+ const text = materializeGrokConfig(template.replace(/^# (\[mcp_servers\.ruvnet-brain\]|command|args|env|enabled|startup_timeout_sec|tool_timeout_sec)/gm, '$1'), launch, winHome);
+ const parsed = TOML.parse(text) as any;
+ expect(parsed.mcp_servers.ruflo.args[0]).toBe(launch.args[0]);
+ expect(parsed.mcp_servers['ruvnet-brain'].env.KB_DIR).toBe('C:\\Users\\Bob/.cache/ruvnet-brain/kb');
+ });
+});
+
+describe('executeGrokInit', () => {
+ let dir: string;
+ let home: string;
+
+ beforeEach(() => {
+ dir = mkdtempSync(join(tmpdir(), 'ruflo-grok-init-'));
+ home = mkdtempSync(join(tmpdir(), 'ruflo-grok-home-'));
+ });
+
+ afterEach(() => {
+ rmSync(dir, { recursive: true, force: true });
+ rmSync(home, { recursive: true, force: true });
+ });
+
+ it('does not touch the home directory unless asked (review #2)', () => {
+ const r = executeGrokInit({ targetDir: dir, homeDir: home });
+ expect(r.success, r.errors.join('\n')).toBe(true);
+ expect(readdirSync(home)).toEqual([]);
+ expect(r.userConfig.action).toBe('not-requested');
+ expect(r.userConfig.snippet).toMatch(/\[ui\.status_line\]/);
+ expect(r.filesCreated.every((f) => f.startsWith(dir))).toBe(true);
+ // Project config is valid TOML and pinned
+ const cfg = TOML.parse(readFileSync(join(dir, '.grok', 'config.toml'), 'utf-8')) as any;
+ expect(cfg.mcp_servers.ruflo.args.join(' ')).not.toMatch(/latest/);
+ });
+
+ it('dry run writes nothing and lists what it would write (review #2)', () => {
+ const r = executeGrokInit({ targetDir: dir, homeDir: home, dryRun: true, statusLine: true });
+ expect(r.success).toBe(true);
+ expect(readdirSync(dir)).toEqual([]);
+ expect(readdirSync(home)).toEqual([]);
+ expect(r.userConfig.action).toBe('would-write');
+ expect(r.filesCreated).toContain(join(home, '.grok', 'config.toml'));
+ expect(r.filesCreated).toContain(join(dir, '.grok', 'config.toml'));
+ });
+
+ it('--grok-statusline merges into an existing user config and lists the path', () => {
+ mkdirSync(join(home, '.grok'), { recursive: true });
+ writeFileSync(join(home, '.grok', 'config.toml'), '# keep me\n[ui]\ntheme = "dark"\n');
+ const r = executeGrokInit({ targetDir: dir, homeDir: home, statusLine: true });
+ expect(r.success, r.errors.join('\n')).toBe(true);
+ expect(r.userConfig.action).toBe('merged');
+ expect(r.filesCreated).toContain(join(home, '.grok', 'config.toml'));
+ const text = readFileSync(join(home, '.grok', 'config.toml'), 'utf-8');
+ expect(text.startsWith('# keep me\n[ui]\ntheme = "dark"\n')).toBe(true);
+ const parsed = TOML.parse(text) as any;
+ expect(parsed.ui.status_line.command).toBe(grokStatusLineCommand(home));
+ expect(existsSync(join(home, '.grok', 'ruflo', 'host-statusline.mjs'))).toBe(true);
+
+ // A second run is a no-op on the config
+ const again = executeGrokInit({ targetDir: dir, homeDir: home, statusLine: true, force: true });
+ expect(again.userConfig.action).toBe('already-set');
+ expect(readFileSync(join(home, '.grok', 'config.toml'), 'utf-8')).toBe(text);
+ });
+
+ it('--grok-statusline leaves a foreign status row alone and installs nothing', () => {
+ mkdirSync(join(home, '.grok'), { recursive: true });
+ const original = '[ ui.status_line ]\ntype = "command"\ncommand = "mine"\n';
+ writeFileSync(join(home, '.grok', 'config.toml'), original);
+ const r = executeGrokInit({ targetDir: dir, homeDir: home, statusLine: true });
+ expect(r.userConfig.action).toBe('already-set');
+ expect(r.userConfig.reason).toMatch(/its own \[ui\.status_line\]/);
+ expect(readFileSync(join(home, '.grok', 'config.toml'), 'utf-8')).toBe(original);
+ expect(existsSync(join(home, '.grok', 'ruflo'))).toBe(false);
+ expect(r.filesCreated.some((f) => f.startsWith(home))).toBe(false);
+ });
+
+ it('--grok-statusline never rewrites a config it cannot merge safely', () => {
+ mkdirSync(join(home, '.grok'), { recursive: true });
+ const original = 'ui = { theme = "dark" }\n';
+ writeFileSync(join(home, '.grok', 'config.toml'), original);
+ const r = executeGrokInit({ targetDir: dir, homeDir: home, statusLine: true });
+ expect(r.success).toBe(true);
+ expect(r.userConfig.action).toBe('snippet');
+ expect(r.userConfig.reason).toMatch(/would not parse/);
+ expect(readFileSync(join(home, '.grok', 'config.toml'), 'utf-8')).toBe(original);
+ });
+
+ it('ships a status row that reports "loaded" after init (review #6)', () => {
+ executeGrokInit({ targetDir: dir, homeDir: home });
+ const r = spawnSync(process.execPath, [join(dir, 'scripts', 'host-statusline.mjs'), '--json'], {
+ cwd: dir,
+ env: { ...process.env, HOME: home, USERPROFILE: home },
+ encoding: 'utf-8',
+ input: '',
+ });
+ expect(r.status, r.stderr).toBe(0);
+ const snap = JSON.parse(r.stdout);
+ expect(snap.loaded).toMatchObject({ mcp: true, rules: true, agents: 4, skills: 1, hook: true });
+ // Only folder trust (a Grok-side setting) is left
+ expect(snap.line).toMatch(/^RuFlo │ missing untrusted/);
+ });
+
+ it('host-statusline.mjs parses real TOML instead of text-matching (round-2 review, minor item 3)', () => {
+ executeGrokInit({ targetDir: dir, homeDir: home });
+ const runStatusline = () =>
+ JSON.parse(
+ spawnSync(process.execPath, [join(dir, 'scripts', 'host-statusline.mjs'), '--json'], {
+ cwd: dir,
+ env: { ...process.env, HOME: home, USERPROFILE: home },
+ encoding: 'utf-8',
+ input: '',
+ }).stdout,
+ );
+ // Node's spawn cwd is resolved to the real path (e.g. macOS /var is a
+ // symlink to /private/var) before the child ever sees process.cwd(), so
+ // the section key must match that resolved path, not the tmpdir's own.
+ const root = realpathSync(dir);
+
+ // A commented-out `trusted = true` must not read as trusted (a
+ // substring/regex match on the section body would say yes).
+ mkdirSync(join(home, '.grok'), { recursive: true });
+ writeFileSync(join(home, '.grok', 'trusted_folders.toml'), `[folders."${root}"]\n# trusted = true\n`);
+ expect(runStatusline().loaded.trusted).toBe(false);
+
+ // A genuine (uncommented) trusted = true in the same section shape
+ // still works — this isn't just rejecting everything.
+ writeFileSync(join(home, '.grok', 'trusted_folders.toml'), `[folders."${root}"]\ntrusted = true\n`);
+ expect(runStatusline().loaded.trusted).toBe(true);
+
+ // An mcp_servers.ruflo table that exists but is explicitly disabled
+ // must not count as "loaded" (a substring match on `[mcp_servers.name]`
+ // alone would say yes regardless of `enabled`).
+ writeFileSync(
+ join(dir, '.grok', 'config.toml'),
+ '[mcp_servers.ruflo]\ncommand = "node"\nargs = ["x"]\nenabled = false\n',
+ );
+ expect(runStatusline().loaded.mcp).toBe(false);
+ });
+
+ it('treats a ] inside a quoted trusted-folder key as part of the path (round-3 review)', () => {
+ executeGrokInit({ targetDir: dir, homeDir: home });
+ const weird = join(dir, 'a]b');
+ mkdirSync(weird, { recursive: true });
+ const root = realpathSync(weird);
+ mkdirSync(join(home, '.grok'), { recursive: true });
+ writeFileSync(join(home, '.grok', 'trusted_folders.toml'), `[folders."${root}"]\ntrusted = true\n`);
+ const r = spawnSync(process.execPath, [join(grokTemplatesRoot(), 'scripts', 'host-statusline.mjs'), '--json'], {
+ cwd: weird,
+ env: { ...process.env, HOME: home, USERPROFILE: home },
+ encoding: 'utf-8',
+ input: '',
+ });
+ expect(r.status, r.stderr).toBe(0);
+ expect(JSON.parse(r.stdout).loaded.trusted).toBe(true);
+ });
+
+ it('writes through a symlinked ~/.grok/config.toml instead of replacing it (round-2 review, minor item 1)', () => {
+ // A dotfiles-managed setup often symlinks ~/.grok/config.toml at a real
+ // file living elsewhere (e.g. a dotfiles repo checkout).
+ const realTarget = join(home, 'dotfiles-config.toml');
+ writeFileSync(realTarget, '# keep me\n[ui]\ntheme = "dark"\n');
+ mkdirSync(join(home, '.grok'), { recursive: true });
+ const symlinkPath = join(home, '.grok', 'config.toml');
+ symlinkSync(realTarget, symlinkPath);
+
+ const r = executeGrokInit({ targetDir: dir, homeDir: home, statusLine: true });
+ expect(r.success, r.errors.join('\n')).toBe(true);
+
+ // The symlink itself must survive, still pointing at the same target.
+ expect(lstatSync(symlinkPath).isSymbolicLink()).toBe(true);
+ expect(realpathSync(symlinkPath)).toBe(realpathSync(realTarget));
+
+ // The status row was written THROUGH the symlink, into the real file.
+ const written = readFileSync(realTarget, 'utf-8');
+ expect(written.startsWith('# keep me\n[ui]\ntheme = "dark"\n')).toBe(true);
+ const parsed = TOML.parse(written) as any;
+ expect(parsed.ui.status_line.command).toBe(grokStatusLineCommand(home));
+ });
+
+ it('rejects an existing user config with an unserializable value before writing anything (round-2 review, minor item 2)', () => {
+ mkdirSync(join(home, '.grok'), { recursive: true });
+ const dest = join(home, '.grok', 'config.toml');
+ // A TOML integer literal above 2^53 parses to a BigInt (@iarna/toml),
+ // which crashes JSON.stringify — previously discovered only as the LAST
+ // step of init, after project files were already written.
+ const original = '# keep me\ngiant = 99999999999999999999\n';
+ writeFileSync(dest, original);
+
+ const r = executeGrokInit({ targetDir: dir, homeDir: home, statusLine: true });
+ expect(r.success).toBe(false);
+ expect(r.errors.join('\n')).toMatch(/config\.toml/);
+ expect(r.errors.join('\n')).toMatch(/giant/);
+ expect(r.errors.join('\n')).toMatch(/BigInt|serialize/i);
+
+ // Nothing was written: not the user config, not a single project file.
+ expect(readFileSync(dest, 'utf-8')).toBe(original);
+ expect(r.filesCreated).toEqual([]);
+ expect(existsSync(join(dir, '.grok'))).toBe(false);
+ expect(readdirSync(dir)).toEqual([]);
+ });
+
+ it('keeps init working when a BigInt sits beside an existing status row (round-3 review)', () => {
+ mkdirSync(join(home, '.grok'), { recursive: true });
+ const dest = join(home, '.grok', 'config.toml');
+ // Nothing is serialized when the user already has [ui.status_line], so
+ // the integer must not fail the whole init.
+ const original = 'giant = 99999999999999999999\n[ui.status_line]\ntype = "command"\ncommand = "mine"\n';
+ writeFileSync(dest, original);
+
+ const r = executeGrokInit({ targetDir: dir, homeDir: home, statusLine: true });
+ expect(r.success, r.errors.join('\n')).toBe(true);
+ expect(r.userConfig.action).toBe('already-set');
+ expect(readFileSync(dest, 'utf-8')).toBe(original);
+ expect(existsSync(join(dir, '.grok', 'config.toml'))).toBe(true);
+ });
+
+ it('copies the scripts byte-for-byte from templates (no second copy to drift)', () => {
+ executeGrokInit({ targetDir: dir, homeDir: home });
+ for (const f of ['grok-team-bus.mjs', 'grok-team-store.mjs', 'grok-subagent-stop-hook.mjs', 'host-statusline.mjs']) {
+ expect(readFileSync(join(dir, 'scripts', f), 'utf-8')).toBe(
+ readFileSync(join(grokTemplatesRoot(), 'scripts', f), 'utf-8'),
+ );
+ }
+ });
+});
diff --git a/v3/@claude-flow/cli/__tests__/team-tools.test.ts b/v3/@claude-flow/cli/__tests__/team-tools.test.ts
new file mode 100644
index 0000000000..e42512a904
--- /dev/null
+++ b/v3/@claude-flow/cli/__tests__/team-tools.test.ts
@@ -0,0 +1,448 @@
+/**
+ * ADR-402 team_* MCP tools + the grok-team-bus.mjs CLI they share a store with.
+ * Regression coverage for the #3512 review (scoping, locking, lifecycle, hook).
+ */
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import fs, {
+ mkdtempSync,
+ rmSync,
+ existsSync,
+ readFileSync,
+ readdirSync,
+ mkdirSync,
+ symlinkSync,
+ utimesSync,
+ writeFileSync,
+} from 'node:fs';
+import { join, resolve } from 'node:path';
+import { tmpdir } from 'node:os';
+import { spawn } from 'node:child_process';
+import { pathToFileURL } from 'node:url';
+import { teamTools } from '../src/mcp-tools/team-tools.js';
+
+const STORE = join(resolve(__dirname, '..', 'templates', 'grok', 'scripts'), 'grok-team-store.mjs');
+
+const SCRIPTS = resolve(__dirname, '..', 'templates', 'grok', 'scripts');
+const BUS = join(SCRIPTS, 'grok-team-bus.mjs');
+const HOOK = join(SCRIPTS, 'grok-subagent-stop-hook.mjs');
+
+type Result = { success: boolean; error?: string } & Record<string, any>;
+
+function tool(name: string) {
+ const t = teamTools.find((x) => x.name === name);
+ if (!t) throw new Error(`missing tool ${name}`);
+ return (input: Record<string, unknown>) => t.handler(input) as Promise<Result>;
+}
+
+function runNode(
+ script: string,
+ args: string[],
+ opts: { cwd: string; stdin?: string; env?: Record<string, string> },
+): Promise<{ code: number; stdout: string; stderr: string }> {
+ return new Promise((done) => {
+ const child = spawn(process.execPath, [script, ...args], {
+ cwd: opts.cwd,
+ env: { ...process.env, CLAUDE_PROJECT_DIR: opts.cwd, TEAM_NAME: '', SUBAGENT_NAME: '', ...opts.env },
+ });
+ let stdout = '';
+ let stderr = '';
+ child.stdout.on('data', (c) => (stdout += c));
+ child.stderr.on('data', (c) => (stderr += c));
+ child.on('close', (code) => done({ code: code ?? 1, stdout, stderr }));
+ child.stdin.end(opts.stdin ?? '');
+ });
+}
+
+function readTeam(cwd: string, name: string) {
+ return JSON.parse(readFileSync(join(cwd, '.claude-flow', 'teams', name, 'team.json'), 'utf-8'));
+}
+
+describe('teamTools (ADR-402)', () => {
+ let cwd: string;
+ let prev: string | undefined;
+
+ beforeEach(() => {
+ cwd = mkdtempSync(join(tmpdir(), 'ruflo-team-'));
+ prev = process.env.CLAUDE_FLOW_CWD;
+ process.env.CLAUDE_FLOW_CWD = cwd;
+ });
+
+ afterEach(() => {
+ if (prev === undefined) delete process.env.CLAUDE_FLOW_CWD;
+ else process.env.CLAUDE_FLOW_CWD = prev;
+ rmSync(cwd, { recursive: true, force: true });
+ });
+
+ it('create → plan → spawn → send → inbox → on_stop → shutdown', async () => {
+ const create = await tool('team_create')({ name: 'demo', maxAgents: 4, host: 'grok' });
+ expect(create.success).toBe(true);
+ expect(existsSync(join(cwd, '.claude-flow', 'teams', 'demo', 'team.json'))).toBe(true);
+
+ expect((await tool('team_plan')({ team: 'demo', steps: ['architect', 'developer'] })).success).toBe(true);
+
+ const spawned = await tool('team_spawn')({
+ team: 'demo',
+ agent: 'architect',
+ role: 'architect',
+ prompt: 'Design the feature',
+ next: ['developer'],
+ });
+ expect(spawned.success).toBe(true);
+ const grok = spawned.spawnPlan.host.grok;
+ expect(Object.keys(grok.spawn).sort()).toEqual(['background', 'description', 'isolation']);
+ expect(grok.spawn).toEqual({ description: 'architect:architect@demo', background: true, isolation: 'none' });
+ expect(grok.advisory.capability_mode).toBe('read-only');
+
+ const send = await tool('team_send')({
+ team: 'demo',
+ to: 'developer',
+ from: 'architect',
+ summary: 'design',
+ message: 'Use layered architecture',
+ });
+ expect(send.success).toBe(true);
+
+ // Pre-spawn handoff: status counts developer's mailbox before registration
+ const early = await tool('team_status')({ team: 'demo' });
+ expect(early.pendingMail.developer).toBe(1);
+
+ await tool('team_spawn')({ team: 'demo', agent: 'developer', role: 'developer', prompt: 'Implement' });
+ const inbox = await tool('team_inbox')({ team: 'demo', agent: 'developer', peek: true });
+ expect(inbox.messages).toHaveLength(1);
+
+ const onStop = await tool('team_on_stop')({ team: 'demo', agent: 'architect' });
+ expect(onStop.assign.agent).toBe('developer');
+
+ expect((await tool('team_shutdown')({ team: 'demo' })).success).toBe(true);
+ expect(readTeam(cwd, 'demo').status).toBe('shutdown');
+ });
+
+ it('rejects invalid team names', async () => {
+ expect((await tool('team_create')({ name: '../evil' })).success).toBe(false);
+ expect((await tool('team_inbox')({ team: '../evil', agent: 'a' })).success).toBe(false);
+ });
+
+ it('scopes mailboxes and status to one team (review #3)', async () => {
+ await tool('team_create')({ name: 'alpha' });
+ await tool('team_create')({ name: 'beta' });
+ await tool('team_spawn')({ team: 'alpha', agent: 'coder' });
+ await tool('team_spawn')({ team: 'beta', agent: 'coder' });
+ await tool('team_send')({ team: 'alpha', to: 'coder', message: 'only for alpha' });
+
+ const beta = await tool('team_inbox')({ team: 'beta', agent: 'coder' });
+ expect(beta.success).toBe(true);
+ expect(beta.messages).toEqual([]);
+ expect((await tool('team_status')({ team: 'beta' })).pendingMail).toEqual({ coder: 0 });
+ expect((await tool('team_status')({ team: 'alpha' })).pendingMail).toEqual({ coder: 1 });
+
+ const alpha = await tool('team_inbox')({ team: 'alpha', agent: 'coder' });
+ expect(alpha.messages.map((m: { content: string }) => m.content)).toEqual(['only for alpha']);
+ expect((await tool('team_inbox')({ agent: 'coder' })).success).toBe(false); // team is required
+ });
+
+ it('registers all 30 members when spawns race across processes (review #4)', async () => {
+ await tool('team_create')({ name: 'race', maxAgents: 50 });
+ const cli = Array.from({ length: 15 }, (_, i) =>
+ runNode(BUS, ['spawn', '--root', cwd, '--team', 'race', '--agent', `cli-${i}`], { cwd }),
+ );
+ const mcp = Array.from({ length: 15 }, (_, i) => tool('team_spawn')({ team: 'race', agent: `mcp-${i}` }));
+ const results = await Promise.all([...cli, ...mcp]);
+ for (const r of results) {
+ if ('code' in r) expect(r.code, r.stdout + r.stderr).toBe(0);
+ else expect(r.success, r.error).toBe(true);
+ }
+ const team = readTeam(cwd, 'race');
+ expect(Object.keys(team.members)).toHaveLength(30);
+ expect(existsSync(join(cwd, '.claude-flow', 'teams', 'race', 'team.lock'))).toBe(false);
+ expect(readdirSync(join(cwd, '.claude-flow', 'teams', 'race')).filter((f) => f.endsWith('.tmp'))).toEqual([]);
+ }, 60_000);
+
+ it('breaks a stale lock left by a crashed holder, and releases its own', async () => {
+ await tool('team_create')({ name: 'stale' });
+ const lock = join(cwd, '.claude-flow', 'teams', 'stale', 'team.lock');
+ writeFileSync(lock, 'crashed-holder');
+ const old = new Date(Date.now() - 120_000);
+ utimesSync(lock, old, old);
+ expect((await tool('team_spawn')({ team: 'stale', agent: 'a' })).success).toBe(true);
+ expect(existsSync(lock)).toBe(false);
+ expect(readdirSync(join(cwd, '.claude-flow', 'teams', 'stale')).filter((f) => f.includes('.stale.'))).toEqual([]);
+ });
+
+ it('re-verifies a stale lock before breaking it, and never renames one that changed underneath it (review N2)', async () => {
+ // Reproduces the round-2 review's race: waiter W1 reads a stale lock's
+ // token; meanwhile another waiter breaks that same lock and a third
+ // party re-acquires a fresh, live one at the same path. A buggy
+ // breakStaleLock would rename that live lock away regardless (and, in a
+ // real multi-process run, risk a fourth party grabbing the vacated slot
+ // before it's put back — two holders at once). The fix re-verifies the
+ // token immediately before renaming and backs off if it changed.
+ await tool('team_create')({ name: 'race2' });
+ const dir = join(cwd, '.claude-flow', 'teams', 'race2');
+ const lock = join(dir, 'team.lock');
+ writeFileSync(lock, 'crashed-holder', { encoding: 'utf8' });
+ const old = new Date(Date.now() - 120_000);
+ utimesSync(lock, old, old);
+
+ const store: any = await import(pathToFileURL(STORE).href);
+
+ const realReadFileSync: any = fs.readFileSync;
+ const realRenameSync: any = fs.renameSync;
+ let renamed = false;
+ let triggered = false;
+ (fs as any).readFileSync = (...args: any[]) => {
+ const result = realReadFileSync(...args);
+ if (!triggered && args[0] === lock && result === 'crashed-holder') {
+ triggered = true;
+ // Simulate another waiter breaking this exact lock and a third
+ // party re-acquiring a fresh one, right after we read the stale
+ // token but before we act on it.
+ writeFileSync(lock, 'C-token', { encoding: 'utf8' });
+ const now = new Date();
+ utimesSync(lock, now, now);
+ }
+ return result;
+ };
+ (fs as any).renameSync = (...args: any[]) => {
+ renamed = true;
+ return realRenameSync(...args);
+ };
+
+ try {
+ store.breakStaleLock(lock, 'our-break-token');
+ } finally {
+ (fs as any).readFileSync = realReadFileSync;
+ (fs as any).renameSync = realRenameSync;
+ }
+
+ expect(triggered).toBe(true);
+ expect(renamed).toBe(false); // never touched the lock once it saw it had changed
+ expect(readFileSync(lock, 'utf8')).toBe('C-token'); // untouched, not clobbered/restored
+ expect(readdirSync(dir).filter((f) => f.includes('.stale.'))).toEqual([]);
+ });
+
+ it('does not break a stale lock whose holder pid is still alive (round-3 review)', async () => {
+ await tool('team_create')({ name: 'alive' });
+ const dir = join(cwd, '.claude-flow', 'teams', 'alive');
+ const lock = join(dir, 'team.lock');
+ const store: any = await import(pathToFileURL(STORE).href);
+ const live = `${process.pid}.${Date.now()}.live`;
+ writeFileSync(lock, live);
+ const old = new Date(Date.now() - 120_000);
+ utimesSync(lock, old, old);
+
+ store.breakStaleLock(lock, 'waiter-token');
+ expect(readFileSync(lock, 'utf8')).toBe(live);
+
+ const deadPid = 2 ** 22 + 12345;
+ writeFileSync(lock, `${deadPid}.${Date.now()}.dead`);
+ utimesSync(lock, old, old);
+ store.breakStaleLock(lock, 'waiter-token');
+ expect(existsSync(lock)).toBe(false);
+ expect(readdirSync(dir).filter((f) => f.includes('.stale.'))).toEqual([]);
+ });
+
+ it('breaks a stale lock safely with several real concurrent waiters, no lost updates (review N2/N3)', async () => {
+ await tool('team_create')({ name: 'race-stale', maxAgents: 10 });
+ const dir = join(cwd, '.claude-flow', 'teams', 'race-stale');
+ const lock = join(dir, 'team.lock');
+ writeFileSync(lock, 'crashed-holder', { encoding: 'utf8' });
+ const old = new Date(Date.now() - 120_000);
+ utimesSync(lock, old, old);
+
+ const results = await Promise.all(
+ Array.from({ length: 3 }, (_, i) =>
+ runNode(BUS, ['spawn', '--root', cwd, '--team', 'race-stale', '--agent', `w${i}`], { cwd }),
+ ),
+ );
+ for (const r of results) expect(r.code, r.stdout + r.stderr).toBe(0);
+
+ const team = readTeam(cwd, 'race-stale');
+ expect(Object.keys(team.members).sort()).toEqual(['w0', 'w1', 'w2']);
+ expect(existsSync(lock)).toBe(false);
+ expect(readdirSync(dir).filter((f) => f.includes('.stale.') || f.endsWith('.tmp'))).toEqual([]);
+ }, 30_000);
+
+ it('lock-wait timeout covers the stale window, so a wait never gives up before the lock could be broken (review N3)', async () => {
+ const store: any = await import(pathToFileURL(STORE).href);
+ // Import the same constants indirectly: a lock that just turned stale
+ // must still be breakable well within one wait attempt's own timeout —
+ // otherwise every spawn in the gap between "give up" and "now stale"
+ // fails even though nothing is actually stuck.
+ await tool('team_create')({ name: 'timing' });
+ const dir = join(cwd, '.claude-flow', 'teams', 'timing');
+ const lock = join(dir, 'team.lock');
+ writeFileSync(lock, 'crashed-holder', { encoding: 'utf8' });
+ // Just past the stale threshold used in grok-team-store.mjs (4s) — not
+ // past the wait timeout (4.5s), so this must succeed, not time out.
+ const justStale = new Date(Date.now() - 4_050);
+ utimesSync(lock, justStale, justStale);
+ const result = await store.withTeamLock(cwd, 'timing', () => 'held');
+ expect(result).toBe('held');
+ });
+
+ it('clears the old mailbox when force-recreating a team (review N4)', async () => {
+ await tool('team_create')({ name: 'reborn' });
+ await tool('team_spawn')({ team: 'reborn', agent: 'old-member' });
+ await tool('team_send')({ team: 'reborn', to: 'old-member', message: 'from the old incarnation' });
+ const mailbox = join(cwd, '.claude-flow', 'teams', 'reborn', 'mailbox');
+ expect(readdirSync(join(mailbox, 'old-member')).filter((f) => f.endsWith('.json'))).toHaveLength(1);
+
+ const recreated = await tool('team_create')({ name: 'reborn', force: true });
+ expect(recreated.success).toBe(true);
+ expect(existsSync(join(mailbox, 'old-member'))).toBe(false); // wiped, not carried over
+ expect(readTeam(cwd, 'reborn').members).toEqual({});
+
+ await tool('team_spawn')({ team: 'reborn', agent: 'new-member' });
+ expect((await tool('team_inbox')({ team: 'reborn', agent: 'new-member' })).messages).toEqual([]);
+ });
+
+ it('closes the team on shutdown and enforces maxAgents (review #8)', async () => {
+ await tool('team_create')({ name: 'small', maxAgents: 2 });
+ expect((await tool('team_spawn')({ team: 'small', agent: 'a' })).success).toBe(true);
+ expect((await tool('team_spawn')({ team: 'small', agent: 'b' })).success).toBe(true);
+ const full = await tool('team_spawn')({ team: 'small', agent: 'c' });
+ expect(full.success).toBe(false);
+ expect(full.error).toMatch(/full \(maxAgents=2\)/);
+ // Re-spawning an existing member is an update, not a new seat
+ expect((await tool('team_spawn')({ team: 'small', agent: 'a', prompt: 'again' })).success).toBe(true);
+
+ await tool('team_send')({ team: 'small', to: 'a', message: 'before close' });
+ await tool('team_shutdown')({ team: 'small' });
+ for (const [name, input] of [
+ ['team_spawn', { team: 'small', agent: 'd' }],
+ ['team_send', { team: 'small', to: 'a', message: 'after close' }],
+ ['team_broadcast', { team: 'small', message: 'after close' }],
+ ['team_plan', { team: 'small', steps: ['a'] }],
+ ] as const) {
+ const r = await tool(name)(input);
+ expect(r.success, name).toBe(false);
+ expect(r.error).toMatch(/is shutdown/);
+ }
+ // Remaining mail can still be drained
+ expect((await tool('team_inbox')({ team: 'small', agent: 'a' })).messages).toHaveLength(1);
+ });
+
+ it('rejects a broadcast with no members, delivers one with members (review minor)', async () => {
+ await tool('team_create')({ name: 'bc' });
+ const empty = await tool('team_broadcast')({ team: 'bc', message: 'anyone?' });
+ expect(empty.success).toBe(false);
+ expect(empty.error).toMatch(/no members/);
+ await tool('team_spawn')({ team: 'bc', agent: 'x' });
+ await tool('team_spawn')({ team: 'bc', agent: 'y' });
+ expect((await tool('team_broadcast')({ team: 'bc', message: 'hi all' })).recipients).toEqual(['x', 'y']);
+ expect((await tool('team_inbox')({ team: 'bc', agent: 'y' })).messages[0].type).toBe('broadcast');
+ });
+
+ it('validates priority and sorts numerically (review minor)', async () => {
+ await tool('team_create')({ name: 'prio' });
+ await tool('team_spawn')({ team: 'prio', agent: 'p' });
+ for (const bad of ['abc', -1, 1.5, 1000, '1e2', '0x10', '0o20', '0b101']) {
+ const r = await tool('team_send')({ team: 'prio', to: 'p', message: 'm', priority: bad });
+ expect(r.success, String(bad)).toBe(false);
+ expect(r.error).toMatch(/priority must be an integer/);
+ }
+ await tool('team_send')({ team: 'prio', to: 'p', message: 'ten', priority: 10 });
+ await tool('team_send')({ team: 'prio', to: 'p', message: 'two', priority: 2 });
+ await tool('team_send')({ team: 'prio', to: 'p', message: 'zero', priority: '0' });
+ const files = readdirSync(join(cwd, '.claude-flow', 'teams', 'prio', 'mailbox', 'p')).filter((f) => f.endsWith('.json'));
+ expect(files.every((f) => /^\d{3}_msg_/.test(f))).toBe(true);
+ const inbox = await tool('team_inbox')({ team: 'prio', agent: 'p' });
+ expect(inbox.messages.map((m: { content: string }) => m.content)).toEqual(['zero', 'two', 'ten']);
+ });
+
+ it('refuses a symlinked mailbox directory (review minor)', async () => {
+ await tool('team_create')({ name: 'sym' });
+ const outside = mkdtempSync(join(tmpdir(), 'ruflo-outside-'));
+ try {
+ const box = join(cwd, '.claude-flow', 'teams', 'sym', 'mailbox');
+ mkdirSync(box, { recursive: true });
+ symlinkSync(outside, join(box, 'victim'), 'dir');
+ const r = await tool('team_send')({ team: 'sym', to: 'victim', message: 'escape?' });
+ expect(r.success).toBe(false);
+ expect(r.error).toMatch(/not a real directory/);
+ expect(readdirSync(outside)).toEqual([]);
+ expect((await tool('team_inbox')({ team: 'sym', agent: 'victim' })).success).toBe(false);
+ } finally {
+ rmSync(outside, { recursive: true, force: true });
+ }
+ });
+
+ it('two concurrent drains split the mail without ENOENT (review minor)', async () => {
+ await tool('team_create')({ name: 'drain' });
+ await tool('team_spawn')({ team: 'drain', agent: 'd' });
+ for (let i = 0; i < 40; i++) {
+ await tool('team_send')({ team: 'drain', to: 'd', message: `m${i}` });
+ }
+ const [a, b] = await Promise.all([
+ runNode(BUS, ['inbox', '--root', cwd, '--team', 'drain', '--agent', 'd'], { cwd }),
+ runNode(BUS, ['inbox', '--root', cwd, '--team', 'drain', '--agent', 'd'], { cwd }),
+ ]);
+ expect(a.code, a.stdout).toBe(0);
+ expect(b.code, b.stdout).toBe(0);
+ const got = [...JSON.parse(a.stdout).messages, ...JSON.parse(b.stdout).messages].map((m) => m.content);
+ expect(got).toHaveLength(40);
+ expect(new Set(got).size).toBe(40);
+ }, 30_000);
+});
+
+describe('SubagentStop hook (review #5)', () => {
+ let cwd: string;
+ let prev: string | undefined;
+
+ beforeEach(() => {
+ cwd = mkdtempSync(join(tmpdir(), 'ruflo-hook-'));
+ prev = process.env.CLAUDE_FLOW_CWD;
+ process.env.CLAUDE_FLOW_CWD = cwd;
+ });
+
+ afterEach(() => {
+ if (prev === undefined) delete process.env.CLAUDE_FLOW_CWD;
+ else process.env.CLAUDE_FLOW_CWD = prev;
+ rmSync(cwd, { recursive: true, force: true });
+ });
+
+ it('advances the plan from the spawn description team_spawn returns', async () => {
+ await tool('team_create')({ name: 'pipe' });
+ await tool('team_plan')({ team: 'pipe', steps: ['alice', 'bob'] });
+ const plan = await tool('team_spawn')({ team: 'pipe', agent: 'alice', role: 'coder' });
+ const description = plan.spawnPlan.host.grok.spawn.description;
+ expect(description).toBe('coder:alice@pipe');
+
+ const r = await runNode(HOOK, [], { cwd, stdin: JSON.stringify({ description }) });
+ expect(r.code, r.stderr).toBe(0);
+ const team = readTeam(cwd, 'pipe');
+ expect(team.plan.steps.map((s: { status: string }) => s.status)).toEqual(['done', 'ready']);
+ expect(team.members.alice.status).toBe('idle');
+ });
+
+ it('ignores non-team subagents and reports failures on stderr', async () => {
+ await tool('team_create')({ name: 'one' });
+ await tool('team_create')({ name: 'two' });
+ await tool('team_spawn')({ team: 'one', agent: 'dup' });
+ await tool('team_spawn')({ team: 'two', agent: 'dup' });
+
+ const unrelated = await runNode(HOOK, [], { cwd, stdin: JSON.stringify({ description: 'Explore the repo for X' }) });
+ expect(unrelated.code).toBe(0);
+ expect(unrelated.stderr).toBe('');
+
+ const ambiguous = await runNode(HOOK, [], { cwd, stdin: JSON.stringify({ description: 'coder:dup' }) });
+ expect(ambiguous.code).toBe(1);
+ expect(ambiguous.stderr).toMatch(/several active teams \(one, two\)/);
+
+ const missing = await runNode(HOOK, [], { cwd, stdin: JSON.stringify({ description: 'coder:dup@nope' }) });
+ expect(missing.code).toBe(1);
+ expect(missing.stderr).toMatch(/Team "nope" not found/);
+ });
+
+ it('does not lose updates when hooks fire in parallel', async () => {
+ await tool('team_create')({ name: 'par', maxAgents: 20 });
+ const names = Array.from({ length: 12 }, (_, i) => `w${i}`);
+ for (const n of names) await tool('team_spawn')({ team: 'par', agent: n });
+ const runs = await Promise.all(
+ names.map((n) => runNode(HOOK, [], { cwd, stdin: JSON.stringify({ description: `coder:${n}@par` }) })),
+ );
+ for (const r of runs) expect(r.code, r.stderr).toBe(0);
+ const team = readTeam(cwd, 'par');
+ expect(names.every((n) => team.members[n].status === 'idle' && team.members[n].lastStopAt)).toBe(true);
+ }, 30_000);
+});
diff --git a/v3/@claude-flow/cli/package.json b/v3/@claude-flow/cli/package.json
index 593c345a62..f49c08187d 100644
--- a/v3/@claude-flow/cli/package.json
+++ b/v3/@claude-flow/cli/package.json
@@ -76,6 +76,7 @@
"!dist/**/*.tsbuildinfo",
"bin",
"scripts/postinstall.cjs",
+ "templates",
".claude",
"plugins",
"README.md",
diff --git a/v3/@claude-flow/cli/src/commands/init.ts b/v3/@claude-flow/cli/src/commands/init.ts
index 97e89c2aff..4b06936f60 100644
--- a/v3/@claude-flow/cli/src/commands/init.ts
+++ b/v3/@claude-flow/cli/src/commands/init.ts
@@ -18,6 +18,7 @@ import {
FULL_INIT_OPTIONS,
type InitOptions,
} from '../init/index.js';
+import { executeGrokInit } from '../init/grok-generator.js';
import {
ENROLLMENT_SCREEN,
recordEnrollmentOutcome,
@@ -392,6 +393,107 @@ async function maybeInstallSkillsSh(ctx: CommandContext): Promise<void> {
}
}
+// Grok Build host initialization (ADR-402)
+async function initGrokAction(
+ ctx: CommandContext,
+ options: { force: boolean; statusLine: boolean; dryRun: boolean }
+): Promise<CommandResult> {
+ const { force, statusLine, dryRun } = options;
+ output.writeln();
+ output.writeln(output.bold(dryRun ? 'Grok Build init (dry run — nothing is written)' : 'Initializing RuFlo for Grok Build'));
+ output.writeln();
+
+ try {
+ const result = executeGrokInit({
+ targetDir: ctx.cwd,
+ force,
+ docs: true,
+ statusLine,
+ dryRun,
+ });
+
+ if (!result.success) {
+ output.printError('Grok initialization failed');
+ for (const err of result.errors) {
+ output.printError(err);
+ }
+ return { success: false, exitCode: 1, message: 'Grok init failed' };
+ }
+
+ output.printBox(
+ [
+ `.grok/config.toml — project MCP (ruflo) + permissions`,
+ `.grok/rules/ruflo-grok.md — host doctrine / tool map`,
+ `.grok/agents/ — ruflo-architect/coder/tester/reviewer`,
+ `.grok/skills/ — agent-teams-grok`,
+ `.grok/hooks/ — SubagentStop advances the team plan`,
+ `scripts/grok-team-bus.mjs (+ grok-team-store.mjs) — ADR-402 team bus CLI`,
+ `scripts/host-statusline.mjs — "what is loaded" row`,
+ `docs/grok/README.md — operator guide`,
+ ].join('\n'),
+ 'Grok Build Integration (ADR-402)'
+ );
+ output.writeln();
+
+ const verb = dryRun ? 'Would write' : 'Wrote';
+ output.writeln(output.bold(`${verb} (${result.filesCreated.length}):`));
+ output.printList(result.filesCreated.map((f) => (path.relative(ctx.cwd, f).startsWith('..') ? f : path.relative(ctx.cwd, f))));
+ if (result.filesSkipped.length > 0) {
+ output.printInfo(`Skipped ${result.filesSkipped.length} existing file(s)${force ? '' : ' — use --force to overwrite'}`);
+ }
+ output.writeln();
+
+ const mcp = result.mcp;
+ output.printInfo(
+ mcp.source === 'published'
+ ? `MCP server pinned to ruflo@${mcp.version} (the release that ships the team_* tools)`
+ : `MCP server points at this checkout: ${mcp.args[0]} — rebuild it before use, and re-run init from a published release before committing .grok/config.toml`
+ );
+
+ const uc = result.userConfig;
+ if (uc.action === 'not-requested' || uc.action === 'snippet') {
+ output.writeln();
+ output.writeln(
+ uc.action === 'snippet'
+ ? output.bold(`Did not change ${uc.path}: ${uc.reason}`)
+ : output.bold('Optional status row (Grok reads it only from your user config):')
+ );
+ output.writeln(output.dim(` Add this to ${uc.path}, or re-run with --grok-statusline to have init merge it`));
+ output.writeln(output.dim(` (that also installs the script it runs under ~/.grok/ruflo/):`));
+ output.writeln(uc.snippet.trimEnd().split('\n').map((l) => ` ${l}`).join('\n'));
+ } else if (uc.action === 'already-set') {
+ output.printInfo(uc.reason || `${uc.path} already has the Ruflo status row; refreshed the script it runs`);
+ }
+
+ output.writeln();
+ output.writeln(output.bold('Next steps:'));
+ output.printList([
+ 'Trust this folder in Grok (/hooks-trust or grok --trust) so MCP, hooks, skills, and rules load together',
+ 'Restart Grok so .grok/config.toml is applied',
+ 'Read docs/grok/README.md — spawn contract checked on Grok Build 1.0.41',
+ 'Verify: grok mcp list && grok mcp doctor ruflo',
+ 'Optional: npx ruvnet-brain@latest then enable ruvnet-brain in .grok/config.toml',
+ 'Teams: team_create / team_spawn MCP tools (or node scripts/grok-team-bus.mjs)',
+ ]);
+ output.writeln();
+
+ return {
+ success: true,
+ data: {
+ adapter: 'grok',
+ dryRun,
+ filesCreated: result.filesCreated,
+ filesSkipped: result.filesSkipped,
+ mcp: result.mcp,
+ userConfig: { action: uc.action, path: uc.path },
+ },
+ };
+ } catch (e) {
+ output.printError(`Grok initialization failed: ${(e as Error).message}`);
+ return { success: false, exitCode: 1, message: (e as Error).message };
+ }
+}
+
// Codex initialization action
async function initCodexAction(
ctx: CommandContext,
@@ -941,6 +1043,16 @@ const initAction = async (ctx: CommandContext): Promise<CommandResult> => {
const full = ctx.flags.full as boolean;
const codexMode = ctx.flags.codex as boolean;
const dualMode = ctx.flags.dual as boolean;
+ const grokMode = ctx.flags.grok as boolean;
+
+ // Grok Build host (ADR-402) — separate surface under .grok/
+ if (grokMode) {
+ return initGrokAction(ctx, {
+ force,
+ statusLine: ctx.flags.grokStatusline === true || ctx.flags['grok-statusline'] === true,
+ dryRun: ctx.flags.dryRun === true || ctx.flags['dry-run'] === true,
+ });
+ }
if (codexMode && !dualMode) {
return initCodexAction(ctx, { codexMode, dualMode: false, force, minimal, full });
@@ -1767,6 +1879,24 @@ export const initCommand: Command = {
type: 'boolean',
default: false,
},
+ {
+ name: 'grok',
+ description: 'Initialize for Grok Build host (creates .grok/, team bus scripts, ADR-402 surface)',
+ type: 'boolean',
+ default: false,
+ },
+ {
+ name: 'grok-statusline',
+ description: 'With --grok: also merge the Ruflo status row into ~/.grok/config.toml (user file; off by default)',
+ type: 'boolean',
+ default: false,
+ },
+ {
+ name: 'dry-run',
+ description: 'With --grok: list the files init would write, write nothing',
+ type: 'boolean',
+ default: false,
+ },
{
name: 'dual',
description: 'Initialize for both Claude Code and OpenAI Codex',
@@ -1816,6 +1946,10 @@ export const initCommand: Command = {
{ command: 'claude-flow init upgrade --verbose', description: 'Show detailed upgrade info' },
{ command: 'claude-flow init --codex', description: 'Initialize for OpenAI Codex (AGENTS.md)' },
{ command: 'claude-flow init --codex --full', description: 'Codex init with all canonical packaged skills' },
+ { command: 'claude-flow init --grok', description: 'Initialize for Grok Build (.grok/, team bus, ADR-402)' },
+ { command: 'claude-flow init --grok --force', description: 'Overwrite existing Grok host files' },
+ { command: 'claude-flow init --grok --dry-run', description: 'Show what init --grok would write' },
+ { command: 'claude-flow init --grok --grok-statusline', description: 'Also add the Ruflo status row to ~/.grok/config.toml' },
{ command: 'claude-flow init --dual', description: 'Initialize for both Claude Code and Codex' },
{ command: 'claude-flow init --no-codex-detect', description: 'Skip auto-configuring OpenAI Codex even if it is installed' },
{ command: 'claude-flow init --no-skills-sh', description: 'Skip the post-init skills.sh registration' },
diff --git a/v3/@claude-flow/cli/src/init/grok-generator.ts b/v3/@claude-flow/cli/src/init/grok-generator.ts
new file mode 100644
index 0000000000..5743a9ed33
--- /dev/null
+++ b/v3/@claude-flow/cli/src/init/grok-generator.ts
@@ -0,0 +1,455 @@
+/**
+ * Grok Build host init (ADR-402).
+ *
+ * Mirrors `init --codex`: writes project-scoped `.grok/` surface + team bus scripts
+ * so any repo can run Ruflo Agent Teams under Grok without Claude SendMessage.
+ *
+ * Writes outside the project only with `statusLine: true` (`--grok-statusline`):
+ * the status row lives in the user's ~/.grok/config.toml, which is parsed and
+ * merged with a real TOML parser, never blindly appended to.
+ */
+
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import * as TOML from '@iarna/toml';
+import { grokPackageRoot, grokTemplatesRoot } from './grok-templates.js';
+
+export interface GrokInitOptions {
+ targetDir: string;
+ force?: boolean;
+ /** Also write docs/grok/README.md operator guide */
+ docs?: boolean;
+ /** Install the status row into the user's ~/.grok/config.toml (opt-in). */
+ statusLine?: boolean;
+ /** Report what would be written; write nothing. */
+ dryRun?: boolean;
+ /** Home directory for the user-level status row (tests). */
+ homeDir?: string;
+}
+
+export type GrokUserConfigAction =
+ | 'not-requested'
+ | 'created'
+ | 'merged'
+ | 'already-set'
+ | 'snippet'
+ | 'would-write';
+
+export interface GrokUserConfigResult {
+ action: GrokUserConfigAction;
+ /** ~/.grok/config.toml */
+ path: string;
+ /** TOML to paste when init did not write it */
+ snippet: string;
+ reason?: string;
+}
+
+export interface GrokMcpLaunch {
+ command: string;
+ args: string[];
+ /** published: pinned to this CLI's npm version; checkout: this local build */
+ source: 'published' | 'checkout';
+ version: string;
+}
+
+export interface GrokInitResult {
+ success: boolean;
+ dryRun: boolean;
+ /** Files written (or, in a dry run, that would be written) */
+ filesCreated: string[];
+ filesSkipped: string[];
+ errors: string[];
+ mcp: GrokMcpLaunch;
+ userConfig: GrokUserConfigResult;
+}
+
+export { grokTemplatesRoot };
+
+function packageVersion(root: string): string {
+ try {
+ return JSON.parse(fs.readFileSync(path.join(root, 'package.json'), 'utf-8')).version || '0.0.0';
+ } catch {
+ return '0.0.0';
+ }
+}
+
+/**
+ * How the project .grok/config.toml starts the Ruflo MCP server.
+ *
+ * The team_* tools ship in the same release as `init --grok`, so the server is
+ * pinned to the version that is running this init — never `@latest`, which can
+ * be an older release without them. Running from a source checkout (not under
+ * node_modules) points at that checkout's CLI, since its version may not be
+ * published yet.
+ */
+export function rufloMcpLaunch(root: string = grokPackageRoot()): GrokMcpLaunch {
+ const version = packageVersion(root);
+ const published = root.split(path.sep).includes('node_modules');
+ if (!published) {
+ return {
+ command: 'node',
+ args: [path.join(root, 'bin', 'cli.js'), 'mcp', 'start'],
+ source: 'checkout',
+ version,
+ };
+ }
+ const npxArgs = ['-y', `ruflo@${version}`, 'mcp', 'start'];
+ return process.platform === 'win32'
+ ? { command: 'cmd', args: ['/c', 'npx', ...npxArgs], source: 'published', version }
+ : { command: 'npx', args: npxArgs, source: 'published', version };
+}
+
+/** A TOML basic string. JSON escaping is a valid subset (\\, \", \uXXXX). */
+function tomlString(value: string): string {
+ return JSON.stringify(value);
+}
+
+/**
+ * Fill the template placeholders. Every inserted value is escaped as a TOML
+ * string, so a Windows path such as C:\Users\x stays valid TOML.
+ */
+export function materializeGrokConfig(template: string, launch: GrokMcpLaunch, home: string): string {
+ const homeInString = tomlString(home.replace(/[\\/]+$/, '')).slice(1, -1);
+ return template
+ .replaceAll('{{RUFLO_MCP_COMMAND}}', tomlString(launch.command))
+ .replaceAll('{{RUFLO_MCP_ARGS}}', `[${launch.args.map(tomlString).join(', ')}]`)
+ .replaceAll('{{HOME}}/', `${homeInString}/`);
+}
+
+// ---------------------------------------------------------------------------
+// User-level status row (~/.grok/config.toml [ui.status_line])
+// ---------------------------------------------------------------------------
+
+/** Where the opt-in status row script is installed: a stable absolute path. */
+export function grokStatusScriptPath(home: string): string {
+ return path.join(home, '.grok', 'ruflo', 'host-statusline.mjs');
+}
+
+/** `node "<abs path>"` — no shell builtins, and never a repo-relative script. */
+export function grokStatusLineCommand(home: string): string {
+ return `node "${grokStatusScriptPath(home)}"`;
+}
+
+export function grokStatusLineSnippet(home: string): string {
+ return TOML.stringify({
+ ui: { status_line: { type: 'command', command: grokStatusLineCommand(home) } },
+ } as TOML.JsonMap);
+}
+
+type MergeOutcome =
+ | { kind: 'write'; text: string }
+ | { kind: 'already-set'; ours: boolean }
+ | { kind: 'unsafe'; reason: string };
+
+function stableJson(value: unknown): string {
+ return JSON.stringify(value, (_k, v) =>
+ v && typeof v === 'object' && !Array.isArray(v) && !(v instanceof Date)
+ ? Object.fromEntries(Object.keys(v).sort().map((k) => [k, (v as Record<string, unknown>)[k]]))
+ : v,
+ );
+}
+
+function statusLineOf(doc: TOML.JsonMap): unknown {
+ const ui = doc.ui;
+ return ui && typeof ui === 'object' && !Array.isArray(ui) ? (ui as TOML.JsonMap).status_line : undefined;
+}
+
+/**
+ * Add the status row to an existing user config without disturbing it.
+ *
+ * Any existing `ui.status_line` — header, `[ ui.status_line ]`,
+ * `[ui."status_line"]`, dotted keys, or an inline table — is detected by
+ * parsing, and left alone. Otherwise the block is appended and the result is
+ * re-parsed: it is written only if it parses, carries exactly our status row,
+ * and every other value is unchanged. Anything else (unparseable file, `ui`
+ * as an inline table, …) falls back to printing the snippet.
+ */
+export function mergeGrokStatusLine(existing: string, home: string): MergeOutcome {
+ let before: TOML.JsonMap;
+ try {
+ before = TOML.parse(existing);
+ } catch (e) {
+ return { kind: 'unsafe', reason: `could not parse it as TOML (${(e as Error).message.split('\n')[0]})` };
+ }
+ const current = statusLineOf(before);
+ if (current !== undefined) {
+ const command = current && typeof current === 'object' ? (current as TOML.JsonMap).command : undefined;
+ return { kind: 'already-set', ours: command === grokStatusLineCommand(home) };
+ }
+
+ const sep = existing.length === 0 || existing.endsWith('\n') ? '' : '\n';
+ const text = `${existing}${sep}\n# Ruflo loaded-status row (added by ruflo init --grok --grok-statusline)\n${grokStatusLineSnippet(home)}`;
+ let after: TOML.JsonMap;
+ try {
+ after = TOML.parse(text);
+ } catch (e) {
+ return { kind: 'unsafe', reason: `appending [ui.status_line] would not parse (${(e as Error).message.split('\n')[0]})` };
+ }
+ const added = statusLineOf(after) as TOML.JsonMap | undefined;
+ if (!added || added.type !== 'command' || added.command !== grokStatusLineCommand(home)) {
+ return { kind: 'unsafe', reason: 'the merged file did not contain the expected status row' };
+ }
+ const ui = after.ui as TOML.JsonMap;
+ delete ui.status_line;
+ if (before.ui === undefined && Object.keys(ui).length === 0) delete after.ui;
+ if (stableJson(after) !== stableJson(before)) {
+ return { kind: 'unsafe', reason: 'the merge would change other settings' };
+ }
+ return { kind: 'write', text };
+}
+
+/**
+ * If `file` is a symlink, resolve it to what it actually points at. A rename
+ * onto a symlink path replaces the symlink itself with a plain file — in a
+ * dotfiles-managed setup where `~/.grok/config.toml` is a symlink, that
+ * silently destroys the symlink instead of updating the file it points to
+ * (ADR-402 round-2 review, minor item 1). A broken symlink (target missing)
+ * falls back to writing `file` itself, same as a plain non-existent path.
+ */
+function resolveWriteTarget(file: string): string {
+ try {
+ if (fs.lstatSync(file).isSymbolicLink()) {
+ return fs.realpathSync(file);
+ }
+ } catch {
+ /* missing, unreadable, or a broken symlink target: write `file` itself */
+ }
+ return file;
+}
+
+function writeFileAtomic(file: string, text: string, mode?: number): void {
+ const target = resolveWriteTarget(file);
+ fs.mkdirSync(path.dirname(target), { recursive: true });
+ const tmp = `${target}.${process.pid}.${Date.now()}.tmp`;
+ fs.writeFileSync(tmp, text, { encoding: 'utf-8', mode: mode ?? 0o600 });
+ fs.renameSync(tmp, target);
+}
+
+function wireGrokUserStatusLine(
+ home: string,
+ dryRun: boolean,
+ created: string[],
+ errors: string[],
+): GrokUserConfigResult {
+ const dest = path.join(home, '.grok', 'config.toml');
+ const snippet = grokStatusLineSnippet(home);
+ const script = grokStatusScriptPath(home);
+ const result = (action: GrokUserConfigAction, reason?: string): GrokUserConfigResult => ({
+ action,
+ path: dest,
+ snippet,
+ reason,
+ });
+
+ let existing: string | null = null;
+ try {
+ existing = fs.existsSync(dest) ? fs.readFileSync(dest, 'utf-8') : null;
+ } catch (e) {
+ return result('snippet', `could not read ${dest}: ${(e as Error).message}`);
+ }
+ const outcome: MergeOutcome = existing === null
+ ? { kind: 'write', text: `# Ruflo loaded-status row (added by ruflo init --grok --grok-statusline)\n${snippet}` }
+ : mergeGrokStatusLine(existing, home);
+ if (outcome.kind === 'unsafe') return result('snippet', `${dest}: ${outcome.reason}`);
+
+ if (outcome.kind === 'already-set' && !outcome.ours) {
+ return result('already-set', `${dest} already has its own [ui.status_line]; left it and did not install the Ruflo script`);
+ }
+ // Ours, or about to be ours: install/refresh the script it runs.
+ const needsConfig = outcome.kind === 'write';
+ if (dryRun) {
+ created.push(script);
+ if (needsConfig) created.push(dest);
+ return result(needsConfig ? 'would-write' : 'already-set');
+ }
+ try {
+ const src = path.join(grokTemplatesRoot(), 'scripts', 'host-statusline.mjs');
+ writeFileAtomic(script, fs.readFileSync(src, 'utf-8'), 0o755);
+ created.push(script);
+ if (!needsConfig) return result('already-set');
+ writeFileAtomic(dest, outcome.text);
+ created.push(dest);
+ return result(existing === null ? 'created' : 'merged');
+ } catch (e) {
+ errors.push(`${dest}: ${(e as Error).message}`);
+ return result('snippet', (e as Error).message);
+ }
+}
+
+// ---------------------------------------------------------------------------
+// Project files
+// ---------------------------------------------------------------------------
+
+interface CopyContext {
+ force: boolean;
+ dryRun: boolean;
+ created: string[];
+ skipped: string[];
+ errors: string[];
+}
+
+/** First `object.key` (or `[index]`) path to a BigInt value, or null. */
+function findBigIntKeyPath(value: unknown, path: string[] = []): string | null {
+ if (typeof value === 'bigint') return path.length ? path.join('.') : '(root)';
+ if (Array.isArray(value)) {
+ for (let i = 0; i < value.length; i++) {
+ const found = findBigIntKeyPath(value[i], [...path, `[${i}]`]);
+ if (found) return found;
+ }
+ return null;
+ }
+ if (value && typeof value === 'object' && !(value instanceof Date)) {
+ for (const [k, v] of Object.entries(value as Record<string, unknown>)) {
+ const found = findBigIntKeyPath(v, [...path, k]);
+ if (found) return found;
+ }
+ }
+ return null;
+}
+
+/**
+ * Whether an existing `~/.grok/config.toml` can be safely parsed and
+ * serialized before init touches anything. A TOML integer literal above
+ * 2^53 parses to a BigInt (@iarna/toml), and `JSON.stringify` — used by
+ * `mergeGrokStatusLine`'s stableJson comparison — throws "Do not know how
+ * to serialize a BigInt" on it. That merge used to run as the LAST step of
+ * `executeGrokInit`, so the crash left project files already written and
+ * nothing to show for the failure. Checked here, first, so init either
+ * fully succeeds or writes nothing at all (ADR-402 round-2 review, minor
+ * item 2). Returns a user-facing error message naming the offending key,
+ * or null if the file is fine (or absent, or already unparseable as
+ * TOML — mergeGrokStatusLine reports that case on its own, safely).
+ */
+function validateExistingUserConfig(dest: string): string | null {
+ let existing: string;
+ try {
+ if (!fs.existsSync(dest)) return null;
+ existing = fs.readFileSync(dest, 'utf-8');
+ } catch (e) {
+ return `could not read ${dest}: ${(e as Error).message}`;
+ }
+ let doc: TOML.JsonMap;
+ try {
+ doc = TOML.parse(existing);
+ } catch {
+ return null;
+ }
+ // An existing status row is left as-is, so nothing in this file is
+ // serialized. A BigInt elsewhere must not fail init in that case
+ // (ADR-402 round-3 review). The status step reports already-set.
+ if (statusLineOf(doc) !== undefined) return null;
+ try {
+ JSON.stringify(doc);
+ } catch (e) {
+ const offending = findBigIntKeyPath(doc);
+ const where = offending ? ` at "${offending}"` : '';
+ return `${dest} has a value ruflo cannot serialize${where} (${(e as Error).message}) — fix or remove it before running init --grok --grok-statusline again`;
+ }
+ return null;
+}
+
+function writeProjectFile(ctx: CopyContext, dest: string, write: () => void): void {
+ try {
+ if (fs.existsSync(dest) && !ctx.force) {
+ ctx.skipped.push(dest);
+ return;
+ }
+ if (!ctx.dryRun) {
+ fs.mkdirSync(path.dirname(dest), { recursive: true });
+ write();
+ }
+ ctx.created.push(dest);
+ } catch (e) {
+ ctx.errors.push(`${dest}: ${(e as Error).message}`);
+ }
+}
+
+function copyFile(ctx: CopyContext, src: string, dest: string): void {
+ writeProjectFile(ctx, dest, () => {
+ fs.copyFileSync(src, dest);
+ fs.chmodSync(dest, fs.statSync(src).mode);
+ });
+}
+
+function walkCopy(ctx: CopyContext, srcDir: string, destDir: string): void {
+ if (!fs.existsSync(srcDir)) {
+ ctx.errors.push(`Template directory missing: ${srcDir}`);
+ return;
+ }
+ for (const ent of fs.readdirSync(srcDir, { withFileTypes: true })) {
+ const src = path.join(srcDir, ent.name);
+ const dest = path.join(destDir, ent.name);
+ if (ent.isDirectory()) walkCopy(ctx, src, dest);
+ else copyFile(ctx, src, dest);
+ }
+}
+
+/**
+ * Initialize Grok host surface in targetDir.
+ */
+export function executeGrokInit(options: GrokInitOptions): GrokInitResult {
+ const { targetDir, force = false, docs = true, statusLine = false, dryRun = false } = options;
+ const home = options.homeDir || os.homedir();
+ const ctx: CopyContext = { force, dryRun, created: [], skipped: [], errors: [] };
+ const tpl = grokTemplatesRoot();
+ const mcp = rufloMcpLaunch();
+ const userConfig: GrokUserConfigResult = {
+ action: 'not-requested',
+ path: path.join(home, '.grok', 'config.toml'),
+ snippet: grokStatusLineSnippet(home),
+ };
+ const done = (): GrokInitResult => ({
+ success: ctx.errors.length === 0,
+ dryRun,
+ filesCreated: ctx.created,
+ filesSkipped: ctx.skipped,
+ errors: ctx.errors,
+ mcp,
+ userConfig,
+ });
+
+ if (!fs.existsSync(path.join(tpl, 'config.toml'))) {
+ ctx.errors.push(
+ `Grok templates not found at ${tpl}. Reinstall @claude-flow/cli or run from a monorepo checkout that includes templates/grok.`,
+ );
+ return done();
+ }
+
+ // Validate any existing user-level config before writing a single project
+ // file — see validateExistingUserConfig for why (BigInt/serialization
+ // failures must not leave a half-initialized project).
+ if (statusLine) {
+ const problem = validateExistingUserConfig(userConfig.path);
+ if (problem) {
+ ctx.errors.push(problem);
+ return done();
+ }
+ }
+
+ // .grok/config.toml — placeholders filled, then checked with a TOML parser
+ const config = materializeGrokConfig(fs.readFileSync(path.join(tpl, 'config.toml'), 'utf-8'), mcp, home);
+ try {
+ TOML.parse(config);
+ } catch (e) {
+ ctx.errors.push(`.grok/config.toml would not be valid TOML: ${(e as Error).message.split('\n')[0]}`);
+ return done();
+ }
+ writeProjectFile(ctx, path.join(targetDir, '.grok', 'config.toml'), () =>
+ fs.writeFileSync(path.join(targetDir, '.grok', 'config.toml'), config, 'utf-8'),
+ );
+
+ for (const dir of ['rules', 'agents', 'hooks', 'skills']) {
+ walkCopy(ctx, path.join(tpl, dir), path.join(targetDir, '.grok', dir));
+ }
+ // scripts/ team bus (project-local CLI + SubagentStop adapter + status row)
+ walkCopy(ctx, path.join(tpl, 'scripts'), path.join(targetDir, 'scripts'));
+ if (docs) {
+ walkCopy(ctx, path.join(tpl, 'docs'), path.join(targetDir, 'docs', 'grok'));
+ }
+
+ if (statusLine) {
+ Object.assign(userConfig, wireGrokUserStatusLine(home, dryRun, ctx.created, ctx.errors));
+ }
+ return done();
+}
diff --git a/v3/@claude-flow/cli/src/init/grok-templates.ts b/v3/@claude-flow/cli/src/init/grok-templates.ts
new file mode 100644
index 0000000000..b0752a29c0
--- /dev/null
+++ b/v3/@claude-flow/cli/src/init/grok-templates.ts
@@ -0,0 +1,30 @@
+/**
+ * Where the Grok host templates live (ADR-402).
+ *
+ * Kept apart from grok-generator.ts so the team_* MCP tools can find the team
+ * bus scripts without loading the TOML parser on every MCP client import.
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+/** Root of the installed @claude-flow/cli package (the one holding templates/grok). */
+export function grokPackageRoot(): string {
+ const here = path.dirname(fileURLToPath(import.meta.url));
+ const candidates = [
+ path.resolve(here, '../../..'), // dist/src/init → package root
+ path.resolve(here, '../..'), // src/init → package root
+ ];
+ for (const c of candidates) {
+ if (fs.existsSync(path.join(c, 'templates', 'grok', 'config.toml'))) {
+ return c;
+ }
+ }
+ return candidates[0];
+}
+
+/** templates/grok inside the installed @claude-flow/cli package. */
+export function grokTemplatesRoot(): string {
+ return path.join(grokPackageRoot(), 'templates', 'grok');
+}
diff --git a/v3/@claude-flow/cli/src/init/index.ts b/v3/@claude-flow/cli/src/init/index.ts
index 9d2c2d91f5..1ae4436133 100644
--- a/v3/@claude-flow/cli/src/init/index.ts
+++ b/v3/@claude-flow/cli/src/init/index.ts
@@ -61,3 +61,7 @@ export {
// Main executor
export { executeInit, executeUpgrade, executeUpgradeWithMissing, default } from './executor.js';
export type { UpgradeResult } from './executor.js';
+
+// Grok Build host (ADR-402)
+export { executeGrokInit } from './grok-generator.js';
+export type { GrokInitOptions, GrokInitResult } from './grok-generator.js';
diff --git a/v3/@claude-flow/cli/src/mcp-client.ts b/v3/@claude-flow/cli/src/mcp-client.ts
index ef9d011a87..c3f91d5365 100644
--- a/v3/@claude-flow/cli/src/mcp-client.ts
+++ b/v3/@claude-flow/cli/src/mcp-client.ts
@@ -79,6 +79,8 @@ import { businessPodTools } from './mcp-tools/business-pod-tools.js';
// + auth headers; opt-in via CLAUDE_FLOW_HTTP_FETCH_ALLOW_PRIVATE / _AUTH=1.
import { httpFetchTools } from './mcp-tools/http-fetch-tools.js';
import { missionTools } from './mcp-tools/mission-tools.js';
+// ADR-402 — host-agnostic Agent Teams bus (team_create/send/inbox/spawn/…)
+import { teamTools } from './mcp-tools/team-tools.js';
// #1916: coverage-aware routing tools — defined in ruvector/coverage-tools.ts
// but were never registered, so the `ruflo hooks coverage-*` CLI subcommands
// failed with `Tool not found: hooks_coverage-route`.
@@ -194,6 +196,8 @@ registerTools([
...httpFetchTools,
// ADR-406 — mission semantic operations (create/plan/get/events/request_action)
...missionTools,
+ // ADR-402 — host-agnostic Agent Teams (9 tools)
+ ...teamTools,
]);
// The capability brain consumes the completed live registry. This is injected
diff --git a/v3/@claude-flow/cli/src/mcp-tools/capability-brain.ts b/v3/@claude-flow/cli/src/mcp-tools/capability-brain.ts
index 7ceb215ec4..fb019e0033 100644
--- a/v3/@claude-flow/cli/src/mcp-tools/capability-brain.ts
+++ b/v3/@claude-flow/cli/src/mcp-tools/capability-brain.ts
@@ -403,9 +403,10 @@ export const CAPABILITY_DOMAINS: readonly CapabilityDomainDefinition[] = [
{
id: 'swarm-coordination',
name: 'Swarm & Coordination',
- prefixes: ['swarm_', 'coordination_', 'daa_'],
+ // team_: host-agnostic Agent Teams bus (ADR-402)
+ prefixes: ['swarm_', 'coordination_', 'daa_', 'team_'],
description: 'Topology-aware multi-agent coordination, task ownership, and collective scheduling.',
- taskSignals: ['swarm', 'concurrent', 'parallel', 'coordinate', 'multi-agent'],
+ taskSignals: ['swarm', 'concurrent', 'parallel', 'coordinate', 'multi-agent', 'agent team'],
commands: ['swarm init', 'swarm status', 'swarm coordinate'],
skills: ['swarm-orchestration', 'swarm-advanced'],
agents: ['coordinator', 'coder', 'tester', 'reviewer'],
@@ -680,6 +681,7 @@ const TOOL_OWNERSHIP: ReadonlyArray<{
{ prefixes: ['guidance_'], packageOwner: '@claude-flow/guidance', pluginOwner: 'ruflo-core' },
{ prefixes: ['seraphina_'], packageOwner: '@claude-flow/cli', pluginOwner: 'ruflo-core' },
{ prefixes: ['x_federation_'], packageOwner: '@claude-flow/cli', pluginOwner: 'ruflo-x-gateway' },
+ { prefixes: ['team_'], packageOwner: '@claude-flow/cli' },
] as const;
function ownershipForTool(
diff --git a/v3/@claude-flow/cli/src/mcp-tools/index.ts b/v3/@claude-flow/cli/src/mcp-tools/index.ts
index d5a9c86b03..d8caf952b7 100644
--- a/v3/@claude-flow/cli/src/mcp-tools/index.ts
+++ b/v3/@claude-flow/cli/src/mcp-tools/index.ts
@@ -70,3 +70,5 @@ export { businessPodTools } from './business-pod-tools.js';
export { httpFetchTools } from './http-fetch-tools.js';
// ADR-406 — mission semantic operations
export { missionTools, createMissionTools } from './mission-tools.js';
+// ADR-402 — host-agnostic Agent Teams bus
+export { teamTools } from './team-tools.js';
diff --git a/v3/@claude-flow/cli/src/mcp-tools/team-tools.ts b/v3/@claude-flow/cli/src/mcp-tools/team-tools.ts
new file mode 100644
index 0000000000..98702b659d
--- /dev/null
+++ b/v3/@claude-flow/cli/src/mcp-tools/team-tools.ts
@@ -0,0 +1,274 @@
+/**
+ * Host-agnostic Agent Teams MCP tools (ADR-402).
+ *
+ * Comms live in Ruflo (filesystem under .claude-flow/teams/), not host
+ * SendMessage. team_spawn returns a host spawn plan (Grok spawn_subagent /
+ * Claude Task adapter).
+ *
+ * The store itself is templates/grok/scripts/grok-team-bus.mjs — the same file
+ * `init --grok` copies into a project as a CLI — so the MCP tools, the CLI and
+ * the SubagentStop hook share one implementation (locking, per-team mailboxes,
+ * atomic writes). This module validates MCP input and maps errors to results.
+ */
+
+import { join } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { type MCPTool, getProjectCwd } from './types.js';
+import { validateText } from './validate-input.js';
+import { grokTemplatesRoot } from '../init/grok-templates.js';
+
+type BusResult = Record<string, unknown>;
+type BusOp = (projectRoot: string, opts: Record<string, unknown>) => BusResult | Promise<BusResult>;
+
+interface TeamBus {
+ createTeam: BusOp;
+ spawnMember: BusOp;
+ sendMessage: BusOp;
+ readInbox: BusOp;
+ teamStatus: BusOp;
+ setPlan: BusOp;
+ onStop: BusOp;
+ shutdownTeam: BusOp;
+}
+
+let busPromise: Promise<TeamBus> | null = null;
+
+function loadBus(): Promise<TeamBus> {
+ if (!busPromise) {
+ const file = join(grokTemplatesRoot(), 'scripts', 'grok-team-bus.mjs');
+ busPromise = import(pathToFileURL(file).href) as Promise<TeamBus>;
+ busPromise.catch(() => {
+ busPromise = null;
+ });
+ }
+ return busPromise;
+}
+
+async function run(
+ op: keyof TeamBus,
+ opts: Record<string, unknown>,
+): Promise<{ success: boolean } & Record<string, unknown>> {
+ try {
+ const bus = await loadBus();
+ // Some ops (create/spawn/send) hold the team lock, which now waits via a
+ // non-blocking async poll rather than Atomics.wait (ADR-402 round-2
+ // review, N3) — always await, whether or not this particular op returns
+ // a promise.
+ return { success: true, ...(await bus[op](getProjectCwd(), opts)) };
+ } catch (e) {
+ return { success: false, error: (e as Error).message || String(e) };
+ }
+}
+
+function textError(value: unknown, field: string, max: number): string | null {
+ if (value === undefined || value === null) return null;
+ const v = validateText(String(value), field, max);
+ return v.valid ? null : v.error || `Invalid ${field}`;
+}
+
+const teamProp = { type: 'string', description: 'Team id (alphanumeric, dash, underscore)' };
+
+export const teamTools: MCPTool[] = [
+ {
+ name: 'team_create',
+ description:
+ 'Create a host-agnostic Agent Team (ADR-402). State under .claude-flow/teams/<team>/. Use when native SendMessage/Task teammate bus is wrong or unavailable (Grok, Codex, multi-host). Pair with team_spawn for spawn plans and team_send/team_inbox for handoffs.',
+ category: 'team',
+ inputSchema: {
+ type: 'object',
+ properties: {
+ name: teamProp,
+ topology: {
+ type: 'string',
+ description: 'Team topology (hierarchical, mesh, star, ring)',
+ },
+ maxAgents: { type: 'number', description: 'Max members (1-50, default 8); team_spawn refuses beyond it' },
+ host: { type: 'string', description: 'Host label (grok, claude, codex)' },
+ force: { type: 'boolean', description: 'Overwrite existing team metadata (reopens a shut-down team)' },
+ },
+ required: ['name'],
+ },
+ handler: async (input) =>
+ run('createTeam', {
+ name: input.name,
+ topology: input.topology,
+ maxAgents: input.maxAgents,
+ host: input.host,
+ force: input.force === true,
+ }),
+ },
+ {
+ name: 'team_spawn',
+ description:
+ 'Register a teammate and return a host spawn plan (Grok spawn_subagent / Claude Task adapter) — does not execute the agent. Use when native Task has no way to register a teammate into the host-agnostic team roster (ADR-402); the host lead still spawns using the returned plan. Refused once the team is shut down or has maxAgents members. Pair with team_create first.',
+ category: 'team',
+ inputSchema: {
+ type: 'object',
+ properties: {
+ team: teamProp,
+ agent: { type: 'string', description: 'Agent name' },
+ role: { type: 'string', description: 'Role (architect, developer, tester, reviewer, …)' },
+ prompt: { type: 'string', description: 'Task body embedded in spawn plan prompt' },
+ next: {
+ type: 'array',
+ description: 'Next agent name(s) for handoff',
+ items: { type: 'string' },
+ },
+ },
+ required: ['team', 'agent'],
+ },
+ handler: async (input) => {
+ const err = textError(input.prompt, 'prompt', 100_000);
+ if (err) return { success: false, error: err };
+ return run('spawnMember', {
+ team: input.team,
+ agent: input.agent,
+ role: input.role,
+ prompt: input.prompt,
+ next: input.next,
+ });
+ },
+ },
+ {
+ name: 'team_send',
+ description:
+ 'Enqueue a message to a named agent mailbox on one team (or broadcast to every member with to="*"). Use when native SendMessage is wrong because the recipient may be on a different host (Grok, Codex) with no SendMessage equivalent — the message persists under .claude-flow/teams/<team>/mailbox/ instead of an in-memory channel. Pair with team_inbox to read it. Refused once the team is shut down.',
+ category: 'team',
+ inputSchema: {
+ type: 'object',
+ properties: {
+ team: teamProp,
+ to: { type: 'string', description: 'Recipient agent name, or * to broadcast to current members' },
+ message: { type: 'string', description: 'Message body' },
+ summary: { type: 'string', description: 'Short summary' },
+ from: { type: 'string', description: 'Sender name (default: lead)' },
+ type: { type: 'string', description: 'Message type (handoff, status, …)' },
+ priority: { type: 'number', description: 'Integer 0-999, lower is read first (default 2)' },
+ },
+ required: ['team', 'to', 'message'],
+ },
+ handler: async (input) => {
+ const err =
+ textError(input.message ?? input.content, 'message', 500_000) ||
+ textError(input.summary, 'summary', 1_000) ||
+ textError(input.type, 'type', 64);
+ if (err) return { success: false, error: err };
+ return run('sendMessage', {
+ team: input.team,
+ to: input.to,
+ message: input.message ?? input.content,
+ summary: input.summary,
+ from: input.from,
+ type: input.type,
+ priority: input.priority,
+ });
+ },
+ },
+ {
+ name: 'team_inbox',
+ description:
+ 'Drain (default) or peek one agent\'s mailbox on one team. Drained messages move to mailbox/<agent>/archive; concurrent drains never return the same message twice. Use when native SendMessage is wrong because there is no host-agnostic inbox to read from — this is the Grok/Codex-side counterpart to team_send for hosts without a live message channel.',
+ category: 'team',
+ inputSchema: {
+ type: 'object',
+ properties: {
+ team: teamProp,
+ agent: { type: 'string', description: 'Agent name whose inbox to read' },
+ peek: { type: 'boolean', description: 'If true, do not archive/drain messages' },
+ },
+ required: ['team', 'agent'],
+ },
+ handler: async (input) =>
+ run('readInbox', { team: input.team, agent: input.agent, peek: input.peek === true }),
+ },
+ {
+ name: 'team_broadcast',
+ description:
+ 'Fan-out a message to all registered members of one team (alias of team_send with to="*"; refused while the team has no members). Use when native SendMessage is wrong because it can\'t reach every teammate on a non-Claude host in one call; each recipient reads back via team_inbox on its own host.',
+ category: 'team',
+ inputSchema: {
+ type: 'object',
+ properties: {
+ team: teamProp,
+ message: { type: 'string', description: 'Message body' },
+ summary: { type: 'string', description: 'Short summary' },
+ from: { type: 'string', description: 'Sender (default: lead)' },
+ },
+ required: ['team', 'message'],
+ },
+ handler: async (input) => {
+ const send = teamTools.find((t) => t.name === 'team_send');
+ if (!send) return { success: false, error: 'team_send not registered' };
+ return send.handler({
+ team: input.team,
+ to: '*',
+ message: input.message,
+ summary: input.summary,
+ from: input.from,
+ type: 'broadcast',
+ });
+ },
+ },
+ {
+ name: 'team_plan',
+ description:
+ 'Set pipeline steps for a team (ordered agents); the first step becomes ready. Use when native TodoWrite is wrong because it can\'t drive multi-host agent sequencing — this pipeline advances via team_on_stop instead of a single host\'s task list.',
+ category: 'team',
+ inputSchema: {
+ type: 'object',
+ properties: {
+ team: teamProp,
+ steps: {
+ type: 'array',
+ description: 'Ordered agent names or {id,agent} objects',
+ items: {},
+ },
+ },
+ required: ['team', 'steps'],
+ },
+ handler: async (input) => run('setPlan', { team: input.team, steps: input.steps }),
+ },
+ {
+ name: 'team_status',
+ description:
+ 'Team members, plan progress, and pending mailbox counts for this team only. Use when native Task is wrong because it has no cross-host visibility into a team\'s roster or pipeline state — reads the same .claude-flow/teams/ state that team_plan and team_send write.',
+ category: 'team',
+ inputSchema: {
+ type: 'object',
+ properties: {
+ team: teamProp,
+ },
+ required: ['team'],
+ },
+ handler: async (input) => run('teamStatus', { team: input.team }),
+ },
+ {
+ name: 'team_on_stop',
+ description:
+ 'Mark agent idle, advance the team_plan pipeline, and return the next assignment hint. Use when native Task has no cross-host equivalent to SubagentStop-driven pipeline advancement; wire this from SubagentStop / post-task hooks instead of polling team_status.',
+ category: 'team',
+ inputSchema: {
+ type: 'object',
+ properties: {
+ team: teamProp,
+ agent: { type: 'string', description: 'Agent that stopped' },
+ },
+ required: ['team', 'agent'],
+ },
+ handler: async (input) => run('onStop', { team: input.team, agent: input.agent }),
+ },
+ {
+ name: 'team_shutdown',
+ description:
+ 'Close a team: marks it and its members shutdown, after which team_spawn, team_send, team_plan and team_on_stop refuse (team_inbox and team_status still work, to drain remaining mail). Use when native Task is wrong because it has no host-agnostic team lifecycle to close out.',
+ category: 'team',
+ inputSchema: {
+ type: 'object',
+ properties: {
+ team: teamProp,
+ },
+ required: ['team'],
+ },
+ handler: async (input) => run('shutdownTeam', { team: input.team }),
+ },
+];
diff --git a/v3/@claude-flow/cli/templates/grok/agents/ruflo-architect.md b/v3/@claude-flow/cli/templates/grok/agents/ruflo-architect.md
new file mode 100644
index 0000000000..4886cd36c6
--- /dev/null
+++ b/v3/@claude-flow/cli/templates/grok/agents/ruflo-architect.md
@@ -0,0 +1,35 @@
+---
+name: ruflo-architect
+description: >
+ Ruflo swarm architect for Grok. Designs implementation blueprints, ADRs, and
+ file-level plans. Use for multi-file features before coding. Read-only by default;
+ hand off to ruflo-coder via team bus.
+prompt_mode: full
+permission_mode: plan
+agents_md: true
+---
+
+You are the **architect** on a Ruflo Agent Team running under **Grok Build**.
+
+This file is a session profile (`grok --agent-profile ruflo-architect` or `/agents`). On Grok Build 1.0.41, `spawn_subagent` does not select it. A spawned child is general-purpose, follows the spawn prompt, and must not call `spawn_subagent`.
+
+## Comms protocol (mandatory)
+
+- There is **no** Claude `SendMessage` tool.
+- At start, drain your inbox:
+ `node scripts/grok-team-bus.mjs inbox --team <TEAM> --agent architect`
+- When design is ready, hand off:
+ `node scripts/grok-team-bus.mjs send --team <TEAM> --to developer --from architect --summary "design-ready" --message "<paths + decisions>"`
+- Prefer storing durable design under memory namespace `team:<TEAM>` when Ruflo MCP is available.
+
+## Deliverable
+
+Produce a decisive blueprint:
+
+1. Patterns found (file:line)
+2. Chosen architecture + trade-offs
+3. Files to create/modify
+4. Build sequence for developer → tester → reviewer
+5. Risks / security notes
+
+Do **not** implement code. Do not wait for Ruflo to execute — you design; the lead/developer executes.
diff --git a/v3/@claude-flow/cli/templates/grok/agents/ruflo-coder.md b/v3/@claude-flow/cli/templates/grok/agents/ruflo-coder.md
new file mode 100644
index 0000000000..5a919c3a02
--- /dev/null
+++ b/v3/@claude-flow/cli/templates/grok/agents/ruflo-coder.md
@@ -0,0 +1,34 @@
+---
+name: ruflo-coder
+description: >
+ Ruflo implementation agent for Grok. Writes production code from architect designs.
+ Prefer isolation=worktree when spawned. Handoffs via team bus, not SendMessage.
+prompt_mode: full
+agents_md: true
+---
+
+You are the **developer/coder** on a Ruflo Agent Team under **Grok Build**.
+
+This file is a session profile (`grok --agent-profile ruflo-coder` or `/agents`). On Grok Build 1.0.41, `spawn_subagent` does not select it. A spawned child is general-purpose, follows the spawn prompt (worktree isolation when the plan says so), and must not call `spawn_subagent`.
+
+## Comms protocol (mandatory)
+
+- No Claude `SendMessage`.
+- Start: `node scripts/grok-team-bus.mjs inbox --team <TEAM> --agent developer`
+- If architect design is in the inbox or memory `team:<TEAM>`, follow it.
+- When implementation is ready:
+ `node scripts/grok-team-bus.mjs send --team <TEAM> --to tester --from developer --summary "impl-ready" --message "<files changed + how to test>"`
+- On stop: `node scripts/grok-team-bus.mjs on-stop --team <TEAM> --agent developer`
+
+## Rules
+
+- Prefer editing existing files; keep changes focused.
+- Match project conventions (Claude.md / Agents.md / ADRs).
+- Run available unit tests for touched areas when practical.
+- If using a git worktree, leave a clear summary of the worktree path and branch for the lead to merge.
+
+## Anti-patterns
+
+- Waiting after `swarm_init` for code to appear by magic
+- Inventing Claude Task / SendMessage APIs
+- Parallel uncoordinated edits outside your worktree
diff --git a/v3/@claude-flow/cli/templates/grok/agents/ruflo-reviewer.md b/v3/@claude-flow/cli/templates/grok/agents/ruflo-reviewer.md
new file mode 100644
index 0000000000..36f597251a
--- /dev/null
+++ b/v3/@claude-flow/cli/templates/grok/agents/ruflo-reviewer.md
@@ -0,0 +1,30 @@
+---
+name: ruflo-reviewer
+description: >
+ Ruflo code review agent for Grok. Reviews quality, security, and test evidence.
+ Read-oriented; reports findings to the team lead via team bus.
+prompt_mode: full
+permission_mode: plan
+agents_md: true
+---
+
+You are the **reviewer** on a Ruflo Agent Team under **Grok Build**.
+
+This file is a session profile (`grok --agent-profile ruflo-reviewer` or `/agents`). On Grok Build 1.0.41, `spawn_subagent` does not select it. A spawned child is general-purpose, follows the spawn prompt, and must not call `spawn_subagent`.
+
+## Comms protocol
+
+- Inbox: `node scripts/grok-team-bus.mjs inbox --team <TEAM> --agent reviewer`
+- Final report to lead:
+ `node scripts/grok-team-bus.mjs send --team <TEAM> --to lead --from reviewer --summary "review-complete" --message "<findings>"`
+ (If `lead` mailbox is unused, print the full review as your final response for the parent session.)
+- `node scripts/grok-team-bus.mjs on-stop --team <TEAM> --agent reviewer`
+
+## Review focus
+
+1. Correctness vs design handoff
+2. Security (injection, secrets, path traversal)
+3. Test evidence quality
+4. Maintainability / ADR alignment
+
+Severity: blocker / major / minor / nit. Blockers must be explicit.
diff --git a/v3/@claude-flow/cli/templates/grok/agents/ruflo-tester.md b/v3/@claude-flow/cli/templates/grok/agents/ruflo-tester.md
new file mode 100644
index 0000000000..ed82f64c8d
--- /dev/null
+++ b/v3/@claude-flow/cli/templates/grok/agents/ruflo-tester.md
@@ -0,0 +1,26 @@
+---
+name: ruflo-tester
+description: >
+ Ruflo tester for Grok. Writes and runs tests from implementation handoffs.
+ Use worktree isolation when modifying the tree. Reports to reviewer via team bus.
+prompt_mode: full
+agents_md: true
+---
+
+You are the **tester** on a Ruflo Agent Team under **Grok Build**.
+
+This file is a session profile (`grok --agent-profile ruflo-tester` or `/agents`). On Grok Build 1.0.41, `spawn_subagent` does not select it. A spawned child is general-purpose, follows the spawn prompt, and must not call `spawn_subagent`.
+
+## Comms protocol
+
+- Inbox: `node scripts/grok-team-bus.mjs inbox --team <TEAM> --agent tester`
+- After tests:
+ `node scripts/grok-team-bus.mjs send --team <TEAM> --to reviewer --from tester --summary "tests-ready" --message "<commands, pass/fail, coverage gaps>"`
+- `node scripts/grok-team-bus.mjs on-stop --team <TEAM> --agent tester`
+
+## Deliverable
+
+- Test plan + implemented tests
+- Exact commands to run
+- Failures with file:line
+- Gaps you did not cover
diff --git a/v3/@claude-flow/cli/templates/grok/config.toml b/v3/@claude-flow/cli/templates/grok/config.toml
new file mode 100644
index 0000000000..c8a26cfe3d
--- /dev/null
+++ b/v3/@claude-flow/cli/templates/grok/config.toml
@@ -0,0 +1,63 @@
+# Ruflo on Grok Build — project-scoped host config
+# Loaded by Grok when this folder is trusted (see ~/.grok/trusted_folders.toml).
+#
+# Goal: full harness (MCP + hooks + skills + agent teams path), not a thin CLI wrapper.
+# See: .grok/rules/ruflo-grok.md and v3/docs/adr/ADR-402-host-agnostic-agent-teams.md
+#
+# After editing: restart Grok (or reload MCPs) so tool lists refresh.
+
+# ---------------------------------------------------------------------------
+# Ruflo MCP — orchestrator / ledger (memory, swarm, hooks, team bus, neural)
+# `ruflo init --grok` pins this to the Ruflo version that ran it, because the
+# team_* tools ship in that same release (an older @latest may lack them).
+# From a source checkout it points at that checkout's bin/cli.js instead.
+# Cold npx can exceed 30s; keep timeouts high.
+# ---------------------------------------------------------------------------
+[mcp_servers.ruflo]
+command = {{RUFLO_MCP_COMMAND}}
+args = {{RUFLO_MCP_ARGS}}
+enabled = true
+startup_timeout_sec = 120
+tool_timeout_sec = 180
+
+# ---------------------------------------------------------------------------
+# Optional: RuvNet Brain grounding (search_ruvnet over embedded rUv source)
+# Install: npx ruvnet-brain@latest → kb under ~/.cache/ruvnet-brain/kb
+#
+# forge-mcp-all defaults KB_DIR to process.cwd(). When Grok spawns MCP from the
+# project root, search fails with "passages sidecar not found: ./agentdb…".
+# Always set env.KB_DIR to the absolute kb path. tool_timeout_sec high for cold
+# BGE model download (first big search can take minutes).
+# init --grok fills in your home directory for the {{HOME}} paths below.
+# ---------------------------------------------------------------------------
+# [mcp_servers.ruvnet-brain]
+# command = "node"
+# args = ["{{HOME}}/.cache/ruvnet-brain/kb/forge-mcp-all.mjs"]
+# env = { KB_DIR = "{{HOME}}/.cache/ruvnet-brain/kb" }
+# enabled = true
+# startup_timeout_sec = 90
+# tool_timeout_sec = 600
+
+# ---------------------------------------------------------------------------
+# Permissions — allow Ruflo CLI + helpers without re-prompting every turn
+# (deny still wins over allow; PreToolUse hooks can still block)
+# ---------------------------------------------------------------------------
+[permission]
+allow = [
+ "Bash(npx ruflo*)",
+ "Bash(npx @claude-flow*)",
+ "Bash(npx claude-flow*)",
+ "Bash(node .claude/*)",
+ "Bash(npx -y ruflo*)",
+ "Bash(node scripts/grok-team-bus.mjs*)",
+ "MCPTool(ruflo__*)",
+ "MCPTool(ruvnet-brain__*)",
+]
+
+# ---------------------------------------------------------------------------
+# Subagent defaults are user-level on Grok Build 1.0.41.
+# Project .grok/config.toml contributes only [mcp_servers], [plugins],
+# [permission], and [mcp].max_output_bytes. A [subagents] table here is ignored.
+# Put role defaults in ~/.grok/config.toml if you need them.
+# Team children: pass host.grok.spawn from team_spawn (see docs/grok/README.md).
+# ---------------------------------------------------------------------------
diff --git a/v3/@claude-flow/cli/templates/grok/docs/README.md b/v3/@claude-flow/cli/templates/grok/docs/README.md
new file mode 100644
index 0000000000..e7f915b857
--- /dev/null
+++ b/v3/@claude-flow/cli/templates/grok/docs/README.md
@@ -0,0 +1,186 @@
+# Ruflo on Grok Build
+
+How to run Ruflo inside [Grok Build](https://x.ai/) after `npx ruflo init --grok`.
+
+**Host contract checked against Grok Build 1.0.41** (`grok 1.0.41`, macOS, 2026-09-27) and the user guide shipped with that binary (`~/.grok/docs/user-guide/`). Newer Grok builds change spawn arguments and which keys a project config may set. Run the check in [When Grok updates](#when-grok-updates) before treating this page as current.
+
+Ruflo is the ledger: memory, swarm records, the team bus, hooks. Grok is the executor: it edits files, runs the shell, and calls `spawn_subagent`. After `team_create` or `swarm_init`, keep working. Those calls record coordination. They do not write the feature.
+
+## What `init --grok` writes
+
+| Path | Purpose |
+|------|---------|
+| `.grok/config.toml` | Project MCP server `ruflo` and permission allows |
+| `.grok/rules/ruflo-grok.md` | Host doctrine loaded as a project rule |
+| `.grok/agents/` | Session profiles (`ruflo-architect`, `ruflo-coder`, `ruflo-tester`, `ruflo-reviewer`) |
+| `.grok/skills/agent-teams-grok/` | Skill the lead follows to spawn a pipeline |
+| `.grok/hooks/subagent-stop-team.json` | `SubagentStop` → team bus idle-assign |
+| `scripts/grok-team-bus.mjs`, `scripts/grok-team-store.mjs` | Team bus CLI (same store as the MCP `team_*` tools) |
+| `scripts/grok-subagent-stop-hook.mjs` | Hook script: advances the plan when a teammate stops |
+| `scripts/host-statusline.mjs` | The "what is loaded" line (see Loaded status) |
+| `docs/grok/README.md` | This guide |
+
+## Setup
+
+From the app you want Grok to work in (any repo, not only the Ruflo monorepo):
+
+```bash
+npx -y ruflo@latest init --grok
+# see what it would write, write nothing:
+# npx -y ruflo@latest init --grok --dry-run
+# overwrite an earlier scaffold:
+# npx -y ruflo@latest init --grok --force
+```
+
+`init --grok` writes only inside this project, and prints every path it wrote. It pins `[mcp_servers.ruflo]` to the Ruflo version that ran it (for example `[email protected]`), because the `team_*` tools ship in that same release and an older `@latest` from a stale npx cache would lack them. Run from a Ruflo source checkout, it points the server at that checkout's `bin/cli.js` instead; re-run it from a published release before you commit `.grok/config.toml`.
+
+Then:
+
+1. Trust the folder. `/hooks-trust`, or launch with `grok --trust`. On 1.0.41 one grant covers project MCP, hooks, skills, and project rules together. The decision is stored in `~/.grok/trusted_folders.toml`.
+2. Restart Grok with this folder as the workspace so `.grok/config.toml` loads.
+3. Confirm the server:
+
+```bash
+grok mcp list # ruflo (project)
+grok mcp doctor ruflo # handshake ok; team_create present once this build is the server
+```
+
+`init` writes the MCP block itself. To register by hand, scope it to the project. The default scope is your user config (`~/.grok/config.toml`), which would install Ruflo for every repo:
+
+```bash
+grok mcp add ruflo --scope project -- npx -y ruflo@<version> mcp start
+```
+
+Use a version that ships `team_*` (the one `init --grok` pinned). `-s project` is the same flag. Cold `npx` often exceeds the 30s default startup timeout; the scaffold sets `startup_timeout_sec = 120`.
+
+## Use it in a session
+
+Grok does not put each Ruflo tool on the model as its own function. The model has `search_tool` and `use_tool`.
+
+1. `search_tool` with a keyword (`team_create`, `memory_search`, `swarm_init`).
+2. `use_tool` with the catalog key: `ruflo__team_create`, `ruflo__memory_search`.
+3. Stay on a small subset. A full Ruflo server exposes hundreds of tools; keyword search is how the model reaches them.
+
+MCP parameter names on the team tools are `team` and `agent`.
+
+### Agent teams
+
+```
+team_create → team_plan → team_spawn → spawn_subagent → team_send / team_inbox → team_on_stop → team_shutdown
+```
+
+`team_spawn` returns a plan. The lead calls `spawn_subagent` with the top-level `prompt` and **only** `host.grok.spawn`:
+
+```text
+spawn_subagent({
+ prompt: spawnPlan.prompt,
+ description: spawnPlan.host.grok.spawn.description,
+ background: spawnPlan.host.grok.spawn.background,
+ isolation: spawnPlan.host.grok.spawn.isolation
+})
+```
+
+`host.grok.advisory.capability_mode` and `subagent_type` describe the role. They are not arguments of `spawn_subagent` on 1.0.41. Passing them fails the call. The child is `general-purpose`. The prompt states the read-only constraint. `isolation: "worktree"` is the setting Grok enforces, and it is how writers avoid editing the lead's tree.
+
+Only the lead spawns. A child that calls `spawn_subagent` hits the depth limit (1).
+
+Pass `description` through unchanged. It is `<role>:<agent>@<team>`, and the `SubagentStop` hook parses it to mark that agent idle and advance that team's plan. If a description has no `@team`, the hook uses the one active team that lists the agent; when several do, it advances nothing and says so on stderr.
+
+How the bus behaves:
+
+- State and mail live in `.claude-flow/teams/<team>/` (`team.json`, `mailbox/<agent>/`). Mail is per team: `team_inbox` needs `team` and `agent`, and `team_status` counts only that team's mail.
+- `team.json` changes take a lock and are written to a temp file and renamed, so parallel spawns and hooks do not drop updates.
+- `team_spawn` refuses once the team has `maxAgents` members (re-spawning an existing member is fine).
+- `team_shutdown` closes the team: spawn, send, broadcast, plan, and on-stop refuse afterwards. `team_inbox` and `team_status` still work so remaining mail can be drained. `team_create --force` reopens the name.
+- A broadcast (`to: "*"`) goes to current members and is refused while the team has none.
+- `priority` is an integer 0-999; lower is read first.
+- Several teams can be active at once; every call names its team.
+
+`.grok/agents/ruflo-coder.md` and the other profiles apply when you start Grok as that agent (`grok --agent-profile ruflo-coder` or `/agents`). Spawn does not select them.
+
+CLI bus, same plan shape, no MCP required:
+
+```bash
+node scripts/grok-team-bus.mjs create --name feature-x --topology hierarchical
+node scripts/grok-team-bus.mjs plan --team feature-x \
+ --steps '["architect","developer","tester","reviewer"]'
+node scripts/grok-team-bus.mjs spawn --team feature-x --agent architect --role architect \
+ --prompt "Design the feature." --next developer
+```
+
+Map the printed `spawnPlan.host.grok.spawn` the same way. Skill: `agent-teams-grok`.
+
+### What the project config loads
+
+On 1.0.41, `.grok/config.toml` contributes:
+
+- `[mcp_servers]`
+- `[plugins]`
+- `[permission]`
+- `[mcp].max_output_bytes`
+
+Other tables, including `[subagents]`, are read from `~/.grok/config.toml` only. The scaffold used to write `[subagents] enabled = true` into the project file. That key does nothing there. Subagents are on by default.
+
+Permission allows in the scaffold use Grok's native forms, `Bash(...)` and `MCPTool(ruflo__*)`. Deny still beats allow.
+
+### Hooks
+
+`.grok/hooks/subagent-stop-team.json` runs on `SubagentStop` and calls `scripts/grok-subagent-stop-hook.mjs`. It runs only after the folder is trusted. `$CLAUDE_PROJECT_DIR` is set (alias of `GROK_WORKSPACE_ROOT`).
+
+`UserPromptSubmit` hooks that allow the prompt do not inject stdout into the model on 1.0.41. If a route hook seems to vanish, read `.swarm/route-latest.md` or call the route tool. That is a host limit, not a missing Ruflo file.
+
+## Loaded status
+
+`scripts/host-statusline.mjs` is the shared "what loaded" line: `RuFlo loaded │ ruflo │ rules │ 4 agents │ skill │ hook │ trusted`, or the names of what is missing. Claude shows its own richer `statusLine`. Codex has no status row; `node scripts/host-statusline.mjs --host codex` prints the same facts.
+
+Grok reads `[ui.status_line]` only from your user file, `~/.grok/config.toml`; a project config cannot set it. `init --grok` does not touch that file unless you ask. It prints the snippet to add, or with `--grok-statusline` it:
+
+- copies the script to `~/.grok/ruflo/host-statusline.mjs`, and
+- merges this into `~/.grok/config.toml` (parsed with a TOML parser; an existing `ui.status_line` in any form is left alone, and a file it cannot merge safely is not changed — you get the snippet instead):
+
+```toml
+[ui.status_line]
+type = "command"
+command = 'node "/home/you/.grok/ruflo/host-statusline.mjs"'
+```
+
+The command is an absolute path to your own copy, so no repo can substitute a script of its own. It reports on whichever folder Grok is in. Restart Grok after the user file changes.
+
+## Prove it
+
+From a Ruflo checkout (this script is not copied by `init --grok`; run `init --grok` in the checkout first):
+
+```bash
+node scripts/probe-host-live.mjs --host grok
+node scripts/probe-host-live.mjs --host all --no-execute
+node scripts/probe-host-live.mjs --host grok --live
+```
+
+One contract (discover, connect, SessionStart receipt, optional memory round trip) with a Grok, Claude, or Codex adapter. A check that CLI cannot answer is a skip, not a pass.
+
+## When Grok updates
+
+The July 2026 host work assumed Grok 1.0.34 and a spawn schema that accepted `subagent_type` and `capability_mode`. 1.0.41 dropped both from the model-facing tool and stopped applying `[subagents]` from project config. The same class of drift will happen again.
+
+After `grok --version` changes:
+
+1. Open `~/.grok/docs/user-guide/16-subagents.md` and read **Spawning Subagents**. The parameter table is the contract. Forward a key only if it is listed.
+2. Open `26-config-reference.md` and confirm which sections a project `.grok/config.toml` may set (1.0.41: mcp servers, plugins, permission, mcp output cap).
+3. Open `07-mcp-servers.md` and confirm `grok mcp add --scope` still defaults to `user`, and that tools are still `search_tool` / `use_tool` with `server__tool` names.
+4. Open `10-hooks.md` and confirm `SubagentStop`, folder trust, and `$CLAUDE_PROJECT_DIR`.
+5. Open `22-permissions-and-safety.md` and confirm `MCPTool(server__tool)` and `Bash(...)` still match the allows in `.grok/config.toml`.
+6. Spawn once with `host.grok.spawn` only. If the tool rejects `background`, the user guide's name for that flag is `run_in_background` — use the name the live schema accepts.
+7. Update the `contract` string in `team_spawn` / `scripts/grok-team-bus.mjs` and this page to the version you just checked.
+
+`grok inspect` shows which rules, skills, and MCP servers the trusted folder actually loaded.
+
+## Optional
+
+```bash
+npx -y ruflo@latest daemon start
+npx -y ruflo@latest doctor
+```
+
+RuvNet Brain is off in the scaffold. Uncomment `[mcp_servers.ruvnet-brain]` in `.grok/config.toml` after `npx ruvnet-brain@latest`, and set `env.KB_DIR` to the absolute `~/.cache/ruvnet-brain/kb` path. `init --grok` fills in your home directory for those paths when it creates the file.
+
+Architecture: ADR-402 (Host-Agnostic Agent Teams), in the Ruflo repo at `v3/docs/adr/ADR-402-host-agnostic-agent-teams.md`.
diff --git a/v3/@claude-flow/cli/templates/grok/hooks/subagent-stop-team.json b/v3/@claude-flow/cli/templates/grok/hooks/subagent-stop-team.json
new file mode 100644
index 0000000000..0e5a75ff11
--- /dev/null
+++ b/v3/@claude-flow/cli/templates/grok/hooks/subagent-stop-team.json
@@ -0,0 +1,15 @@
+{
+ "hooks": {
+ "SubagentStop": [
+ {
+ "hooks": [
+ {
+ "type": "command",
+ "command": "node \"$CLAUDE_PROJECT_DIR/scripts/grok-subagent-stop-hook.mjs\"",
+ "timeout": 5
+ }
+ ]
+ }
+ ]
+ }
+}
diff --git a/v3/@claude-flow/cli/templates/grok/rules/ruflo-grok.md b/v3/@claude-flow/cli/templates/grok/rules/ruflo-grok.md
new file mode 100644
index 0000000000..0857f4f4d4
--- /dev/null
+++ b/v3/@claude-flow/cli/templates/grok/rules/ruflo-grok.md
@@ -0,0 +1,132 @@
+# Ruflo on Grok — host doctrine
+
+You are running **inside Grok Build**, not Claude Code. Ruflo is the harness (orchestrator/ledger). **You** execute.
+
+## Division of labor
+
+| Layer | Role |
+|-------|------|
+| **Grok** | Executor — edit files, shell, tests, `spawn_subagent`, synthesize |
+| **Ruflo MCP/CLI** | Orchestrator — memory, swarm records, team bus, learning, security hooks |
+
+After any `swarm_init` / `team_create` / `agent_spawn` / MCP coordination call: **immediately continue working**. Never wait for Ruflo to “build the feature.” It does not execute code.
+
+## Tool map (Claude / CLAUDE.md → Grok)
+
+| Claude / CLAUDE.md | Grok |
+|--------------------|------|
+| `Task(...)` / Agent Teams spawn | `spawn_subagent` (`background: true` for parallel) |
+| `SendMessage` | Ruflo MCP `team_send` / `team_inbox` (host-agnostic bus) — until available: AgentDB memory namespace `team:{id}` or `collaboration` |
+| `TodoWrite` | `todo_write` |
+| `Bash` | `run_terminal_command` |
+| `Read` / `Grep` / `Glob` | `read_file` / `grep` / `list_dir` |
+| `Write` / `Edit` / `MultiEdit` | `write` / `search_replace` |
+| `claude -p` workers | `spawn_subagent` or `grok -p` |
+| `mcp__claude-flow__*` / `mcp__ruflo__*` | `search_tool` then `use_tool` with `ruflo__*` names |
+| Haiku / Sonnet / Opus routing | Ignore Anthropic tiers; use Grok models / subagent `model` only when needed |
+
+## MCP usage
+
+1. Discover: `search_tool` with keywords (`memory_search`, `swarm_init`, `team_`, `hooks`).
+2. Call: `use_tool` with the fully-qualified name (e.g. `ruflo__memory_search`).
+3. Prefer memory + team/swarm subset over flooding with all 300+ tools.
+
+## Before complex work (mandatory)
+
+1. `memory_search` (namespace `patterns` when available) for similar past solutions.
+2. If RuvNet Brain / `search_ruvnet` is available: ground stack choices in real rUv source **before** recommending Pinecone, pgvector, LangChain, or other training-prior defaults.
+3. For multi-file / multi-role work: open a **named team** pipeline (see Agent Teams below).
+
+## After success (mandatory)
+
+Store what worked via `memory_store` (namespace `patterns`): approach, files, gotchas, commands.
+
+## Agent Teams on Grok (comms-first)
+
+Named agents coordinate via the **Ruflo team bus** (MCP), not proprietary Claude `SendMessage`.
+
+### Preferred pipeline
+
+```
+lead (you)
+ → spawn named subagents in ONE turn (background: true)
+ → each agent handoff via team_send / memory key
+ → SubagentStop / you assign next step
+ → lead synthesizes
+```
+
+### Spawn contract (Grok Build 1.0.41)
+
+`spawn_subagent` takes `prompt`, `description`, `background`, `isolation`, and optionally `cwd`, `resume_from`, and `model`. It does not take `subagent_type` or `capability_mode`. An omitted type is `general-purpose`. Nesting depth is 1, so only the lead spawns.
+
+`team_spawn` returns `host.grok.spawn` for those arguments and `host.grok.advisory` for the role constraint. Pass `spawn` plus `prompt`. The prompt tells a read-only role not to edit. `isolation: "worktree"` is what Grok enforces for writers.
+
+`.grok/agents/ruflo-*` are session profiles (`grok --agent-profile` or `/agents`). They are not spawn types.
+
+Project `.grok/config.toml` contributes `[mcp_servers]`, `[plugins]`, `[permission]`, and `[mcp].max_output_bytes`. A `[subagents]` table in that file is ignored. Subagent defaults belong in `~/.grok/config.toml`.
+
+Operator guide: `docs/grok/README.md`. If `grok --version` moves past 1.0.41, re-check `~/.grok/docs/user-guide/16-subagents.md` and `26-config-reference.md` before forwarding new spawn keys.
+
+### Defaults
+
+| Role | Prompt constraint | `isolation` |
+|------|-------------------|-------------|
+| researcher / architect / reviewer | read-only | `none` |
+| coder / implementer | full tools | **`worktree`** |
+| tester | full tools | **`worktree`** when writing tests |
+
+- Always pass a clear **name/role** in the prompt (“You are architect on team feature-x”).
+- Tell each agent **who to message next** and **what artifact to produce**.
+- Prefer short cycles with verification gates over one giant agent.
+- Hierarchical topology for coding swarms; max ~6–8 concurrent workers.
+
+### Spawn pattern (all in one message)
+
+```
+spawn_subagent({ prompt, description, background: true, isolation: "none" })
+ architect → team_send to developer
+spawn_subagent({ ..., isolation: "worktree" })
+ developer → tester → reviewer (reviewer isolation "none")
+```
+
+Use MCP team tools or memory handoffs. There is no `SendMessage` tool.
+
+## Skills
+
+- Prefer project skills under `.agents/skills/` and `.claude/skills/`.
+- High-value first: swarm-orchestration, memory-management, sparc-methodology, security-audit, github-automation, hive-mind.
+- Load a skill when the task matches its description; don’t dump all 100+ into context.
+
+## Hooks (already in `.claude/settings.json`)
+
+Grok loads Claude-compatible hooks when the folder is trusted. Expect:
+
+- SessionStart: session restore + memory import
+- UserPromptSubmit: route / intelligence context
+- PreToolUse Bash: pre-bash safety
+- PostToolUse edits: post-edit learning
+- SubagentStop: post-task / idle assign
+
+If route context does not appear in the transcript, call `hooks route` via CLI/MCP or read `.swarm/route-latest.md` when present.
+
+## CLI fallback
+
+When MCP is down:
+
+```bash
+npx -y ruflo@latest memory search --query "…"
+npx -y ruflo@latest memory store --key "…" --value "…" --namespace patterns
+npx -y ruflo@latest swarm init --topology hierarchical --max-agents 8
+npx -y ruflo@latest doctor
+```
+
+Team calls have their own fallback that needs no npx: `node scripts/grok-team-bus.mjs <command> --team <team> …` (same store as the `team_*` tools).
+
+## Anti-patterns
+
+- Waiting after `swarm start` for code to appear
+- Calling Claude-only tools (`SendMessage`, Claude `Task` agent types as host APIs)
+- Shared-tree parallel coders without worktrees (file races)
+- Skipping memory_search / grounding on stack decisions
+- Creating docs in repo root or committing secrets
+)
diff --git a/v3/@claude-flow/cli/templates/grok/scripts/grok-subagent-stop-hook.mjs b/v3/@claude-flow/cli/templates/grok/scripts/grok-subagent-stop-hook.mjs
new file mode 100644
index 0000000000..ee71692424
--- /dev/null
+++ b/v3/@claude-flow/cli/templates/grok/scripts/grok-subagent-stop-hook.mjs
@@ -0,0 +1,90 @@
+#!/usr/bin/env node
+/**
+ * Grok SubagentStop → team bus on-stop (ADR-402).
+ *
+ * Reads the hook JSON from stdin (Grok / Claude compatible fields) and marks
+ * the stopped teammate idle, advancing its team's plan.
+ *
+ * Which teammate: team_spawn sets the spawn description to
+ * `<role>:<agent>@<team>`. The hook parses that; TEAM_NAME / SUBAGENT_NAME
+ * env vars or explicit `team` / `agentName` fields override it.
+ *
+ * Which team, when the description has no @team: the one active team that
+ * lists the agent as a member. Several matches are reported as ambiguous and
+ * nothing is advanced.
+ *
+ * Exit codes: 0 done, or the subagent is not a team member (nothing to do);
+ * 1 a team subagent could not be recorded (reason on stderr, non-blocking).
+ */
+import { dirname, join } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+const here = dirname(fileURLToPath(import.meta.url));
+const bus = await import(pathToFileURL(join(here, 'grok-team-bus.mjs')).href);
+
+const projectRoot = process.env.CLAUDE_PROJECT_DIR || process.env.GROK_WORKSPACE_ROOT || process.cwd();
+
+function readStdin() {
+ if (process.stdin.isTTY) return Promise.resolve('');
+ return new Promise((resolve) => {
+ let data = '';
+ const t = setTimeout(() => resolve(data), 1000);
+ process.stdin.setEncoding('utf8');
+ process.stdin.on('data', (c) => { data += c; });
+ process.stdin.on('end', () => { clearTimeout(t); resolve(data); });
+ process.stdin.on('error', () => { clearTimeout(t); resolve(data); });
+ });
+}
+
+function fail(reason) {
+ process.stderr.write(`ruflo team hook: ${reason}\n`);
+ process.exit(1);
+}
+
+let input = {};
+const raw = await readStdin();
+try {
+ input = raw.trim() ? JSON.parse(raw) : {};
+} catch {
+ input = {};
+}
+
+const description = input.description ?? input.toolInput?.description ?? input.tool_input?.description;
+const parsed = bus.parseSpawnDescription(description) || {};
+const agent =
+ process.env.SUBAGENT_NAME
+ || input.subagentName
+ || input.agentName
+ || input.agent
+ || parsed.agent;
+const explicitTeam = process.env.TEAM_NAME || input.teamName || input.team || parsed.team;
+
+if (!agent) {
+ // Not a team spawn (no description in <role>:<agent>@<team> form).
+ process.exit(0);
+}
+
+let team = explicitTeam;
+if (!team) {
+ let matches;
+ try {
+ matches = bus.teamsWithMember(projectRoot, String(agent));
+ } catch (err) {
+ fail(err.message);
+ }
+ if (matches.length === 0) process.exit(0);
+ if (matches.length > 1) {
+ fail(`agent "${agent}" is on several active teams (${matches.join(', ')}); spawn with the description from team_spawn (<role>:<agent>@<team>) or set TEAM_NAME`);
+ }
+ team = matches[0];
+}
+
+try {
+ const r = await bus.onStop(projectRoot, { team: String(team), agent: String(agent) });
+ if (!r.member && !r.advanced) {
+ fail(`agent "${agent}" is not a member of team "${team}" and is not its current plan step`);
+ }
+} catch (err) {
+ fail(err.message || String(err));
+}
+process.exit(0);
diff --git a/v3/@claude-flow/cli/templates/grok/scripts/grok-team-bus.mjs b/v3/@claude-flow/cli/templates/grok/scripts/grok-team-bus.mjs
new file mode 100755
index 0000000000..4595e78007
--- /dev/null
+++ b/v3/@claude-flow/cli/templates/grok/scripts/grok-team-bus.mjs
@@ -0,0 +1,525 @@
+#!/usr/bin/env node
+/**
+ * Host-agnostic Agent Teams bus (ADR-402) — filesystem store.
+ *
+ * Works from any host (Grok, Claude, Codex) without proprietary SendMessage.
+ * The team_* MCP tools and the SubagentStop hook import this file, and
+ * `init --grok` copies it (with grok-team-store.mjs, the storage layer) into a
+ * project as a zero-dependency CLI:
+ *
+ * node scripts/grok-team-bus.mjs <create|spawn|send|inbox|status|plan|on-stop|shutdown> --team <team> …
+ *
+ * Run with no arguments for the full usage. `spawn` prints the plan that Grok
+ * maps to spawn_subagent.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+import {
+ NAME_RE,
+ assertActive,
+ ensureRealDir,
+ loadTeam,
+ mailboxDir,
+ nowIso,
+ readJson,
+ realDirExists,
+ safeName,
+ teamDir,
+ teamFile,
+ teamsRoot,
+ updateTeam,
+ withTeamLock,
+ writeJsonAtomic,
+} from './grok-team-store.mjs';
+
+export const GROK_CONTRACT = 'grok-build-1.0.41';
+export const MAX_PRIORITY = 999;
+export const DEFAULT_PRIORITY = 2;
+
+
+const ROLE_DEFAULTS = {
+ researcher: { capability_mode: 'read-only', isolation: 'none', subagent_type: 'explore', claudeTaskType: 'researcher' },
+ architect: { capability_mode: 'read-only', isolation: 'none', subagent_type: 'plan', claudeTaskType: 'system-architect' },
+ developer: { capability_mode: 'all', isolation: 'worktree', subagent_type: 'general-purpose', claudeTaskType: 'coder' },
+ coder: { capability_mode: 'all', isolation: 'worktree', subagent_type: 'general-purpose', claudeTaskType: 'coder' },
+ tester: { capability_mode: 'all', isolation: 'worktree', subagent_type: 'general-purpose', claudeTaskType: 'tester' },
+ reviewer: { capability_mode: 'read-only', isolation: 'none', subagent_type: 'general-purpose', claudeTaskType: 'reviewer' },
+ security: { capability_mode: 'read-only', isolation: 'none', subagent_type: 'general-purpose', claudeTaskType: 'security-auditor' },
+ coordinator: { capability_mode: 'all', isolation: 'none', subagent_type: 'general-purpose', claudeTaskType: 'coordinator' },
+};
+
+// ---------------------------------------------------------------------------
+// Spawn plan
+// ---------------------------------------------------------------------------
+
+/**
+ * The spawn description carries role, agent, and team so the SubagentStop
+ * hook can resolve which plan step finished: `<role>:<agent>@<team>`.
+ */
+export function spawnDescription(role, agent, team) {
+ return `${role}:${agent}@${team}`;
+}
+
+/** Inverse of spawnDescription. Also accepts a bare agent name. */
+export function parseSpawnDescription(desc) {
+ if (typeof desc !== 'string') return null;
+ const m = /^\s*(?:([A-Za-z0-9_-]+):)?([A-Za-z0-9][A-Za-z0-9_-]{0,63})(?:@([A-Za-z0-9][A-Za-z0-9_-]{0,63}))?\s*$/.exec(desc);
+ if (!m) return null;
+ return { role: m[1] || null, agent: m[2], team: m[3] || null };
+}
+
+function roleConstraint(mode, isolation) {
+ if (mode === 'read-only') {
+ return 'Constraint: do not create, edit, delete, or move files, and do not run commands that change the repo. Read, search, and report.';
+ }
+ if (isolation === 'worktree') {
+ return 'Constraint: Grok isolates your edits in a git worktree. Stay inside that worktree and report its path when you finish.';
+ }
+ return 'Constraint: report results to the team lead. Stay inside the files this task names.';
+}
+
+function buildSpawnPlan(t, agent, role, prompt, next) {
+ const defaults = ROLE_DEFAULTS[role] || ROLE_DEFAULTS.coder;
+ const spawn = {
+ description: spawnDescription(role, agent, t.name),
+ background: true,
+ isolation: defaults.isolation,
+ };
+ const protocol = [
+ `You are "${agent}" (role: ${role}) on team "${t.name}".`,
+ 'Grok Build 1.0.41 runs you as a general-purpose subagent. Nesting depth is 1: do not call spawn_subagent.',
+ roleConstraint(defaults.capability_mode, defaults.isolation),
+ 'Host-agnostic Agent Teams bus (ADR-402). There is no Claude SendMessage tool.',
+ `Read your inbox first: team_inbox (team=${t.name}, agent=${agent}).`,
+ 'Hand off with team_send. Without the Ruflo MCP server, use the CLI:',
+ ` node scripts/grok-team-bus.mjs inbox --team ${t.name} --agent ${agent}`,
+ ` node scripts/grok-team-bus.mjs send --team ${t.name} --from ${agent} --to <next> --summary "<short>" --message "<handoff>"`,
+ next.length
+ ? `Primary next agent(s): ${next.join(', ')}`
+ : 'Report completion to the team lead (parent session).',
+ '',
+ 'Task:',
+ prompt || `(No task body — wait for inbox / lead instructions for role ${role}.)`,
+ ].join('\n');
+
+ return {
+ teamId: t.id,
+ name: agent,
+ role,
+ prompt: protocol,
+ next,
+ host: {
+ grok: {
+ // Pass `spawn` to spawn_subagent together with top-level `prompt`.
+ contract: GROK_CONTRACT,
+ spawn,
+ advisory: {
+ capability_mode: defaults.capability_mode,
+ subagent_type: defaults.subagent_type,
+ note: 'Grok Build 1.0.41 does not take capability_mode or subagent_type on spawn_subagent. The child is general-purpose; the prompt carries the constraint. isolation is the enforced knob. .grok/agents/*.md are session profiles (grok --agent-profile), not spawn types.',
+ },
+ },
+ claude: {
+ taskType: defaults.claudeTaskType || role,
+ note: 'optional back-compat path via Task tool',
+ },
+ },
+ };
+}
+
+// ---------------------------------------------------------------------------
+// Operations (throw Error on failure; return plain objects)
+// ---------------------------------------------------------------------------
+
+export async function createTeam(projectRoot, opts) {
+ const name = safeName(opts.name, 'name');
+ const dir = teamDir(projectRoot, name);
+ ensureRealDir(projectRoot, dir);
+ const maxAgents = Math.min(Math.max(Math.trunc(Number(opts.maxAgents)) || 8, 1), 50);
+ const t = {
+ id: name,
+ name,
+ topology: opts.topology || 'hierarchical',
+ maxAgents,
+ status: 'active',
+ createdAt: nowIso(),
+ host: opts.host || 'grok',
+ members: {},
+ plan: { steps: [], index: 0 },
+ };
+ return withTeamLock(projectRoot, name, () => {
+ const existed = fs.existsSync(teamFile(projectRoot, name));
+ if (existed && !opts.force) {
+ throw new Error(`Team "${name}" already exists (pass force to overwrite its metadata)`);
+ }
+ if (existed && opts.force) {
+ // Recreating an existing team must not leak the old incarnation's
+ // mailboxes (pending or archived messages) into the fresh one — wipe
+ // them along with the metadata (ADR-402 round-2 review, N4).
+ const mailbox = path.join(dir, 'mailbox');
+ if (realDirExists(mailbox)) fs.rmSync(mailbox, { recursive: true, force: true });
+ }
+ writeJsonAtomic(teamFile(projectRoot, name), t);
+ ensureRealDir(projectRoot, path.join(dir, 'mailbox'));
+ return { action: 'create', team: t };
+ });
+}
+
+function parseNext(next) {
+ const list = Array.isArray(next)
+ ? next.map(String)
+ : typeof next === 'string' ? next.split(',') : [];
+ return list.map((s) => s.trim()).filter(Boolean).map((s) => safeName(s, 'next'));
+}
+
+export async function spawnMember(projectRoot, opts) {
+ const agent = safeName(opts.agent, 'agent');
+ const role = safeName(opts.role || agent, 'role');
+ const next = parseNext(opts.next);
+ const prompt = typeof opts.prompt === 'string' ? opts.prompt : '';
+ const result = await updateTeam(projectRoot, opts.team, (t) => {
+ assertActive(t);
+ const members = t.members || (t.members = {});
+ if (!members[agent] && Object.keys(members).length >= t.maxAgents) {
+ throw new Error(`Team "${t.name}" is full (maxAgents=${t.maxAgents})`);
+ }
+ const plan = buildSpawnPlan(t, agent, role, prompt, next);
+ members[agent] = {
+ name: agent,
+ role,
+ status: 'registered',
+ registeredAt: nowIso(),
+ next,
+ spawn: plan.host,
+ };
+ return { action: 'spawn', spawnPlan: plan, teamId: t.id };
+ });
+ ensureRealDir(projectRoot, mailboxDir(projectRoot, opts.team, agent));
+ return result;
+}
+
+/**
+ * Priority must be a plain base-10 integer literal 0-MAX_PRIORITY. A string
+ * value is checked against that shape directly, rejecting anything
+ * `Number()` would otherwise happily coerce — scientific notation ("1e2")
+ * and hex/octal/binary prefixes ("0x10", "0o20", "0b101") all parse to an
+ * in-range integer but are not the small plain integer this field is meant
+ * to be (ADR-402 round-2 review, N5, minor item 5).
+ */
+export function parsePriority(value) {
+ if (value === undefined || value === null || value === '') return DEFAULT_PRIORITY;
+ let n;
+ if (typeof value === 'number') {
+ n = value;
+ } else {
+ const s = String(value).trim();
+ if (!/^-?\d+$/.test(s)) {
+ throw new Error(`priority must be an integer 0-${MAX_PRIORITY} (lower is read first), got "${value}"`);
+ }
+ n = Number(s);
+ }
+ if (!Number.isInteger(n) || n < 0 || n > MAX_PRIORITY) {
+ throw new Error(`priority must be an integer 0-${MAX_PRIORITY} (lower is read first), got "${value}"`);
+ }
+ return n;
+}
+
+const messageFileName = (msg) => `${String(msg.priority).padStart(3, '0')}_${msg.id}.json`;
+
+export function sendMessage(projectRoot, opts) {
+ const to = opts.to || '*';
+ if (to !== '*') safeName(to, 'to');
+ const from = safeName(opts.from || 'lead', 'from');
+ const content = String(opts.message ?? opts.content ?? '');
+ if (!content.trim()) throw new Error('message is required');
+ const priority = parsePriority(opts.priority);
+
+ // Hold the lock so a concurrent shutdown or spawn cannot interleave.
+ return withTeamLock(projectRoot, opts.team, () => {
+ const t = loadTeam(projectRoot, opts.team);
+ assertActive(t);
+ const recipients = to === '*' ? Object.keys(t.members || {}) : [to];
+ if (recipients.length === 0) {
+ throw new Error(`Team "${t.name}" has no members to broadcast to — team_spawn them first, or send to a named agent`);
+ }
+ const msg = {
+ id: `msg_${Date.now()}_${Math.random().toString(36).slice(2, 10)}`,
+ teamId: t.id,
+ from,
+ to,
+ summary: String(opts.summary || ''),
+ content,
+ type: String(opts.type || 'handoff'),
+ priority,
+ timestamp: nowIso(),
+ };
+ for (const r of recipients) {
+ const dir = mailboxDir(projectRoot, t.name, r);
+ ensureRealDir(projectRoot, dir);
+ // wx: never write through a pre-existing file or symlink of that name.
+ fs.writeFileSync(path.join(dir, messageFileName(msg)), JSON.stringify(msg, null, 2) + '\n', {
+ encoding: 'utf8',
+ flag: 'wx',
+ mode: 0o600,
+ });
+ }
+ return { action: 'send', message: msg, recipients };
+ });
+}
+
+function pendingFiles(dir) {
+ if (!realDirExists(dir)) return [];
+ return fs.readdirSync(dir).filter((f) => f.endsWith('.json')).sort();
+}
+
+/**
+ * Drain (default) or peek one agent's mailbox on one team. A drain claims each
+ * file by renaming it into archive/ first, so two concurrent drains each get a
+ * disjoint set of messages and neither throws.
+ */
+export function readInbox(projectRoot, opts) {
+ const agent = safeName(opts.agent, 'agent');
+ loadTeam(projectRoot, opts.team);
+ const dir = mailboxDir(projectRoot, opts.team, agent);
+ const peek = opts.peek === true;
+ const messages = [];
+ const files = pendingFiles(dir);
+ if (files.length && !peek) ensureRealDir(projectRoot, path.join(dir, 'archive'));
+ for (const f of files) {
+ let file = path.join(dir, f);
+ if (!peek) {
+ const archived = path.join(dir, 'archive', f);
+ try {
+ fs.renameSync(file, archived);
+ } catch (err) {
+ if (err.code === 'ENOENT') continue; // another reader claimed it
+ throw err;
+ }
+ file = archived;
+ }
+ const msg = readJson(file);
+ if (msg) messages.push(msg);
+ }
+ return { action: 'inbox', team: opts.team, agent, messages, peek };
+}
+
+export function teamStatus(projectRoot, opts) {
+ const t = loadTeam(projectRoot, opts.team);
+ const names = new Set(Object.keys(t.members || {}));
+ const box = path.join(teamDir(projectRoot, opts.team), 'mailbox');
+ if (realDirExists(box)) {
+ for (const ent of fs.readdirSync(box, { withFileTypes: true })) {
+ if (ent.isDirectory() && NAME_RE.test(ent.name)) names.add(ent.name);
+ }
+ }
+ const pendingMail = {};
+ for (const name of [...names].sort()) {
+ pendingMail[name] = pendingFiles(mailboxDir(projectRoot, opts.team, name)).length;
+ }
+ return { action: 'status', team: t, pendingMail };
+}
+
+function normalizeSteps(steps) {
+ let list = steps;
+ if (typeof list === 'string') {
+ try {
+ list = JSON.parse(list);
+ } catch {
+ list = list.split(',').map((s) => s.trim()).filter(Boolean);
+ }
+ }
+ if (!Array.isArray(list) || list.length === 0) throw new Error('steps must be a non-empty list');
+ return list.map((s, i) => {
+ const agent = typeof s === 'string' ? s : s && (s.agent || s.id);
+ const id = typeof s === 'string' ? s : s && (s.id || s.agent);
+ return {
+ id: safeName(String(id), 'step id'),
+ agent: safeName(String(agent), 'step agent'),
+ status: i === 0 ? 'ready' : 'pending',
+ };
+ });
+}
+
+export function setPlan(projectRoot, opts) {
+ const steps = normalizeSteps(opts.steps);
+ return updateTeam(projectRoot, opts.team, (t) => {
+ assertActive(t);
+ t.plan = { steps, index: 0, updatedAt: nowIso() };
+ return { action: 'plan', plan: t.plan };
+ });
+}
+
+export function onStop(projectRoot, opts) {
+ const agent = safeName(opts.agent, 'agent');
+ return updateTeam(projectRoot, opts.team, (t) => {
+ assertActive(t);
+ const member = t.members?.[agent];
+ if (member) {
+ member.status = 'idle';
+ member.lastStopAt = nowIso();
+ }
+ const plan = t.plan || (t.plan = { steps: [], index: 0 });
+ const cur = plan.steps[plan.index];
+ const advanced = Boolean(cur && (cur.agent === agent || cur.id === agent));
+ if (advanced) {
+ cur.status = 'done';
+ plan.index = Math.min(plan.index + 1, plan.steps.length);
+ const nxt = plan.steps[plan.index];
+ if (nxt) nxt.status = 'ready';
+ plan.updatedAt = nowIso();
+ }
+ const nextStep = plan.steps[plan.index] || null;
+ return {
+ action: 'on-stop',
+ agent,
+ member: Boolean(member),
+ advanced,
+ next: nextStep,
+ assign: nextStep
+ ? { hint: `Spawn or resume agent "${nextStep.agent}" for the next plan step`, agent: nextStep.agent }
+ : { hint: 'Plan complete — lead should synthesize' },
+ };
+ });
+}
+
+export function shutdownTeam(projectRoot, opts) {
+ return updateTeam(projectRoot, opts.team, (t) => {
+ t.status = 'shutdown';
+ t.shutdownAt = nowIso();
+ for (const m of Object.values(t.members || {})) m.status = 'shutdown';
+ return { action: 'shutdown', teamId: t.id };
+ });
+}
+
+/**
+ * Active teams that list `agent` as a member. The SubagentStop hook uses this
+ * when the spawn description carries no @team: exactly one match is used,
+ * several matches are reported as ambiguous.
+ */
+export function teamsWithMember(projectRoot, agent) {
+ const root = teamsRoot(projectRoot);
+ if (!realDirExists(root)) return [];
+ const out = [];
+ for (const ent of fs.readdirSync(root, { withFileTypes: true })) {
+ if (!ent.isDirectory() || !NAME_RE.test(ent.name)) continue;
+ const t = readJson(path.join(root, ent.name, 'team.json'));
+ if (t && t.status === 'active' && t.members && t.members[agent]) out.push(ent.name);
+ }
+ return out.sort();
+}
+
+// ---------------------------------------------------------------------------
+// CLI
+// ---------------------------------------------------------------------------
+
+function parseArgs(argv) {
+ const out = { _: [] };
+ for (let i = 0; i < argv.length; i++) {
+ const a = argv[i];
+ if (a.startsWith('--')) {
+ const key = a.slice(2);
+ const next = argv[i + 1];
+ if (next === undefined || next.startsWith('--')) {
+ out[key] = true;
+ } else {
+ out[key] = next;
+ i++;
+ }
+ } else {
+ out._.push(a);
+ }
+ }
+ return out;
+}
+
+const print = (obj) => process.stdout.write(JSON.stringify(obj, null, 2) + '\n');
+
+const USAGE = [
+ 'create --name <team> [--topology hierarchical] [--max-agents 8] [--force]',
+ 'spawn --team <team> --agent <name> [--role <role>] [--prompt "..."] [--next a,b]',
+ 'send --team <team> --to <agent|*> --message "..." [--summary s] [--from lead] [--priority 0-999]',
+ 'inbox --team <team> --agent <name> [--peek]',
+ 'status --team <team>',
+ 'plan --team <team> --steps \'["architect","developer","tester"]\'',
+ 'on-stop --team <team> --agent <name>',
+ 'shutdown --team <team>',
+];
+
+export async function runCli(argv, env = process.env) {
+ const args = parseArgs(argv);
+ const cmd = args._[0];
+ const projectRoot = path.resolve(
+ typeof args.root === 'string' ? args.root : env.CLAUDE_PROJECT_DIR || env.GROK_WORKSPACE_ROOT || process.cwd(),
+ );
+ const team = args.team || args.name;
+ switch (cmd) {
+ case 'create':
+ return createTeam(projectRoot, {
+ name: team,
+ topology: args.topology,
+ maxAgents: args['max-agents'] ?? args.maxAgents,
+ host: args.host,
+ force: args.force === true,
+ });
+ case 'spawn':
+ return spawnMember(projectRoot, {
+ team,
+ agent: args.agent || args.member,
+ role: args.role,
+ prompt: args.prompt || args.message,
+ next: args.next,
+ });
+ case 'send':
+ return sendMessage(projectRoot, {
+ team,
+ to: args.to,
+ from: args.from,
+ summary: args.summary,
+ message: args.message ?? args.content,
+ type: args.type,
+ priority: args.priority,
+ });
+ case 'inbox':
+ return readInbox(projectRoot, { team, agent: args.agent || args.to, peek: args.peek === true });
+ case 'status':
+ return teamStatus(projectRoot, { team });
+ case 'plan':
+ return setPlan(projectRoot, { team, steps: args.steps });
+ case 'on-stop':
+ return onStop(projectRoot, { team, agent: args.agent });
+ case 'shutdown':
+ return shutdownTeam(projectRoot, { team });
+ default:
+ return null;
+ }
+}
+
+async function main() {
+ let result;
+ try {
+ result = await runCli(process.argv.slice(2));
+ } catch (err) {
+ print({ ok: false, error: err.message || String(err) });
+ process.exit(1);
+ return;
+ }
+ if (result === null) {
+ print({ ok: false, error: 'usage', commands: USAGE });
+ process.exit(process.argv[2] ? 1 : 0);
+ return;
+ }
+ print({ ok: true, ...result });
+}
+
+function invokedDirectly() {
+ if (!process.argv[1]) return false;
+ try {
+ return import.meta.url === pathToFileURL(fs.realpathSync(process.argv[1])).href;
+ } catch {
+ return false;
+ }
+}
+
+if (invokedDirectly()) main();
diff --git a/v3/@claude-flow/cli/templates/grok/scripts/grok-team-store.mjs b/v3/@claude-flow/cli/templates/grok/scripts/grok-team-store.mjs
new file mode 100644
index 0000000000..0e04bc623f
--- /dev/null
+++ b/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`);
+ }
+}
+
diff --git a/v3/@claude-flow/cli/templates/grok/scripts/host-statusline.mjs b/v3/@claude-flow/cli/templates/grok/scripts/host-statusline.mjs
new file mode 100755
index 0000000000..6d0a1b7277
--- /dev/null
+++ b/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`);
+}
diff --git a/v3/@claude-flow/cli/templates/grok/skills/agent-teams-grok/SKILL.md b/v3/@claude-flow/cli/templates/grok/skills/agent-teams-grok/SKILL.md
new file mode 100644
index 0000000000..a444d15bf1
--- /dev/null
+++ b/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)
diff --git a/v3/docs/adr/ADR-402-host-agnostic-agent-teams.md b/v3/docs/adr/ADR-402-host-agnostic-agent-teams.md
new file mode 100644
index 0000000000..c566087856
--- /dev/null
+++ b/v3/docs/adr/ADR-402-host-agnostic-agent-teams.md
@@ -0,0 +1,161 @@
+# ADR-402: Host-Agnostic Agent Teams (Grok-first, Claude-portable)
+
+**Status:** Proposed
+**Date:** 2026-07-20
+**Deciders:** Ruflo maintainers
+**Related:** ADR-018 (Claude Code integration), teammate-plugin, swarm-comms mailbox, RuvNet Brain grounding, `init --codex` pattern
+
+---
+
+## Context
+
+Ruflo’s multi-agent “Agent Teams” UX on Claude Code depends on host features:
+
+- Named agents + proprietary **`SendMessage`** mailbox
+- Claude `Task` tool / TeammateTool (`@claude-flow/teammate-plugin`, `~/.claude/teams/`)
+- Optional `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS`
+
+Grok Build already provides strong primitives that Claude Agent Teams lack or only partially have:
+
+| Capability | Grok | Claude Agent Teams |
+|------------|------|--------------------|
+| Parallel children | `spawn_subagent` + background | Task / teammates |
+| Isolation | **`isolation: worktree`** | Shared tree (race-prone) |
+| Least privilege | `capability_mode` | Soft / prompt-level |
+| Stage continuity | `resume_from` | Message-only handoff |
+| Hooks | Claude-compat + SubagentStop | TeammateIdle / TaskCompleted |
+| Skills | `.agents` + `.claude` discovery | Claude skills |
+
+Today’s **teammate-plugin is Claude-bound** (peerDep on Claude Code, spawn returns `AgentInput` for Claude Task). A Grok-only prompt convention is not enough: teams, skills, and learning are product-critical and must work **better than Claude Code**.
+
+Existing seed in-tree: `.claude/helpers/swarm-comms.sh` already implements a **filesystem mailbox** under `.claude-flow/swarm/mailbox/`.
+
+## Decision
+
+1. **Put the Agent Teams bus in Ruflo, not in the host.**
+ Comms are MCP + on-disk/AgentDB state. Hosts only execute spawns and run hooks.
+
+2. **Ship `team_*` MCP tools** (host-agnostic contract):
+
+ | Tool | Purpose |
+ |------|---------|
+ | `team_create` | Create team + topology + max members |
+ | `team_spawn` | Register teammate; return **spawn plan** for the host |
+ | `team_send` | Enqueue message to named agent (or `*`) |
+ | `team_inbox` | Drain / peek mailbox for agent |
+ | `team_broadcast` | Fan-out |
+ | `team_plan` | Steps + dependencies (pipeline) |
+ | `team_status` | Members, queues, plan progress |
+ | `team_on_stop` | Idle-assign / train (hook entry) |
+ | `team_shutdown` | Graceful teardown |
+
+3. **Spawn plan contract** (host adapter):
+
+```json
+{
+ "teamId": "team_…",
+ "name": "architect",
+ "role": "architect",
+ "prompt": "…comms protocol embedded…",
+ "host": {
+ "grok": {
+ "subagent_type": "general-purpose",
+ "capability_mode": "read-only",
+ "isolation": "none",
+ "background": true
+ },
+ "claude": {
+ "taskType": "system-architect",
+ "note": "optional back-compat path"
+ }
+ },
+ "next": ["developer"]
+}
+```
+
+Grok lead calls `spawn_subagent` with the plan; it does **not** need `SendMessage`.
+
+4. **Storage**
+
+ - Team state: project-local `.claude-flow/teams/{teamId}/` (not `~/.claude/teams/`)
+ - Mailbox: per team, `.claude-flow/teams/{teamId}/mailbox/{agent}/` (+ optional AgentDB namespace `team:{id}`). Not the shared `.claude-flow/swarm/mailbox/`: an agent name is only unique within its team.
+ - Learning: existing `post-task` / memory_store patterns
+
+5. **Grok defaults that beat Claude**
+
+ - Write agents: `isolation: worktree`
+ - Research/review: `read-only` / explore
+ - Pipeline: short cycles + `team_on_stop` idle assign
+ - Optional `resume_from` for stage continuity when mailbox payload is large
+
+6. **Grounding (RuvNet Brain)** is in scope for the same host effort:
+ `search_ruvnet` (or forge-mcp) + intent/action policy so the model does not drift to training-prior infra.
+
+7. **Product entry:** `npx ruflo init --grok` (later) mirrors `init --codex` — writes `.grok/config.toml`, rules, agents, MCP registration.
+
+## Consequences
+
+### Positive
+
+- Same team semantics on Grok, Codex, Claude (Claude becomes one adapter).
+- Worktree isolation reduces multi-agent file conflicts vs Claude shared-tree teams.
+- Federation can later ride the same bus.
+- Upstreamable: host-agnostic core can be proposed back to ruvnet/ruflo.
+
+### Negative / costs
+
+- Must implement and maintain `team_*` tools and adapters.
+- Grok may not inject `UserPromptSubmit` stdout the way Claude injects `additionalContext` — route/brain hooks need file or MCP fallbacks.
+- Skill/tool surface must be curated to avoid context drowning (300+ MCP tools + 100+ skills).
+
+### Neutral
+
+- teammate-plugin remains for native Claude TeammateTool users until migrated to the agnostic bus.
+- CLAUDE.md Claude-specific examples stay valid for Claude hosts; Grok overlay (`.grok/rules/ruflo-grok.md`) takes precedence on Grok.
+
+## Implementation plan (summary)
+
+1. Phase 0: project `.grok/config.toml` + rules + MCP smoke — **done**.
+2. Phase 1: mailbox-backed `team_create/send/inbox/status` MVP — **done** (CLI + MCP).
+3. Phase 2: `team_spawn` spawn plans + Grok agent defs + SubagentStop → `team_on_stop` — **done**.
+4. Phase 3: RuvNet Brain MCP + grounding rules — **done** (`KB_DIR` required).
+5. Phase 4: `init --grok` — **done**. A host conformance bench is proposed separately.
+
+## Alternatives considered
+
+| Alternative | Why rejected |
+|-------------|--------------|
+| Prompt-only “pretend SendMessage” | No durable bus, no idle assign, not better than Claude |
+| Depend on Grok adding SendMessage | Speculative; bus should not be proprietary |
+| Codex-style “single executor + swarm records only” | Fails requirement: agent teams + skills are critical |
+| Fork forever without agnostic bus | Blocks upstream and multi-host |
+
+## Amendment (2026-09-27) — Grok Build 1.0.41
+
+Re-checked against `grok 1.0.41` and `~/.grok/docs/user-guide/` on that binary. The spawn example in the Decision section above matches Grok as of 2026-07-20. The live tool no longer matches it.
+
+- `spawn_subagent` accepts `prompt`, `description`, `background`, `isolation`, and optionally `cwd`, `resume_from`, and `model`. It does not accept `subagent_type` or `capability_mode`. An omitted type is `general-purpose`. Capability is a property of the agent definition, which spawn cannot select.
+- Nesting depth is 1. Only the lead calls `spawn_subagent`.
+- Project `.grok/config.toml` contributes `[mcp_servers]`, `[plugins]`, `[permission]`, and `[mcp].max_output_bytes`. `[subagents]` in that file is ignored.
+- `.grok/agents/*.md` are session profiles (`--agent-profile`, `/agents`).
+- MCP tools are still reached through `search_tool` / `use_tool` (`ruflo__team_create`). `grok mcp add` still defaults to user scope; `--scope project` / `-s project` writes `./.grok/config.toml`.
+- Folder trust (`/hooks-trust`, `grok --trust`) gates project MCP, hooks, skills, and rules together.
+
+`team_spawn` now returns `host.grok.spawn` (the arguments to pass) and `host.grok.advisory` (role constraint, not a spawn argument). The prompt states the read-only or worktree constraint. `isolation: "worktree"` remains the enforced isolation knob. Operator steps and the re-check list live in `v3/@claude-flow/cli/templates/grok/docs/README.md` (copied to `docs/grok/README.md` by `init --grok`).
+
+## Amendment (2026-09-28) — review of #3512
+
+- One implementation: `templates/grok/scripts/grok-team-bus.mjs` is the store. The `team_*` MCP tools import it; `init --grok` copies it into a project as a CLI; the SubagentStop hook imports it. No repo-root copies.
+- `team.json` writes take a cross-process lock (`team.lock`, an O_EXCL file with an owner token; a stale lock is broken by rename and token check, never by a blind delete) and go through temp file + rename. Mail is per team (`teams/{id}/mailbox/{agent}/`); a drain claims each file by rename, so concurrent drains are disjoint. Mailbox paths that are symlinks are refused.
+- `team_shutdown` closes the team (spawn, send, plan, on-stop refuse); `team_spawn` enforces `maxAgents`; a broadcast with no members is refused; `priority` is an integer 0-999 in a zero-padded filename.
+- The spawn description is `<role>:<agent>@<team>`; the SubagentStop hook parses it, and reports on stderr (exit 1) when a team subagent cannot be recorded or the team is ambiguous.
+- `init --grok` writes only inside the project unless `--grok-statusline` is passed; then it installs `~/.grok/ruflo/host-statusline.mjs` and merges `[ui.status_line]` into `~/.grok/config.toml` with a TOML parser, or prints the snippet when it cannot merge safely. `--dry-run` lists what would be written. The project MCP entry is pinned to the running Ruflo version (the one that ships `team_*`), not `@latest`.
+
+## References
+
+- [RuvNet Brain](https://isovision.ai/ruvnet-brain/) — grounding at intent + action; `search_ruvnet`
+- `v3/plugins/teammate-plugin` — Claude-bound prior art
+- `.claude/helpers/swarm-comms.sh` — mailbox seed
+- `v3/@claude-flow/cli/templates/grok/rules/ruflo-grok.md` — Grok host doctrine
+- Grok user guide: MCP, hooks, subagents, skills, Claude compat
+)