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: contributor funnel — templates, README CTAs, loop-audit build order (#513)

Cobus Greyling344915811380
diff --git a/.github/ISSUE_TEMPLATE/bug-report.md b/.github/ISSUE_TEMPLATE/bug-report.md
deleted file mode 100644
index 0c9a0c2..0000000
--- a/.github/ISSUE_TEMPLATE/bug-report.md
+++ /dev/null
@@ -1,26 +0,0 @@
----
-name: Bug report
-about: Something is broken, inaccurate, or loop-audit gives wrong results
-title: "[bug] "
-labels: ["bug"]
----
-
-**Describe the bug**
-
-**Steps to reproduce**
-1.
-2.
-
-**Expected behavior**
-
-**Actual behavior** (include `loop-audit --json` or command output if relevant)
-
-**Environment**
-- OS:
-- Node (for CLIs):
-- Tool (Grok / Claude / Codex / Cursor / Opencode / other):
-- Target repo (if not this one):
-
-**Additional context**
-
-If this is a pattern or safety issue, reference `docs/safety.md` or `docs/failure-modes.md`.
diff --git a/.github/ISSUE_TEMPLATE/bug-report.yml b/.github/ISSUE_TEMPLATE/bug-report.yml
new file mode 100644
index 0000000..d9910d1
--- /dev/null
+++ b/.github/ISSUE_TEMPLATE/bug-report.yml
@@ -0,0 +1,42 @@
+name: Bug report
+description: Something is broken, inaccurate, or loop-audit gives wrong results
+title: "[bug] "
+labels:
+ - bug
+body:
+ - type: textarea
+ id: describe
+ attributes:
+ label: Describe the bug
+ validations:
+ required: true
+ - type: textarea
+ id: reproduce
+ attributes:
+ label: Steps to reproduce
+ placeholder: |
+ 1.
+ 2.
+ 3.
+ validations:
+ required: true
+ - type: textarea
+ id: expected
+ attributes:
+ label: Expected behavior
+ validations:
+ required: true
+ - type: textarea
+ id: actual
+ attributes:
+ label: Actual behavior
+ description: Include `npx @cobusgreyling/loop audit . --json` or other command output if relevant
+ validations:
+ required: true
+ - type: input
+ id: env
+ attributes:
+ label: Environment
+ placeholder: "OS: macOS 15 · Node: 22 · package: @cobusgreyling/loop-audit@…"
+ validations:
+ required: true
diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml
index 3487e22..83772c1 100644
--- a/.github/ISSUE_TEMPLATE/config.yml
+++ b/.github/ISSUE_TEMPLATE/config.yml
@@ -12,3 +12,6 @@ contact_links:
- name: "🌱 Good first issues"
url: https://github.com/cobusgreyling/loop-engineering/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22
about: "Scoped ~10 min–1 hr tasks. Comment I'll take this to get assigned."
+ - name: "🔒 Security vulnerability"
+ url: https://github.com/cobusgreyling/loop-engineering/blob/main/SECURITY.md
+ about: "Report security issues privately — do not open a public issue."
diff --git a/.github/ISSUE_TEMPLATE/pattern-request.md b/.github/ISSUE_TEMPLATE/pattern-request.md
deleted file mode 100644
index c833e96..0000000
--- a/.github/ISSUE_TEMPLATE/pattern-request.md
+++ /dev/null
@@ -1,16 +0,0 @@
----
-name: Pattern request
-about: Request a new documented loop pattern
-title: "[pattern] "
-labels: ["pattern-request"]
----
-
-**Pattern name** (short)
-
-**Problem it solves**
-
-**Tools you care about** (Grok / Claude / Codex / Cursor / …)
-
-**Similar existing pattern?** (link under `patterns/` if any)
-
-**Would you draft a PR?** yes / no / need guidance
diff --git a/.github/ISSUE_TEMPLATE/pattern-request.yml b/.github/ISSUE_TEMPLATE/pattern-request.yml
new file mode 100644
index 0000000..329d993
--- /dev/null
+++ b/.github/ISSUE_TEMPLATE/pattern-request.yml
@@ -0,0 +1,41 @@
+name: Pattern request
+description: Request a new loop pattern or tool mapping
+title: "[pattern] "
+labels:
+ - pattern-request
+body:
+ - type: input
+ id: name
+ attributes:
+ label: Pattern name
+ placeholder: e.g. Nightly Flake Hunter
+ validations:
+ required: true
+ - type: textarea
+ id: goal
+ attributes:
+ label: Goal (one sentence)
+ validations:
+ required: true
+ - type: dropdown
+ id: tools
+ attributes:
+ label: Tools you need it for
+ multiple: true
+ options:
+ - Grok
+ - Claude Code
+ - Codex
+ - Cursor
+ - Opencode
+ - GitHub Actions
+ - Other
+ validations:
+ required: true
+ - type: textarea
+ id: context
+ attributes:
+ label: Context
+ description: When would this run? What does success look like?
+ validations:
+ required: true
diff --git a/.github/ISSUE_TEMPLATE/share-story.md b/.github/ISSUE_TEMPLATE/share-story.md
deleted file mode 100644
index 691266f..0000000
--- a/.github/ISSUE_TEMPLATE/share-story.md
+++ /dev/null
@@ -1,18 +0,0 @@
----
-name: Share a production story
-about: Honest win or failure from running a loop
-title: "[story] "
-labels: ["story", "good first issue"]
----
-
-**Pattern used** (Daily Triage / PR Babysitter / CI Sweeper / other)
-
-**Tool** (Grok / Claude / Codex / Cursor / Opencode / other)
-
-**What worked**
-
-**What failed or surprised you** (required — failures are first-class)
-
-**Actionable lesson** (one paragraph)
-
-**Optional:** PR under `stories/` instead of this issue — same-day review when possible.
diff --git a/.github/ISSUE_TEMPLATE/share-story.yml b/.github/ISSUE_TEMPLATE/share-story.yml
new file mode 100644
index 0000000..e81e138
--- /dev/null
+++ b/.github/ISSUE_TEMPLATE/share-story.yml
@@ -0,0 +1,67 @@
+name: Share a production story
+description: Honest win or failure from running a loop (failures are first-class)
+title: "[story] "
+labels:
+ - story
+ - good first issue
+body:
+ - type: markdown
+ value: |
+ Real experience preferred. Anonymize if needed. You can also open a PR under `stories/` — same-day review when possible.
+
+ - type: dropdown
+ id: pattern
+ attributes:
+ label: Pattern used
+ options:
+ - Daily Triage
+ - PR Babysitter
+ - CI Sweeper
+ - Dependency Sweeper
+ - Changelog Drafter
+ - Post-Merge Cleanup
+ - Issue Triage
+ - Other / custom
+ validations:
+ required: true
+
+ - type: dropdown
+ id: tool
+ attributes:
+ label: Primary tool
+ options:
+ - Grok
+ - Claude Code
+ - Codex
+ - Cursor
+ - Opencode
+ - Windsurf
+ - GitHub Actions
+ - Mixed / other
+ validations:
+ required: true
+
+ - type: textarea
+ id: worked
+ attributes:
+ label: What worked
+ placeholder: What the loop did well for a week or more
+ validations:
+ required: true
+
+ - type: textarea
+ id: failed
+ attributes:
+ label: What failed or surprised you
+ description: Required — failures are first-class content in this repo
+ placeholder: Token spike, bad auto-merge, drift, human gate miss…
+ validations:
+ required: true
+
+ - type: textarea
+ id: lesson
+ attributes:
+ label: Actionable lesson
+ description: One paragraph others can act on
+ validations:
+ required: true
diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md
index 13a3b70..56f1daa 100644
--- a/.github/PULL_REQUEST_TEMPLATE.md
+++ b/.github/PULL_REQUEST_TEMPLATE.md
@@ -1,27 +1,28 @@
## Summary
-<!-- One sentence what this does and why -->
+<!-- One sentence: what this does and why -->
+
+## Related issue
+<!-- Fixes #123 or Relates to #456 — link if there is one -->
## Changes
- [ ] New pattern or starter (followed `templates/pattern-template.md` + updated `registry.yaml`)
-- [ ] Doc / example improvement
-- [ ] Tool change (loop-audit)
-- [ ] Story (includes real failure or surprise + lesson)
+- [ ] Doc / example / story improvement
+- [ ] Tool / CLI change under `tools/`
+- [ ] Test only
+- [ ] Other
## Checklist (from CONTRIBUTING)
-- [ ] All required sections present for patterns
-- [ ] Links work from README, patterns/README, starters/README, docs/index
-- [ ] No secrets, tokens, internal company URLs
+- [ ] Links work from README or the relevant index
+- [ ] No secrets, tokens, or internal company URLs
- [ ] `STATE.md*` examples use `.example` suffix
- [ ] Safety-related content references `docs/safety.md`
-- [ ] Ran `node tools/loop-audit/dist/cli.js .` (or on the starter) and addressed findings
+- [ ] If you touched a package under `tools/<pkg>`: `cd tools/<pkg> && npm ci && npm test`
+- [ ] If you touched the registry: root `npm ci && npm run validate:registry`
## Testing / Dogfood
-- [ ] `loop-audit` passes on affected starters or this repo
-- [ ] Manual review of generated state / skill output
-
-## Screenshots / Examples (if UI or command output)
-<!-- Paste relevant output or link to rendered docs -->
+- [ ] `npx @cobusgreyling/loop audit .` (or package-local tests) on affected paths
+- [ ] Manual review of generated state / skill output if scaffolding changed
---
-*This template enforces the high bar this reference is known for.*
+Docs, stories, adopters, and small tests: **maintainers aim to review within 48 hours** (same-day when possible).
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 96b1951..4b489c3 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -2,6 +2,8 @@
This repo is a **practical engineering reference**, not a hype collection. We welcome patterns, stories, tool mappings, and honest failure reports.
+**Maintainer response:** docs, stories, adopters, and small tests get a first response within **48 hours** (same-day when possible). Comment *I'll take this* on a [`good first issue`](https://github.com/cobusgreyling/loop-engineering/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22) to get assigned.
+
## Ways to Contribute
| Contribution | Where |
diff --git a/README.md b/README.md
index 40f6492..b28b5ac 100644
--- a/README.md
+++ b/README.md
@@ -35,18 +35,23 @@
<img src="assets/visuals/LE5.jpeg" alt="Loop Engineering — design the system that prompts your agents" width="100%" />
</p>
+<p align="center">
+ <strong>Start in 5 minutes</strong> ·
+ <a href="docs/QUICKSTART.md">Quickstart</a> ·
+ <a href="https://cobusgreyling.github.io/loop-engineering/#interactive">Pattern picker</a> ·
+ <a href="#help-wanted">Contribute</a> ·
+ <a href="https://github.com/cobusgreyling/loop-engineering/stargazers">⭐ Star</a>
+</p>
+
+<p align="center"><sub>If this repo changed how you run agents, a star helps others find the patterns. Docs &amp; small PRs: we aim to review within <strong>48 hours</strong>.</sub></p>
+
```bash
-# Front door (recommended) — one binary for init + doctor + status
+# One front door — init + doctor + status
npx @cobusgreyling/loop init . --pattern daily-triage --tool grok
npx @cobusgreyling/loop doctor .
-
-# Same as before (still fully supported — forks need not change)
-npx @cobusgreyling/loop-init .
-# Optional: also scaffold a versioned harness (harness-foundry)
-npx @cobusgreyling/loop init . --with-foundry
```
-`loop init` (or `loop-init`) scaffolds skills, state, and budget files, then prints your **Loop Ready** score and first loop command. `loop doctor` combines audit + sync + file checks into top-3 next actions. Swap `--tool` for `claude`, `codex`, or `opencode`. Use `--with-foundry` when you want the loop as a composable runtime stack. See [docs/cli-front-door.md](docs/cli-front-door.md).
+`loop init` scaffolds skills, state, and budget files, then prints your **Loop Ready** score. `loop doctor` turns audit + sync into top-3 next actions. Swap `--tool` for `claude`, `codex`, or `opencode`. Optional: `--with-foundry` for a versioned harness stack. Legacy `npx @cobusgreyling/loop-init .` still works. See [docs/cli-front-door.md](docs/cli-front-door.md).
<p align="center">
<a href="docs/QUICKSTART.md">
@@ -56,7 +61,7 @@ npx @cobusgreyling/loop init . --with-foundry
Loop engineering replaces you as the person who prompts the agent — you design the system that does it instead.
-**New here?** [Quickstart (5 min)](docs/QUICKSTART.md) · [Interactive picker](https://cobusgreyling.github.io/loop-engineering/#interactive)
+**New here?** [Quickstart (5 min)](docs/QUICKSTART.md) · [Interactive picker](https://cobusgreyling.github.io/loop-engineering/#interactive) · [Help wanted](#help-wanted)
For developers using Grok, Claude Code, Codex, Cursor, and other AI coding agents.
@@ -299,9 +304,11 @@ Addy Osmani:
## Help wanted
-**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).
+**First PR?** Pick an open issue below, or [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).
+
+**Review SLA:** docs, stories, adopters, and small tests — **within 48 hours** (same-day when possible). See [CONTRIBUTORS.md](CONTRIBUTORS.md) and the [contributor quickstart](https://github.com/cobusgreyling/loop-engineering/discussions/123).
-**12 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.
+[`good first issue` backlog](https://github.com/cobusgreyling/loop-engineering/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22) (comment **"I'll take this"** for assignment). Prefer the live filter if a row below looks stale.
| Time | Issue | What you ship |
|------|-------|---------------|
@@ -313,7 +320,7 @@ Addy Osmani:
| 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!):** 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.
+**Recently shipped (thanks!):** @pxmpsdev — loop-sync CRLF tests (#496), readiness skill-dedup (#497), append-run-log invalid-JSON (#498), metrics unparseable run_id (#499). @shixi-li — Hermes CI Sweeper example (#500). Earlier: @pxmpsdev #474–#477.
**Docs/examples triage:** @AIMindCrafter co-owns `docs/`, `examples/`, and `stories/` (see [CODEOWNERS](CODEOWNERS) + [docs/area-owners.md](docs/area-owners.md)).
@@ -321,7 +328,9 @@ Maintainers re-seed the backlog with `bash scripts/create-good-first-issues.sh`
## Contributing
-Share production patterns, tool mappings, and failure stories. See [CONTRIBUTING.md](CONTRIBUTING.md) (contribution ladder + [`good first issue` backlog](https://github.com/cobusgreyling/loop-engineering/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22)), [Code of Conduct](CODE_OF_CONDUCT.md), [adopters](docs/adopters.md), and hubs: [Show your loop](https://github.com/cobusgreyling/loop-engineering/discussions/326) · [Ask anything](https://github.com/cobusgreyling/loop-engineering/discussions/327).
+Share production patterns, tool mappings, and failure stories. See [CONTRIBUTING.md](CONTRIBUTING.md) (ladder + setup), [Code of Conduct](CODE_OF_CONDUCT.md), [adopters](docs/adopters.md), and hubs: [Show your loop](https://github.com/cobusgreyling/loop-engineering/discussions/326) · [Ask anything](https://github.com/cobusgreyling/loop-engineering/discussions/327).
+
+We aim to **first-respond within 48 hours** on external PRs. Start here: [`good first issue`](https://github.com/cobusgreyling/loop-engineering/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22) · [Help wanted](#help-wanted).
## Sources
diff --git a/tools/goal-audit/package.json b/tools/goal-audit/package.json
index 72d0a66..70c6b53 100644
--- a/tools/goal-audit/package.json
+++ b/tools/goal-audit/package.json
@@ -14,7 +14,8 @@
"build": "tsc",
"test": "npm run build && node --test test/auditor.test.mjs",
"prepublishOnly": "npm test",
- "start": "node dist/cli.js"
+ "start": "node dist/cli.js",
+ "prebuild": "npm install --prefix ../readiness-core --no-fund --no-audit && npm run build --prefix ../readiness-core"
},
"engines": {
"node": ">=18"
diff --git a/tools/loop-audit/README.md b/tools/loop-audit/README.md
index 9c96e7b..eb71105 100644
--- a/tools/loop-audit/README.md
+++ b/tools/loop-audit/README.md
@@ -16,9 +16,10 @@ npx @cobusgreyling/loop-audit . --suggest
**From this repo:**
```bash
+# readiness-core is a monorepo sibling (file: dep) — prebuild builds it for you
cd tools/loop-audit
npm install
-npm run build
+npm run build # runs prebuild → builds ../readiness-core, then tsc
node dist/cli.js /path/to/your/project
```
diff --git a/tools/loop-audit/package.json b/tools/loop-audit/package.json
index 63ad42d..184f412 100644
--- a/tools/loop-audit/package.json
+++ b/tools/loop-audit/package.json
@@ -17,7 +17,8 @@
"start": "node dist/cli.js",
"audit": "npm run build && node dist/cli.js",
"audit:suggest": "npm run build && node dist/cli.js . --suggest",
- "demo": "bash ../../scripts/before-after-demo.sh"
+ "demo": "bash ../../scripts/before-after-demo.sh",
+ "prebuild": "npm install --prefix ../readiness-core --no-fund --no-audit && npm run build --prefix ../readiness-core"
},
"engines": {
"node": ">=18"