Imported from am423/grok-swarms (SKILL.md). Install upstream with npx skills add am423/grok-swarms. Copyright stays with the author (MIT).

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:

     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

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