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: expand Help wanted with swarm, MiniMax, lock, sandbox story (#429)
Cobus Greyling1a10ca76586a
diff --git a/README.md b/README.mdindex 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.shindex 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.mdnew file mode 100644index 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.mdnew file mode 100644index 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.mdnew file mode 100644index 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.mdnew file mode 100644index 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.mdnew file mode 100644index 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.