| name | git-worktree |
| description | Use Git worktrees for important modifications that require a plan. This skill is activated automatically when entering plan mode.
|
| autoActivate | true |
Git Worktree for Important Changes
When this applies
This skill applies automatically whenever you enter plan mode
(EnterPlanMode) or when the user explicitly asks to work in a worktree.
Any modification that is significant enough to require a plan must be
developed in a dedicated Git worktree, not directly on the current branch.
Why
- The main working tree stays clean and usable while the change is in progress.
- Easy to discard a failed attempt without polluting the main branch.
- Enables parallel work on multiple changes.
Workflow
1. Create the worktree
Before writing any code, create a feature branch and worktree.
Use -b to create the new branch (it does not need to exist beforehand):
git worktree add -b feature/<short-name> ../alexandreroman.fr-<short-name>
The worktree is placed next to the main repo directory (sibling folder)
so it doesn't interfere with the current tree.
2. Work inside the worktree
All file reads, edits, and writes for the planned change must target the
worktree path (../alexandreroman.fr-<short-name>/...), not the main
repo.
3. Verify with Hugo
Do not commit yet. First verify that the changes work correctly.
Start Hugo from the worktree on a different port so it doesn't
conflict with the main dev server (1313) or other worktrees.
Always start Hugo as a background Bash command so you can stop it
reliably afterwards:
cd ../alexandreroman.fr-<short-name>
make dev PORT=1314
Dependencies (npm install) are handled automatically by make dev.
Use the hugo-site-check skill pointing at that port to verify.
After verification, always stop the Hugo server using TaskStop with
the background task ID. This must happen before the commit and
integration steps. Never leave Hugo processes running.
4. Commit
Only commit after the changes have been verified in the browser.
Stage and commit all relevant files in the worktree.
5. Integrate into main (rebase, no merge commit)
Once the change is validated, rebase the feature branch onto main and
fast-forward main. Never create merge commits — the history must stay
linear.
cd ../alexandreroman.fr-<short-name>
git restore package-lock.json
git rebase main
cd ../alexandreroman.fr
git merge --ff-only feature/<short-name>
6. Clean up (mandatory)
Always remove the worktree and branch at the end, whether the change was
integrated or abandoned. This step is not optional.
After a successful integration:
git worktree remove ../alexandreroman.fr-<short-name>
git branch -d feature/<short-name>
After an abandoned change:
git worktree remove ../alexandreroman.fr-<short-name>
git branch -D feature/<short-name>
Rules
- Never commit planned changes directly to the current branch. Always use
a worktree.
- Never create merge commits. Always rebase + fast-forward (
--ff-only).
- Always clean up the worktree and branch at the end of every operation.
No worktree or feature branch should remain after the task is complete.
- The worktree branch name should reflect the change (e.g.
feature/precompile-css, feature/round-favicon).
- Keep the main working tree on the original branch at all times during the
plan execution.
- Use
make dev PORT=<port> to start Hugo in a worktree (handles dependencies automatically).
- Always clean up temporary scripts used during generation.
