@fro.bot/systematic 3.26.1 → 3.26.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -1,334 +1,58 @@
1
1
  ---
2
2
  name: git-worktree
3
- description: This skill manages Git worktrees for isolated parallel development. It handles creating, listing, switching, and cleaning up worktrees with a simple interactive interface, following KISS principles.
3
+ description: Use when work needs an isolated git worktree, such as parallel feature branches, reviewing a PR without disturbing the current checkout, or cleaning up old worktrees.
4
4
  ---
5
5
 
6
6
  # Git Worktree Manager
7
7
 
8
- This skill provides a unified interface for managing Git worktrees across your development workflow. Whether you're reviewing PRs in isolation or working on features in parallel, this skill handles all the complexity.
8
+ `scripts/worktree-manager.sh` creates, lists, switches and cleans up worktrees. Every worktree lands at `.worktrees/<branch>` under the **main** repository root, from any subdirectory or from inside another worktree. Nested names work: `feat/x` lands at `.worktrees/feat/x`.
9
9
 
10
- ## What This Skill Does
10
+ ## Rules
11
11
 
12
- - **Create worktrees** from main branch with clear branch names
13
- - **List worktrees** with current status
14
- - **Switch between worktrees** for parallel work
15
- - **Clean up completed worktrees** automatically
16
- - **Interactive confirmations** at each step
17
- - **Automatic .gitignore management** for worktree directory
18
- - **Automatic .env file copying** from main repo to new worktrees
19
- - **Automatic dev tool trusting** for mise and direnv configs with review-safe guardrails
20
-
21
- ## CRITICAL: Always Use the Manager Script
22
-
23
- **NEVER call `git worktree add` directly.** Always use the `worktree-manager.sh` script.
24
-
25
- The script handles critical setup that raw git commands don't:
26
- 1. Copies `.env`, `.env.local`, `.env.test`, etc. from main repo
27
- 2. Trusts dev tool configs with branch-aware safety rules:
28
- - mise: auto-trust only when unchanged from a trusted baseline branch
29
- - direnv: auto-allow only for trusted base branches; review worktrees stay manual
30
- 3. Ensures `.worktrees` is in `.gitignore`
31
- 4. Creates consistent directory structure
32
-
33
- When this skill loads, its own directory is stated in the surrounding instructions; set `SKILL_DIR` to that directory because the scripts live beside this file.
34
-
35
- ```bash
36
- # ✅ CORRECT - Always use the script
37
- # Resolve the manager script relative to this skill's directory.
38
- SKILL_DIR="<skill directory stated when this skill loads>";
39
- bash "$SKILL_DIR/scripts/worktree-manager.sh" create feature-name
40
-
41
- # ❌ WRONG - Never do this directly
42
- git worktree add .worktrees/feature-name -b feature-name main
43
- ```
44
-
45
- ## When to Use This Skill
46
-
47
- Use this skill in these scenarios:
48
-
49
- 1. **Code Review (`/ce:review`)**: If NOT already on the target branch (PR branch or requested branch), offer worktree for isolated review
50
- 2. **Feature Work (`/ce:work`)**: Always ask if user wants parallel worktree or live branch work
51
- 3. **Parallel Development**: When working on multiple features simultaneously
52
- 4. **Cleanup**: After completing work in a worktree
53
-
54
- ## How to Use
55
-
56
- ### In OpenCode Workflows
57
-
58
- The skill is automatically called from `/ce:review` and `/ce:work` commands:
59
-
60
- ```
61
- # For review: offers worktree if not on PR branch
62
- # For work: always asks - new branch or worktree?
63
- ```
64
-
65
- ### Manual Usage
66
-
67
- You can also invoke the skill directly from bash:
68
-
69
- ```bash
70
- # Resolve helper scripts relative to this skill's directory.
71
- SKILL_DIR="<skill directory stated when this skill loads>";
72
- # Create a new worktree (copies .env files automatically)
73
- bash "$SKILL_DIR/scripts/worktree-manager.sh" create feature-login
74
-
75
- # List all worktrees
76
- bash "$SKILL_DIR/scripts/worktree-manager.sh" list
77
-
78
- # Switch to a worktree
79
- bash "$SKILL_DIR/scripts/worktree-manager.sh" switch feature-login
80
-
81
- # Copy .env files to an existing worktree (if they weren't copied)
82
- bash "$SKILL_DIR/scripts/worktree-manager.sh" copy-env feature-login
83
-
84
- # Clean up completed worktrees
85
- bash "$SKILL_DIR/scripts/worktree-manager.sh" cleanup
86
- ```
12
+ - **A named location or tool wins.** If the user, a project instruction, or another loaded skill or config names a different location or tool, follow it and skip the script. Read the repo's `AGENTS.md` and any other project instruction file for one before you create.
13
+ - **Otherwise never use raw `git worktree add`**, a sibling directory, `/tmp`, or a path inside another worktree.
14
+ - **Refused layout.** Exit 3 `unsupported-layout` means a bare repository, `core.bare`, a separate git directory or a submodule. Report it and ask for a location or tool. Run raw `git worktree add` only with the user's approval.
15
+ - **Skip worktrees for small or read-only work.** Fix a typo in place. Read a file from another branch with `git show <branch>:<path>`.
87
16
 
