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: add loop-worktree to QUICKSTART and refresh release draft
Cobus Greylingd599c4b12ee2
diff --git a/RELEASE_NOTES_DRAFT.md b/RELEASE_NOTES_DRAFT.mdindex e35bd4b..e001a7f 100644--- a/RELEASE_NOTES_DRAFT.md+++ b/RELEASE_NOTES_DRAFT.md@@ -1,62 +1,73 @@# Release notes draft — since `loop-mcp-server-v1.0.0`-**Status:** Draft for human review ([#181](https://github.com/cobusgreyling/loop-engineering/issues/181)). Edit before publishing a discussion post or tagging packages.+**Status:** Published to [Discussions](https://github.com/cobusgreyling/loop-engineering/discussions) on 2026-07-08. Archive copy for the next changelog-drafter run.-**Window:** 2026-07-06 → 2026-07-07+**Window:** 2026-07-06 → 2026-07-08---## Highlights-### New: `loop-worktree` CLI ([#190](https://github.com/cobusgreyling/loop-engineering/pull/190))+### 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.+Isolated git worktrees per fix attempt — supports PR Babysitter and CI Sweeper L2 patterns without branch collisions. Tagged `loop-worktree-v1.0.0`.```bash+npx @cobusgreyling/loop-worktree create --run-id fix-1 --pattern pr-babysitternpx @cobusgreyling/loop-worktree list-npx @cobusgreyling/loop-worktree create fix-123 --branch fix/issue-123+npx @cobusgreyling/loop-worktree cleanup --older-than 24h```Thanks [@KhaiTrang1995](https://github.com/KhaiTrang1995).-### Community docs & stories+### Docs & examples| PR | Contributor | What shipped ||----|-------------|--------------|+| [#217](https://github.com/cobusgreyling/loop-engineering/pull/217) | @Mahizhan-S | MCP server `npx` quickstart in `examples/mcp/` ([#201](https://github.com/cobusgreyling/loop-engineering/issues/201)) |+| [#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, copy-paste starters row |+| 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 |+| QUICKSTART `loop-worktree` | maintainer ([#197](https://github.com/cobusgreyling/loop-engineering/issues/197)) | L2 worktree subsection + cheat sheet |### Philosophy & contributor growth- KY cut surface philosophy v0.1 ([#179](https://github.com/cobusgreyling/loop-engineering/pull/179)) — thanks [@sololys](https://github.com/sololys)- `CONTRIBUTORS.md` automation refresh ([#180](https://github.com/cobusgreyling/loop-engineering/pull/180))+- Star-history page redesign ([#205](https://github.com/cobusgreyling/loop-engineering/pull/205))-### Housekeeping (this batch)+### Housekeeping- **Star-history workflow** — opens an auto-merge PR instead of pushing to protected `main`-- **examples/README.md** — deduplicated Hermes/Aider tool-directory rows+- Dependabot bumps: `actions/github-script` 7→9, `@types/node` in loop-audit/loop-init- Stale branch prune + contributor PR backlog triage----## npm publish checklist+## npm packages (current)-No version bumps required unless you want to ship `loop-worktree` to npm.--| Package | Current | Action |-|---------|---------|--------|+| Package | Version | Notes |+|---------|---------|-------|+| `@cobusgreyling/loop-worktree` | **1.0.0** | New — `loop-worktree-v1.0.0` || `@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 |-| `loop-worktree` | repo-only | Optional first publish + `loop-worktree-v*` tag |+| `@cobusgreyling/loop-cost` | 1.0.3 | No change |+| `@cobusgreyling/loop-sync` | 1.0.0 | No change |+| `@cobusgreyling/loop-context` | 1.0.0 | No change |----## Suggested publish steps+## Try it in 5 minutes++```bash+npx @cobusgreyling/loop-init . --pattern daily-triage --tool grok+npx @cobusgreyling/loop-audit . --suggest+LOOP_PROJECT_ROOT=. npx @cobusgreyling/loop-mcp-server+```-1. Review and edit this draft.-2. Post summary to [Discussions](https://github.com/cobusgreyling/loop-engineering/discussions/new?category=announcements).-3. Close [#181](https://github.com/cobusgreyling/loop-engineering/issues/181) when published.-4. (Optional) Tag `loop-worktree-v1.0.0` if npm publish is desired — add `release-loop-worktree.yml` first.\ No newline at end of file+Week two (L2): pair `loop-worktree` with `loop-context --check` — see [QUICKSTART](docs/QUICKSTART.md#l2-isolated-fix-attempts-loop-worktree).\ No newline at end of filediff --git a/docs/QUICKSTART.md b/docs/QUICKSTART.mdindex f9fb3cd..d719784 100644--- a/docs/QUICKSTART.md+++ b/docs/QUICKSTART.md@@ -156,11 +156,33 @@ Commit the scaffold + first run update so `loop-audit` sees activity on the next| When | Do this ||------|---------|| End of week one | Re-run `loop-audit . --suggest` — aim for L1 (score ~40+) |-| Week two | Add a verifier skill; try one assisted fix in a worktree (L2) |+| Week two | Add a verifier skill; try one assisted fix in a worktree (L2) — see [loop-worktree](#l2-isolated-fix-attempts-loop-worktree) below || Before unattended (L3) | `loop-budget.md` + `loop-run-log.md` filled, human gates in `LOOP.md`, proven runs || Unsure which pattern | [pattern-picker.md](./pattern-picker.md) · [loop-design-checklist.md](./loop-design-checklist.md) || Something broke | [failure-modes.md](./failure-modes.md) · [stories/](../stories/) |+### L2: isolated fix attempts (`loop-worktree`)++PR Babysitter and CI Sweeper need **one git worktree per fix attempt** so retries don't collide on the same branch. `loop-worktree` tracks them in a manifest and sweeps rejected attempts.++```bash+# Create an isolated worktree for one fix attempt+npx @cobusgreyling/loop-worktree create --run-id pr-217-fix-1 --pattern pr-babysitter++# Run your fix in the worktree path printed by create, then verifier...++# Verifier rejected — mark for cleanup (audit trail only)+npx @cobusgreyling/loop-worktree mark --run-id pr-217-fix-1 --status rejected++# Sweep rejected/escalated worktrees older than 24h+npx @cobusgreyling/loop-worktree cleanup --older-than 24h++# List active worktrees+npx @cobusgreyling/loop-worktree list+```++Pair with the [circuit breaker](#circuit-breaker-for-l2-loops-optional) above: when `loop-context --check` exits `2`, mark the worktree `escalated` before handing off to a human. The two tools stay independent — see [tools/loop-worktree/README.md](../tools/loop-worktree/README.md).+## Copy-paste cheat sheet```bash@@ -182,6 +204,11 @@ npx @cobusgreyling/loop-audit . --badge# Optional MCP runtime lookup (patterns, skills, state on demand)LOOP_PROJECT_ROOT=. npx @cobusgreyling/loop-mcp-server++# L2: isolated worktree per fix attempt (PR Babysitter, CI Sweeper)+npx @cobusgreyling/loop-worktree create --run-id <id> --pattern <pattern>+npx @cobusgreyling/loop-worktree mark --run-id <id> --status rejected+npx @cobusgreyling/loop-worktree cleanup --older-than 24h```## Learn the why (optional, 10 minutes)