From 5786fc173db4f95c40657fc1934ebd7e3d0b6272 Mon Sep 17 00:00:00 2001 From: Abishek Yadav Date: Wed, 15 Apr 2026 09:35:03 -0500 Subject: [PATCH] docs: Cursor + Spec Kit workflow, worktrees.json example (v1.3.2) Made-with: Cursor --- CHANGELOG.md | 9 ++++++ PUBLISH.md | 2 +- README.md | 32 +++++++++++++++++-- catalog-entry.json | 6 ++-- examples/README.md | 13 ++++++++ .../cursor-worktrees.spec-kit.example.json | 12 +++++++ extension.yml | 9 +++--- 7 files changed, 73 insertions(+), 10 deletions(-) create mode 100644 examples/README.md create mode 100644 examples/cursor-worktrees.spec-kit.example.json diff --git a/CHANGELOG.md b/CHANGELOG.md index 70ac83f..8bc3fea 100644 --- 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 index 0d1b7fe..ce7d488 100644 --- 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 index 3b54400..1753bc8 100644 --- 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 index 6712bd7..0b01444 100644 --- 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 new file mode 100644 index 0000000..ce68b02 --- /dev/null +++ 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 new file mode 100644 index 0000000..f50700c --- /dev/null +++ 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 index 3668ab6..dc55be8 100644 --- 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"