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.

docs: add loop-worktree to QUICKSTART and refresh release draft

Cobus Greylingd599c4b12ee2
diff --git a/RELEASE_NOTES_DRAFT.md b/RELEASE_NOTES_DRAFT.md
index 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-babysitter
npx @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 file
diff --git a/docs/QUICKSTART.md b/docs/QUICKSTART.md
index 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)