---
slug: "grok-swarms"
source_type: "skill_md"
source_url: "https://cdn.jsdelivr.net/gh/am423/grok-swarms@main/SKILL.md"
repo: "https://github.com/am423/grok-swarms"
source_file: "SKILL.md"
branch: "main"
---
---
name: grok-swarms
description: Use when orchestrating complex multi-agent projects. A Grok 4.3 orchestrator plans with the human then dispatches swarms of optimal Grok executors in isolated TMUX sessions using native Hermes kanban for assignment, progress, and approve/kick-back review loops.
license: MIT
metadata:
  version: "0.1.0"
  author: r0b0tlab
  tags: [multi-agent, tmux, kanban, grok, orchestration, swarms]
  related_skills: [tmux-agent-teams, hermes-agent, writing-plans, kanban-orchestrator]
---

# Grok Swarms

Grok Swarms turns Hermes into a high-scale orchestrator for Grok-powered agent teams. A single Grok 4.3 instance acts as the human-facing planner and reviewer. It dispatches focused Grok executors (choosing the best model variant per task) inside dedicated tmux windows, each with its own kanban task, isolated workspace, and strict review gate.

Load this skill when you see triggers like: "swarm", "multi-agent team", "orchestrator", "dispatch executors", or "kanban review loop".

## When to Use
- Large feature implementations, research projects, or refactorings that benefit from parallel specialized agents
- You want Grok 4.3 quality planning + review while keeping execution cheap/fast with smaller Grok variants
- You already use Hermes kanban and tmux-agent-teams patterns and want a Grok-specific variant
- Projects where you need explicit "approve or kick-back with instructions" loops

Do not use for simple one-off tasks or when you prefer a single agent.

## Core Workflow

1. **Plan Phase (Orchestrator + Human)**
   - Orchestrator loads `writing-plans` or `kanban-orchestrator` patterns
   - Collaborates with you to produce a numbered task list with clear success criteria
   - Creates kanban board entries via the `kanban` tool (or `/kanban create`)

2. **Dispatch Phase**
   - For each task the orchestrator chooses the optimal Grok model (4.1 for simple work, 4.3 for complex reasoning, etc.)
   - Spawns an isolated executor:
     ```bash
     tmux new-session -d -s grok-exec-01 -x 120 -y 40 \
       'hermes -p grok-executor chat'
     ```
   - Injects task + kanban ID + acceptance criteria
   - Sets `HERMES_KANBAN_TASK` and `HERMES_KANBAN_BOARD` so the agent only sees its work

3. **Execution (Grok Executors)**
   - Each executor works autonomously inside its tmux pane
   - Uses kanban tools to report status (`kanban_heartbeat`, `kanban_comment`)
   - On completion calls `kanban_complete` and posts a summary

4. **Review Loop (Orchestrator)**
   - Orchestrator polls kanban or receives the completion notice
   - Reviews against acceptance criteria
   - Either marks complete or issues `kanban_block` with exact correction instructions
   - Executor fixes and resubmits

## TMUX + Kanban Integration

See `references/tmux-spawn-patterns.md` and `references/kanban-review-loop.md` for exact commands and lifecycle.

## Profile & Model Setup (Load references/grok-model-config.md when creating profiles)

Recommended: one orchestrator profile (Grok 4.3) and one or more executor profiles. The orchestrator dynamically picks the best model per task.

## Scripts

Helper scripts live in `scripts/`. Source them from the orchestrator session when needed.

## References (load only when needed)

- `references/kanban-review-loop.md` — full approve / kick-back protocol
- `references/tmux-spawn-patterns.md` — spawn commands and env isolation
- `references/grok-model-config.md` — profile YAML examples
- `references/acceptance-criteria-template.md` — reusable task definition template

## Common Pitfalls
- Forgetting `HERMES_KANBAN_TASK` per executor → agents collide on the board
- Same profile/model for orchestrator and executors → loses cost/quality split
- Skipping the kick-back comment → executors don't know what to fix
- Not using `-w` (worktree) when editing the same repo → git conflicts
- Leaving tmux sessions running after project end
- Executor tmux session dies or crashes mid-task → use `tmux capture-pane` + re-spawn with same kanban task ID and resume from last heartbeat comment

## Verification Checklist
- [ ] Kanban board initialized (`hermes kanban init`)
- [ ] Orchestrator and executor profiles created
- [ ] First task dispatched and visible in `hermes kanban list`
- [ ] Executor shows correct model via `/model`
- [ ] Review loop tested end-to-end (block → fix → complete)
- [ ] All sessions cleaned up on project end

## Quick Start

```bash
/skill grok-swarms
"Start a new grok-swarm for <goal>. Build the plan then dispatch the first executors."
```