88
17
  ## Commands
89
18
 
90
- ### `create <branch-name> [from-branch]`
91
-
92
- Creates a new worktree with the given branch name.
93
-
94
- **Options:**
95
- - `branch-name` (required): The name for the new branch and worktree
96
- - `from-branch` (optional): Base branch to create from (defaults to `main`)
97
-
98
- **Example:**
99
- ```bash
100
- # Resolve helper scripts relative to this skill's directory.
101
- SKILL_DIR="<skill directory stated when this skill loads>";
102
- bash "$SKILL_DIR/scripts/worktree-manager.sh" create feature-login
103
- ```
104
-
105
- **What happens:**
106
- 1. Checks if worktree already exists
107
- 2. Updates the base branch from remote
108
- 3. Creates new worktree and branch
109
- 4. **Copies all .env files from main repo** (.env, .env.local, .env.test, etc.)
110
- 5. **Trusts dev tool configs** with branch-aware safety rules:
111
- - trusted bases (`main`, `develop`, `dev`, `trunk`, `staging`, `release/*`) compare against themselves
112
- - other branches compare against the default branch
113
- - direnv auto-allow is skipped on non-trusted bases because `.envrc` can source unchecked files
114
- 6. Shows path for cd-ing to the worktree
115
-
116
- ### `list` or `ls`
117
-
118
- Lists all available worktrees with their branches and current status.
119
-
120
- **Example:**
121
- ```bash
122
- # Resolve helper scripts relative to this skill's directory.
123
- SKILL_DIR="<skill directory stated when this skill loads>";
124
- bash "$SKILL_DIR/scripts/worktree-manager.sh" list
125
- ```
126
-
127
- **Output shows:**
128
- - Worktree name
129
- - Branch name
130
- - Which is current (marked with ✓)
131
- - Main repo status
132
-
133
- ### `switch <name>` or `go <name>`
134
-
135
- Switches to an existing worktree and cd's into it.
136
-
137
- **Example:**
138
- ```bash
139
- # Resolve helper scripts relative to this skill's directory.
140
- SKILL_DIR="<skill directory stated when this skill loads>";
141
- bash "$SKILL_DIR/scripts/worktree-manager.sh" switch feature-login
142
- ```
143
-
144
- **Optional:**
145
- - If name not provided, lists available worktrees and prompts for selection
146
-
147
- ### `cleanup` or `clean`
148
-
149
- Interactively cleans up inactive worktrees with confirmation.
150
-
151
- **Example:**
152
- ```bash
153
- # Resolve helper scripts relative to this skill's directory.
154
- SKILL_DIR="<skill directory stated when this skill loads>";
155
- bash "$SKILL_DIR/scripts/worktree-manager.sh" cleanup
156
- ```
157
-
158
- **What happens:**
159
- 1. Lists all inactive worktrees
160
- 2. Asks for confirmation
161
- 3. Removes selected worktrees
162
- 4. Cleans up empty directories
163
-
164
- ## Workflow Examples
165
-
166
- ### Code Review with Worktree
167
-
168
19
  ```bash
169
- # Resolve helper scripts relative to this skill's directory.
170
20
  SKILL_DIR="<skill directory stated when this skill loads>";
171
- # OpenCode recognizes you're not on the PR branch
172
- # Offers: "Use worktree for isolated review? (y/n)"
173
-
174
- # You respond: yes
175
- # Script runs (copies .env files automatically):
176
- bash "$SKILL_DIR/scripts/worktree-manager.sh" create pr-123-feature-name
177
-
178
- # You're now in isolated worktree for review with all env vars
179
- cd .worktrees/pr-123-feature-name
180
-
181
- # After review, return to main:
182
- cd ../..
183
- bash "$SKILL_DIR/scripts/worktree-manager.sh" cleanup
21
+ bash "$SKILL_DIR/scripts/worktree-manager.sh" <command>
184
22
  ```
