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
chore: Wave 3 good-first issue backlog + README refresh
Cobus Greylingeed3135e6c63
diff --git a/README.md b/README.mdindex 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.shindex 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" "$Bcreate_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 filediff --git a/scripts/issue-bodies/amazon-q-appendix.md b/scripts/issue-bodies/amazon-q-appendix.mdnew file mode 100644index 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 filediff --git a/scripts/issue-bodies/codeium-appendix.md b/scripts/issue-bodies/codeium-appendix.mdnew file mode 100644index 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 filediff --git a/scripts/issue-bodies/cursor-changelog-drafter-example.md b/scripts/issue-bodies/cursor-changelog-drafter-example.mdnew file mode 100644index 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 filediff --git a/scripts/issue-bodies/cursor-ci-sweeper-example.md b/scripts/issue-bodies/cursor-ci-sweeper-example.mdnew file mode 100644index 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 filediff --git a/scripts/issue-bodies/cursor-dependency-sweeper-example.md b/scripts/issue-bodies/cursor-dependency-sweeper-example.mdnew file mode 100644index 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 filediff --git a/scripts/issue-bodies/cursor-issue-triage-example.md b/scripts/issue-bodies/cursor-issue-triage-example.mdnew file mode 100644index 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 filediff --git a/scripts/issue-bodies/cursor-post-merge-cleanup-example.md b/scripts/issue-bodies/cursor-post-merge-cleanup-example.mdnew file mode 100644index 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 filediff --git a/scripts/issue-bodies/hermes-pr-babysitter-example.md b/scripts/issue-bodies/hermes-pr-babysitter-example.mdnew file mode 100644index 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 filediff --git a/scripts/issue-bodies/loop-init-validation-checklist.md b/scripts/issue-bodies/loop-init-validation-checklist.mdnew file mode 100644index 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 filediff --git a/scripts/issue-bodies/loop-worktree-week-two-story.md b/scripts/issue-bodies/loop-worktree-week-two-story.mdnew file mode 100644index 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 filediff --git a/scripts/issue-bodies/multi-loop-failure-story.md b/scripts/issue-bodies/multi-loop-failure-story.mdnew file mode 100644index 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 filediff --git a/scripts/issue-bodies/quickstart-loop-sync.md b/scripts/issue-bodies/quickstart-loop-sync.mdnew file mode 100644index 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