@claude-flow/cli 3.58.1 → 3.59.1

package/plugins/ruflo-metaharness/scripts/similarity.mjs

@@ -147,6 +147,7 @@ function main() {
     console.log(`| jaccard     | ${components.jaccard.toFixed(4)} | ${weights.jaccard}   | ${(components.jaccard * weights.jaccard).toFixed(4)} |`);
     console.log('');
     console.log(`**Overall:** ${payload.overall.toFixed(4)}`);
+    console.log(`**Verdict:** ${payload.verdict}`);
     if (payload.alert) {
       console.log('');
       console.log(payload.alert.triggered ? `⚠ ALERT: ${payload.alert.reason}` : `✓ ${payload.alert.reason}`);

package/plugins/ruflo-metaharness/scripts/test-similarity.mjs

@@ -23,6 +23,7 @@
 
 import {
   projectToVec, cosine, categoricalAgreement, jaccard, similarity,
+  normalizeCost, COST_BAND_USD, verdictFor, VERDICT_THRESHOLDS,
 } from './_similarity.mjs';
 // iter 64 — also test the iter-63 shared severity primitives
 import { SEVERITY_RANK, rankSeverity, parseMcpScanText } from './_harness.mjs';
@@ -174,6 +175,68 @@ assert(typeof hf.contribution === 'number', 'perDimension has numeric contributi
 const sNoPD = similarity(A, B);
 assert(!('perDimension' in sNoPD), 'perDimension omitted by default');
 
+console.log('\nPhase 7b — normalizeCost (vector index 8, ADR-152 Table 1)');
+// The pre-fix transform was `log10(usd + 0.001) / log10(10)` clamped to
+// [0,1]. `Math.log10(10)` is 1, so the division was a no-op and the raw
+// log — negative for every cost below $0.999 — clamped to a flat 0. That
+// dead zone covered the whole realistic per-run range, including ruflo's
+// own $0.048 Phase-0 baseline.
+assert(normalizeCost(COST_BAND_USD.min) === 0, 'band floor → 0');
+assert(normalizeCost(COST_BAND_USD.max) === 1, 'band ceiling → 1');
+assert(normalizeCost(50) === 1, 'above band ceiling clamps to 1');
+assert(normalizeCost(0) === 0, 'zero cost clamps to 0');
+assert(normalizeCost(-5) === 0, 'negative cost clamps to 0');
+// The regression that motivated the fix: realistic costs must not collide.
+assert(normalizeCost(0.048) !== normalizeCost(0.11),
+  'ruflo baseline $0.048 and $0.11 must not collapse to the same value (dead-zone regression)');
+assert(normalizeCost(0.048) > 0,
+  '$0.048 (ruflo Phase-0 baseline) must be strictly inside the band');
+// Monotonic non-decreasing across the band, sampled log-evenly.
+const costSamples = [0.001, 0.005, 0.02, 0.048, 0.11, 0.5, 1, 5, 10];
+const costVec = costSamples.map(normalizeCost);
+assert(costVec.every((v, i) => i === 0 || v >= costVec[i - 1]),
+  'normalizeCost is monotonic non-decreasing across the band');
+assert(costVec.every((v) => v >= 0 && v <= 1), 'normalizeCost bounded to [0, 1]');
+// End-to-end: the dimension must now reach the composite. Two harnesses
+// identical except for cost previously scored cosine === 1 because both
+// collapsed to 0; they must now differ.
+const costTwin = (usd) => ({
+  score: { ...A.score, estCostPerRunUsd: usd }, genome: A.genome,
+});
+const cheapTwin = similarity(costTwin(0.048), A);
+const priceyTwin = similarity(costTwin(1), A);
+assert(cheapTwin.components.cosine !== priceyTwin.components.cosine,
+  'cost now influences cosine (was a dead dimension below $0.999)');
+assert(priceyTwin.components.cosine < cheapTwin.components.cosine,
+  'a same-shaped harness with a higher cost is less similar to a cheap one');
+
+console.log('\nPhase 7c — verdictFor + VERDICT_THRESHOLDS (single source of truth)');
+assert(VERDICT_THRESHOLDS.length === 4, 'four verdict bands');
+assert(VERDICT_THRESHOLDS.every((b, i) => i === 0 || b.min < VERDICT_THRESHOLDS[i - 1].min),
+  'bands are ordered highest-first');
+const LAST_BAND = VERDICT_THRESHOLDS[VERDICT_THRESHOLDS.length - 1];
+assert(LAST_BAND.min === Number.NEGATIVE_INFINITY,
+  'final band is unbounded so verdictFor always returns a verdict');
+assert(verdictFor(1) === 'near-identical', 'overall 1 → near-identical');
+assert(verdictFor(0.95) === 'near-identical', 'boundary 0.95 → near-identical (inclusive)');
+assert(verdictFor(0.9499) === 'minor-drift', 'just below 0.95 → minor-drift');
+assert(verdictFor(0.85) === 'minor-drift', 'boundary 0.85 → minor-drift (inclusive, the documented floor)');
+assert(verdictFor(0.8499) === 'moderate-drift', 'just below 0.85 → moderate-drift');
+assert(verdictFor(0.5) === 'moderate-drift', 'boundary 0.5 → moderate-drift (inclusive)');
+assert(verdictFor(0.4999) === 'major-drift', 'just below 0.5 → major-drift');
+assert(verdictFor(0) === 'major-drift', 'overall 0 → major-drift');
+// Regression: audit-trend.mjs used to inline a 0.80 minor-drift floor while
+// docs/metaharness-user-guide.md documented 0.85. 0.80 must resolve to
+// moderate-drift now that the bands live in one place.
+assert(verdictFor(0.80) === 'moderate-drift',
+  '0.80 resolves via the shared bands (was a divergent inline 0.80 floor in audit-trend.mjs)');
+
+console.log('\nPhase 7d — verdict on the similarity() return shape');
+assert(typeof sAA.verdict === 'string', 'similarity() includes a verdict string');
+assert(sAA.verdict === 'near-identical', 'self-match verdict is near-identical');
+assert(sPD.verdict === verdictFor(sPD.overall),
+  'similarity().verdict agrees with verdictFor(overall)');
+
 console.log('\nPhase 8 — round-trip with the iter-35 spike fixtures (regression anchor)');
 // Hard-coded spike numbers from `_spike-similarity.mjs` — ANY change
 // here means the production module drifted from the spike's frozen

package/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.

package/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

package/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.

package/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

package/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).
+# ---------------------------------------------------------------------------

package/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 `ruflo@3.48.0`), 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`.

package/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
+          }
+        ]
+      }
+    ]
+  }
+}

package/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
+)