Grok-Heavy Team — a Claude Code /team skill

A /team skill for Claude Code that runs a task as a grok-heavy multi-agent team on one governing principle: Anthropic decides, Grok builds. Claude (Fable 5) plans and integrates and opus owns the tough calls (standing decision authority); a persistent Grok master audits the plan, audits the execution, and tests the built program — spawning up to 10 slave auditors/researchers as needed; an execution master fans the build out to up to 16 fast Grok executors, and hard/risky subtasks are built by 3 blind redundant Grok attempts (adjudicated on evidence) instead of one slow Claude lane. The verify loop runs up to 3×, then asks you. While a task is active, follow-up prompts auto-continue in team mode — no need to retype /team.

Have the Cursor CLI too? Answer one setup question and the team pairs grok:cursor 1:1 — cross-family blind races, an advisory Cursor assistant on each master, and supercharged verify cycles. Don't have it, or don't want it? Say no and nothing changes — this README describes that path throughout. See Optional: Cursor.

This is the grok-heavy edition. It leans on Grok for almost everything — the persistent master + 10 slaves, the 16-wide executor pool, all research, all testing, and Grok Imagine for UI mockups. It expects a generous Grok plan (SuperGrok Heavy / X Premium+). If your Grok usage is limited, use the lighter claude-team-skill instead, which uses Grok only for lightweight plan-audit and verification.

The payoff: Ultracode-like multi-agent coverage while sparing your Claude plan. Almost all the compute — building, auditing, testing, research, image concepts — rides your Grok subscription; your Claude tokens go mostly to planning, dispatch, and integration.

                     ┌─────────────────────────────────────┐
                     │  your Claude Code session (Fable 5)  │
                     │  ORCHESTRATOR · plan · integrate · git│
                     └───┬───────────────┬──────────────┬───┘
        PLAN.md / specs  │               │              │  diff + summaries
                         ▼               ▼              ▼
     ┌───────────────────────────┐  ┌─────────────┐  ┌──────────────────────────┐
     │ EXECUTION MASTER (Claude) │  │ GROK MASTER │  │  verify loop, max 3×      │
     │ decomposes + dispatches   │  │ grok-4.5    │  │  findings ─► rework ─►    │
     │        │  up to 16         │  │ PERSISTENT  │  │  re-test on same master  │
     │        ▼                  │  │  · plan audit                            │
     │ ┌────────────────────┐    │  │  · exec audit  ┌───────────────────────┐ │
     │ │ GROK EXECUTORS ×≤16 │    │  │  · tester (API)│ SLAVES ×≤10 (subagents)│ │
     │ │ grok-4.5, worktrees │    │  │  · UI Imagine  │ research OR review,   │ │
     │ │ hard: 3 blind race  │    │  │  · adjudicate  │ close when done       │ │
     │ │ close when done     │    │  │  stays open    └───────────────────────┘ │
     │ └────────────────────┘    │  └─────────────┘                            │
     │ (opus = DECISIONS: spec   │                                             │
     │  calls + adjudication;    │                                             │
     │  Claude lanes = fallback) │                                             │
     └───────────────────────────┘                                             │

Everything is roster-driven: one JSON file defines the members, caps, roles, design rules, and binding policies. Add or remove models by editing JSON — the skill never hardcodes a member.

What makes it grok-heavy

