fix: place agent worktrees consistently under <repo>/.worktrees/#462
Merged
Conversation
setup-agent-worktree.sh created worktrees as repo siblings (../<repo>-<agent>), which scattered them outside the project and diverged from where other tooling expects them. Standardize on a single project-local location, <repo>/.worktrees/<agent>, matching the superpowers using-git-worktrees convention. - setup-agent-worktree.sh: compute worktree path under .worktrees/ and ensure .worktrees/ is gitignored before creating the worktree so a worktree's checkout is never accidentally committed - gitignore.ts: add .worktrees/ to the scaffold-managed block so downstream-scaffolded projects ignore it automatically - git-workflow.md meta-prompt: instruct downstream-generated worktree scripts to use the .worktrees/ convention + gitignore guard - docs/git-workflow.md, worktree-management knowledge, multi-agent guide (md + regenerated html, cite lines re-pointed): document the new path - tests: assert new location, no sibling dir, and .worktrees/ ignored Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Address multi-channel review findings on the worktree gitignore guard: - The pre-create check `git check-ignore -q .worktrees` false-negatived when `.worktrees/` was already ignored but the directory did not yet exist (a directory-only pattern only matches a path git knows is a dir). That caused a duplicate `.worktrees/` rule to be appended, including when src/project/gitignore.ts had already added it. Use the trailing-slash form `.worktrees/` so the check matches correctly regardless of whether the dir exists. Adds a regression test. - Remove the redundant `git worktree prune` from the bats teardown; the whole clone (with its .git/worktree metadata) is rm -rf'd right after. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
- Re-point :cite line numbers in content/guides/multi-agent to the shifted lines in setup-agent-worktree.sh (branch add, worktree add, mkdir .scaffold, identity printf, beads check) and rebuild index.html. - Align the "ensures .worktrees/ is gitignored" test to use the trailing-slash check-ignore form the script uses. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
A git add -A swept the Claude Code scheduler lock file (session id, PID, process start time) into the branch. Untrack it and add .claude/*.lock to .gitignore so runtime locks are never committed. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
zigrivers
added a commit
that referenced
this pull request
May 31, 2026
Document the worktree-location standardization (#462): agent worktrees now created under <repo>/.worktrees/<agent> with a gitignore guard, downstream propagation via the git-workflow meta-prompt and the scaffold-managed .gitignore block, plus a migration note for existing sibling worktrees. Bump version 3.32.0 -> 3.32.1 and align the README harvest example to the new convention. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
zigrivers
added a commit
that referenced
this pull request
May 31, 2026
Document the worktree-location standardization (#462): agent worktrees now created under <repo>/.worktrees/<agent> with a gitignore guard, downstream propagation via the git-workflow meta-prompt and the scaffold-managed .gitignore block, plus a migration note for existing sibling worktrees. Bump version 3.32.0 -> 3.32.1 and align the README harvest example to the new convention. Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Problem
setup-agent-worktree.shcreated agent worktrees as repo siblings(
../<repo>-<agent>), scattering them outside the project and diverging fromwhere other tooling expects worktrees. Worktree placement was inconsistent
across mechanisms; this standardizes scaffold's own worktrees on a single,
project-local location.
Change
Standardize on
<repo>/.worktrees/<agent>, matching the superpowersusing-git-worktreesconvention.scripts/setup-agent-worktree.sh— compute the worktree path under.worktrees/and ensure.worktrees/is gitignored before creating theworktree, so a worktree's full checkout is never accidentally committed.
src/project/gitignore.ts(+ test) — add.worktrees/to thescaffold-managed
.gitignoreblock so downstream-scaffolded projects ignoreit automatically.
content/pipeline/environment/git-workflow.md— the meta-prompt thatgenerates each downstream project's worktree script now specifies the
.worktrees/convention and the gitignore guard.docs/git-workflow.md§7, the worktree-management knowledge entry,and the multi-agent guide (md + regenerated html,
:citelines re-pointed tothe shifted script lines).
tests/setup-agent-worktree.bats— assert the new location, that nosibling dir is created, and that
.worktrees/ends up gitignored.Scope notes
.claude/worktrees/, Codex~/.codex/worktrees/) are created by those tools, not scaffold, and areintentionally left alone — per best practice, don't fight the harness.
.worktrees/.Verification
make check-allgreen: 690 TS tests pass, bats suite passes, ShellCheck clean,knowledge validation 0 errors, guides drift + security scan pass. TDD followed
(tests red → implementation → green).
🤖 Generated with Claude Code