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.

release: v1.5.0 community tools drop

Cobus Greylingc32ee1412d4b
diff --git a/.github/workflows/release-loop-sync.yml b/.github/workflows/release-loop-sync.yml
new file mode 100644
index 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 file
diff --git a/README.md b/README.md
index 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.md
new file mode 100644
index 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 file
diff --git a/docs/RELEASE.md b/docs/RELEASE.md
index 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.0
git 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/releas
npx @cobusgreyling/loop-audit --help
npx @cobusgreyling/loop-init --help
npx @cobusgreyling/loop-cost --help
+npx @cobusgreyling/loop-sync --help
mkdir /tmp/loop-init-test && cd /tmp/loop-init-test
npx @cobusgreyling/loop-init . --pattern daily-triage --tool grok --dry-run
diff --git a/tools/loop-audit/CHANGELOG.md b/tools/loop-audit/CHANGELOG.md
index 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
### Changed
diff --git a/tools/loop-audit/package.json b/tools/loop-audit/package.json
index 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.json
index 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": {