• A persistent Grok master. One Grok session stays open for the whole task (context caching) and wears five hats: plan auditor, execution auditor, tester, UI visualizer, and routine adjudicator. It decides how to deploy up to 10 slave subagents — each either researches an unknown or reviews a slice — then consolidates and reports.
• A 16-wide Grok executor pool. A Claude execution master decomposes the build for maximum lane count (test/gate code always splits off the algorithm lane) and dispatches it to up to 16 Grok executors running in isolated worktrees.
• Redundant races instead of Claude lanes. A hard/risky subtask gets its subtle part authored into the spec by opus (the standing decision authority), then 3 blind Grok attempts build the identical spec in separate worktrees. An adjudicator that authored none of them picks or merges on evidence; Claude executor tiers are only the fallback when a race cannot converge.
• It tests what it builds. Every program is expected to expose an API, so the Grok master runs the built program headlessly and drives its API to confirm each feature actually works — capturing screenshots for visual features and comparing them to the approved mockup.
• Grok Imagine UI gate. For any UI, the master renders concept mockups and a candidate app icon with Grok's in-session image_gen tool, and you approve the look before a line of feature code is written. Iterate on the mockup, not on shipped code.
• Pipelined per-lane audits + thrift reports. As each build lane finishes, the execution master hands it to the persistent Grok master for an independent audit slice (serialized, one master owner via _team/MASTER-OWNER). Full detail lives in _team/reports/ files; channel replies stay ~15 lines.
• Per-lane verify under a whole-phase cap. Dirty lanes rework once per cycle; clean lanes stay closed. Cap is caps.verify_loops (3) per phase, then it asks you rather than looping forever.
• HARD RULE — orchestrator never implements. During EXECUTE/VERIFY the session only plans, dispatches, and reviews. Build work goes to lanes; the cost ladder ends at "ask the user," not "I'll just fix it inline."
• Everything-visible dispatch. When Agent Switchboard is installed, long-running work (executors, spike bees, detached exec-master / Claude tiers) is dispatched as tracked lanes via agent-dispatch (--exec grok-ask or --exec claude-ask).
• Auto-continue team mode (session-scoped). A UserPromptSubmit hook keeps a project flowing through the protocol across follow-up prompts until you say "exit team mode" — per session, so a second window cannot inherit another session's task.

Design defaults

Baked into the roster's coordinator_focus charter and design_rules: UIs are dark mode with no emojis, run the Grok Imagine approval gate first, and every app ships a custom Grok-Imagine icon that fits its purpose; consistent button alignment / color / spacing with design notes left for the next agent; seamless animation; multi-threaded compute; Apple Silicon first.

Live team reports

The skill narrates the run in real time — you watch the models disagree, not just read about it afterward: the Grok audit verdict and every risk/gap/contradiction, which findings the orchestrator accepted vs rejected, each executor starting and finishing, each test verdict as it lands, and every rework cycle.

Install

The shipped roster is the author's reference setup, model-to-model and prompt-to-prompt: Fable 5 orchestrating, a Claude execution master, Grok 4.5 as the master auditor/tester and the executor pool, and opus/sonnet/haiku as direct executors for hard/risky/trivial subtasks.

1. Grok Build CLI (the master, executors, and Imagine)

Requires a SuperGrok Heavy or X Premium+ subscription (macOS or Linux):

curl -fsSL https://x.ai/cli/install.sh | bash
grok login          # authenticate with your X / xAI subscription (no API key)

Grok Imagine (UI mockups + icons) needs Grok Build CLI ≥ 0.2.102 — update with ~/.grok/bin/grok update if needed. Verify: ~/.grok/bin/grok --version.

2. claude-grok-bridge (the grok-ask wrapper the roster invokes)

git clone https://github.com/BlinkingSun/claude-grok-bridge.git
cd claude-grok-bridge && ./install.sh

Installs the bridge to ~/grok-bridge/bin/grok-ask — persistent channels, consult/worker safety modes, native subagents, full audit logs.

3. This skill

git clone https://github.com/BlinkingSun/claude-team-grok-heavy.git
cd claude-team-grok-heavy && ./install.sh

The installer copies the skill (+ prompt templates) to ~/.claude/skills/team/, seeds ~/agent-team/ with the roster and bridges, and registers the auto-continue hook in ~/.claude/settings.json (idempotent; backs the file up first; pass --no-hook to skip). It never overwrites an existing team.json.

It also asks one optional question: do you have the Cursor CLI? Answer no (or say nothing) and everything below runs exactly as it always has. Answer yes and you get the paired protocol — see Optional: Cursor.

