dango85 · dango85 · Apr 15, 2026
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,5 +1,14 @@
 # Changelog
 
+## 1.3.2 (2026-04-15)
+
+### Added
+- README section **Cursor IDE: best results with Spec Kit** — `/worktree`, `.cursor/worktrees.json`, avoiding double isolation with this extension’s `after_specify` hook; links to [Cursor worktrees](https://cursor.com/docs/configuration/worktrees) and Cursor CLI
+- **`examples/cursor-worktrees.spec-kit.example.json`** and **`examples/README.md`** — starter `worktrees.json` for copying `.env` / optional `.specify` into Cursor-managed checkouts
+
+### Changed
+- **`install_notes`**: points Cursor users at official worktrees docs and the new README section
+
 ## 1.3.1 (2026-04-14)
 
 ### Added

diff --git a/PUBLISH.md b/PUBLISH.md
@@ -37,5 +37,5 @@ Reference issues: #61, #1476
 ## 3. Install in any repo
 
 ```bash
-specify extension add worktrees --from https://github.com/dango85/spec-kit-worktree-parallel/archive/refs/tags/v1.3.1.zip
+specify extension add worktrees --from https://github.com/dango85/spec-kit-worktree-parallel/archive/refs/tags/v1.3.2.zip
 ```
diff --git a/README.md b/README.md
@@ -19,9 +19,37 @@ This extension **does not** change another extension’s configuration on instal
 ## Installation
 
 ```bash
-specify extension add worktrees --from https://github.com/dango85/spec-kit-worktree-parallel/archive/refs/tags/v1.3.1.zip
+specify extension add worktrees --from https://github.com/dango85/spec-kit-worktree-parallel/archive/refs/tags/v1.3.2.zip
 ```
 
+## Cursor IDE: best results with Spec Kit
+
+Cursor implements **editor-native** isolation: **`/worktree`** keeps the **rest of that chat** in a **separate checkout**, with optional **`.cursor/worktrees.json`** to run setup (deps, env files) using **`$ROOT_WORKTREE_PATH`**. See the official **[Cursor worktrees](https://cursor.com/docs/configuration/worktrees)** documentation and the **[Cursor CLI `--worktree` flag](https://cursor.com/docs/cli/using.md#cli-worktrees)** for the same behavior outside the UI.
+
+### Recommended pattern (agent focus = one tree)
+
+1. **Start the feature** with **`/worktree …`** (or **`/best-of-n`** when comparing models). That aligns **agent tools and cwd** with Cursor’s isolated checkout.
+2. Add **`.cursor/worktrees.json`** at your **main project root** so each new checkout gets a working dev environment (copy `.env`, install packages, migrations, etc.). Copy and edit **`examples/cursor-worktrees.spec-kit.example.json`** from this repo as a starting point for Spec Kit repos.
+3. Run **`/speckit.specify`**, then plan / tasks / implement **in the same chat** so spec artifacts and edits stay in that checkout.
+
+### How this extension fits (do not double-isolate by accident)
+
+| Mechanism | Who creates it | Typical use |
+|-----------|----------------|-------------|
+| **Cursor `/worktree`** | Cursor (`~/.cursor/worktrees`, cleanup, setup hooks) | **Best default for Cursor users** — session root matches isolation. |
+| **This extension (`after_specify`)** | `git worktree add` under **`.worktrees/`** or sibling dirs | **In-repo** worktrees, **CLI/CI**, **non-Cursor** editors, **list/clean** helpers. |
+
+Using **both** at once for the same feature usually adds **confusion** (two different worktree locations and mental models). For **Cursor-heavy** teams:
+
+- Prefer **`/worktree` + `.cursor/worktrees.json`** for isolation, and set **`auto_create: false`** in **`worktree-config.yml`** so this extension does **not** also spawn an in-repo worktree after every specify — invoke **`/speckit.worktrees.create`** manually when you still want a **git** worktree inside the repo (e.g. sibling layout for a second IDE window).
+
+If you keep **`auto_create: true`**, you still get in-repo worktrees after specify; treat that as the **non-Cursor** or **second checkout** path and understand specs may land on the **primary** tree first (see **Parallel agents and the Git extension** below).
+
+### Summary
+
+- **Cursor:** isolation + agent focus → **`/worktree`** + **`worktrees.json`**.  
+- **This extension:** **`git worktree`** automation, dashboards, cleanup — complements Cursor; it does **not** replace Cursor’s chat root behavior.
+
 ## Layout modes
 
 ### Nested (default)
@@ -82,7 +110,7 @@ Create `.specify/extensions/worktrees/worktree-config.yml` to override defaults:
 
 ```yaml
 layout: "nested"            # nested | sibling
-auto_create: true            # false to prompt instead of auto-creating
+auto_create: true           # Cursor + /worktree users: set false to avoid in-repo worktrees after every specify
 sibling_pattern: "{{repo}}--{{branch}}"
 dotworktrees_dir: ".worktrees"
 ```

diff --git a/catalog-entry.json b/catalog-entry.json
@@ -4,8 +4,8 @@
     "id": "worktrees",
     "description": "Default-on worktree isolation for parallel agents — sibling or nested layout",
     "author": "dango85",
-    "version": "1.3.1",
-    "download_url": "https://github.com/dango85/spec-kit-worktree-parallel/archive/refs/tags/v1.3.1.zip",
+    "version": "1.3.2",
+    "download_url": "https://github.com/dango85/spec-kit-worktree-parallel/archive/refs/tags/v1.3.2.zip",
     "repository": "https://github.com/dango85/spec-kit-worktree-parallel",
     "homepage": "https://github.com/dango85/spec-kit-worktree-parallel",
     "documentation": "https://github.com/dango85/spec-kit-worktree-parallel/blob/main/README.md",
@@ -29,6 +29,6 @@
     "downloads": 0,
     "stars": 0,
     "created_at": "2026-04-13T00:00:00Z",
-    "updated_at": "2026-04-14T00:00:00Z"
+    "updated_at": "2026-04-15T00:00:00Z"
   }
 }
