Worktrees and Wave Branches
The detail behind git-conventions.md § Worktree Commands and § Wave Branches. The rule that
stays there for every session: give git its path with git -C <path>, never cd <path>; git ….
forge-worktree-up provisions worktrees and branches and /forge-deliver sequences them; this file
is what they run, for reading a worktree set or recovering one by hand.
Worktree Commands
$WS is the workspace parent — the directory holding every repo as a sibling. Set it once
per shell; the commands below then work from any cwd:
WS="$(dirname "$(dirname "$(git rev-parse --path-format=absolute --git-common-dir)")")" # the directory holding the harness and the app repos
Derive it rather than typing a path: it is correct on every machine, and it keeps machine-specific
paths out of the repo. Run it from anywhere in any of the repos, a linked worktree included: git’s
common directory is always the primary checkout’s .git, whereas --show-toplevel inside a
worktree names the worktree, whose parent is $WS/worktrees/<TICKET>, not $WS.
Install dependencies in a fresh app-repo worktree before the first commit. All three app repos wire their git hooks through husky (
"prepare": "husky"), and a new worktree has nonode_modules, so thecommit-msghook (commitlint) andpre-commit(lint-staged) silently do not run and a non-conforming message is committed without complaint. The Fast lane lints only the PR title, so nothing catches it before merge. Runcorepack pnpm install --frozen-lockfilein the worktree first (forge-worktree-updoes this). To check commits already made there:npx --no-install commitlint --from origin/main --to HEAD, run from a checkout that hasnode_modules.
Worktree paths are absolute on purpose — do not “simplify” them to relative.
git -C <repo>moves git’s working directory into the repo, so a relative worktree path resolves inside it (forge-et-be/worktrees/FS-1/forge-et-be) rather than beside it. Git reports success, so the only symptom is a nested worktree quietly appearing in every repo. Telling the reader to “run from the workspace parent” does not fix it, because-Coverrides the shell’s cwd.forge-worktree-upalready uses workspace-rooted paths; these match it.
Single-plan specs (branch from main)
A single-plan spec gets one feature branch per repo, branched from main.
# Create
git -C "$WS/<repo>" worktree add -b feature/<TICKET>-<description> "$WS/worktrees/<TICKET>/<repo>" main
Multi-repo (one worktree per repo, branch coordinated):
git -C "$WS/<backend-repo>" worktree add -b feature/<TICKET>-<description> "$WS/worktrees/<TICKET>/<backend-repo>" main
git -C "$WS/<frontend-repo>" worktree add -b feature/<TICKET>-<description> "$WS/worktrees/<TICKET>/<frontend-repo>" main
# Cleanup (after merge to main)
git -C "$WS/<backend-repo>" worktree remove "$WS/worktrees/<TICKET>/<backend-repo>"
git -C "$WS/<frontend-repo>" worktree remove "$WS/worktrees/<TICKET>/<frontend-repo>"
rmdir "$WS/worktrees/<TICKET>"
Multi-plan specs (wave mode — see below)
A decomposed feature ships one wave at a time, each wave as its own PR to main. There is no
long-lived spec branch in the app repos. forge-worktree-up provisions every branch and worktree
below, and /forge-deliver sequences them — these commands are what they run, for reading a
worktree set or recovering one by hand:
# Per-WI branch + worktree for a sub WI — from main
git -C "$WS/<repo>" worktree add -b feature/<SPEC_ID>-WI-<wave>.<index>-<slug> "$WS/worktrees/<SPEC_ID>/<wi-id>/<repo>" main
# The wave integration branch + its wave worktree, cut from origin/main when the wave's WIs
# integrate (Stage 11) — never `git checkout -b` in the repo's main checkout, which other
# sessions may be using (.forge/lessons.md L-076)
git -C "$WS/<repo>" worktree add --no-track -b feature/<SPEC_ID>-wave-<N> "$WS/worktrees/<SPEC_ID>/wave-<N>/<repo>" origin/main
Cleanup after the wave PR merges: GitHub deletes the wave branch; the per-WI remote branches (their
PRs closed as superseded, not merged), local branches and worktrees — the wave worktrees first, since
git branch -d refuses a branch a worktree has checked out — are cleaned by /forge-deliver
Stage 14 on confirmation (git-conventions.md § Deleting merged branches).
Wave Branches (multi-plan specs)
Applies when a spec is decomposed into work items (decomposed: true, ship_unit: wave). The
authoritative description is /forge-deliver § PR strategy; this is the branch-naming summary.
In the harness repo (specs, plans, tracker):
feature/<ticket>-spec→main— the spec PR (Stage 4).feature/<ticket>-plan→ stacked onfeature/<ticket>-spec— the plan PR, opened early after Wave 1’s plans are approved; later waves’ plans land as follow-up commits (Stage 9).
In each touched app repo, per wave:
feature/<ticket>-WI-<wave>.<index>-<slug>— one per work item. AsubWI branches frommain(or from its owner’s branch when a same-repo compile coupling forces stacking,/forge-wave-decomposestep 5.b.3); its PR is a transient review PR, opened as a draft, and closed as superseded when the wave PR opens.feature/<ticket>-wave-<N>— the wave integration branch. The wave’s WIs merge into it (Stage 11);verify/e2eWI PRs target it. Its PR targetsmain(Stage 12) and is the unit that ships and gets/forge-review-pr.
Keeping current: a wave branch merges main in — never a rebase or force-push once its PR is
open — and only for one of the reasons in git-conventions.md § Branching, not because it has
fallen behind. Resolve conflicts with the resolve-prove-commit rule (git-conventions.md § Branching).
Naming: no WI- suffix on the wave branch; the feature id is the prefix of every branch —
feature/F11-a-wave-1, feature/F11-a-WI-1.2-lead-intake-api.