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
community: Wave 6 GFIs + docs/examples area owner + Help wanted refresh
Cobus Greylinge539604433dc
diff --git a/CODEOWNERS b/CODEOWNERSindex 23fa2e1..cc08e74 100644--- a/CODEOWNERS+++ b/CODEOWNERS@@ -1,8 +1,14 @@-# Default owner for review routing (solo maintainer today).+# Default owner for review routing.* @cobusgreyling+# Core patterns, tools, CI — maintainer/patterns/ @cobusgreyling/tools/ @cobusgreyling/.github/ @cobusgreyling-/docs/ @cobusgreyling-/starters/ @cobusgreyling\ No newline at end of file+/starters/ @cobusgreyling++# Docs / examples / stories — co-triaged by community area owner+# (AIMindCrafter: multi-PR docs/examples track; write access for CODEOWNERS reviews)+/docs/ @cobusgreyling @AIMindCrafter+/examples/ @cobusgreyling @AIMindCrafter+/stories/ @cobusgreyling @AIMindCrafterdiff --git a/CONTRIBUTING.md b/CONTRIBUTING.mdindex 1bea3ed..d51c0a4 100644--- a/CONTRIBUTING.md+++ b/CONTRIBUTING.md@@ -50,7 +50,17 @@ Also add an entry to `patterns/registry.yaml`.- Include at least one failure or surprise- Actionable lesson in one paragraph-## Development Setup+## Contributor paths (pick one)++| Path | When | Setup |+|------|------|--------|+| **A — Content** | Stories, examples, adopters, most docs | No install — edit markdown, open PR |+| **B — One package** | Fix a single CLI under `tools/<pkg>` | `cd tools/<pkg> && npm ci && npm test` |+| **C — Full monorepo** | Registry / cross-package scripts | Root `npm ci` then commands below |++Stories and adopters get **same-day review** when possible. Live backlog: [`good first issue`](https://github.com/cobusgreyling/loop-engineering/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22).++## Development Setup (Path C)```bashnpm ci # at repo root – installs yaml/ajv for scripts/validate-registry.mjs@@ -58,6 +68,10 @@ npm run validate:registrynpm run check:loop-init```+## Area owners++See [docs/area-owners.md](./docs/area-owners.md). Docs/examples/stories PRs are co-reviewed by [@AIMindCrafter](https://github.com/AIMindCrafter) (CODEOWNERS).+## Pull Request Checklist- [ ] Links work from README or relevant indexdiff --git a/README.md b/README.mdindex f298d0d..69d8c0c 100644--- a/README.md+++ b/README.md@@ -301,19 +301,21 @@ 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).-**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.+**13 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-08-10** — Wave 6 from real community PR pain). 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) · [#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/` |+| ~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 |+| ~20–25 min | [#482 — CONTRIBUTING Path A/B/C](https://github.com/cobusgreyling/loop-engineering/issues/482) · [#483 — Windows notes](https://github.com/cobusgreyling/loop-engineering/issues/483) | Setup map + Windows/CRLF landing notes (pain from #477 / #476) |+| ~20–40 min | [#481 — append-run-log JSON test](https://github.com/cobusgreyling/loop-engineering/issues/481) · [#480 — skill-dedup test](https://github.com/cobusgreyling/loop-engineering/issues/480) · [#479 — loop-sync CRLF tests](https://github.com/cobusgreyling/loop-engineering/issues/479) | Regression tests locking fixes from #474–#476 |+| ~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) · [#484 — Windsurf Post-Merge](https://github.com/cobusgreyling/loop-engineering/issues/484) · [#485 — Windsurf Changelog](https://github.com/cobusgreyling/loop-engineering/issues/485) | Fill pattern-coverage gaps in `examples/` || 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) |-**Recently shipped (thanks!):** Windsurf examples (#384–#386), loop-action/sandbox/gate QUICKSTART (#389–#391), CI Sweeper story (#392), loop-action hardening (#393/#395).+**Recently shipped (thanks!):** Community batch from @pxmpsdev — goal-audit fixture + run-log guard (#474), readiness-core skill dedup (#475), loop-sync CRLF (#476), root `npm ci` docs (#477). Earlier: Windsurf examples, loop-action/sandbox/gate QUICKSTART, CI Sweeper story.++**Docs/examples triage:** @AIMindCrafter co-owns `docs/`, `examples/`, and `stories/` (see [CODEOWNERS](CODEOWNERS) + [docs/area-owners.md](docs/area-owners.md)).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.diff --git a/docs/area-owners.md b/docs/area-owners.mdnew file mode 100644index 0000000..8892fca--- /dev/null+++ b/docs/area-owners.md@@ -0,0 +1,27 @@+# Area owners++Optional community ownership for review routing. **Owner** still ships `main` and releases; area owners help triage and review scoped PRs faster.++| Area | Paths | Owner | Scope |+|------|-------|-------|--------|+| **Maintainer** | repo-wide | [@cobusgreyling](https://github.com/cobusgreyling) | Releases, tools, patterns, safety |+| **Docs / examples / stories** | `docs/`, `examples/`, `stories/` | [@AIMindCrafter](https://github.com/AIMindCrafter) (triage + review) | QUICKSTART, tool examples, production stories, adopters-adjacent docs |++## What area owners do++1. **Triage** issues labeled `docs`, `story`, or `good first issue` that touch their paths+2. **Review** PRs that only change those paths (approve, request changes, or ping maintainer)+3. **Unstick** stale “I'll take this” claims after ~14 days with no PR (comment + free the issue)+4. **Escalate** anything that changes scoring, safety, npm publish, or CI to the maintainer++## What they do *not* need to do++- Merge to `main` alone if branch rules require maintainer approval+- Own npm releases or security advisories ([SECURITY.md](../SECURITY.md))+- Review `tools/` CLI changes unless they ask++## Becoming an area owner++Multi-PR track record in the area + public invite from the maintainer. Start with [CONTRIBUTING.md](../CONTRIBUTING.md) and the [contributor quickstart](https://github.com/cobusgreyling/loop-engineering/discussions/123).++CODEOWNERS file: [../CODEOWNERS](../CODEOWNERS).diff --git a/scripts/create-good-first-issues.sh b/scripts/create-good-first-issues.shindex 827cd4a..091ac81 100755--- a/scripts/create-good-first-issues.sh+++ b/scripts/create-good-first-issues.sh@@ -79,3 +79,12 @@ create_issue "Add MiniMax foundry flags to QUICKSTART" "good first issue,docs" "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"++# Wave 6 — 2026-08-10 community pain (from merged PRs #474–#477) + coverage gaps+create_issue "Add CRLF frontmatter regression tests for loop-sync" "good first issue,tooling" "$BODY_DIR/loop-sync-crlf-tests.md"+create_issue "Add skill-dedup regression test for readiness-core" "good first issue,tooling" "$BODY_DIR/readiness-core-skill-dedup-test.md"+create_issue "Add invalid-JSON test for append-run-log" "good first issue,tooling" "$BODY_DIR/append-run-log-invalid-json-test.md"+create_issue "Expand CONTRIBUTING with Path A/B/C setup map" "good first issue,docs" "$BODY_DIR/contributing-path-abc.md"+create_issue "Add Windows contributor notes to QUICKSTART" "good first issue,docs" "$BODY_DIR/windows-contributor-notes.md"+create_issue "Add Windsurf Post-Merge Cleanup example doc" "good first issue,docs" "$BODY_DIR/windsurf-post-merge-cleanup-example.md"+create_issue "Add Windsurf Changelog Drafter example doc" "good first issue,docs" "$BODY_DIR/windsurf-changelog-drafter-example.md"diff --git a/scripts/issue-bodies/append-run-log-invalid-json-test.md b/scripts/issue-bodies/append-run-log-invalid-json-test.mdnew file mode 100644index 0000000..dfbca0d--- /dev/null+++ b/scripts/issue-bodies/append-run-log-invalid-json-test.md@@ -0,0 +1,20 @@+## Goal++Add a test (or small smoke script check) that `scripts/append-run-log.mjs` exits cleanly on invalid JSON.++**Pain source:** Community PR #474 replaced a stacktrace with a Usage message + exit 1. Lock that behaviour in.++## Files++- Prefer a tiny test under `scripts/` or document a one-liner in an existing script test if present+- Or add `scripts/append-run-log.test.mjs` if that matches repo style++## Acceptance criteria++- [ ] Invalid second arg (not JSON) → exit code 1 and message mentions Usage / valid JSON+- [ ] Valid minimal JSON entry does not throw on parse (can mock/skip file write if needed)+- [ ] No secrets; keeps change small++**Estimated time:** ~20–30 minutes · label: tooling++Comment **"I'll take this"** to get assigned.diff --git a/scripts/issue-bodies/contributing-path-abc.md b/scripts/issue-bodies/contributing-path-abc.mdnew file mode 100644index 0000000..63fc4dc--- /dev/null+++ b/scripts/issue-bodies/contributing-path-abc.md@@ -0,0 +1,22 @@+## Goal++Expand **CONTRIBUTING.md** with Path A / B / C so first-time contributors do not hit monorepo setup walls.++**Pain source:** Community PR #477 documented root `npm ci` after fresh clones failed with `ERR_MODULE_NOT_FOUND: yaml` when only `tools/*/npm ci` was run. Still missing a clear “which path do I need?” map.++## Files++- `CONTRIBUTING.md` — add **Contributor paths** section near Development Setup+- Optional one-line pointer from README Help wanted → CONTRIBUTING paths++## Acceptance criteria++- [ ] **Path A — Content only:** markdown under `stories/`, `examples/`, `docs/adopters.md` — no install+- [ ] **Path B — One package:** `cd tools/<pkg> && npm ci && npm test` for a single CLI fix+- [ ] **Path C — Full monorepo:** root `npm ci` + `validate:registry` + `check:loop-init`+- [ ] Mentions same-day review for stories/adopters+- [ ] Links live GFI filter++**Estimated time:** ~20–25 minutes · label: docs++Comment **"I'll take this"** to get assigned.diff --git a/scripts/issue-bodies/loop-sync-crlf-tests.md b/scripts/issue-bodies/loop-sync-crlf-tests.mdnew file mode 100644index 0000000..011b700--- /dev/null+++ b/scripts/issue-bodies/loop-sync-crlf-tests.md@@ -0,0 +1,21 @@+## Goal++Add **regression tests** for CRLF frontmatter parsing in `loop-sync`.++**Pain source:** Community PR #476 fixed Windows line endings (`\r\n`) in `extractFrontmatter`. Without tests, a future change can re-break Windows contributors.++## Files++- `tools/loop-sync/test/sync.test.mjs` (extend)+- Optional fixture files under `tools/loop-sync/test/fixtures/` if cleaner++## Acceptance criteria++- [ ] Test: LF frontmatter still parses (existing behaviour)+- [ ] Test: CRLF frontmatter (`---\r\nkey: value\r\n---\r\nbody`) parses keys without trailing `\r`+- [ ] Test: `---hello` (no newline after opening fence) is **rejected** / not treated as frontmatter+- [ ] `cd tools/loop-sync && npm test` passes++**Estimated time:** ~30–40 minutes · label: tooling++Comment **"I'll take this"** to get assigned.diff --git a/scripts/issue-bodies/readiness-core-skill-dedup-test.md b/scripts/issue-bodies/readiness-core-skill-dedup-test.mdnew file mode 100644index 0000000..04b8dcd--- /dev/null+++ b/scripts/issue-bodies/readiness-core-skill-dedup-test.md@@ -0,0 +1,21 @@+## Goal++Add a **regression test** that skill names are deduplicated across skill directories in `readiness-core`.++**Pain source:** Community PR #475 fixed double-counting when the same skill existed in e.g. `.grok/skills/foo` and `skills/foo`, which inflated the Loop Readiness score.++## Files++- `tools/readiness-core/test/index.test.mjs` (extend)+- Temp fixture dirs created in the test (prefer no permanent multi-dir fixtures unless needed)++## Acceptance criteria++- [ ] Fixture: same skill directory name under two scanned roots → `scanSkillDirectories` returns count **1** for that name+- [ ] Distinct skill names still count separately+- [ ] Documents why dedup matters (score signals `skillsOne` vs `skillsTwoPlus`)+- [ ] `cd tools/readiness-core && npm test` passes++**Estimated time:** ~25–35 minutes · label: tooling++Comment **"I'll take this"** to get assigned.diff --git a/scripts/issue-bodies/windows-contributor-notes.md b/scripts/issue-bodies/windows-contributor-notes.mdnew file mode 100644index 0000000..f5f21fb--- /dev/null+++ b/scripts/issue-bodies/windows-contributor-notes.md@@ -0,0 +1,22 @@+## Goal++Add a short **Windows / CRLF notes** subsection so Windows users do not re-discover line-ending bugs.++**Pain source:** PR #476 (loop-sync frontmatter CRLF) and earlier loop-sandbox Windows `spawn ENOENT` notes. Scattered fixes; no single “Windows contributors” landing spot.++## Files++- `docs/QUICKSTART.md` — short subsection (or link from Development / Operating)+- Optionally cross-link from `CONTRIBUTING.md`++## Acceptance criteria++- [ ] Notes git `core.autocrlf` recommendation for this repo+- [ ] Points at loop-sync frontmatter LF/CRLF support (after #476)+- [ ] Points at loop-sandbox Windows `npx` / `.cmd` shim behaviour if already documented+- [ ] 1 short “if you hit X, try Y” troubleshooting bullet list+- [ ] No wall of text — ~15–25 lines max++**Estimated time:** ~20–25 minutes · label: docs++Comment **"I'll take this"** to get assigned.diff --git a/scripts/issue-bodies/windsurf-changelog-drafter-example.md b/scripts/issue-bodies/windsurf-changelog-drafter-example.mdnew file mode 100644index 0000000..a592f54--- /dev/null+++ b/scripts/issue-bodies/windsurf-changelog-drafter-example.md@@ -0,0 +1,20 @@+## Goal++Add a **Windsurf Changelog Drafter** example to complete Windsurf pattern coverage.++## Files++- `examples/windsurf/changelog-drafter.md` (new)+- `examples/windsurf/README.md` (link)+- `examples/README.md` (matrix cell if present)++## Acceptance criteria++- [ ] Week-one L1 draft-only (no auto-publish)+- [ ] Follow tone of existing Windsurf examples+- [ ] Tag/cadence notes + state schema sketch+- [ ] Link from Windsurf README index++**Estimated time:** ~40 minutes · label: docs++Comment **"I'll take this"** to get assigned.diff --git a/scripts/issue-bodies/windsurf-post-merge-cleanup-example.md b/scripts/issue-bodies/windsurf-post-merge-cleanup-example.mdnew file mode 100644index 0000000..f50c897--- /dev/null+++ b/scripts/issue-bodies/windsurf-post-merge-cleanup-example.md@@ -0,0 +1,20 @@+## Goal++Add a **Windsurf Post-Merge Cleanup** example. Windsurf already has daily-triage, PR babysitter, CI/dependency/issue triage — post-merge is a gap.++## Files++- `examples/windsurf/post-merge-cleanup.md` (new)+- `examples/windsurf/README.md` (link)+- `examples/README.md` (matrix cell if present)++## Acceptance criteria++- [ ] Week-one L1 report-only (no auto-delete of branches without human gate)+- [ ] Follow tone of existing `examples/windsurf/*.md`+- [ ] Cadence / skill / state notes+- [ ] Link from Windsurf README index++**Estimated time:** ~40 minutes · label: docs++Comment **"I'll take this"** to get assigned.