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: 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.mddeleted file mode 100644index 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.ymlnew file mode 100644index 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: truediff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.ymlindex 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%22about: "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.mddeleted file mode 100644index 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 guidancediff --git a/.github/ISSUE_TEMPLATE/pattern-request.yml b/.github/ISSUE_TEMPLATE/pattern-request.ymlnew file mode 100644index 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: truediff --git a/.github/ISSUE_TEMPLATE/share-story.md b/.github/ISSUE_TEMPLATE/share-story.mddeleted file mode 100644index 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.ymlnew file mode 100644index 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: truediff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.mdindex 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.mdindex 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.mdindex 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 & 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 + statusnpx @cobusgreyling/loop init . --pattern daily-triage --tool groknpx @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-foundryLoop 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).## Sourcesdiff --git a/tools/goal-audit/package.json b/tools/goal-audit/package.jsonindex 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.mdindex 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 youcd tools/loop-auditnpm install-npm run build+npm run build # runs prebuild → builds ../readiness-core, then tscnode dist/cli.js /path/to/your/project```diff --git a/tools/loop-audit/package.json b/tools/loop-audit/package.jsonindex 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"