Then, inside any Claude Code session:

/team build a small menu-bar app that shows disk usage, dark mode, with an icon

Follow-ups continue in team mode automatically until you say "exit team mode".

4. Optional: Cursor

Entirely optional, and off unless you turn it on. Grok remains the build muscle; Cursor is a second free-at-the-margin pool that lets the team run two model families against the same work.

The installer asks once (--cursor / --no-cursor to answer up front). If it can't ask — a piped install, CI — it leaves the question unanswered and /team asks you in-session, once, before it plans anything, then records your answer in ~/agent-team/team.json under cursor.enabled.

cursor.enabled	What /team does
false	Nothing changes. Every Cursor block in the skill is ignored; the protocol is the grok-only edition, unmodified.
true	Builders are dispatched 1:1 grok:cursor; hard/risky subtasks are built by a cross-family blind race (4 attempts, 2 per family, blind to each other and to which family their siblings are); each master beneath the planner gets an advisory Cursor assistant doing live plan-conformance checks; the verify cap rises to 4, and cycles 3–4 are supercharged (grok + cursor + opus in parallel on the same failing lane, then adjudicated).
null / missing	Unanswered — the skill asks you.

If you say yes, the installer drops the cursor-ask bridge into ~/cursor-bridge/bin/ (override with $CURSOR_BRIDGE_DIR). It exposes the identical interface to grok-ask (-c -n -w -d -m -f -t -j --status --channels), which is the whole reason the integration is small: every dispatch, wait, channel and re-dispatch rule in the skill applies to a Cursor lane unchanged — only --exec differs. It also scrubs CLAUDE_* from the worker's environment, without which a worker can resolve "the current directory" to a Claude-Code scratchpad and write outside the worktree it was handed.

You need the Cursor CLI itself, on your Cursor subscription login:

curl https://cursor.com/install -fsS | bash
cursor-agent login          # never set CURSOR_API_KEY

Turning it back off later is one key: set cursor.enabled to false (and enabled: false on the cursor-executor, cursor-assistant and blind-race members), or just re-run ./install.sh --no-cursor. The skill also fails safe — if the gate says true but the bridge or CLI is missing, it says so and runs the grok-only protocol for that session rather than dispatching lanes that would refuse.

5. Optional: Agent Switchboard (recommended)

Agent Switchboard gives every executor a tracked "lane" with derived liveness, and replaces blind polling with event-driven waits. The skill detects it by presence and upgrades its Step 3 dispatch behavior automatically; without it, everything still works the classic way.

Why you want it — measured on a real 7-hour overnight team build:

• Sleep-poll waste eliminated. The execution master had spent 309 of its 448 minutes blocked in blind sleep 30 polling loops; with the switchboard it blocks on one event-driven switchboard wait and reviews each executor the moment it finishes.
• Silent deaths caught in seconds, not half-hours. A worker killed mid-flight (crash, OOM, harness kill) sat undetected for ~70 minutes because its log read "still running." Derived liveness (pids + session-file activity — workers never have to heartbeat) flags it as DIED within a poll tick, with ORPHAN/QUIET/CORRUPT for the subtler failure modes.
• Capacity backpressure. The per-task executor cap is enforced at dispatch (lock-serialized, refusal = exit 2) instead of honor-system counting.
• A live dashboard. Optional daemon (127.0.0.1:17920) plus a native dark-mode viewer (macOS DMG on its releases page; Windows buildable) that stays readable at 100+ concurrent lanes across several team tasks.

Install (Python 3.9+ stdlib only, macOS/Linux/Windows):

git clone https://github.com/BlinkingSun/agent-switchboard.git ~/agent-switchboard
export PATH="$HOME/agent-switchboard/bin:$PATH"   # add to your shell profile
bash ~/agent-switchboard/tests/sb_test.sh          # optional: 29-check self-test
python3 ~/agent-switchboard/bin/switchboard serve  # optional: daemon for the viewer

