You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
# Comment to post on the github/spec-kit PR (e.g. hook overrides / modifies_hooks)
2
+
3
+
Use or shorten as needed.
4
+
5
+
---
6
+
7
+
Thanks for the feedback — I agree with the boundary and I’m **closing / withdrawing this PR** in favor of the approach you described.
8
+
9
+
**Cross-extension configuration:** I won’t ship logic where one extension rewrites another’s hooks or config on install (including `modifies_hooks` targeting the Git extension). That coupling is brittle when the Git extension evolves and it conflicts with **Git becoming opt-in at 1.0.0**.
10
+
11
+
**Parallel worktrees:** The real issue is that `before_specify → speckit.git.feature` runs `git checkout` / `git checkout -b` on the **shared** primary checkout, which disrupts parallel agents. Worktree-based flows should rely on **`git worktree add -b`** (branch created in the new worktree, primary `HEAD` unchanged) and on **explicit** project config: users who need a stable primary branch can set `enabled: false` on that hook in **`.specify/extensions.yml`**.
12
+
13
+
**Presets:** Opinionated “worktree-first” command text and ordering should live in a **preset** that overrides only the commands that need to differ — so teams stay in control.
14
+
15
+
**Spec-kit follow-up:** No spec-kit changes are required from this PR. The operational guidance (*parallel agents*, `.specify/extensions.yml`, presets) lives in the **Worktrees extension** repository README so it ships with the extension.
Copy file name to clipboardExpand all lines: CHANGELOG.md
+9Lines changed: 9 additions & 0 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,5 +1,14 @@
1
1
# Changelog
2
2
3
+
## 1.3.0 (2026-04-14)
4
+
5
+
### Added
6
+
- README section **Parallel agents and the Git extension**: manual `.specify/extensions.yml` change to disable Git’s `before_specify` hook when you need a stable primary checkout; branch base `--base-ref HEAD`; honest note on `after_specify` ordering vs running specify from the worktree root
7
+
- Command doc prerequisites: Git extension vs `git` CLI, and corrected branch-creation rule (worktree can create the branch with `git worktree add -b`)
8
+
9
+
### Changed
10
+
- Documentation-only release aligned with Spec Kit maintainer guidance: no cross-extension hook mutation on install; optional future **preset** for worktree-first command overrides called out in README
This is a public repository. Changes should follow the usual **GitHub flow**: work on a **branch**, open a **pull request** into `main`, and merge only after review — **not** by committing directly to `main`.
4
+
5
+
## For contributors
6
+
7
+
1.**Fork** the repository (or use a branch if you have write access).
8
+
2. Create a **feature branch** from up-to-date `main`:
9
+
10
+
```bash
11
+
git fetch origin
12
+
git checkout -b your-branch-name origin/main
13
+
```
14
+
15
+
3. Make commits with clear messages.
16
+
4.**Push** your branch and open a **pull request** targeting `main`.
17
+
5. Wait for CI (GitHub Actions) to pass and for maintainer review.
18
+
19
+
## For maintainers
20
+
21
+
- Merge contributions via **Pull request** → **Merge** (squash or merge commit, per repo preference).
22
+
-**Do not** push commits directly to `main` for routine changes; use a short-lived branch and PR so history and review stay consistent with contributor expectations.
23
+
- In repository **Settings → Rules → Rulesets** (or **Branch protection rules**), protect `main`: require a pull request before merging, and require status checks where appropriate.
24
+
25
+
## Releases
26
+
27
+
After a change to versioned files (`extension.yml`, `CHANGELOG.md`, `catalog-entry.json`) is **merged** to `main`:
28
+
29
+
1. Tag a semantic version (e.g. `v1.3.0`) on the merge commit.
30
+
2. Push the tag so `download_url` and install snippets that point at `/archive/refs/tags/v…` stay valid.
31
+
32
+
See [PUBLISH.md](PUBLISH.md) for catalog and distribution notes.
**Contributing:** use a **branch + pull request** into `main` — see [CONTRIBUTING.md](CONTRIBUTING.md).
6
+
5
7
A [Spec Kit](https://github.com/github/spec-kit) extension for **default-on** git worktree isolation — work on multiple features (or run parallel agents) without checkout switching.
6
8
7
9
## Why another worktree extension?
@@ -10,12 +12,14 @@ The community [spec-kit-worktree](https://github.com/Quratulain-bilal/spec-kit-w
10
12
11
13
1.**Default-on** — worktrees are created automatically after `/speckit.specify`. Opt *out* with `--in-place`, rather than opting in.
12
14
2.**Nested layout by default** — worktrees live at `.worktrees/<branch>/` inside the repo (gitignored, self-contained). Sibling-dir layout (`../<repo>--<branch>`) is available as an option for IDE-per-feature workflows.
13
-
3.**Deterministic bash script** — a real script (`create-worktree.sh`) with `--json` output, `--dry-run`, and `SPECIFY_WORKTREE_PATH` override, suitable for CI and scripted workflows.
15
+
3.**Deterministic bash script** — a real script (`create-worktree.sh`) with `--json` output, `--dry-run`, `--base-ref`, and `SPECIFY_WORKTREE_PATH` override, suitable for CI and scripted workflows.
16
+
17
+
This extension **does not** change another extension’s configuration on install (for example it does not disable the Git extension’s hooks). You opt into hook changes explicitly in `.specify/extensions.yml` when you need them (see below).
Open each directory in its own IDE window. Switch with `layout: "sibling"` in `worktree-config.yml`.
50
54
55
+
## Parallel agents and the Git extension
56
+
57
+
**Git extension vs `git` on your PATH:** This extension requires the **`git` CLI** only. It does not require the Spec Kit **Git extension** (`speckit.git.*`). That distinction matters because the Git extension registers **`before_specify → speckit.git.feature`**, which runs `git checkout` / `git checkout -b` on **whatever directory the agent is using as the repo root**. On a **shared** primary clone, that moves `HEAD` for everyone and fights parallel worktrees.
58
+
59
+
**What this extension does instead:**`create-worktree.sh` uses **`git worktree add`** (and **`git worktree add -b`** for a new branch). That creates the feature branch **inside the new worktree** and leaves the primary checkout’s `HEAD` alone.
60
+
61
+
**If the Git extension is installed and you want a stable primary checkout:** edit **`.specify/extensions.yml`** and set **`enabled: false`** on the `before_specify` entry whose **`extension`** is **`git`** and **`command`** is **`speckit.git.feature`**. Your file may include extra keys (`optional`, `prompt`, …); only `enabled` needs to change.
62
+
63
+
```yaml
64
+
hooks:
65
+
before_specify:
66
+
- extension: git
67
+
command: speckit.git.feature
68
+
enabled: false
69
+
optional: false
70
+
# …other keys from your install stay as-is…
71
+
```
72
+
73
+
After disabling that hook, **feature branch naming** is no longer applied by `speckit.git.feature` before specify. Use **`create-new-feature.sh --dry-run --json`** from the Git extension if you still want the same numbering **without** a checkout, or agree on branch names in the specify step. **Branch from current `HEAD`** when creating a worktree: pass **`--base-ref HEAD`** to `create-worktree.sh` (default base is `main` / `origin/main` when present).
74
+
75
+
**`after_specify` ordering:** This extension’s hook runs **after**`/speckit.specify`. Spec files are written to the **current** working tree first, then the worktree is created. For **full** isolation, run specify **from the worktree root** (worktree-first workflow). A Spec Kit **preset** that overrides only the commands you need is the maintainers’ recommended way to encode that workflow explicitly; this repo does not ship that preset yet.
76
+
77
+
**Spec Kit 1.0.0:** The Git extension is expected to become **opt-in**. Do not assume `before_specify` / `speckit.git.feature` is always present; keep the worktree flow valid with Git extension off.
78
+
51
79
## Configuration
52
80
53
81
Create `.specify/extensions/worktrees/worktree-config.yml` to override defaults:
Copy file name to clipboardExpand all lines: commands/speckit.worktrees.create.md
+5-2Lines changed: 5 additions & 2 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -22,6 +22,8 @@ You **MUST** consider the user input before proceeding (if not empty). The user
22
22
1. Verify the project is a git repository (`git rev-parse --show-toplevel`)
23
23
2. Verify `git worktree` is available (`git worktree list` succeeds)
24
24
25
+
**Git extension (optional):** The Spec Kit Git extension’s `before_specify → speckit.git.feature` checks out the feature branch on the **current** tree. For parallel agents on one primary clone, maintainers recommend disabling that hook in `.specify/extensions.yml` and relying on `git worktree add -b` (this script) so the primary `HEAD` stays put. See the extension README *Parallel agents and the Git extension*.
26
+
25
27
## Configuration
26
28
27
29
Read configuration from `.specify/extensions/worktrees/worktree-config.yml` if it exists. Defaults apply when the file is absent.
- Run `git worktree add -b <branch> <path> <base-ref>` (new branch) or `git worktree add <path> <branch>` (existing branch)
68
71
- For nested layout, ensure `.worktrees/` is in `.gitignore`
69
72
70
-
3.**Verify spec artifacts**: Check that `specs/<branch>/`exists in the new worktree. List which artifacts are present (spec.md, plan.md, tasks.md).
73
+
3.**Verify spec artifacts**: Prefer `specs/<branch>/`**in the worktree** when using a worktree-first workflow. If `/speckit.specify` ran on the primary checkout first (`after_specify` hook order), artifacts may still be under the primary tree — report where they actually are.
-**One worktree per branch** — refuse to create a duplicate; report the existing path instead
94
97
-**Never modify the primary checkout** — worktree operations happen in the new directory only
95
98
-**Always update .gitignore for nested layout** — add the `dotworktrees_dir` value if not present
96
-
-**Validate branch exists** — for existing branches; for new branches the `after_specify` hook should have already created the branch via the git extension
99
+
-**New vs existing branch** — if the branch does not exist locally, `git worktree add -b` creates it from the configured base ref; if it already exists, the worktree attaches to it. Do not assume the Git extension ran `speckit.git.feature` first (it may be disabled for parallel worktrees)
0 commit comments