diff --git a/examples/README.md b/examples/README.md
@@ -0,0 +1,13 @@
+# Examples
+
+## Cursor + Spec Kit (`cursor-worktrees.spec-kit.example.json`)
+
+Cursor can isolate a chat in a **separate checkout** using **`/worktree`** and configure bootstrap with **`.cursor/worktrees.json`** ([Cursor worktrees docs](https://cursor.com/docs/configuration/worktrees)).
+
+1. Copy `cursor-worktrees.spec-kit.example.json` to **`.cursor/worktrees.json`** at your **project root** (the tree you open in Cursor — usually your main clone).
+2. Edit the arrays: add **`npm ci`**, **`uv sync`**, migrations, etc., after the copy lines as your stack requires.
+3. Start a feature chat with **`/worktree …`**, then run **`/speckit.specify`** and the rest of Spec Kit **in that same chat** so agent tools use the isolated checkout.
+
+The example uses **`$ROOT_WORKTREE_PATH`** so secrets and a **local-only** `.specify` (if you copy it from the primary tree) follow the Cursor worktree. If `.specify` is **fully committed** in git, the clone may already include it — keep or drop the `cp -R .specify` line accordingly.
+
+This file is **not** installed into target projects by `specify extension add`; it lives in this repo for you to copy when you set up Cursor.
diff --git a/examples/cursor-worktrees.spec-kit.example.json b/examples/cursor-worktrees.spec-kit.example.json
@@ -0,0 +1,12 @@
+{
+  "setup-worktree-unix": [
+    "test -f \"$ROOT_WORKTREE_PATH/.env\" && cp \"$ROOT_WORKTREE_PATH/.env\" .env || true",
+    "test -d \"$ROOT_WORKTREE_PATH/.specify\" && cp -R \"$ROOT_WORKTREE_PATH/.specify\" .specify 2>/dev/null || true"
+  ],
+  "setup-worktree-windows": [
+    "if exist \"%ROOT_WORKTREE_PATH%\\.env\" copy /Y \"%ROOT_WORKTREE_PATH%\\.env\" .env"
+  ],
+  "setup-worktree": [
+    "echo \"Define OS-specific setup in setup-worktree-unix / setup-worktree-windows for full support.\""
+  ]
+}
diff --git a/extension.yml b/extension.yml
@@ -3,15 +3,16 @@ schema_version: "1.0"
 extension:
   id: worktrees
   name: "Worktrees"
-  version: "1.3.1"
+  version: "1.3.2"
   description: "Default-on worktree isolation for parallel agents — sibling or nested layout"
   author: "dango85"
   repository: "https://github.com/dango85/spec-kit-worktree-parallel"
   license: "MIT"
   install_notes: |
-    Parallel worktrees: if the Spec Kit Git extension is installed, consider disabling its
-    before_specify → speckit.git.feature hook in .specify/extensions.yml (set enabled: false)
-    so the primary checkout is not switched for every agent. Full YAML snippet: README "Git extension vs worktrees".
+    Cursor users: for agent isolation aligned with the editor, prefer /worktree + .cursor/worktrees.json
+    (see https://cursor.com/docs/configuration/worktrees and README "Cursor IDE").
+    If the Git extension is installed, consider disabling before_specify → speckit.git.feature in
+    .specify/extensions.yml — README "Parallel agents and the Git extension".
 
 requires:
   speckit_version: ">=0.4.0"