Autostart templates (launchd / systemd / Task Scheduler) ship in its service/ directory; harness recipes beyond this skill are in its INTEGRATIONS.md.

Requirements

• Claude Code CLI (claude) installed and authenticated.
• python3 and perl on PATH (both ship with macOS; standard on Linux).
• Grok Build CLI + claude-grok-bridge (steps 1–2), on a generous Grok plan. Without Grok, the skill falls back to Claude tiers for audit/test/execute and tells you — at which point the lighter claude-team-skill is the better fit.
• Optional: Cursor CLI (cursor-agent) on a Cursor subscription, if you want the paired protocol. Not required, and not assumed.

How a run works

1. PLAN — the orchestrator decomposes the task, writes a SPEC.md per subtask and a master PLAN.md, and may spawn Grok worker bees as spike-* switchboard lanes to research unknowns (reaped before build fan-out).
2. UI GATE (if any UI) — the Grok master renders mockups + an app icon with Grok Imagine; you approve the look before features are built.
3. AUDIT — the persistent Grok master audits PLAN.md (spawning up to 10 slaves for research/review), writing _team/reports/plan-audit.md and a ≤15-line reply (verdict, risks, gaps, executor picks, splits). Capped at 2 audit cycles. 3a. TOUGH DECISIONS — opus (the standing decision authority) authors the hard part of any flagged spec — the algorithm, formula, contract, or trade-off — into SPEC.md + _team/reports/DECISION-<topic>.md before the build starts, and fires again whenever a tough_decision_triggers case comes up.
4. EXECUTE — the Claude execution master dispatches the build to up to 16 Grok executors in isolated worktrees (everything-visible via agent-dispatch when the switchboard is installed). Hard/risky subtasks run as 3-way blind redundant races on the opus-authored spec, adjudicated on evidence; Claude tiers are the fallback when a race cannot converge. As each BUILD lane lands, the exec-master pipelines a per-lane master audit (RESCAN + MASTER-OWNER; spike lanes skip audits).
5. PHASE-END GATE + TEST — after every expected audit-<lane>.md exists, the same Grok master does cross-lane consistency + runs the program's API headlessly, screenshotting visual features against the mockup (FINDINGS-0.md).
6. VERIFY LOOP — dirty lanes rework once per cycle under the phase cap; re-test on the same master channel; up to 3 cycles, then it asks you.
7. INTEGRATE — the orchestrator reviews the final diff, merges, runs the real build/tests, integrates the icon, commits per your rules, and reports what each member did and caught. Then team-cleanup reaps Grok daemons.

The roster (~/agent-team/team.json)

Role	Default	Notes
orchestrator / planner	fable (the current session)	ALWAYS the planner; plans, dispatches, integrates; owns git/sign/deploy
decision_authority	opus	authors the hard part of a spec; every tough_decision_triggers case
plan_master · execution_auditor · tester · ui_visualizer · researcher	grok-master	one persistent master-<task> channel; spawns ≤10 slaves
adjudicator_routine / adjudicator_contested	grok-master / opus	picks the winner of a redundant race, on evidence
execution_master	sonnet (Claude)	maximizes lane count, dispatches + reviews the executor pool
executor_pool	grok-executor ×≤16	fast bulk build in isolated worktrees
executor_direct.hard/risky/trivial	grok-redundant / grok-redundant / grok-executor	hard/risky → opus decision + blind Grok race; _fallback (opus/sonnet) only when a race cannot converge

Caps live in caps (slave_auditors: 10, grok_executors: 16, grok_redundancy: 3, verify_loops: 3).

