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.

chore: Wave 3 good-first issue backlog + README refresh

Cobus Greylingeed3135e6c63
diff --git a/README.md b/README.md
index 00e1f42..ddfa91a 100644
--- a/README.md
+++ b/README.md
@@ -96,7 +96,7 @@ For developers using Grok, Claude Code, Codex, Cursor, and other AI coding agent
| [loop-worktree](tools/loop-worktree/) | Manage isolated git worktrees per fix attempt — `npx @cobusgreyling/loop-worktree create --run-id <id> --pattern <p>` |
| [Goal Engineering](https://github.com/cobusgreyling/goal-engineering) | **Companion:** loops discover, goals finish — `/goal` + [stack cookbook](https://github.com/cobusgreyling/goal-engineering/blob/main/docs/stack-cookbook.md) (`npx @cobusgreyling/goal doctor .`) |
| [Stories](stories/) | Real wins and honest failures |
-| [Contributor quickstart](https://github.com/cobusgreyling/loop-engineering/discussions/123) | **Help wanted:** 17 scoped `good first issues` — comment *I'll take this* to get assigned |
+| [Contributor quickstart](https://github.com/cobusgreyling/loop-engineering/discussions/123) | **Help wanted:** 25 scoped `good first issues` — comment *I'll take this* to get assigned |
| [Community update](https://github.com/cobusgreyling/loop-engineering/discussions/145) | **July 4:** 5.5k stars, traffic sources, contributor merges |
| [Prior release notes](https://github.com/cobusgreyling/loop-engineering/discussions/89) | v1.5.0 — loop-sync, constraints, MCP server |
| [Add your project](https://github.com/cobusgreyling/loop-engineering/discussions/92) | **Pinned:** Loop Ready badge + adopters list |
@@ -255,8 +255,10 @@ Addy Osmani:
| Pick one | Issue |
|----------|-------|
| ~10 min | [#120 — Add your project to adopters](https://github.com/cobusgreyling/loop-engineering/issues/120) |
-| ~20 min | [#121 — QUICKSTART `loop-init --tool` values](https://github.com/cobusgreyling/loop-engineering/issues/121) |
-| ~1 hr | [#118](https://github.com/cobusgreyling/loop-engineering/issues/118) / [#119](https://github.com/cobusgreyling/loop-engineering/issues/119) — **failure stories welcome** |
+| ~15 min | [#227 — `loop-sync` subsection in QUICKSTART](https://github.com/cobusgreyling/loop-engineering/issues/227) |
+| ~30 min | [#147 — Cline appendix](https://github.com/cobusgreyling/loop-engineering/issues/147) · [#220 — Cursor CI Sweeper example](https://github.com/cobusgreyling/loop-engineering/issues/220) |
+| ~45 min | [#225 — Hermes PR Babysitter example](https://github.com/cobusgreyling/loop-engineering/issues/225) |
+| ~1 hr | [#230](https://github.com/cobusgreyling/loop-engineering/issues/230) / [#231](https://github.com/cobusgreyling/loop-engineering/issues/231) — **your story** (worktree week-two, multi-loop failure) |
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.
diff --git a/scripts/create-good-first-issues.sh b/scripts/create-good-first-issues.sh
index 13dd5e6..d4a7665 100755
--- a/scripts/create-good-first-issues.sh
+++ b/scripts/create-good-first-issues.sh
@@ -44,5 +44,19 @@ create_issue "Share an Issue Triage week-one story" "good first issue,story" "$B
create_issue "Add Opencode constraints example doc" "good first issue,docs" "$BODY_DIR/opencode-constraints-example.md"
create_issue "Share a multi-loop coordination story" "good first issue,story" "$BODY_DIR/multi-loop-story.md"
+# Wave 3 — example gaps, QUICKSTART tools, community stories (Jul 2026)
+create_issue "Add Cursor CI Sweeper example doc" "good first issue,docs" "$BODY_DIR/cursor-ci-sweeper-example.md"
+create_issue "Add Cursor Post-Merge Cleanup example doc" "good first issue,docs" "$BODY_DIR/cursor-post-merge-cleanup-example.md"
+create_issue "Add Cursor Dependency Sweeper example doc" "good first issue,docs" "$BODY_DIR/cursor-dependency-sweeper-example.md"
+create_issue "Add Cursor Changelog Drafter example doc" "good first issue,docs" "$BODY_DIR/cursor-changelog-drafter-example.md"
+create_issue "Add Cursor Issue Triage example doc" "good first issue,docs" "$BODY_DIR/cursor-issue-triage-example.md"
+create_issue "Add Hermes PR Babysitter example doc" "good first issue,docs" "$BODY_DIR/hermes-pr-babysitter-example.md"
+create_issue "Add loop-sync subsection to QUICKSTART" "good first issue,docs" "$BODY_DIR/quickstart-loop-sync.md"
+create_issue "Add Amazon Q appendix to primitives matrix" "good first issue,docs" "$BODY_DIR/amazon-q-appendix.md"
+create_issue "Add Codeium appendix to primitives matrix" "good first issue,docs" "$BODY_DIR/codeium-appendix.md"
+create_issue "Share your loop-worktree week-two story" "good first issue,story" "$BODY_DIR/loop-worktree-week-two-story.md"
+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"
+
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/amazon-q-appendix.md b/scripts/issue-bodies/amazon-q-appendix.md
new file mode 100644
index 0000000..f9b8a76
--- /dev/null
+++ b/scripts/issue-bodies/amazon-q-appendix.md
@@ -0,0 +1,15 @@
+## Goal
+Document **Amazon Q Developer** in the primitives matrix for contributors using Q as their loop host.
+
+## Files
+- `docs/primitives-matrix.md`
+
+## Acceptance criteria
+- [ ] Add an **Amazon Q appendix** (same style as Gemini CLI / Zed appendices)
+- [ ] Cover scheduling, rules/context files, `STATE.md`, maker/checker split
+- [ ] Honest note where a primitive is not first-class in Q yet
+- [ ] One copy-paste week-one Daily Triage prompt (report-only)
+
+**Estimated time:** ~30 minutes
+
+Comment **"I'll take this"** to get assigned.
\ No newline at end of file
diff --git a/scripts/issue-bodies/codeium-appendix.md b/scripts/issue-bodies/codeium-appendix.md
new file mode 100644
index 0000000..5cdce1b
--- /dev/null
+++ b/scripts/issue-bodies/codeium-appendix.md
@@ -0,0 +1,15 @@
+## Goal
+Document **Codeium / Windsurf-adjacent CLI agents** (or Codeium in VS Code) in the primitives matrix.
+
+## Files
+- `docs/primitives-matrix.md`
+
+## Acceptance criteria
+- [ ] Add a **Codeium appendix** (same style as Cline / Continue.dev rows)
+- [ ] Clarify which product surface you document (VS Code extension vs CLI) in the PR description
+- [ ] Cover scheduling, skills/rules path, `STATE.md`, maker/checker split
+- [ ] Honest gaps where primitives are manual-only
+
+**Estimated time:** ~30 minutes
+
+Comment **"I'll take this"** to get assigned.
\ No newline at end of file
diff --git a/scripts/issue-bodies/cursor-changelog-drafter-example.md b/scripts/issue-bodies/cursor-changelog-drafter-example.md
new file mode 100644
index 0000000..190ac0e
--- /dev/null
+++ b/scripts/issue-bodies/cursor-changelog-drafter-example.md
@@ -0,0 +1,17 @@
+## Goal
+Add a **Cursor Changelog Drafter** example doc — fill the `—` in Changelog Drafter × Cursor.
+
+## Files
+- `examples/cursor/changelog-drafter.md` (new)
+- `examples/cursor/README.md` (link it)
+- `examples/README.md` (update pattern table cell)
+
+## Acceptance criteria
+- [ ] L1 draft-only: produce `RELEASE_NOTES_DRAFT.md` or section; human approves before publish
+- [ ] Map scheduling (Automations), `changelog-drafter-state.md`, scan + draft skills
+- [ ] Explicit gate: no tags, releases, or Discussions posts without human review
+- [ ] Link to `starters/changelog-drafter/` and `stories/changelog-drafter-week-one.md` as reference tone
+
+**Estimated time:** ~40 minutes
+
+Comment **"I'll take this"** to get assigned.
\ No newline at end of file
diff --git a/scripts/issue-bodies/cursor-ci-sweeper-example.md b/scripts/issue-bodies/cursor-ci-sweeper-example.md
new file mode 100644
index 0000000..9f851e5
--- /dev/null
+++ b/scripts/issue-bodies/cursor-ci-sweeper-example.md
@@ -0,0 +1,17 @@
+## Goal
+Add a **Cursor CI Sweeper** example doc — the pattern coverage table has a gap for Cursor × CI Sweeper.
+
+## Files
+- `examples/cursor/ci-sweeper.md` (new)
+- `examples/cursor/README.md` (link it)
+- `examples/README.md` (fill the `—` in CI Sweeper × Cursor cell)
+
+## Acceptance criteria
+- [ ] Week-one report-only default; human gate before unattended fixes
+- [ ] Map primitives: Automations, skills/rules, `ci-sweeper-state.md`, verifier + `loop-worktree` for fix attempts
+- [ ] Follow tone/structure of `examples/cursor/pr-babysitter.md`
+- [ ] Honest note where Cursor has no native cron — pair with GitHub Action or external scheduler if needed
+
+**Estimated time:** ~45 minutes
+
+Comment **"I'll take this"** to get assigned.
\ No newline at end of file
diff --git a/scripts/issue-bodies/cursor-dependency-sweeper-example.md b/scripts/issue-bodies/cursor-dependency-sweeper-example.md
new file mode 100644
index 0000000..5c5608f
--- /dev/null
+++ b/scripts/issue-bodies/cursor-dependency-sweeper-example.md
@@ -0,0 +1,17 @@
+## Goal
+Add a **Cursor Dependency Sweeper** example doc — fill the `—` in Dependency Sweeper × Cursor.
+
+## Files
+- `examples/cursor/dependency-sweeper.md` (new)
+- `examples/cursor/README.md` (link it)
+- `examples/README.md` (update pattern table cell)
+
+## Acceptance criteria
+- [ ] Patch-only week one; denylist + human gate on majors (mirror `patterns/dependency-sweeper.md`)
+- [ ] Worktree per attempt via `npx @cobusgreyling/loop-worktree`
+- [ ] Verifier skill required before any merge proposal
+- [ ] Follow structure of `examples/opencode/dependency-sweeper.md` adapted for Cursor Automations
+
+**Estimated time:** ~45 minutes
+
+Comment **"I'll take this"** to get assigned.
\ No newline at end of file
diff --git a/scripts/issue-bodies/cursor-issue-triage-example.md b/scripts/issue-bodies/cursor-issue-triage-example.md
new file mode 100644
index 0000000..47deb08
--- /dev/null
+++ b/scripts/issue-bodies/cursor-issue-triage-example.md
@@ -0,0 +1,17 @@
+## Goal
+Add a **Cursor Issue Triage** example doc — fill the `—` in Issue Triage × Cursor.
+
+## Files
+- `examples/cursor/issue-triage.md` (new)
+- `examples/cursor/README.md` (link it)
+- `examples/README.md` (update pattern table cell)
+
+## Acceptance criteria
+- [ ] Week one: propose labels and priority notes only — no auto-close, no assignment without human gate
+- [ ] Map `issue-triage-state.md`, skills from `starters/issue-triage/`
+- [ ] One copy-paste Automation prompt for report-only triage
+- [ ] Link to GitHub MCP read-only discovery pattern in `examples/mcp/`
+
+**Estimated time:** ~40 minutes
+
+Comment **"I'll take this"** to get assigned.
\ No newline at end of file
diff --git a/scripts/issue-bodies/cursor-post-merge-cleanup-example.md b/scripts/issue-bodies/cursor-post-merge-cleanup-example.md
new file mode 100644
index 0000000..0841455
--- /dev/null
+++ b/scripts/issue-bodies/cursor-post-merge-cleanup-example.md
@@ -0,0 +1,17 @@
+## Goal
+Add a **Cursor Post-Merge Cleanup** example doc — fill the `—` in Post-Merge Cleanup × Cursor.
+
+## Files
+- `examples/cursor/post-merge-cleanup.md` (new)
+- `examples/cursor/README.md` (link it)
+- `examples/README.md` (update pattern table cell)
+
+## Acceptance criteria
+- [ ] L1 default: scan recent merges, update `post-merge-state.md`, no code changes week one
+- [ ] Map Automations / Agent prompt, skills, state file, verifier for L2 docs-only fixes
+- [ ] Link to `starters/post-merge-cleanup/` and `patterns/post-merge-cleanup.md`
+- [ ] One copy-paste week-one automation prompt
+
+**Estimated time:** ~40 minutes
+
+Comment **"I'll take this"** to get assigned.
\ No newline at end of file
diff --git a/scripts/issue-bodies/hermes-pr-babysitter-example.md b/scripts/issue-bodies/hermes-pr-babysitter-example.md
new file mode 100644
index 0000000..2d50336
--- /dev/null
+++ b/scripts/issue-bodies/hermes-pr-babysitter-example.md
@@ -0,0 +1,17 @@
+## Goal
+Add a **Hermes PR Babysitter** example — Hermes only has daily-triage in the examples table today.
+
+## Files
+- `examples/hermes/pr-babysitter.md` (new)
+- `examples/hermes/README.md` (link it)
+- `examples/README.md` (fill PR Babysitter × Hermes cell; optional copy-paste starters row)
+
+## Acceptance criteria
+- [ ] Week-one report-only: scan PRs, update `pr-babysitter-state.md`, no merges
+- [ ] Map `hermes cron` scheduling, skill install, channel delivery (`--deliver local` default)
+- [ ] Verifier + worktree notes for week two (link `loop-worktree` QUICKSTART subsection)
+- [ ] Follow tone of `examples/hermes/daily-triage.md`
+
+**Estimated time:** ~45 minutes
+
+Comment **"I'll take this"** to get assigned.
\ No newline at end of file
diff --git a/scripts/issue-bodies/loop-init-validation-checklist.md b/scripts/issue-bodies/loop-init-validation-checklist.md
new file mode 100644
index 0000000..b621737
--- /dev/null
+++ b/scripts/issue-bodies/loop-init-validation-checklist.md
@@ -0,0 +1,16 @@
+## Goal
+Start a **loop-init validation checklist** — `STATE.md` watch list asks for fresh-project scaffolds across patterns.
+
+## Files
+- `docs/loop-init-validation.md` (new)
+- Optional one-line link from `tools/loop-init/README.md`
+
+## Acceptance criteria
+- [ ] Table: pattern × `--tool` (grok, claude, codex, opencode) with columns for Loop Ready score, files created, notes
+- [ ] **You validate at least one row** by running `npx @cobusgreyling/loop-init` in a temp git repo and recording results
+- [ ] Document the exact commands used so others can repeat
+- [ ] Leave empty rows for other contributors to fill (do not block PR on full matrix)
+
+**Estimated time:** ~45 minutes
+
+Comment **"I'll take this"** to get assigned.
\ No newline at end of file
diff --git a/scripts/issue-bodies/loop-worktree-week-two-story.md b/scripts/issue-bodies/loop-worktree-week-two-story.md
new file mode 100644
index 0000000..09e1978
--- /dev/null
+++ b/scripts/issue-bodies/loop-worktree-week-two-story.md
@@ -0,0 +1,15 @@
+## Goal
+Share **your** week-two story using `loop-worktree` — the reference repo now documents it in QUICKSTART; we want real community voices.
+
+## Files
+- New file under `stories/` (follow format in existing stories)
+
+## Acceptance criteria
+- [ ] Which pattern (PR Babysitter, CI Sweeper, etc.) and tool you used
+- [ ] How you used `create` / `mark` / `cleanup` (or `gc`)
+- [ ] Whether you paired with `loop-context --check`
+- [ ] One surprise (good or bad) and what you would change
+
+**Estimated time:** ~15 minutes
+
+Comment **"I'll take this"** to get assigned.
\ No newline at end of file
diff --git a/scripts/issue-bodies/multi-loop-failure-story.md b/scripts/issue-bodies/multi-loop-failure-story.md
new file mode 100644
index 0000000..3df1b94
--- /dev/null
+++ b/scripts/issue-bodies/multi-loop-failure-story.md
@@ -0,0 +1,15 @@
+## Goal
+Share a **multi-loop failure** story — `stories/multi-loop-coordination.md` covers a win; we need honest collision / priority failures too.
+
+## Files
+- New file under `stories/` (follow format in existing stories)
+
+## Acceptance criteria
+- [ ] Which loops ran concurrently and how they were scheduled
+- [ ] What collided (branch, state file, token budget, human attention)
+- [ ] How you detected it and what you changed (priority order, kill switch, cadence)
+- [ ] Link to `docs/multi-loop.md` if you adjusted the default priority stack
+
+**Estimated time:** ~20 minutes
+
+Comment **"I'll take this"** to get assigned.
\ No newline at end of file
diff --git a/scripts/issue-bodies/quickstart-loop-sync.md b/scripts/issue-bodies/quickstart-loop-sync.md
new file mode 100644
index 0000000..b1a2b6d
--- /dev/null
+++ b/scripts/issue-bodies/quickstart-loop-sync.md
@@ -0,0 +1,15 @@
+## Goal
+Document **`loop-sync`** drift detection in the Quickstart — catch when `STATE.md` and `LOOP.md` diverge before a loop runs on stale instructions.
+
+## Files
+- `docs/QUICKSTART.md`
+
+## Acceptance criteria
+- [ ] Short subsection in "What next?" or after the audit step
+- [ ] Show `npx @cobusgreyling/loop-sync .` with sample output interpretation
+- [ ] One sentence on when to run it (after editing `LOOP.md`, before scheduling L2)
+- [ ] Link to `tools/loop-sync/README.md`
+
+**Estimated time:** ~15 minutes
+
+Comment **"I'll take this"** to get assigned.
\ No newline at end of file