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
release: v1.5.0 community tools drop
Cobus Greylingc32ee1412d4b
diff --git a/.github/workflows/release-loop-sync.yml b/.github/workflows/release-loop-sync.ymlnew file mode 100644index 0000000..66a9902--- /dev/null+++ b/.github/workflows/release-loop-sync.yml@@ -0,0 +1,47 @@+name: Release loop-sync++on:+ push:+ tags:+ - 'loop-sync-v*'+ workflow_dispatch:+ inputs:+ tag:+ description: 'Tag to publish (e.g. loop-sync-v1.0.0)'+ required: true+ type: string++permissions:+ contents: read+ id-token: write++jobs:+ test-and-publish:+ runs-on: ubuntu-latest+ steps:+ - uses: actions/checkout@v7+ with:+ ref: ${{ github.event_name == 'workflow_dispatch' && format('refs/tags/{0}', github.event.inputs.tag) || github.ref }}++ - uses: actions/setup-node@v6+ with:+ node-version: '22'+ registry-url: 'https://registry.npmjs.org'+ cache: 'npm'+ cache-dependency-path: tools/loop-sync/package-lock.json++ - name: Ensure npm supports trusted publishing (OIDC)+ run: npm install -g npm@latest++ - name: Install, build, test+ working-directory: tools/loop-sync+ run: |+ npm ci+ npm run build+ npm test++ - name: Publish to npm+ working-directory: tools/loop-sync+ run: npm publish --access public --provenance+ env:+ NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}\ No newline at end of filediff --git a/README.md b/README.mdindex 80c151c..5124553 100644--- a/README.md+++ b/README.md@@ -13,6 +13,7 @@<a href="https://www.npmjs.com/package/@cobusgreyling/loop-audit"><img src="https://img.shields.io/npm/v/@cobusgreyling/loop-audit?label=loop-audit" alt="loop-audit npm"></a><a href="https://www.npmjs.com/package/@cobusgreyling/loop-init"><img src="https://img.shields.io/npm/v/@cobusgreyling/loop-init?label=loop-init" alt="loop-init npm"></a><a href="https://www.npmjs.com/package/@cobusgreyling/loop-cost"><img src="https://img.shields.io/npm/v/@cobusgreyling/loop-cost?label=loop-cost" alt="loop-cost npm"></a>+ <a href="https://www.npmjs.com/package/@cobusgreyling/loop-sync"><img src="https://img.shields.io/npm/v/@cobusgreyling/loop-sync?label=loop-sync" alt="loop-sync npm"></a><a href="https://github.com/cobusgreyling/loop-engineering/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="MIT"></a><a href="https://cobusgreyling.github.io/loop-engineering/"><img src="https://img.shields.io/badge/GitHub_Pages-live%20%7C%20interactive-3ee8c5" alt="Pages"></a></p>@@ -72,10 +73,10 @@ A loop is a recursive goal: you define a purpose and the AI iterates (often with| [Loop Design Checklist](docs/loop-design-checklist.md) | Ship readiness rubric || [Patterns](patterns/README.md) | 7 production patterns + [interactive picker](https://cobusgreyling.github.io/loop-engineering/#interactive) || [Starters](starters/) | Clone-and-run kits (Grok, Claude Code, Codex) |-| [loop-audit](tools/loop-audit/) | Loop Readiness Score CLI (v1.4 + activity detection) — `npx @cobusgreyling/loop-audit . --suggest` · `--badge` for README |-| [loop-init](tools/loop-init/) | Scaffold starters + budget/run-log (v1.2) — `npx @cobusgreyling/loop-init . --pattern daily-triage --tool grok` |+| [loop-audit](tools/loop-audit/) | Loop Readiness Score CLI (v1.5 + constraints scoring) — `npx @cobusgreyling/loop-audit . --suggest` · `--badge` for README |+| [loop-init](tools/loop-init/) | Scaffold starters + budget/run-log + constraints (v1.2) — `npx @cobusgreyling/loop-init . --pattern daily-triage --tool grok` || [loop-cost](tools/loop-cost/) | Token spend estimator — `npx @cobusgreyling/loop-cost` |-| [loop-sync](tools/loop-sync/) | Drift detection between `STATE.md` and `LOOP.md` — `node tools/loop-sync/dist/cli.js .` |+| [loop-sync](tools/loop-sync/) | Drift detection between `STATE.md` and `LOOP.md` — `npx @cobusgreyling/loop-sync .` || [loop-mcp-server](tools/mcp-server/) | MCP runtime lookup for patterns, skills, state — `node tools/mcp-server/dist/index.js` (repo v1; npm pending) || [Goal Engineering](https://github.com/cobusgreyling/goal-engineering) | Companion: Grok Build `/goal` — run-until-done objectives (`npx @cobusgreyling/goal-audit`) || [Stories](stories/) | Real wins and honest failures |diff --git a/RELEASE_NOTES_v1.5.0.md b/RELEASE_NOTES_v1.5.0.mdnew file mode 100644index 0000000..58712cc--- /dev/null+++ b/RELEASE_NOTES_v1.5.0.md@@ -0,0 +1,83 @@+# v1.5.0 — Community Tools Drop++Seven community PRs merged. Three new tools ship. One command to try everything.++## Quickstart (copy-paste)++```bash+# Scaffold your first loop (any git repo)+npx @cobusgreyling/loop-init . --pattern daily-triage --tool grok++# Check token cost before you schedule+npx @cobusgreyling/loop-cost --pattern daily-triage --level L1 --cadence 1d++# Score readiness + get next steps+npx @cobusgreyling/loop-audit . --suggest++# Detect drift between STATE.md and LOOP.md+npx @cobusgreyling/loop-sync .+```++**New here?** [Quickstart (5 min)](docs/QUICKSTART.md) · [Interactive pattern picker](https://cobusgreyling.github.io/loop-engineering/#interactive)++---++## What's new++### New: `loop-sync` CLI (npm v1.0.0)++Detect configuration drift between `STATE.md`, `LOOP.md`, and skill versions. Run in CI or locally:++```bash+npx @cobusgreyling/loop-sync . -v+```++Contributed via [#47](https://github.com/cobusgreyling/loop-engineering/pull/47) — thanks @community.++### New: `loop-constraints`++Structured guardrails file + enforcement skill. `loop-init` now scaffolds `loop-constraints.md` and the `loop-constraints` skill on every run. `loop-audit` scores constraints presence (+6 readiness points when file + skill both exist).++Contributed via [#71](https://github.com/cobusgreyling/loop-engineering/pull/71).++### New: `loop-mcp-server` (repo v1)++MCP runtime lookup for patterns, skills, and state. Path traversal guards included.++```bash+node tools/mcp-server/dist/index.js+```++Contributed via [#72](https://github.com/cobusgreyling/loop-engineering/pull/72). npm publish coming soon.++### Updated npm packages++| Package | Version | Highlights |+|---------|---------|------------|+| `@cobusgreyling/loop-audit` | **1.5.0** | Constraints scoring + recommendations |+| `@cobusgreyling/loop-init` | **1.2.3** | Constraints scaffold; serialized asset bundling fix ([#80](https://github.com/cobusgreyling/loop-engineering/pull/80)) |+| `@cobusgreyling/loop-sync` | **1.0.0** | First npm release |++### Docs & discoverability++- [QUICKSTART.md](docs/QUICKSTART.md) — 5-minute path from zero to first loop+- [OpenClaw primitives matrix](docs/primitives-matrix.md) — cron, webhooks, heartbeat mapping+- Dark-theme SVG visuals + README polish+- Star History chart in README+- Post-run critique sections in daily-triage and changelog-drafter starters++---++## Community++This release merges work from 7 community PRs. Read the full story in [Discussion #89](https://github.com/cobusgreyling/loop-engineering/discussions/89).++**Run a loop?** Add yourself to [docs/adopters.md](docs/adopters.md) or [open an Add Adopter issue](https://github.com/cobusgreyling/loop-engineering/issues/new?template=add-adopter.yml).++**Show & tell:** [Discussions → Show and tell](https://github.com/cobusgreyling/loop-engineering/discussions/categories/show-and-tell)++---++## Companion++Loops discover ongoing work. Goals finish bounded tasks → [goal-engineering](https://github.com/cobusgreyling/goal-engineering)\ No newline at end of filediff --git a/docs/RELEASE.md b/docs/RELEASE.mdindex 2e92258..a09a10d 100644--- a/docs/RELEASE.md+++ b/docs/RELEASE.md@@ -1,12 +1,13 @@# Release playbook — npm packages-This repo ships two public npm packages from `tools/`:+This repo ships four public npm packages from `tools/`:| Package | Directory | Release tag ||---------|-----------|-------------|| `@cobusgreyling/loop-audit` | `tools/loop-audit` | `loop-audit-v*` || `@cobusgreyling/loop-init` | `tools/loop-init` | `loop-init-v*` || `@cobusgreyling/loop-cost` | `tools/loop-cost` | `loop-cost-v*` |+| `@cobusgreyling/loop-sync` | `tools/loop-sync` | `loop-sync-v*` |## One-time setup (trusted publishing — recommended)@@ -17,6 +18,7 @@ Link npm to GitHub, then for **each package** on [npmjs.com](https://www.npmjs.c| `@cobusgreyling/loop-audit` | `cobusgreyling/loop-engineering` | `release-loop-audit.yml` || `@cobusgreyling/loop-init` | `cobusgreyling/loop-engineering` | `release-loop-init.yml` || `@cobusgreyling/loop-cost` | `cobusgreyling/loop-engineering` | `release-loop-cost.yml` |+| `@cobusgreyling/loop-sync` | `cobusgreyling/loop-engineering` | `release-loop-sync.yml` |Names must match **exactly** (case-sensitive). No `NPM_TOKEN` secret is required when trusted publishing is configured.@@ -46,9 +48,13 @@ git push origin loop-init-v1.2.0# loop-cost (bundles patterns/registry.yaml)git tag loop-cost-v1.0.0git push origin loop-cost-v1.0.0++# loop-sync (drift detection between STATE.md and LOOP.md)+git tag loop-sync-v1.0.0+git push origin loop-sync-v1.0.0```-Workflows: `.github/workflows/release-loop-audit.yml`, `.github/workflows/release-loop-init.yml`, `.github/workflows/release-loop-cost.yml`.+Workflows: `.github/workflows/release-loop-audit.yml`, `.github/workflows/release-loop-init.yml`, `.github/workflows/release-loop-cost.yml`, `.github/workflows/release-loop-sync.yml`.## Verify after publish@@ -56,6 +62,7 @@ Workflows: `.github/workflows/release-loop-audit.yml`, `.github/workflows/releasnpx @cobusgreyling/loop-audit --helpnpx @cobusgreyling/loop-init --helpnpx @cobusgreyling/loop-cost --help+npx @cobusgreyling/loop-sync --helpmkdir /tmp/loop-init-test && cd /tmp/loop-init-testnpx @cobusgreyling/loop-init . --pattern daily-triage --tool grok --dry-rundiff --git a/tools/loop-audit/CHANGELOG.md b/tools/loop-audit/CHANGELOG.mdindex f610aa9..a54076b 100644--- a/tools/loop-audit/CHANGELOG.md+++ b/tools/loop-audit/CHANGELOG.md@@ -2,6 +2,12 @@All notable changes to `@cobusgreyling/loop-audit` are documented here.+## [1.5.0] - 2026-06-30++### Added+- `loop-constraints.md` and `loop-constraints` skill detection in readiness scoring (+6 points when both present)+- Recommendations when constraints file or skill is missing+## [1.4.1] - 2026-06-13### Changeddiff --git a/tools/loop-audit/package.json b/tools/loop-audit/package.jsonindex 616b513..e406a56 100644--- a/tools/loop-audit/package.json+++ b/tools/loop-audit/package.json@@ -1,6 +1,6 @@{"name": "@cobusgreyling/loop-audit",- "version": "1.4.2",+ "version": "1.5.0","description": "Loop engineering readiness auditor. Compute Loop Readiness Score (L0-L3), detect activity, and get actionable suggestions. npx @cobusgreyling/loop-audit . --suggest","type": "module","bin": {diff --git a/tools/loop-init/package.json b/tools/loop-init/package.jsonindex 3b510fc..a27f0e0 100644--- a/tools/loop-init/package.json+++ b/tools/loop-init/package.json@@ -1,6 +1,6 @@{"name": "@cobusgreyling/loop-init",- "version": "1.2.2",+ "version": "1.2.3","description": "Scaffold loop engineering patterns and starters into any project. Supports Grok, Claude Code, Codex and more. npx @cobusgreyling/loop-init . --pattern daily-triage --tool grok","type": "module","bin": {