Skip to content

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.

docs: expand Help wanted with swarm, MiniMax, lock, sandbox story (#429)

Cobus Greyling1a10ca76586a
diff --git a/README.md b/README.md
index a374d98..f298d0d 100644
--- a/README.md
+++ b/README.md
@@ -301,12 +301,14 @@ Addy Osmani:
**First PR?** Pick one open issue below. Stories and adopters get **same-day review** when possible. See [CONTRIBUTORS.md](CONTRIBUTORS.md) and the [contributor quickstart](https://github.com/cobusgreyling/loop-engineering/discussions/123).
-**6 open** [`good first issue`](https://github.com/cobusgreyling/loop-engineering/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22)s (refreshed 2026-07-29). Comment **"I'll take this"** for assignment.
+**11 open** [`good first issue`](https://github.com/cobusgreyling/loop-engineering/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22)s (refreshed 2026-07-29). Comment **"I'll take this"** for assignment.
| Time | Issue | What you ship |
|------|-------|---------------|
| ~10 min | [#120 — Adopters list](https://github.com/cobusgreyling/loop-engineering/issues/120) | One row in `docs/adopters.md` (or [Add Adopter](https://github.com/cobusgreyling/loop-engineering/issues/new?template=add-adopter.yml) template) |
-| ~15–20 min | [#118 — Daily Triage story](https://github.com/cobusgreyling/loop-engineering/issues/118) · [#173 — Issue Triage story](https://github.com/cobusgreyling/loop-engineering/issues/173) · [#119 — PR Babysitter failure](https://github.com/cobusgreyling/loop-engineering/issues/119) | Honest `stories/` write-up + index row |
+| ~15–20 min | [#118 — Daily Triage story](https://github.com/cobusgreyling/loop-engineering/issues/118) · [#173 — Issue Triage story](https://github.com/cobusgreyling/loop-engineering/issues/173) · [#119 — PR Babysitter failure](https://github.com/cobusgreyling/loop-engineering/issues/119) · [#427 — loop-sandbox story](https://github.com/cobusgreyling/loop-engineering/issues/427) | Honest `stories/` write-up + index row |
+| ~20–25 min | [#425 — MiniMax foundry flags](https://github.com/cobusgreyling/loop-engineering/issues/425) · [#426 — worktree lock import](https://github.com/cobusgreyling/loop-engineering/issues/426) | Additive QUICKSTART notes for MiniMax + public `loop-worktree/lock` |
+| ~25–30 min | [#424 — loop-swarm QUICKSTART](https://github.com/cobusgreyling/loop-engineering/issues/424) · [#428 — budget-negotiator docs](https://github.com/cobusgreyling/loop-engineering/issues/428) | Discoverability for swarm consensus + L3 budget negotiation |
| ~40–45 min | [#387 — Hermes CI Sweeper](https://github.com/cobusgreyling/loop-engineering/issues/387) · [#388 — Hermes Issue Triage](https://github.com/cobusgreyling/loop-engineering/issues/388) | Fill pattern-coverage gaps in `examples/hermes/` |
| Anytime | Templates | [Add Adopter](https://github.com/cobusgreyling/loop-engineering/issues/new?template=add-adopter.yml) · [Share a story](https://github.com/cobusgreyling/loop-engineering/issues/new?template=share-story.yml) |
| Hubs | Discussions | [Show your loop](https://github.com/cobusgreyling/loop-engineering/discussions/326) · [Ask anything](https://github.com/cobusgreyling/loop-engineering/discussions/327) |
diff --git a/scripts/create-good-first-issues.sh b/scripts/create-good-first-issues.sh
index 7532204..827cd4a 100755
--- a/scripts/create-good-first-issues.sh
+++ b/scripts/create-good-first-issues.sh
@@ -72,4 +72,10 @@ create_issue "Share a Changelog Drafter week-one story" "good first issue,story"
create_issue "Harden loop-action command invocation (safe quoting)" "good first issue,tooling" "$BODY_DIR/harden-loop-action-command.md"
echo "Done. Open backlog:"
-echo "https://github.com/cobusgreyling/loop-engineering/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22"
\ No newline at end of file
+echo "https://github.com/cobusgreyling/loop-engineering/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22"
+# Wave 5 — post 2026-07-29 tools (swarm, MiniMax, lock API, sandbox stories)
+create_issue "Add loop-swarm subsection to QUICKSTART" "good first issue,docs" "$BODY_DIR/quickstart-loop-swarm.md"
+create_issue "Add MiniMax foundry flags to QUICKSTART" "good first issue,docs" "$BODY_DIR/quickstart-minimax-foundry.md"
+create_issue "Document public loop-worktree lock import in QUICKSTART" "good first issue,docs" "$BODY_DIR/quickstart-worktree-lock-import.md"
+create_issue "Share a loop-sandbox production story" "good first issue,story" "$BODY_DIR/loop-sandbox-story.md"
+create_issue "Add budget-negotiator skill discoverability to docs" "good first issue,docs" "$BODY_DIR/budget-negotiator-docs.md"
diff --git a/scripts/issue-bodies/budget-negotiator-docs.md b/scripts/issue-bodies/budget-negotiator-docs.md
new file mode 100644
index 0000000..1be3874
--- /dev/null
+++ b/scripts/issue-bodies/budget-negotiator-docs.md
@@ -0,0 +1,19 @@
+## Goal
+
+Make the **budget-negotiator** skill discoverable: short pointer from QUICKSTART or `docs/safety.md` / budget docs so L3 loops know when to negotiate token spend vs escalate.
+
+## Files
+
+- Prefer a short subsection or bullet in `docs/QUICKSTART.md` (L3 / budget) **or** `docs/safety.md`
+- Cross-link the skill path under `skills/` (or starters) where the skill lives
+
+## Acceptance criteria
+
+- [ ] Explains when to use budget negotiation vs hard stop / human gate
+- [ ] Links the skill file and `loop-budget.md` / circuit-breaker concepts
+- [ ] Safety: no auto-spend without a human gate note
+- [ ] Additive only
+
+**Estimated time:** ~25–30 minutes
+
+Comment **"I'll take this"** to get assigned.
diff --git a/scripts/issue-bodies/loop-sandbox-story.md b/scripts/issue-bodies/loop-sandbox-story.md
new file mode 100644
index 0000000..20ae7a7
--- /dev/null
+++ b/scripts/issue-bodies/loop-sandbox-story.md
@@ -0,0 +1,19 @@
+## Goal
+
+Share a real **loop-sandbox** production (or serious dogfood) story — ephemeral worktree isolation in an L2 loop, what worked, and what surprised you.
+
+## Files
+
+- New `stories/<your-slug>.md`
+- Update index row in `stories/README.md`
+
+## Acceptance criteria
+
+- [ ] Names the tool (`loop-sandbox`) and the loop pattern it protected
+- [ ] Includes at least one failure, near-miss, or surprising patch outcome
+- [ ] Actionable lesson in one paragraph
+- [ ] No secrets or internal URLs
+
+**Estimated time:** ~20 minutes
+
+Comment **"I'll take this"** to get assigned.
diff --git a/scripts/issue-bodies/quickstart-loop-swarm.md b/scripts/issue-bodies/quickstart-loop-swarm.md
new file mode 100644
index 0000000..216ce6a
--- /dev/null
+++ b/scripts/issue-bodies/quickstart-loop-swarm.md
@@ -0,0 +1,19 @@
+## Goal
+
+Add a **loop-swarm** subsection to QUICKSTART so multi-agent consensus sandboxing is discoverable next to `loop-sandbox` / L2 safety tools.
+
+## Files
+
+- `docs/QUICKSTART.md` — short subsection after loop-sandbox (or under L2/L3 safety)
+- Cross-link `tools/loop-swarm/README.md` and `docs/safety.md`
+
+## Acceptance criteria
+
+- [ ] Explains sequential multi-agent runs + majority byte-identical consensus in 1–2 paragraphs
+- [ ] Shows a copy-paste example: `npx @cobusgreyling/loop-swarm run --count 3 -- <agent-cmd>`
+- [ ] Notes limitations (serialized runs, SIGINT, not an OS sandbox) with a link to safety docs
+- [ ] Does **not** rewrite the unified `@cobusgreyling/loop` front door
+
+**Estimated time:** ~25–30 minutes
+
+Comment **"I'll take this"** to get assigned.
diff --git a/scripts/issue-bodies/quickstart-minimax-foundry.md b/scripts/issue-bodies/quickstart-minimax-foundry.md
new file mode 100644
index 0000000..b3aac65
--- /dev/null
+++ b/scripts/issue-bodies/quickstart-minimax-foundry.md
@@ -0,0 +1,28 @@
+## Goal
+
+Document **MiniMax** `--with-foundry` flags in QUICKSTART (or the Foundry CTA section) so implementer stacks can pick MiniMax without reading only `loop-init` help text.
+
+## Context
+
+`loop-init` 1.6.0 supports:
+
+```bash
+npx @cobusgreyling/loop-init . --pattern daily-triage --tool grok \
+ --with-foundry --model-provider minimax --region global_en --model MiniMax-M3
+```
+
+## Files
+
+- `docs/QUICKSTART.md` — short note near Foundry / `--with-foundry` CTA
+- Optional one-line cross-link from `docs/cli-front-door.md` if present
+
+## Acceptance criteria
+
+- [ ] Documents `--model-provider minimax`, `--region` (`global_en` | `cn_zh`), and `--model` options
+- [ ] One copy-paste example that works with the unified front door *or* `loop-init`
+- [ ] Points to MiniMax / foundry docs if linked from the repo
+- [ ] Additive only — no front-door regressions
+
+**Estimated time:** ~20–25 minutes
+
+Comment **"I'll take this"** to get assigned.
diff --git a/scripts/issue-bodies/quickstart-worktree-lock-import.md b/scripts/issue-bodies/quickstart-worktree-lock-import.md
new file mode 100644
index 0000000..9c5aca7
--- /dev/null
+++ b/scripts/issue-bodies/quickstart-worktree-lock-import.md
@@ -0,0 +1,28 @@
+## Goal
+
+Document the **public** `@cobusgreyling/loop-worktree/lock` import path in QUICKSTART (L2 worktree section), so loops can use advisory path locks from JS without deep-importing `dist/`.
+
+## Context
+
+`loop-worktree` 1.3.0 exports:
+
+```js
+import { lockPaths, unlockPaths, LOCKS_DIR } from '@cobusgreyling/loop-worktree/lock';
+```
+
+CLI still has `lock` / `unlock` / `locks`.
+
+## Files
+
+- `docs/QUICKSTART.md` — under L2 / `loop-worktree`
+- Cross-link `tools/loop-worktree/README.md`
+
+## Acceptance criteria
+
+- [ ] Shows both CLI lock example and public JS import
+- [ ] Notes multi-loop collision use case in one sentence
+- [ ] Additive only
+
+**Estimated time:** ~20 minutes
+
+Comment **"I'll take this"** to get assigned.