Skip to main content
Status: superseded · ADR-43 · Filed 2026-05-02

​
ADR — Git Worktree Location Convention

​
Decision

All git worktrees created by Prism agents (or by prism install / bootstrap tooling) MUST be placed under $PROJECT_ROOT/.worktrees/<worktree-name>, never directly in $PROJECT_ROOT/. A per-repo git alias wt SHALL be configured at install time: 
git config alias.wt '!f() { git worktree add "$PROJECT_ROOT/.worktrees/$1" "$2"; }; f'
so that git wt prism-daemon-skeleton daemon/skeleton automatically lands in the correct location. The $PROJECT_ROOT/.worktrees/ directory SHALL be:
  • Created by prism install (both local and LAN modes)
  • Added to the project’s .gitignore if not already present
  • Documented in HOST_CONTRACT.md

​
Rationale

Git does not allow worktrees inside the repo they belong to (nested .git references are ambiguous). Agents defaulted to creating worktrees in $PROJECT_ROOT/ — the parent directory — because it was the simplest path satisfying git’s constraint. This caused 28 worktree directories to accumulate alongside actual project directories (Prism, MemRGR, DFW), making ~/projects/ unreadable and confusing to the operator. A hidden dot-directory (.worktrees/) keeps $PROJECT_ROOT/ clean for actual projects while remaining persistent and accessible. The git alias eliminates the need for agents to remember or construct the path manually.

​
Alternatives Considered

  1. $PROJECT_ROOT/<ProjectName>-worktrees/ — visible, explicit, but still clutters the project listing and requires per-project naming.
  2. /tmp/prism-worktrees/ — ephemeral, cleaned on reboot, unsuitable for long-lived feature branches.
  3. No convention (status quo) — rejected; 28 stray directories in ~/projects/ is the direct consequence.
  4. Per-repo .worktrees/ inside each project — rejected; git prohibits worktrees nested inside their parent repo.

​
Implementation

  1. Retrofit (Donna): Prune merged-branch worktrees, git worktree move surviving ones to $PROJECT_ROOT/.worktrees/, run git worktree prune.
  2. Install integration (Lafonda): Add mkdir -p $PROJECT_ROOT/.worktrees + git alias setup to prism install flow in cli/src/index.ts.
  3. Methodology rule: Agents creating worktrees MUST use the alias or the full .worktrees/ path. Direct git worktree add ../<name> in $PROJECT_ROOT/ is a methodology violation.
Last modified on May 3, 2026