The Cursor gate. Top-level cursor.enabled decides which shape the skill runs (see Optional: Cursor). While it is false the roster above is the whole roster: cursor-executor, cursor-assistant and blind-race ship enabled: false, and every key ending _with_cursor is inert. Flip the gate to true (and those three members with it) and one mechanical rule applies — <key>_with_cursor replaces <key>: executor_pool_with_cursor [grok-executor, cursor-executor], blind_race_attempts_with_cursor: 4, grok_executors_with_cursor: 32 (both pools plus audit-*/assist-*/spike-* lanes, doubled so pairing doesn't halve grok width), verify_loops_with_cursor: 4 with verify_supercharge_from_cycle: 3. Nothing else about the roster changes.

Editing the layout:

• Add a model — add a members[] block: name, provider, model, invoke.method (agent-tool | claude-ask | grok-ask | current-session), strengths, budget, enabled: true.
• Remove/bench a model — set enabled: false. Fallbacks live in policies.
• Change caps / rewire roles — edit caps or repoint assignment.
• Swap the second model — Grok is the default, not a hard requirement. Wrap any CLI to expose the same interface (-c channel, -w worker, -d cwd, -f attach, text on stdout), drop it in ~/agent-team/bin/, and point the roles at it. (Note: the UI-Imagine and native-subagent features are Grok-specific.)

Design invariants the skill enforces regardless of layout: every plan is audited before execution (master advises, orchestrator decides); the auditor/tester is never the member that wrote the code and is read-only on it; workers only in scratch/worktrees; only the orchestrator commits/signs/deploys; UIs are dark-mode, emoji-free, and go through the Grok Imagine approval gate.

Auto-continue team mode (session-scoped, v2)

bin/team-mode-hook.py is a UserPromptSubmit hook the installer registers in ~/.claude/settings.json. When you type /team, the hook writes ~/agent-team/state/active-<session_id> for this session only — a /clear or a second window cannot inherit another session's team task. While the flag exists, every prompt is routed through the skill. Plain-language toggles: "exit team mode" deactivates only this session; "enter team mode" forces it on.

A pre-v2 global state/active is still honored for back-compat, but the reminder warns it may belong to a different session and names a per-session detach marker. Orchestrator identity is not assumable: a session that finds an in-flight task after context loss must verify ownership (live processes, switchboard trail, _team records) before dispatching or adjudicating — never auto-accept work done under assumed authority.

To remove the hook: delete the UserPromptSubmit entry from ~/.claude/settings.json (the installer left a .bak), or run ./install.sh --no-hook on a fresh machine.

Memory hygiene

Slaves and executors close when their task finishes (Grok bridge calls are one-shot; native subagents die with their parent). Only the master channel persists, for context caching. At integrate, ~/agent-team/bin/team-cleanup reaps stray Grok "leader" daemons and clears finished channel state; --exit also leaves team mode. It is run at the end of a task, never mid-task (that would drop the master's warm cache).

Token economics

• Grok 4.5 (master, slaves, executor pool, research, testing, Imagine) rides your Grok plan — free from the Claude budget's perspective. This edition pushes as much as possible onto Grok on purpose.
• Your Claude plan is spent mostly on planning (Fable), dispatch (the execution master), integration, and opus decisions — short, high-leverage spec calls and adjudications, not bulk implementation. Claude executor lanes are the fallback of last resort, not the answer to "this looks hard".
• Headless claude -p calls (via the bundled claude-ask) are metered like any session; per-call cost is logged to ~/agent-team/logs/<channel>.jsonl.

Layout

skill/SKILL.md              the /team protocol       -> ~/.claude/skills/team/
skill/references/prompts.md per-actor prompt templates -> ~/.claude/skills/team/references/
team.json                   roster template          -> ~/agent-team/
bin/claude-ask              headless Claude bridge    -> ~/agent-team/bin/
bin/team-mode-hook.py       auto-continue hook        -> ~/agent-team/bin/  (registered in settings.json)
bin/team-cleanup            end-of-task memory hygiene-> ~/agent-team/bin/
bin/cursor-ask              headless Cursor bridge    -> ~/cursor-bridge/bin/  (only if you enable Cursor)
install.sh                  installer
CHANGELOG.md                release history

License

MIT — see LICENSE.