source: .claude/rules/worktrees-and-waves.md · generated — edit the markdown, not this file

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 no node_modules, so the commit-msg hook (commitlint) and pre-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. Run corepack pnpm install --frozen-lockfile in the worktree first (forge-worktree-up does this). To check commits already made there: npx --no-install commitlint --from origin/main --to HEAD, run from a checkout that has node_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 -C overrides the shell’s cwd. forge-worktree-up already 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 on feature/<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. A sub WI branches from main (or from its owner’s branch when a same-repo compile coupling forces stacking, /forge-wave-decompose step 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 / e2e WI PRs target it. Its PR targets main (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.

Generated from .claude/rules/worktrees-and-waves.md by .claude/lib/render-docs-html.js. Markdown is canonical.