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
docs: sync version references across README, RELEASE, and CHANGELOG (#238)
Cobus Greyling0954794686e6
diff --git a/README.md b/README.mdindex ddfa91a..d2d960b 100644--- a/README.md+++ b/README.md@@ -87,8 +87,8 @@ For developers using Grok, Claude Code, Codex, Cursor, and other AI coding agent| [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, Opencode) || [Opencode examples](examples/opencode/) | CLI-first loops: cron/systemd + `opencode run`, skills, worktrees |-| [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-audit](tools/loop-audit/) | Loop Readiness Score CLI (v1.6 — constraints + governance scoring) — `npx @cobusgreyling/loop-audit . --suggest` · `--badge` for README |+| [loop-init](tools/loop-init/) | Scaffold starters + budget/run-log + constraints (v1.3) — `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` — `npx @cobusgreyling/loop-sync .` || [loop-context](tools/loop-context/) | Stateful memory manager + circuit breaker for long runs — `npx @cobusgreyling/loop-context --check --ledger run.json` |@@ -98,6 +98,7 @@ For developers using Grok, Claude Code, Codex, Cursor, and other AI coding agent| [Stories](stories/) | Real wins and honest failures || [Contributor quickstart](https://github.com/cobusgreyling/loop-engineering/discussions/123) | **Help wanted:** 25 scoped `good first issues` — comment *I'll take this* to get assigned || [Community update](https://github.com/cobusgreyling/loop-engineering/discussions/145) | **July 4:** 5.5k stars, traffic sources, contributor merges |+| [Community week (Jul 8)](https://github.com/cobusgreyling/loop-engineering/discussions/219) | loop-worktree npm, MCP quickstart, tool appendices || [Prior release notes](https://github.com/cobusgreyling/loop-engineering/discussions/89) | v1.5.0 — loop-sync, constraints, MCP server || [Add your project](https://github.com/cobusgreyling/loop-engineering/discussions/92) | **Pinned:** Loop Ready badge + adopters list |@@ -204,7 +205,7 @@ bash scripts/before-after-demo.sh/loop 1d Run loop-triage. Update STATE.md. No auto-fix in week one.```-All three CLIs publish to npm from tagged releases — see [docs/RELEASE.md](docs/RELEASE.md). No clone required.+All npm CLIs publish from tagged releases — see [docs/RELEASE.md](docs/RELEASE.md). No clone required.**Develop from source** (monorepo contributors):diff --git a/RELEASE_NOTES_DRAFT.md b/RELEASE_NOTES_DRAFT.mdindex e001a7f..5342017 100644--- a/RELEASE_NOTES_DRAFT.md+++ b/RELEASE_NOTES_DRAFT.md@@ -1,13 +1,27 @@# Release notes draft — since `loop-mcp-server-v1.0.0`-**Status:** Published to [Discussions](https://github.com/cobusgreyling/loop-engineering/discussions) on 2026-07-08. Archive copy for the next changelog-drafter run.+**Status:** Published to [Discussions #219](https://github.com/cobusgreyling/loop-engineering/discussions/219) on 2026-07-08. Post-publish additions below (loop-audit 1.6.0). Archive copy for the next changelog-drafter run.-**Window:** 2026-07-06 → 2026-07-08+**Window:** 2026-07-06 → 2026-07-09---## Highlights+### loop-audit 1.6.0 — governance scoring ([#233](https://github.com/cobusgreyling/loop-engineering/pull/233))++Readiness scoring now checks multi-agent safety signals:++- Least-privilege tool scope (`allowed-tools` in skills, scoped MCP)+- Stall / no-progress detection (`loop-context`, circuit breaker, max attempts)+- Human-escalation path (HITL, handoff language in `LOOP.md` / constraints)++Tagged `loop-audit-v1.6.0`.++```bash+npx @cobusgreyling/loop-audit . --suggest+```+### New on npm: `@cobusgreyling/loop-worktree` ([#190](https://github.com/cobusgreyling/loop-engineering/pull/190), [#204](https://github.com/cobusgreyling/loop-engineering/pull/204))Isolated git worktrees per fix attempt — supports PR Babysitter and CI Sweeper L2 patterns without branch collisions. Tagged `loop-worktree-v1.0.0`.@@ -20,6 +34,13 @@ npx @cobusgreyling/loop-worktree cleanup --older-than 24hThanks [@KhaiTrang1995](https://github.com/KhaiTrang1995).+### Stories++| PR | What shipped |+|----|--------------|+| [#234](https://github.com/cobusgreyling/loop-engineering/pull/234) | CI Sweeper infinite flaky-test failure story |+| [#182](https://github.com/cobusgreyling/loop-engineering/pull/182) | Multi-loop coordination story (@k-anushka14) |+### Docs & examples| PR | Contributor | What shipped |@@ -28,7 +49,6 @@ Thanks [@KhaiTrang1995](https://github.com/KhaiTrang1995).| [#202](https://github.com/cobusgreyling/loop-engineering/pull/202) | @Mahizhan-S | Gemini CLI appendix in primitives matrix || [#206](https://github.com/cobusgreyling/loop-engineering/pull/206) | @Mahizhan-S | Zed appendix in primitives matrix || [#208](https://github.com/cobusgreyling/loop-engineering/pull/208) | @Mahizhan-S | Windsurf PR Babysitter example |-| [#182](https://github.com/cobusgreyling/loop-engineering/pull/182) | @k-anushka14 | Multi-loop coordination story || [#183](https://github.com/cobusgreyling/loop-engineering/pull/183) | @k-anushka14 | Opencode constraints example || [#185](https://github.com/cobusgreyling/loop-engineering/pull/185) | @k-anushka14 | Aider appendix link in examples index || Hermes index + QUICKSTART | @AshayK003 ([#187](https://github.com/cobusgreyling/loop-engineering/pull/187)–[#189](https://github.com/cobusgreyling/loop-engineering/pull/189)) | `examples/hermes/README.md`, QUICKSTART section |@@ -43,6 +63,7 @@ Thanks [@KhaiTrang1995](https://github.com/KhaiTrang1995).### Housekeeping- **Star-history workflow** — opens an auto-merge PR instead of pushing to protected `main`+- **loop-audit publish** — install `sigstore` before npm publish ([#236](https://github.com/cobusgreyling/loop-engineering/pull/236))- Dependabot bumps: `actions/github-script` 7→9, `@types/node` in loop-audit/loop-init- Stale branch prune + contributor PR backlog triage@@ -52,13 +73,14 @@ Thanks [@KhaiTrang1995](https://github.com/KhaiTrang1995).| Package | Version | Notes ||---------|---------|-------|+| `@cobusgreyling/loop-audit` | **1.6.0** | Governance scoring — `loop-audit-v1.6.0` || `@cobusgreyling/loop-worktree` | **1.0.0** | New — `loop-worktree-v1.0.0` |+| `@cobusgreyling/loop-init` | 1.3.3 | Contributor CTA after scaffold || `@cobusgreyling/loop-mcp-server` | 1.0.0 | No change |-| `@cobusgreyling/loop-audit` | 1.5.3 | No change |-| `@cobusgreyling/loop-init` | 1.3.3 | No change || `@cobusgreyling/loop-cost` | 1.0.3 | No change || `@cobusgreyling/loop-sync` | 1.0.0 | No change || `@cobusgreyling/loop-context` | 1.0.0 | No change |+| `@cobusgreyling/goal-audit` | 1.0.2 | Companion — Goal Engineering stack |---diff --git a/STATE.md b/STATE.mdindex cbe9217..781a76a 100644--- a/STATE.md+++ b/STATE.md@@ -5,7 +5,7 @@ Last run: 2026-07-09T10:41:53Z (automated daily-triage workflow)## High Priority (loop is acting or waiting on human)- Maintain loop readiness score ≥ 58 (current: **100**, level **L3**).-- Keep npm packages current after tool changes (tag `loop-audit-v*`, `loop-init-v*`, `loop-cost-v*` — see docs/RELEASE.md).+- Keep npm packages current after tool changes (per-package tags — see [docs/RELEASE.md](docs/RELEASE.md)).## Watch Listdiff --git a/docs/RELEASE.md b/docs/RELEASE.mdindex 142c9ea..1755d11 100644--- a/docs/RELEASE.md+++ b/docs/RELEASE.md@@ -1,6 +1,6 @@# Release playbook — npm packages-This repo ships six public npm packages from `tools/`:+This repo ships eight public npm packages from `tools/`:| Package | Directory | Release tag ||---------|-----------|-------------|@@ -10,6 +10,8 @@ This repo ships six public npm packages from `tools/`:| `@cobusgreyling/loop-sync` | `tools/loop-sync` | `loop-sync-v*` || `@cobusgreyling/loop-context` | `tools/loop-context` | `loop-context-v*` || `@cobusgreyling/loop-mcp-server` | `tools/mcp-server` | `loop-mcp-server-v*` |+| `@cobusgreyling/loop-worktree` | `tools/loop-worktree` | `loop-worktree-v*` |+| `@cobusgreyling/goal-audit` | `tools/goal-audit` | `goal-audit-v*` |## One-time setup (trusted publishing — recommended)@@ -23,12 +25,14 @@ Link npm to GitHub, then for **each package** on [npmjs.com](https://www.npmjs.c| `@cobusgreyling/loop-sync` | `cobusgreyling/loop-engineering` | `release-loop-sync.yml` || `@cobusgreyling/loop-context` | `cobusgreyling/loop-engineering` | `release-loop-context.yml` || `@cobusgreyling/loop-mcp-server` | `cobusgreyling/loop-engineering` | `release-loop-mcp-server.yml` |+| `@cobusgreyling/loop-worktree` | `cobusgreyling/loop-engineering` | `release-loop-worktree.yml` |+| `@cobusgreyling/goal-audit` | `cobusgreyling/loop-engineering` | `release-goal-audit.yml` |Names must match **exactly** (case-sensitive). No `NPM_TOKEN` secret is required when trusted publishing is configured.**Auth:** release workflows use repo secret `NPM_TOKEN` (Automation token). Refresh it at [npmjs.com](https://www.npmjs.com/) → Access Tokens if publishes fail with `E401`/`E404`.-**Retry without re-tagging:** Actions → Release workflow → **Run workflow** → enter the tag (e.g. `loop-audit-v1.4.2`).+**Retry without re-tagging:** Actions → Release workflow → **Run workflow** → enter the tag (e.g. `loop-audit-v1.6.0`).**Trusted publishing (optional):** configure per package on npm; OIDC alone is not sufficient unless `NPM_TOKEN` is removed and trusted publishers are verified.@@ -42,16 +46,16 @@ Tag pushes trigger the release workflows:```bash# loop-audit (runs tests before publish)-git tag loop-audit-v1.3.0-git push origin loop-audit-v1.3.0+git tag loop-audit-v1.6.0+git push origin loop-audit-v1.6.0# loop-init (bundles starters/templates, runs smoke tests)-git tag loop-init-v1.2.0-git push origin loop-init-v1.2.0+git tag loop-init-v1.3.3+git push origin loop-init-v1.3.3# loop-cost (bundles patterns/registry.yaml)-git tag loop-cost-v1.0.0-git push origin loop-cost-v1.0.0+git tag loop-cost-v1.0.3+git push origin loop-cost-v1.0.3# loop-sync (drift detection between STATE.md and LOOP.md)git tag loop-sync-v1.0.0@@ -64,9 +68,17 @@ git push origin loop-context-v1.0.0# loop-mcp-server (MCP runtime lookup for patterns, skills, state)git tag loop-mcp-server-v1.0.0git push origin loop-mcp-server-v1.0.0++# loop-worktree (isolated git worktrees per fix attempt)+git tag loop-worktree-v1.0.0+git push origin loop-worktree-v1.0.0++# goal-audit (Goal Engineering readiness scorer — companion repo)+git tag goal-audit-v1.0.2+git push origin goal-audit-v1.0.2```-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`, `.github/workflows/release-loop-context.yml`, `.github/workflows/release-loop-mcp-server.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`, `.github/workflows/release-loop-context.yml`, `.github/workflows/release-loop-mcp-server.yml`, `.github/workflows/release-loop-worktree.yml`, `.github/workflows/release-goal-audit.yml`.## Verify after publish@@ -77,6 +89,8 @@ npx @cobusgreyling/loop-cost --helpnpx @cobusgreyling/loop-sync --helpnpx @cobusgreyling/loop-context --helpnpx @cobusgreyling/loop-mcp-server --help+npx @cobusgreyling/loop-worktree --help+npx @cobusgreyling/goal-audit --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 eed7709..9131c9f 100644--- a/tools/loop-audit/CHANGELOG.md+++ b/tools/loop-audit/CHANGELOG.md@@ -2,6 +2,18 @@All notable changes to `@cobusgreyling/loop-audit` are documented here.+## [1.6.0] - 2026-07-09++### Added+- Governance scoring signals: least-privilege tool scope, stall / no-progress detection, human-escalation path+- `allowed-tools` frontmatter in `SKILL.md` detected as a least-privilege signal+- `--suggest` recommendations when governance signals are missing++## [1.5.3] - 2026-07-06++### Added+- Contributor quickstart CTA after CLI runs (skipped for `--json`, `--md`, and `--badge`)+## [1.5.2] - 2026-06-30### Addeddiff --git a/tools/loop-audit/README.md b/tools/loop-audit/README.mdindex 7af369f..dbe1dae 100644--- a/tools/loop-audit/README.md+++ b/tools/loop-audit/README.md@@ -52,7 +52,7 @@ npm run buildnpm publish --access public```-## Signals Checked (v1.4+)+## Signals Checked (v1.6+)| Signal | Notes ||-------------------------|-------|diff --git a/tools/loop-audit/package-lock.json b/tools/loop-audit/package-lock.jsonindex 9e08396..5e15284 100644--- a/tools/loop-audit/package-lock.json+++ b/tools/loop-audit/package-lock.json@@ -1,12 +1,12 @@{"name": "@cobusgreyling/loop-audit",- "version": "1.5.3",+ "version": "1.6.0","lockfileVersion": 3,"requires": true,"packages": {"": {"name": "@cobusgreyling/loop-audit",- "version": "1.5.3",+ "version": "1.6.0","license": "MIT","bin": {"loop-audit": "dist/cli.js"