Practical patterns, starters & CLI tools for loop engineering with AI coding agents. Design systems that prompt and orchestrate agents (inspired by Addy Osmani and Boris Cherny). Includes loop-audit, loop-init, loop-cost.
TypeScript agentic-aiai-agentsai-codinganthropicautomationclaudeclaude-codecodexcoding-agentsdevops-automationdevtoolsgithub-actionsgrokllmloop-engineeringmcpprompt-engineering
docs: add loop-swarm subsection to QUICKSTART (#424) (#431)
Muhammad Zeshan Malikc56129d60752
diff --git a/docs/QUICKSTART.md b/docs/QUICKSTART.mdindex d02c04b..5ceeb30 100644--- a/docs/QUICKSTART.md+++ b/docs/QUICKSTART.md@@ -305,6 +305,19 @@ git apply .loop-sandbox/patches/<patch-id>.patch>> **Safety note:** `loop-sandbox` provides worktree isolation, but process execution retains OS-level filesystem and network access — see [docs/safety.md](./safety.md). Always inspect patch files before running `git apply`.+### Multi-agent consensus sandboxing (`loop-swarm`)++For high-confidence L3 operations, `loop-swarm` ([tools/loop-swarm/README.md](../tools/loop-swarm/README.md)) runs an agent command multiple times sequentially across `N` (default: 3) isolated `loop-sandbox` worktrees. It hashes the resulting `.patch` files and verifies that a majority produced byte-identical changes before writing a consensus patch to `.loop-sandbox/patches/consensus.patch`.++If an agent produces non-deterministic edits, `loop-swarm` acts as a consensus safety net by accepting only changes independently reproduced across runs.++```bash+# Run multi-agent consensus across 3 sequential sandboxes+npx @cobusgreyling/loop-swarm run --count 3 -- <agent-cmd>+```++> **Limitations & Safety:** Runs are serialized sequentially to maintain safety guarantees on the manifest (~N× longer execution), shared stdio, and `SIGINT` signals exit the entire process. `loop-swarm` provides git worktree isolation rather than OS-level container isolation — see [docs/safety.md](./safety.md).+## Copy-paste cheat sheet```bash@@ -338,6 +351,9 @@ npx @cobusgreyling/loop-worktree cleanup --older-than 24h# Ephemeral worktree isolation + patch capturenpx @cobusgreyling/loop-sandbox run -- <command>npx @cobusgreyling/loop-sandbox review++# Multi-agent consensus sandboxing across sequential sandboxes+npx @cobusgreyling/loop-swarm run --count 3 -- <agent-cmd>```## Learn the why (optional, 10 minutes)diff --git a/docs/safety.md b/docs/safety.mdindex 06353dd..bbe5de9 100644--- a/docs/safety.md+++ b/docs/safety.md@@ -106,4 +106,9 @@ For runtime enforcement, define constraints in `loop-constraints.md` at the projThe `loop-constraints` skill reads this file at the start of every loop run and enforcesevery rule. Template: [templates/loop-constraints.md](../templates/loop-constraints.md).-Tool examples: [Grok](../examples/grok/constraints.md) · [Claude Code](../examples/claude-code/constraints.md) · [Codex](../examples/codex/constraints.md)\ No newline at end of file+Tool examples: [Grok](../examples/grok/constraints.md) · [Claude Code](../examples/claude-code/constraints.md) · [Codex](../examples/codex/constraints.md)++## Worktree Isolation & Consensus Sandboxing++- `loop-sandbox`: Ephemeral git worktree isolation for single agent runs. Captures changes as reviewable patch files before applying. See [tools/loop-sandbox/README.md](../tools/loop-sandbox/README.md).+- `loop-swarm`: Multi-agent consensus sandboxing across sequential `loop-sandbox` runs. Requires byte-identical patch consensus across runs before accepting edits. See [tools/loop-swarm/README.md](../tools/loop-swarm/README.md) and [Quickstart](./QUICKSTART.md#multi-agent-consensus-sandboxing-loop-swarm).\ No newline at end of filediff --git a/tools/loop-swarm/README.md b/tools/loop-swarm/README.mdindex a213028..ef433f7 100644--- a/tools/loop-swarm/README.md+++ b/tools/loop-swarm/README.md@@ -15,6 +15,8 @@ If an agent produces non-deterministic results, `loop-swarm` acts as an L3 safetnpx @cobusgreyling/loop-swarm run --count 3 -- npx my-agent run --task "Refactor utils.ts"```+See [Quickstart](../../docs/QUICKSTART.md#multi-agent-consensus-sandboxing-loop-swarm) for workflow examples and command patterns.+## How it works1. Spawns `N` (default: 3) instances of `loop-sandbox` sequentially (to prevent git worktree and signal handler races).