Worktree Workflow

worktree-workflow Sop

sop active workflow

Project

Worktree Workflow

All agent work uses /tmp/ clones for isolation. Agents clone the repo to /tmp/{repo}-{branch}, do their work, push, and clean up.

How It Works

When spawning a Dev agent for any repo:

Clone the repo to /tmp/{repo}-{branch}/
Create a feature branch (named {issue-number}-{description})
Run the agent inside that clone
Push to remote, open PR
Clean up: rm -rf /tmp/{repo}-{branch}

Do NOT use .claude/worktrees/. The old isolation: worktree approach created directories inside the repo that accumulated and caused permission issues. /tmp/ clones are disposable and isolated by design.

Pre-Spawn: Freshness Check

Before spawning a Dev agent, ensure local main is fresh:

Why: Agents branch from local HEAD. If local main is stale, the clone will be missing merged changes. This caused an incident on 2026-03-06 where a PR would have destroyed production resources. See todo-worktree-staleness-prevention.

Clone Pattern

Conflict Resolution

When a branch has conflicts with main or is behind main, always merge, never rebase:

NEVER rebase. NEVER force push. Rebase rewrites history, which forces the branch to diverge from the remote. The only way to update the remote after a rebase is force push, which destroys history and breaks traceability. Merge avoids the entire problem. See sop-branch-conflict-resolution for the full policy and incident history.

Post-Merge: Cleanup

After a PR merges, two things happen automatically:
1. Local main fast-forward: post-merge-rebase.sh (for gh pr merge) and post-mcp-merge-rebase.sh (for Forgejo MCP merges) fetch origin and fast-forward local main via git update-ref. This ensures the next clone/branch starts from the latest state.
2. Clone cleanup: The /tmp/ clone should already be removed by the agent. The cleanup-worktrees.sh SessionStart hook scans for stale /tmp/ clones older than 7 days as a safety net.
If hooks fail silently, manual recovery: git fetch origin main && git pull origin main

Remote Conventions

Repo	Remote
pal-e-platform	<code>forgejo</code>
pal-e-docs	<code>origin</code>
pal-e-docs-sdk	<code>origin</code>
pal-e-docs-mcp	<code>origin</code>
claude-custom	<code>origin</code>
landscaping-assistant	<code>origin</code>
basketball-api	<code>origin</code>

Rules

All work clones to /tmp/{repo}-{branch} — sole exception: ~/claude-custom uses direct branch checkout (symlink from ~/.claude/ requires it)
Always git fetch + pull before spawning agents — stale local main = stale clone
After every merge to main, local main MUST be fast-forwarded to match remote — automated by post-merge-rebase.sh and post-mcp-merge-rebase.sh
NEVER rebase, NEVER force push — use git merge origin/main to update branches. See sop-branch-conflict-resolution
One clone per issue — one agent, one branch, one PR
All work is pushed to Forgejo before PR creation — local clones are disposable
Agents clean up their own /tmp/ clone when done

What Changed (2026-06-06)

Moved from .claude/worktrees/ to /tmp/ clones. The old isolation: worktree approach stored worktrees inside the repo at .claude/worktrees/agent-{id}/. These accumulated, caused permission issues, and required sudo to clean. /tmp/ clones are ephemeral and isolated.
Removed isolation: worktree dependency. Agents clone manually instead of relying on Claude Code's built-in worktree feature.

agent-spawn-conventions — the axiom: no plan, no agent
solo-dev-pr-workflow — PR conventions
sop-branch-conflict-resolution — merge-only policy, never rebase, never force push
todo-worktree-staleness-prevention — the incident that motivated pre-spawn fetch

Worktree Workflow