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.

community: Wave 6 GFIs + docs/examples area owner + Help wanted refresh

Cobus Greylinge539604433dc
diff --git a/CODEOWNERS b/CODEOWNERS
index 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 @AIMindCrafter
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 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)
```bash
npm ci # at repo root – installs yaml/ajv for scripts/validate-registry.mjs
@@ -58,6 +68,10 @@ npm run validate:registry
npm 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 index
diff --git a/README.md b/README.md
index 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.md
new file mode 100644
index 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.sh
index 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.md
new file mode 100644
index 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.md
new file mode 100644
index 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.md
new file mode 100644
index 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.md
new file mode 100644
index 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.md
new file mode 100644
index 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.md
new file mode 100644
index 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.md
new file mode 100644
index 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.