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: refresh Help wanted list and reseed good first issues (#394)
Cobus Greyling42e64a7bddf5
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.mdindex 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 vulnerabilitiesdiff --git a/README.md b/README.mdindex 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.## Contributingdiff --git a/scripts/create-good-first-issues.sh b/scripts/create-good-first-issues.shindex 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 filediff --git a/scripts/issue-bodies/changelog-drafter-story.md b/scripts/issue-bodies/changelog-drafter-story.mdnew file mode 100644index 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.mdnew file mode 100644index 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.mdnew file mode 100644index 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.mdnew file mode 100644index 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.mdnew file mode 100644index 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.mdnew file mode 100644index 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.mdnew file mode 100644index 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.mdnew file mode 100644index 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.mdnew file mode 100644index 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.mdnew file mode 100644index 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.mdnew file mode 100644index 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.