grok-workflows

grok-workflows

Dynamic workflows for Grok Code (the grok CLI).

A small, dependency-free orchestration engine that lets you build multi-agent harnesses on top of Grok's headless mode — fan-out, pipelines, tournaments, adversarial verification, and loop-until-done — plus a library of ready-to-run harnesses you can invoke from the command line or as Grok slash-commands.

It's the Grok analog of Claude Code's built-in dynamic workflows: instead of one agent planning and executing in a single context window, you spawn many focused Grok agents, each with its own fresh context, and coordinate them with plain JavaScript.

---

Why

When a single agent plans and executes a long, parallel, or adversarial task in one context window, three failure modes creep in:

• Agentic laziness — it stops at 35 of 50 items and calls it done.
• Self-preferential bias — it rates its own output highly when asked to judge it.
• Goal drift — the original objective decays across compactions.

Giving each unit of work its own Grok process — its own context window, its own goal — structurally defeats all three. A deterministic JS loop holds the structure; the agents just do the focused work. That is what this engine provides.

Every agent here is a real grok -p … --output-format json --yolo child process. Nothing about the orchestration is magic — it's child_process + a concurrency limiter + the patterns from the Claude Code dynamic-workflows playbook, ported to Grok's CLI.

---

Requirements

• Node ≥ 18 (uses only node:* built-ins; zero npm dependencies).
• The grok CLI on your PATH and authenticated (grok login, or set XAI_API_KEY). See Grok's headless-mode docs.
  • Point at a specific binary with GROK_BIN=/path/to/grok if it's not on PATH.

You do not need an API key to develop or test the orchestration logic — see Testing without spending credits.

---

Quick start

git clone https://github.com/lswank/grok-workflows
cd grok-workflows

# list the bundled harnesses
node src/cli.mjs list

# run one
node workflows/deep-research.mjs "Did Postgres add MERGE in v15 or v16?"
node workflows/sort-tournament.mjs "severity :: login broken | typo in footer | data loss on save"
node workflows/triage.mjs ./incidents.txt

Each harness prints a JSON result to stdout; progress narration goes to stderr (silence it with GROK_WORKFLOWS_QUIET=1).

---

The bundled harnesses

Harness	What it does	Core pattern
deep-research	Fan out web searches, fetch sources, adversarially verify each claim, synthesize a cited report.	fan-out + verify
deep-verify	Extract every factual/technical claim from a doc and verify each against the codebase and/or web. (Per-claim investigator/auditor isolation is prompt-only + disallowedTools:['Agent']; see src/SPEC.md for the documented tradeoff.)	fan-out + adversarial verify
sort-tournament	Rank a list by a qualitative criterion via pairwise comparison (beats absolute scoring).	tournament
root-cause	Generate competing hypotheses from disjoint evidence, test each against a panel until one survives. (Lane isolation between the 3 evidence slices is prompt-only + disallowedTools:['Agent']; code lane needs repo reads via shell — see src/SPEC.md for the explicit assumption + guardrails.)	multi-hypothesis + loop-until-done
triage	Classify each backlog item, dedupe against what's tracked, route to fix or escalation (with quarantine).	classify-and-act
migrate	Discover change sites, fix each in an isolated worktree, adversarially review, report.	fan-out + worktree isolation
rule-mine	Mine recurring corrections from past sessions/reviews, cluster, verify, distill into AGENTS.md rules.	generate-and-filter
brainstorm-tournament	Brainstorm many options (names, designs), run a rubric-scored tournament, return the top 3.	generate + tournament
eval-skill	Run a task N ways in isolated worktrees, grade against a rubric, pick and explain the best.	best-of-N + grading
goal	Repeat an inner workflow/task until an independent checker agent confirms a hard, explicit criterion is met (first-class implementation of the "pair with /goal" pattern).	loop-until + adversarial checker
loop	Run any other harness (or a plain agent task) on a fixed interval (10s / 5m / 1h ...), with --max and dry-streak stopping. Composes with /goal.	recurring scheduler + delegation
write-workflow	Describe a novel multi-agent process; Claude writes a complete, saveable, reusable .mjs harness using the engine primitives, executes it immediately for today's task, and returns the source so you can persist it.	dynamic script generation (the heart of "Claude writes the orchestration")