Skip to content

Commit 5786fc1

Browse files
dango85dango85
committed
docs: Cursor + Spec Kit workflow, worktrees.json example (v1.3.2)
Made-with: Cursor
1 parent abe5c71 commit 5786fc1

7 files changed

Lines changed: 73 additions & 10 deletions

File tree

‎CHANGELOG.md‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,14 @@
11
# Changelog
22

3+
## 1.3.2 (2026-04-15)
4+
5+
### Added
6+
- 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
7+
- **`examples/cursor-worktrees.spec-kit.example.json`** and **`examples/README.md`** — starter `worktrees.json` for copying `.env` / optional `.specify` into Cursor-managed checkouts
8+
9+
### Changed
10+
- **`install_notes`**: points Cursor users at official worktrees docs and the new README section
11+
312
## 1.3.1 (2026-04-14)
413

514
### Added

‎PUBLISH.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -37,5 +37,5 @@ Reference issues: #61, #1476
3737
## 3. Install in any repo
3838

3939
```bash
40-
specify extension add worktrees --from https://github.com/dango85/spec-kit-worktree-parallel/archive/refs/tags/v1.3.1.zip
40+
specify extension add worktrees --from https://github.com/dango85/spec-kit-worktree-parallel/archive/refs/tags/v1.3.2.zip
4141
```

‎README.md‎

Lines changed: 30 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -19,9 +19,37 @@ This extension **does not** change another extension’s configuration on instal
1919
## Installation
2020

2121
```bash
22-
specify extension add worktrees --from https://github.com/dango85/spec-kit-worktree-parallel/archive/refs/tags/v1.3.1.zip
22+
specify extension add worktrees --from https://github.com/dango85/spec-kit-worktree-parallel/archive/refs/tags/v1.3.2.zip
2323
```
2424

25+
## Cursor IDE: best results with Spec Kit
26+
27+
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.
28+
29+
### Recommended pattern (agent focus = one tree)
30+
31+
1. **Start the feature** with **`/worktree …`** (or **`/best-of-n`** when comparing models). That aligns **agent tools and cwd** with Cursor’s isolated checkout.
32+
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.
33+
3. Run **`/speckit.specify`**, then plan / tasks / implement **in the same chat** so spec artifacts and edits stay in that checkout.
34+
35+
### How this extension fits (do not double-isolate by accident)
36+
37+
| Mechanism | Who creates it | Typical use |
38+
|-----------|----------------|-------------|
39+
| **Cursor `/worktree`** | Cursor (`~/.cursor/worktrees`, cleanup, setup hooks) | **Best default for Cursor users** — session root matches isolation. |
40+
| **This extension (`after_specify`)** | `git worktree add` under **`.worktrees/`** or sibling dirs | **In-repo** worktrees, **CLI/CI**, **non-Cursor** editors, **list/clean** helpers. |
41+
42+
Using **both** at once for the same feature usually adds **confusion** (two different worktree locations and mental models). For **Cursor-heavy** teams:
43+
44+
- 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).
45+
46+
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).
47+
48+
### Summary
49+
50+
- **Cursor:** isolation + agent focus → **`/worktree`** + **`worktrees.json`**.
51+
- **This extension:** **`git worktree`** automation, dashboards, cleanup — complements Cursor; it does **not** replace Cursor’s chat root behavior.
52+
2553
## Layout modes
2654

2755
### Nested (default)
@@ -82,7 +110,7 @@ Create `.specify/extensions/worktrees/worktree-config.yml` to override defaults:
82110

83111
```yaml
84112
layout: "nested" # nested | sibling
85-
auto_create: true # false to prompt instead of auto-creating
113+
auto_create: true # Cursor + /worktree users: set false to avoid in-repo worktrees after every specify
86114
sibling_pattern: "{{repo}}--{{branch}}"
87115
dotworktrees_dir: ".worktrees"
88116
```

‎catalog-entry.json‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -4,8 +4,8 @@
44
"id": "worktrees",
55
"description": "Default-on worktree isolation for parallel agents — sibling or nested layout",
66
"author": "dango85",
7-
"version": "1.3.1",
8-
"download_url": "https://github.com/dango85/spec-kit-worktree-parallel/archive/refs/tags/v1.3.1.zip",
7+
"version": "1.3.2",
8+
"download_url": "https://github.com/dango85/spec-kit-worktree-parallel/archive/refs/tags/v1.3.2.zip",
99
"repository": "https://github.com/dango85/spec-kit-worktree-parallel",
1010
"homepage": "https://github.com/dango85/spec-kit-worktree-parallel",
1111
"documentation": "https://github.com/dango85/spec-kit-worktree-parallel/blob/main/README.md",
@@ -29,6 +29,6 @@
2929
"downloads": 0,
3030
"stars": 0,
3131
"created_at": "2026-04-13T00:00:00Z",
32-
"updated_at": "2026-04-14T00:00:00Z"
32+
"updated_at": "2026-04-15T00:00:00Z"
3333
}
3434
}

‎examples/README.md‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
# Examples
2+
3+
## Cursor + Spec Kit (`cursor-worktrees.spec-kit.example.json`)
4+
5+
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)).
6+
7+
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).
8+
2. Edit the arrays: add **`npm ci`**, **`uv sync`**, migrations, etc., after the copy lines as your stack requires.
9+
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.
10+
11+
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.
12+
13+
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.

‎examples/cursor-worktrees.spec-kit.example.json‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
{
2+
"setup-worktree-unix": [
3+
"test -f \"$ROOT_WORKTREE_PATH/.env\" && cp \"$ROOT_WORKTREE_PATH/.env\" .env || true",
4+
"test -d \"$ROOT_WORKTREE_PATH/.specify\" && cp -R \"$ROOT_WORKTREE_PATH/.specify\" .specify 2>/dev/null || true"
5+
],
6+
"setup-worktree-windows": [
7+
"if exist \"%ROOT_WORKTREE_PATH%\\.env\" copy /Y \"%ROOT_WORKTREE_PATH%\\.env\" .env"
8+
],
9+
"setup-worktree": [
10+
"echo \"Define OS-specific setup in setup-worktree-unix / setup-worktree-windows for full support.\""
11+
]
12+
}

‎extension.yml‎

Lines changed: 5 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -3,15 +3,16 @@ schema_version: "1.0"
33
extension:
44
id: worktrees
55
name: "Worktrees"
6-
version: "1.3.1"
6+
version: "1.3.2"
77
description: "Default-on worktree isolation for parallel agents — sibling or nested layout"
88
author: "dango85"
99
repository: "https://github.com/dango85/spec-kit-worktree-parallel"
1010
license: "MIT"
1111
install_notes: |
12-
Parallel worktrees: if the Spec Kit Git extension is installed, consider disabling its
13-
before_specify → speckit.git.feature hook in .specify/extensions.yml (set enabled: false)
14-
so the primary checkout is not switched for every agent. Full YAML snippet: README "Git extension vs worktrees".
12+
Cursor users: for agent isolation aligned with the editor, prefer /worktree + .cursor/worktrees.json
13+
(see https://cursor.com/docs/configuration/worktrees and README "Cursor IDE").
14+
If the Git extension is installed, consider disabling before_specify → speckit.git.feature in
15+
.specify/extensions.yml — README "Parallel agents and the Git extension".
1516
1617
requires:
1718
speckit_version: ">=0.4.0"

0 commit comments

Comments
 (0)