@fro.bot/systematic 3.26.0 → 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.
- package/HARNESSES.md +23 -8
- package/dist/index.js +20 -2
- package/dist/lib/bootstrap.d.ts +17 -2
- package/dist/pi.js +23 -5
- package/package.json +7 -7
- package/skills/ce-review/SKILL.md +4 -4
- package/skills/compound-docs/schema.yaml +55 -55
- package/skills/git-clean-gone-branches/SKILL.md +17 -7
- package/skills/git-commit-push-pr/SKILL.md +10 -9
- package/skills/git-worktree/SKILL.md +33 -309
- package/skills/git-worktree/scripts/worktree-manager.sh +568 -391
- package/skills/orchestrating-subagents/SKILL.md +1 -1
- package/skills/using-systematic/references/worktree-placement.md +1 -0
|
@@ -1,334 +1,58 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: git-worktree
|
|
3
|
-
description:
|
|
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
|
-
|
|
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
|
-
##
|
|
10
|
+
## Rules
|
|
11
11
|
|
|
12
|
-
- **
|
|
13
|
-
- **
|
|
14
|
-
- **
|
|
15
|
-
- **
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
213
|
-
|
|
214
|
-
|
|
215
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
42
|
+
## After create
|
|
262
43
|
|
|
263
|
-
|
|
264
|
-
|
|
265
|
-
|
|
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
|
-
|
|
48
|
+
## Reviewing a PR
|
|
322
49
|
|
|
323
|
-
-
|
|
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
|
-
|
|
52
|
+
## Cleanup
|
|
330
53
|
|
|
331
|
-
|
|
332
|
-
|
|
333
|
-
|
|
334
|
-
|
|
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`.
|