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: document public loop-worktree lock import in QUICKSTART (#426) (#433)

Muhammad Zeshan Malik99cbedc49608
diff --git a/docs/QUICKSTART.md b/docs/QUICKSTART.md
index 76f636c..d1a3879 100644
--- a/docs/QUICKSTART.md
+++ b/docs/QUICKSTART.md
@@ -304,6 +304,23 @@ npx @cobusgreyling/loop-worktree cleanup --older-than 24h
npx @cobusgreyling/loop-worktree list
```
+To prevent multi-loop collisions on shared paths across concurrent runs, use advisory path locks via CLI or public JS import:
+
+```bash
+# CLI advisory lock (skips or queues if another owner holds an overlapping path)
+npx @cobusgreyling/loop-worktree lock --paths package.json,package-lock.json --owner dependency-sweeper --ttl 6h
+npx @cobusgreyling/loop-worktree unlock --owner dependency-sweeper
+```
+
+Programmatic loops can import lock primitives directly from `@cobusgreyling/loop-worktree/lock` without deep-importing internal files under `dist/`:
+
+```js
+import { lockPaths, unlockOwner, LOCKS_DIR } from '@cobusgreyling/loop-worktree/lock';
+
+await lockPaths({ root, owner, paths, ttl: '6h' });
+await unlockOwner(root, owner);
+```
+
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).
### Ephemeral worktree isolation (`loop-sandbox`)
diff --git a/tools/loop-worktree/README.md b/tools/loop-worktree/README.md
index 198c09a..e6ad6fd 100644
--- a/tools/loop-worktree/README.md
+++ b/tools/loop-worktree/README.md
@@ -30,7 +30,7 @@ import { lockPaths, unlockOwner } from '@cobusgreyling/loop-worktree/lock';
```
The `lock` subpath is the stable programmatic entry point for tools that need
-advisory path locking without importing private files under `dist/`.
+advisory path locking without importing private files under `dist/`. See [Quickstart](../../docs/QUICKSTART.md#l2-isolated-fix-attempts-loop-worktree) for CLI and JS usage.
## Commands