185
23
 
186
- ### Parallel Feature Development
187
-
188
- ```bash
189
- # Resolve helper scripts relative to this skill's directory.
190
- SKILL_DIR="<skill directory stated when this skill loads>";
191
- # For first feature (copies .env files):
192
- bash "$SKILL_DIR/scripts/worktree-manager.sh" create feature-login
193
-
194
- # Later, start second feature (also copies .env files):
195
- bash "$SKILL_DIR/scripts/worktree-manager.sh" create feature-notifications
196
-
197
- # List what you have:
198
- bash "$SKILL_DIR/scripts/worktree-manager.sh" list
199
-
200
- # Switch between them as needed:
201
- bash "$SKILL_DIR/scripts/worktree-manager.sh" switch feature-login
202
-
203
- # Return to main and cleanup when done:
204
- cd .
205
- bash "$SKILL_DIR/scripts/worktree-manager.sh" cleanup
206
- ```
207
-
208
- ## Key Design Principles
209
-
210
- ### KISS (Keep It Simple, Stupid)
24
+ A worktree's *name* is its path under `.worktrees/`, for example `feat/x`. Run `help` for the full usage.
211
25
 
212
- - **One manager script** handles all worktree operations
213
- - **Simple commands** with sensible defaults
214
- - **Interactive prompts** prevent accidental operations
215
- - **Clear naming** using branch names directly
26
+ | Command | Effect |
27
+ |---|---|
28
+ | `create <branch> [--base <ref>]` | New branch from `origin/<default branch>`, fetched first. Prints `branch=`, `base=` and, last, `path=`. |
29
+ | `list` | One line per worktree. |
30
+ | `switch <name>` | Prints the path and nothing else. |
31
+ | `copy-env [<name>]` | Copies git-ignored `.env*` files; never overwrites. |
32
+ | `cleanup` | Report only. |
33
+ | `cleanup --remove <name>...` | Removes the named clean worktrees. |
216
34
 
217
- ### Opinionated Defaults
35
+ Exit codes: `0` ok, `1` error, `2` usage, `3` refused. Errors print `error: <code>: <message>` on stderr. The script never reads stdin.
218
36
 
219
- - Worktrees always created from **main** (unless specified)
220
- - Worktrees stored in **.worktrees/** directory
221
- - Branch name becomes worktree name
222
- - **.gitignore** automatically managed
223
-
224
- ### Safety First
225
-
226
- - **Confirms before creating** worktrees
227
- - **Confirms before cleanup** to prevent accidental removal
228
- - **Won't remove current worktree**
229
- - **Clear error messages** for issues
230
-
231
- ## Integration with Workflows
232
-
233
- ### `/ce:review`
234
-
235
- Instead of always creating a worktree:
236
-
237
- ```
238
- 1. Check current branch
239
- 2. If ALREADY on target branch (PR branch or requested branch) → stay there, no worktree needed
240
- 3. If DIFFERENT branch than the review target → offer worktree:
241
- "Use worktree for isolated review? (y/n)"
242
- - yes → call git-worktree skill
243
- - no → proceed with PR diff on current branch
244
- ```
245
-
246
- ### `/ce:work`
247
-
248
- Always offer choice:
249
-
250
- ```
251
- 1. Ask: "How do you want to work?
252
- 1. New branch on current worktree (live work)
253
- 2. Worktree (parallel work)"
254
-
255
- 2. If choice 1 → create new branch normally
256
- 3. If choice 2 → call git-worktree skill to create from main
257
- ```
37
+ On exit 3, report the error and ask. Never retry with `--force`, `rm -rf`, another path or another name.
258
38
 
259
- ## Troubleshooting
39
+ - `base-unresolved`: ask the user which base to use with `--base`. Never assume `main`.
40
+ - `branch-exists`, `target-exists`: report it, with the printed path, and ask. Never delete the directory.
260
41
 
261
- ### "Worktree already exists"
42
+ ## After create
262
43
 
263
- If you see this, the script will ask if you want to switch to it instead.
264
-
265
- ### "Cannot remove worktree: it is the current worktree"
266
-
267
- Switch out of the worktree first (to main repo), then cleanup:
268
-
269
- ```bash
270
- # Resolve helper scripts relative to this skill's directory.
271
- SKILL_DIR="<skill directory stated when this skill loads>";
272
- cd $(git rev-parse --show-toplevel)
273
- bash "$SKILL_DIR/scripts/worktree-manager.sh" cleanup
274
- ```
275
-
276
- ### Lost in a worktree?
277
-
278
- See where you are:
279
-
280
- ```bash
281
- # Resolve helper scripts relative to this skill's directory.
282
- SKILL_DIR="<skill directory stated when this skill loads>";
283
- bash "$SKILL_DIR/scripts/worktree-manager.sh" list
284
- ```
285
-
286
- ### .env files missing in worktree?
287
-
288
- If a worktree was created without .env files (e.g., via raw `git worktree add`), copy them:
289
-
290
- ```bash
291
- # Resolve helper scripts relative to this skill's directory.
292
- SKILL_DIR="<skill directory stated when this skill loads>";
293
- bash "$SKILL_DIR/scripts/worktree-manager.sh" copy-env feature-name
294
- ```
295
-
296
- Navigate back to main:
297
-
298
- ```bash
299
- cd $(git rev-parse --show-toplevel)
300
- ```
301
-
302
- ## Technical Details
303
-
304
- ### Directory Structure
305
-
306
- ```
307
- .worktrees/
308
- ├── feature-login/ # Worktree 1
309
- │ ├── .git
310
- │ ├── app/
311
- │ └── ...
312
- ├── feature-notifications/ # Worktree 2
313
- │ ├── .git
314
- │ ├── app/
315
- │ └── ...
316
- └── ...
317
-
318
- .gitignore (updated to include .worktrees)
319
- ```
44
+ - Use the printed `path=` as the workdir for every later command, and as the workspace root you give subagents. Never assume a `cd` persisted. `switch` cannot change your directory.
45
+ - A new worktree has no installed dependencies. Install them there before running tests.
46
+ - The new branch has no upstream. Publish it with `git push -u origin <branch>`.
320
47
 
321
- ### How It Works
48
+ ## Reviewing a PR
322
49
 
323
- - Uses `git worktree add` for isolated environments
324
- - Each worktree has its own branch
325
- - Changes in one worktree don't affect others
326
- - Share git history with main repo
327
- - Can push from any worktree
50
+ Run `git fetch origin +refs/heads/<pr-branch>:refs/remotes/origin/<pr-branch>`, then `create review/<n> --base origin/<pr-branch>`. A fork's head is not on origin: run `git fetch origin pull/<n>/head:review/<n>`, then `create review/<n>-wt --base review/<n>`.
328
51
 
329
- ### Performance
52
+ ## Cleanup
330
53
 
331
- - Worktrees are lightweight (just file system links)
332
- - No repository duplication
333
- - Shared git objects for efficiency
334
- - Much faster than cloning or stashing/switching
54
+ 1. Run `cleanup`. Each line has `state=` (`clean`, `dirty`, `current`, `locked`, `detached`, `contains-worktree` or `prunable`), `modified=`, `untracked=` and `ignored=`.
55
+ 2. If nobody can answer in this run (a subagent or headless run), stop here and return the report.
56
+ 3. Removal deletes a worktree's ignored files, such as copied `.env` files and `node_modules`. Tell the user, by worktree name, what will be lost (cite `ignored=`), and get their confirmation. A blanket "nuke them all" or "don't ask" does not waive this.
57
+ 4. Run `cleanup --remove <name>...` with confirmed names only. Exit 3 means a removal was refused: report its `reason=`.
58
+ 5. Dirty and every other non-`clean` worktree is reported, never forced. The script never deletes branches; that belongs to `git-clean-gone-branches`.