docs: add tmux pattern for agent handoffs

.claude-plugin/skills/worktrunk/SKILL.md

@@ -256,3 +256,36 @@ grep -A 20 "## Setup" reference/llm-commits.md
 grep -A 30 "### post-create" reference/hook.md
 grep -A 20 "## Warning Messages" reference/shell-integration.md
 ```
+
+## Advanced: Agent Handoffs
+
+When the user requests spawning a worktree with Claude in a background session ("spawn a worktree for...", "hand off to another agent"), use the appropriate pattern for their terminal multiplexer:
+
+**tmux** (check `$TMUX` env var):
+```bash
+tmux new-session -d -s <branch-name> "wt switch --create <branch-name> -x claude -- '<task description>'"
+```
+
+**Zellij** (check `$ZELLIJ` env var):
+```bash
+zellij run -- wt switch --create <branch-name> -x claude -- '<task description>'
+```
+
+**Requirements** (all must be true):
+- User explicitly requests spawning/handoff
+- User is in a supported multiplexer (tmux or Zellij)
+- User's CLAUDE.md or explicit instruction authorizes this pattern
+
+**Do not use this pattern** for normal worktree operations.
+
+Example (tmux):
+```bash
+tmux new-session -d -s fix-auth-bug "wt switch --create fix-auth-bug -x claude -- \
+  'The login session expires after 5 minutes. Find the session timeout config and extend it to 24 hours.'"
+```
+
+Example (Zellij):
+```bash
+zellij run -- wt switch --create fix-auth-bug -x claude -- \
+  'The login session expires after 5 minutes. Find the session timeout config and extend it to 24 hours.'
+```

.claude-plugin/skills/worktrunk/reference/tips-patterns.md

@@ -194,6 +194,31 @@ wt switch --create feature-part2 --base=@
 
 Creates a worktree that builds on the current branch's changes.
 
+## Agent handoffs
+
+Spawn a worktree with Claude running in the background:
+
+**tmux** (new detached session):
+```bash
+tmux new-session -d -s fix-auth-bug "wt switch --create fix-auth-bug -x claude -- \
+  'The login session expires after 5 minutes. Find the session timeout config and extend it to 24 hours.'"
+```
+
+**Zellij** (new pane in current session):
+```bash
+zellij run -- wt switch --create fix-auth-bug -x claude -- \
+  'The login session expires after 5 minutes. Find the session timeout config and extend it to 24 hours.'
+```
+
+This lets one Claude session hand off work to another that runs in the background. Hooks run inside the multiplexer session/pane.
+
+The [worktrunk skill](https://worktrunk.dev/claude-code/) includes guidance for Claude Code to execute this pattern. To enable it, request it explicitly ("spawn a parallel worktree for...") or add to `CLAUDE.md`:
+
+```markdown
+When I ask you to spawn parallel worktrees, use the agent handoff pattern
+from the worktrunk skill.
+```
+
 ## Bare repository layout
 
 An alternative to the default sibling layout (`myproject.feature/`) uses a bare repository with worktrees as subdirectories:

docs/content/tips-patterns.md

@@ -206,6 +206,31 @@ wt switch --create feature-part2 --base=@
 
 Creates a worktree that builds on the current branch's changes.
 
+## Agent handoffs
+
+Spawn a worktree with Claude running in the background:
+
+**tmux** (new detached session):
+```bash
+tmux new-session -d -s fix-auth-bug "wt switch --create fix-auth-bug -x claude -- \
+  'The login session expires after 5 minutes. Find the session timeout config and extend it to 24 hours.'"
+```
+
+**Zellij** (new pane in current session):
+```bash
+zellij run -- wt switch --create fix-auth-bug -x claude -- \
+  'The login session expires after 5 minutes. Find the session timeout config and extend it to 24 hours.'
+```
+
+This lets one Claude session hand off work to another that runs in the background. Hooks run inside the multiplexer session/pane.
+
+The [worktrunk skill](@/claude-code.md) includes guidance for Claude Code to execute this pattern. To enable it, request it explicitly ("spawn a parallel worktree for...") or add to `CLAUDE.md`:
+
+```markdown
+When I ask you to spawn parallel worktrees, use the agent handoff pattern
+from the worktrunk skill.
+```
+
 ## Bare repository layout
 
 An alternative to the default sibling layout (`myproject.feature/`) uses a bare repository with worktrees as subdirectories: