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: refresh Help wanted list and reseed good first issues (#394)

Cobus Greyling42e64a7bddf5
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index aafcaa8..514a9c7 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -24,7 +24,7 @@ Start small — every merged PR counts.
| **3** | Half day | New starter, skill template, or MCP cookbook entry |
| **4** | Full day | Full pattern in `patterns/` + `patterns/registry.yaml` entry |
-**Fastest paths:** [Add your project to adopters](https://github.com/cobusgreyling/loop-engineering/issues/new?template=add-adopter.yml) · [Share a story issue](https://github.com/cobusgreyling/loop-engineering/issues/new?template=share-story.yml) · [`good first issue` backlog](https://github.com/cobusgreyling/loop-engineering/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22)
+**Fastest paths:** [Help wanted (README)](./README.md#help-wanted) · [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) · [open `good first issue` backlog](https://github.com/cobusgreyling/loop-engineering/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22)
## Pattern Requirements
@@ -83,7 +83,7 @@ Automation posts a welcome comment on new story/adopter PRs (see `.github/workfl
- **Questions**: [Ask anything](https://github.com/cobusgreyling/loop-engineering/discussions/327) (preferred) or issue with label `question`
- **Show your loop**: [Show your loop](https://github.com/cobusgreyling/loop-engineering/discussions/326), [Add Adopter issue](https://github.com/cobusgreyling/loop-engineering/issues/new?template=add-adopter.yml), or a row in [docs/adopters.md](./docs/adopters.md)
- **Loop Ready badge**: `npx @cobusgreyling/loop-audit . --badge` — paste into your README
-- **Good first issues**: look for the label [`good first issue`](https://github.com/cobusgreyling/loop-engineering/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22)
+- **Good first issues**: curated list in [README § Help wanted](./README.md#help-wanted); filter: [`good first issue`](https://github.com/cobusgreyling/loop-engineering/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22)
- **Hall of fame**: [CONTRIBUTORS.md](./CONTRIBUTORS.md) — regenerate after merges with `npm run contributors:generate`
- **Security**: see [SECURITY.md](./SECURITY.md) — do not file public issues for exploitable vulnerabilities
diff --git a/README.md b/README.md
index cf4012b..0aa792e 100644
--- a/README.md
+++ b/README.md
@@ -79,6 +79,7 @@ For developers using Grok, Claude Code, Codex, Cursor, and other AI coding agent
- [Examples by Tool](#examples-by-tool)
- [Operating & Safety](#operating--safety)
- [Caveats](#caveats)
+- [Help wanted](#help-wanted)
- [Contributing](#contributing)
- [Sources](#sources)
- [License](#license)
@@ -130,7 +131,12 @@ memory-engineering → loop-engineering → harness-foundry → outerloop → fl
**Scale beyond one loop:** when agents forget across sessions, add [memory-engineering](https://github.com/cobusgreyling/memory-engineering). When you have many agents/loops on a team, add [fleet-engineering](https://github.com/cobusgreyling/fleet-engineering).
**Next after Loop Ready 80+:** version the loop as a harness — `loop-init` prints the CTA automatically; `loop-audit` recommends Foundry when the score is strong but `.foundry/stack.yaml` is missing.
-| [Contributor quickstart](https://github.com/cobusgreyling/loop-engineering/discussions/123) | **Help wanted:** 21 scoped `good first issues` — comment *I'll take this* to get assigned |
+
+### Community & announcements
+
+| Discussion | Summary |
+|------------|---------|
+| [Contributor quickstart](https://github.com/cobusgreyling/loop-engineering/discussions/123) | **Help wanted:** open `good first issues` — comment *I'll take this* to get assigned · see [Help wanted](#help-wanted) |
| [Community update](https://github.com/cobusgreyling/loop-engineering/discussions/145) | **July 4:** 5.5k stars, traffic sources, contributor merges |
| [Community week (Jul 8)](https://github.com/cobusgreyling/loop-engineering/discussions/219) | loop-worktree npm, MCP quickstart, tool appendices |
| [npm update (Jul 16)](https://github.com/cobusgreyling/loop-engineering/discussions/294) | `loop-context` 1.2.0 + `loop-worktree` 1.1.0 — daily budget, path locks |
@@ -291,20 +297,22 @@ Addy Osmani:
## Help wanted
-**First PR?** Start with the [contributor quickstart](https://github.com/cobusgreyling/loop-engineering/discussions/123) — ~10 min to ~1 hr tasks with same-day review on stories and adopters. See [CONTRIBUTORS.md](CONTRIBUTORS.md) for everyone who has shipped so far.
+**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).
+
+**14 open** [`good first issue`](https://github.com/cobusgreyling/loop-engineering/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22)s (refreshed Jul 2026). Comment **"I'll take this"** for assignment.
-| Pick one | Issue |
-|----------|-------|
-| ~10 min | [#120 — Add your project to adopters](https://github.com/cobusgreyling/loop-engineering/issues/120) |
-| ~15 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) |
-| ~20 min | [#119 — PR Babysitter failure story](https://github.com/cobusgreyling/loop-engineering/issues/119) |
-| ~30 min | [#117 — Continue.dev](https://github.com/cobusgreyling/loop-engineering/issues/117) · [#147 — Cline](https://github.com/cobusgreyling/loop-engineering/issues/147) |
-| ~30 min | [#195 — Roo Code](https://github.com/cobusgreyling/loop-engineering/issues/195) · [#196 — GitHub Copilot](https://github.com/cobusgreyling/loop-engineering/issues/196) |
-| ~40 min | [#220 — Cursor CI Sweeper](https://github.com/cobusgreyling/loop-engineering/issues/220) · [#223 — Cursor Changelog Drafter](https://github.com/cobusgreyling/loop-engineering/issues/223) |
-| ~40 min | [#224 — Cursor Issue Triage](https://github.com/cobusgreyling/loop-engineering/issues/224) |
-| Hubs | [Show your loop](https://github.com/cobusgreyling/loop-engineering/discussions/326) · [Ask anything](https://github.com/cobusgreyling/loop-engineering/discussions/327) |
+| 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) · [#392 — CI Sweeper story](https://github.com/cobusgreyling/loop-engineering/issues/392) | Honest `stories/` write-up + index row |
+| ~25–30 min | [#389 — loop-action QUICKSTART](https://github.com/cobusgreyling/loop-engineering/issues/389) · [#390 — loop-sandbox QUICKSTART](https://github.com/cobusgreyling/loop-engineering/issues/390) · [#391 — loop-gate QUICKSTART](https://github.com/cobusgreyling/loop-engineering/issues/391) | Doc subsection + links to tool READMEs |
+| ~40 min | [#384 — Windsurf CI Sweeper](https://github.com/cobusgreyling/loop-engineering/issues/384) · [#385 — Windsurf Issue Triage](https://github.com/cobusgreyling/loop-engineering/issues/385) · [#386 — Windsurf Dependency Sweeper](https://github.com/cobusgreyling/loop-engineering/issues/386) | Fill pattern-coverage gaps in `examples/windsurf/` |
+| ~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/` |
+| ~45–60 min | [#393 — Harden loop-action quoting](https://github.com/cobusgreyling/loop-engineering/issues/393) | Safer `inputs.command` handling in `tools/loop-action` |
+| 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) |
-Comment **"I'll take this"** on any [`good first issue`](https://github.com/cobusgreyling/loop-engineering/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22) for assignment.
+Maintainers re-seed the backlog with `bash scripts/create-good-first-issues.sh` (idempotent; skips existing titles). Prefer [live open GFI filter](https://github.com/cobusgreyling/loop-engineering/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22) over this table if a row looks stale.
## Contributing
diff --git a/scripts/create-good-first-issues.sh b/scripts/create-good-first-issues.sh
index d4a7665..7532204 100755
--- a/scripts/create-good-first-issues.sh
+++ b/scripts/create-good-first-issues.sh
@@ -58,5 +58,18 @@ create_issue "Share your loop-worktree week-two story" "good first issue,story"
create_issue "Share your multi-loop failure story" "good first issue,story" "$BODY_DIR/multi-loop-failure-story.md"
create_issue "Add loop-init validation checklist doc" "good first issue,docs" "$BODY_DIR/loop-init-validation-checklist.md"
+# Wave 4 — coverage gaps after Jul 2026 merges (Hermes/Windsurf, new tools, stories)
+create_issue "Add Windsurf CI Sweeper example doc" "good first issue,docs" "$BODY_DIR/windsurf-ci-sweeper-example.md"
+create_issue "Add Windsurf Issue Triage example doc" "good first issue,docs" "$BODY_DIR/windsurf-issue-triage-example.md"
+create_issue "Add Windsurf Dependency Sweeper example doc" "good first issue,docs" "$BODY_DIR/windsurf-dependency-sweeper-example.md"
+create_issue "Add Hermes CI Sweeper example doc" "good first issue,docs" "$BODY_DIR/hermes-ci-sweeper-example.md"
+create_issue "Add Hermes Issue Triage example doc" "good first issue,docs" "$BODY_DIR/hermes-issue-triage-example.md"
+create_issue "Add loop-action subsection to QUICKSTART" "good first issue,docs" "$BODY_DIR/quickstart-loop-action.md"
+create_issue "Add loop-sandbox subsection to QUICKSTART" "good first issue,docs" "$BODY_DIR/quickstart-loop-sandbox.md"
+create_issue "Add loop-gate subsection to QUICKSTART" "good first issue,docs" "$BODY_DIR/quickstart-loop-gate.md"
+create_issue "Share a CI Sweeper production story" "good first issue,story" "$BODY_DIR/ci-sweeper-story.md"
+create_issue "Share a Changelog Drafter week-one story" "good first issue,story" "$BODY_DIR/changelog-drafter-story.md"
+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
diff --git a/scripts/issue-bodies/changelog-drafter-story.md b/scripts/issue-bodies/changelog-drafter-story.md
new file mode 100644
index 0000000..1b55b8b
--- /dev/null
+++ b/scripts/issue-bodies/changelog-drafter-story.md
@@ -0,0 +1,19 @@
+## Goal
+
+Share a real **Changelog Drafter** week-one story — how report-only drafting helped (or went sideways) before any auto-publish.
+
+## Files
+
+- New `stories/<your-slug>.md`
+- Update index row in `stories/README.md`
+
+## Acceptance criteria
+
+- [ ] Names the pattern (Changelog Drafter) and tool(s) used
+- [ ] Includes at least one failure or surprise
+- [ ] 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/ci-sweeper-story.md b/scripts/issue-bodies/ci-sweeper-story.md
new file mode 100644
index 0000000..1c359ce
--- /dev/null
+++ b/scripts/issue-bodies/ci-sweeper-story.md
@@ -0,0 +1,19 @@
+## Goal
+
+Share a real **CI Sweeper** production story — win or failure. Failures preferred (token burn, wrong auto-fix, flaky-test loops).
+
+## Files
+
+- New `stories/<your-slug>.md`
+- Update index row in `stories/README.md`
+
+## Acceptance criteria
+
+- [ ] Names the pattern (CI Sweeper) and tool(s) used
+- [ ] Includes at least one failure or surprise
+- [ ] Actionable lesson in one paragraph
+- [ ] No secrets or internal URLs
+
+**Estimated time:** ~20 minutes
+
+Comment **"I'll take this"** to get assigned. Use the [Share a story](https://github.com/cobusgreyling/loop-engineering/issues/new?template=share-story.yml) template if easier.
diff --git a/scripts/issue-bodies/harden-loop-action-command.md b/scripts/issue-bodies/harden-loop-action-command.md
new file mode 100644
index 0000000..c517ca9
--- /dev/null
+++ b/scripts/issue-bodies/harden-loop-action-command.md
@@ -0,0 +1,19 @@
+## Goal
+
+Harden `tools/loop-action/action.yml` so `inputs.command` is not expanded unquoted into the shell (fragile for multi-arg / multi-line agent invocations).
+
+## Files
+
+- `tools/loop-action/action.yml`
+- `tools/loop-action/README.md` (document the safe usage)
+
+## Acceptance criteria
+
+- [ ] Sandbox and direct paths pass the command safely (e.g. write to a temp script, or use `bash -lc` with a properly quoted string / env var)
+- [ ] Multi-line `command: |` examples in `examples/github-actions/*.yml` still work
+- [ ] README warns against embedding untrusted input in `command`
+- [ ] No behavior change for the simple placeholder `echo` examples beyond safer invocation
+
+**Estimated time:** ~45–60 minutes (tooling; still scoped)
+
+Comment **"I'll take this"** to get assigned.
diff --git a/scripts/issue-bodies/hermes-ci-sweeper-example.md b/scripts/issue-bodies/hermes-ci-sweeper-example.md
new file mode 100644
index 0000000..ef32a97
--- /dev/null
+++ b/scripts/issue-bodies/hermes-ci-sweeper-example.md
@@ -0,0 +1,20 @@
+## Goal
+
+Add a **Hermes CI Sweeper** example. Hermes currently only documents Daily Triage + PR Babysitter.
+
+## Files
+
+- `examples/hermes/ci-sweeper.md` (new)
+- `examples/hermes/README.md` (link it)
+- `examples/README.md` (fill CI Sweeper × Hermes cell + copy-paste starters row if needed)
+
+## Acceptance criteria
+
+- [ ] Week-one report-only: classify failure, update state, no auto-fix
+- [ ] Map `hermes cron` (or event trigger) + skill install + optional channel delivery
+- [ ] Verifier + worktree notes for week two
+- [ ] Follow tone of `examples/hermes/daily-triage.md` / `pr-babysitter.md`
+
+**Estimated time:** ~45 minutes
+
+Comment **"I'll take this"** to get assigned.
diff --git a/scripts/issue-bodies/hermes-issue-triage-example.md b/scripts/issue-bodies/hermes-issue-triage-example.md
new file mode 100644
index 0000000..e285385
--- /dev/null
+++ b/scripts/issue-bodies/hermes-issue-triage-example.md
@@ -0,0 +1,20 @@
+## Goal
+
+Add a **Hermes Issue Triage** example so Hermes covers another L1 pattern beyond daily triage.
+
+## Files
+
+- `examples/hermes/issue-triage.md` (new)
+- `examples/hermes/README.md` (link it)
+- `examples/README.md` (fill Issue Triage × Hermes cell)
+
+## Acceptance criteria
+
+- [ ] Week-one: propose labels/priority only — no auto-apply or close
+- [ ] Map Hermes scheduling + delivery (`--deliver local` default)
+- [ ] State schema matches issue-triage pattern
+- [ ] Follow tone of `examples/hermes/daily-triage.md`
+
+**Estimated time:** ~40 minutes
+
+Comment **"I'll take this"** to get assigned.
diff --git a/scripts/issue-bodies/quickstart-loop-action.md b/scripts/issue-bodies/quickstart-loop-action.md
new file mode 100644
index 0000000..de75208
--- /dev/null
+++ b/scripts/issue-bodies/quickstart-loop-action.md
@@ -0,0 +1,20 @@
+## Goal
+
+Document the new **`loop-action`** composite action in QUICKSTART so CI adopters discover it next to the other npm tools.
+
+## Files
+
+- `docs/QUICKSTART.md` — short subsection (inputs, one workflow snippet)
+- `examples/github-actions/README.md` — point at `tools/loop-action` and the refactored workflow examples
+- Optional: one-line mention in root `README.md` Quick Links if other tools are listed there
+
+## Acceptance criteria
+
+- [ ] Shows `uses: cobusgreyling/loop-engineering/tools/loop-action@…` with `pattern`, `command`, `level`, `sandbox`
+- [ ] Notes week-one report-only / no auto-merge
+- [ ] Links `tools/loop-action/README.md` and `docs/safety.md`
+- [ ] Mentions that unquoted multi-arg `command` values are fragile (prefer a single script path)
+
+**Estimated time:** ~30 minutes
+
+Comment **"I'll take this"** to get assigned.
diff --git a/scripts/issue-bodies/quickstart-loop-gate.md b/scripts/issue-bodies/quickstart-loop-gate.md
new file mode 100644
index 0000000..02a9e8c
--- /dev/null
+++ b/scripts/issue-bodies/quickstart-loop-gate.md
@@ -0,0 +1,19 @@
+## Goal
+
+Add a **loop-gate** subsection to QUICKSTART so the denylist / auto-merge allowlist is discoverable next to `gate.yaml`.
+
+## Files
+
+- `docs/QUICKSTART.md` — short subsection
+- Cross-link `tools/loop-gate/` and `templates/gate.yaml.template` (or repo `gate.yaml`)
+
+## Acceptance criteria
+
+- [ ] Shows `npx @cobusgreyling/loop-gate check --action auto-merge --paths …`
+- [ ] Explains `version: 1` + `denylist` + `autoMergeAllowlist` schema (not a free-form gates list)
+- [ ] Notes that `loop-audit --auto-fix` should emit a loadable `gate.yaml`
+- [ ] Links `docs/safety.md`
+
+**Estimated time:** ~25 minutes
+
+Comment **"I'll take this"** to get assigned.
diff --git a/scripts/issue-bodies/quickstart-loop-sandbox.md b/scripts/issue-bodies/quickstart-loop-sandbox.md
new file mode 100644
index 0000000..cc27687
--- /dev/null
+++ b/scripts/issue-bodies/quickstart-loop-sandbox.md
@@ -0,0 +1,19 @@
+## Goal
+
+Add a **loop-sandbox** subsection to QUICKSTART. The package is published and used by `loop-action`, but newcomers may only see audit/init.
+
+## Files
+
+- `docs/QUICKSTART.md` — short subsection after worktree / safety tools
+- Cross-link `tools/loop-sandbox/README.md`
+
+## Acceptance criteria
+
+- [ ] Explains ephemeral worktree isolation in one paragraph
+- [ ] Shows `npx @cobusgreyling/loop-sandbox run -- <cmd>` (and optional `--shell`)
+- [ ] Notes Windows ENOENT auto-retry for npm `.cmd` shims (no need to force `--shell` for npx)
+- [ ] Links safety / review of patches before apply
+
+**Estimated time:** ~25 minutes
+
+Comment **"I'll take this"** to get assigned.
diff --git a/scripts/issue-bodies/windsurf-ci-sweeper-example.md b/scripts/issue-bodies/windsurf-ci-sweeper-example.md
new file mode 100644
index 0000000..5611c77
--- /dev/null
+++ b/scripts/issue-bodies/windsurf-ci-sweeper-example.md
@@ -0,0 +1,20 @@
+## Goal
+
+Add a **Windsurf CI Sweeper** example. The pattern coverage table has a gap for Windsurf on CI Sweeper (Cursor and Opencode already ship one).
+
+## Files
+
+- `examples/windsurf/ci-sweeper.md` (new)
+- `examples/windsurf/README.md` (link it)
+- `examples/README.md` (fill CI Sweeper × Windsurf cell)
+
+## Acceptance criteria
+
+- [ ] Week-one report-only: classify failure, update state, no auto-fix
+- [ ] Map Windsurf / Cascade scheduling or manual trigger; link `docs/safety.md`
+- [ ] Point at `loop-worktree` + verifier notes for week-two L2
+- [ ] Follow tone of `examples/cursor/ci-sweeper.md` or `examples/windsurf/daily-triage.md`
+
+**Estimated time:** ~40 minutes
+
+Comment **"I'll take this"** to get assigned.
diff --git a/scripts/issue-bodies/windsurf-dependency-sweeper-example.md b/scripts/issue-bodies/windsurf-dependency-sweeper-example.md
new file mode 100644
index 0000000..dd56512
--- /dev/null
+++ b/scripts/issue-bodies/windsurf-dependency-sweeper-example.md
@@ -0,0 +1,20 @@
+## Goal
+
+Add a **Windsurf Dependency Sweeper** example. Coverage table gap for Windsurf × Dependency Sweeper.
+
+## Files
+
+- `examples/windsurf/dependency-sweeper.md` (new)
+- `examples/windsurf/README.md` (link it)
+- `examples/README.md` (fill Dependency Sweeper × Windsurf cell)
+
+## Acceptance criteria
+
+- [ ] Week-one report-only: audit/outdated summary, patch-only proposal notes
+- [ ] Escalate majors; no silent major bumps
+- [ ] Circuit-breaker / budget mention for L2
+- [ ] Follow tone of `examples/cursor/dependency-sweeper.md`
+
+**Estimated time:** ~40 minutes
+
+Comment **"I'll take this"** to get assigned.
diff --git a/scripts/issue-bodies/windsurf-issue-triage-example.md b/scripts/issue-bodies/windsurf-issue-triage-example.md
new file mode 100644
index 0000000..ba1c691
--- /dev/null
+++ b/scripts/issue-bodies/windsurf-issue-triage-example.md
@@ -0,0 +1,20 @@
+## Goal
+
+Add a **Windsurf Issue Triage** example. Pattern coverage currently leaves Issue Triage × Windsurf empty.
+
+## Files
+
+- `examples/windsurf/issue-triage.md` (new)
+- `examples/windsurf/README.md` (link it)
+- `examples/README.md` (fill Issue Triage × Windsurf cell)
+
+## Acceptance criteria
+
+- [ ] Week-one: propose labels/priority only — no auto-apply or close
+- [ ] State file schema matches `issue-triage-state.md` pattern
+- [ ] Safety: report-only first week; human gate before label writes
+- [ ] Follow tone of `examples/cursor/issue-triage.md`
+
+**Estimated time:** ~40 minutes
+
+Comment **"I'll take this"** to get assigned.