Worktrunk is a CLI for Git worktree management, designed for parallel AI agent workflows
feat(skill): auto-sync skill reference files from docs (#467)
Maximilian Roosa1d384b30496
diff --git a/.claude-plugin/skills/worktrunk/SKILL.md b/.claude-plugin/skills/worktrunk/SKILL.mdindex 0bb72cc92..44ad28b77 100644--- a/.claude-plugin/skills/worktrunk/SKILL.md+++ b/.claude-plugin/skills/worktrunk/SKILL.md@@ -11,11 +11,15 @@ Help users work with Worktrunk, a CLI tool for managing git worktrees.## Available Documentation-- **SKILL.md**: Configuration workflows and common patterns-- **reference/user-config.md**: User config (LLM, worktree paths, command defaults)-- **reference/project-config.md**: Project config (lifecycle hooks)-- **reference/hook-types-reference.md**: Detailed hook behavior and timing+Reference files are synced from [worktrunk.dev](https://worktrunk.dev) documentation:++- **reference/config.md**: User and project configuration (LLM, hooks, command defaults)+- **reference/hook.md**: Hook types, timing, and execution order+- **reference/switch.md**, **merge.md**, **list.md**, etc.: Command documentation+- **reference/llm-commits.md**: LLM commit message generation+- **reference/tips-patterns.md**: Language-specific tips and patterns- **reference/shell-integration.md**: Shell integration debugging+- **reference/troubleshooting.md**: Troubleshooting for LLM and hooks (Claude-specific)For command-specific options, run `wt <command> --help`. For configuration, follow the workflows below.@@ -28,14 +32,14 @@ Worktrunk uses two separate config files with different scopes and behaviors:- **Location**: `~/.config/worktrunk/config.toml` (never checked into git)- **Contains**: LLM integration, worktree path templates, command settings, user hooks, approved commands- **Permission model**: Always propose changes and get consent before editing-- **See**: `reference/user-config.md` for detailed guidance+- **See**: `reference/config.md` for detailed guidance### Project Config (`.config/wt.toml`)- **Scope**: Team-wide automation shared by all developers- **Location**: `<repo>/.config/wt.toml` (checked into git)- **Contains**: Hooks for worktree lifecycle (post-create, pre-merge, etc.)- **Permission model**: Proactive (create directly, changes are reversible via git)-- **See**: `reference/project-config.md` for detailed guidance+- **See**: `reference/hook.md` for detailed guidance## Determining Which Config to Use@@ -96,7 +100,7 @@ Most common request. Follow this sequence:wt merge # in a repo with uncommitted changes```-**See `reference/user-config.md` for complete details.**+**See `reference/config.md` and `reference/llm-commits.md` for complete details.**### Setting Up Project Hooks (Project Config)@@ -147,7 +151,58 @@ Common request for workflow automation. Follow discovery process:wt switch --create test-hooks```-**See `reference/project-config.md` for complete details.**+**See `reference/hook.md` for complete details.**++### Adding Hooks to Existing Config++When users want to add automation to an existing project:++1. **Read existing config**: `cat .config/wt.toml`++2. **Determine hook type** - When should this run?+ - Creating worktree (blocking) → `post-create`+ - Creating worktree (background) → `post-start`+ - Every switch → `post-switch`+ - Before committing → `pre-commit`+ - Before merging → `pre-merge`+ - After merging → `post-merge`+ - Before removal → `pre-remove`++3. **Handle format conversion if needed**++ Single command to named table:+ ```toml+ # Before+ post-create = "npm install"++ # After (adding db:migrate)+ [post-create]+ install = "npm install"+ migrate = "npm run db:migrate"+ ```++4. **Preserve existing structure and comments**++### Validation Before Adding Commands++Before adding hooks, validate:++```bash+# Verify command exists+which npm+which cargo++# For npm, verify script exists+npm run lint --dry-run++# For shell commands, check syntax+bash -n -c "if [ true ]; then echo ok; fi"+```++**Dangerous patterns** — Warn users before creating hooks with:+- Destructive commands: `rm -rf`, `DROP TABLE`+- External dependencies: `curl http://...`+- Privilege escalation: `sudo`## Permission Models@@ -166,20 +221,17 @@ Common request for workflow automation. Follow discovery process:## Common Tasks Reference### User Config Tasks-- Set up LLM integration → `reference/user-config.md#llm-setup`-- Customize worktree paths → `reference/user-config.md#worktree-paths`-- Custom commit templates → `reference/user-config.md#templates`-- Configure command defaults → `reference/user-config.md#command-settings`-- Set up personal hooks → `reference/user-config.md#user-hooks`-- Troubleshoot LLM issues → `reference/user-config.md#troubleshooting`+- Set up LLM integration → `reference/llm-commits.md`+- Customize worktree paths → `reference/config.md#worktree-path-template`+- Custom commit templates → `reference/llm-commits.md#templates`+- Configure command defaults → `reference/config.md#command-settings`+- Set up personal hooks → `reference/config.md#user-hooks`### Project Config Tasks-- Set up hooks for new project → `reference/project-config.md#new-project`-- Add hook to existing config → `reference/project-config.md#add-hook`-- Use template variables → `reference/project-config.md#variables`-- Convert command formats → `reference/project-config.md#formats`-- Add dev server URL to list → `reference/project-config.md#dev-server-url`-- Troubleshoot hook execution → `reference/project-config.md#troubleshooting`+- Set up hooks for new project → `reference/hook.md`+- Add hook to existing config → `reference/hook.md#configuration`+- Use template variables → `reference/hook.md#template-variables`+- Add dev server URL to list → `reference/config.md#dev-server-url`## Key Commands@@ -200,7 +252,7 @@ Load **reference files** for detailed configuration, hook specifications, and trFind specific sections with grep:```bash-grep -A 20 "## LLM Setup" reference/user-config.md-grep -A 30 "### post-create" reference/project-config.md+grep -A 20 "## Setup" reference/llm-commits.md+grep -A 30 "### post-create" reference/hook.mdgrep -A 20 "## Warning Messages" reference/shell-integration.md```diff --git a/.claude-plugin/skills/worktrunk/reference/claude-code.md b/.claude-plugin/skills/worktrunk/reference/claude-code.mdnew file mode 100644index 000000000..b2863c023--- /dev/null+++ b/.claude-plugin/skills/worktrunk/reference/claude-code.md@@ -0,0 +1,53 @@+# Claude Code Integration++Worktrunk includes a Claude Code plugin that automatically tracks which worktrees have active Claude sessions. When Claude starts working in a worktree, the plugin sets a status marker; when Claude waits for input, the marker updates. This makes it easy to monitor multiple parallel agents from `wt list`.++## Status tracking++The plugin adds status indicators to `wt list`:++<span class="prompt">$</span> <span class="cmd">wt list</span>+ <b>Branch</b> <b>Status</b> <b>HEAD±</b> <b>main↕</b> <b>Path</b> <b>Remote⇅</b> <b>Commit</b> <b>Age</b> <b>Message</b>+@ main <span class=d>^</span> . <span class=d>a058e792</span> <span class=d>1d</span> <span class=d>Initial commit</span>++ feature-api <span class=d>↑</span> 🤖 <span class=g>↑1</span> ../repo.feature-api <span class=d>95e48b49</span> <span class=d>1d</span> <span class=d>Add REST API endpoints</span>++ review-ui <span class=c>?</span> <span class=d>↑</span> 💬 <span class=g>↑1</span> ../repo.review-ui <span class=d>46b6a187</span> <span class=d>1d</span> <span class=d>Add dashboard component</span>++ wip-docs <span class=c>?</span> <span class=d>–</span> ../repo.wip-docs <span class=d>a058e792</span> <span class=d>1d</span> <span class=d>Initial commit</span>++<span class=d>○</span> <span class=d>Showing 4 worktrees, 2 with changes, 2 ahead</span>++- 🤖 — Claude is working+- 💬 — Claude is waiting for input++### Installation++```bash+$ claude plugin marketplace add max-sixty/worktrunk+$ claude plugin install worktrunk@worktrunk+```++### Manual status markers++Set status markers manually for any workflow:++```bash+$ wt config state marker set "🚧" # Current branch+$ wt config state marker set "✅" --branch feature # Specific branch+$ git config worktrunk.state.feature.marker '{"marker":"💬","set_at":0}' # Direct+```++## Statusline++`wt list statusline --claude-code` outputs a single-line status for the Claude Code statusline. This may fetch CI status from the network when the cache is stale (often ~1–2 seconds), making it suitable for async statuslines but too slow for synchronous shell prompts. If a faster version would be helpful, please [open an issue](https://github.com/max-sixty/worktrunk/issues).++<code>~/w/myproject.feature-auth !🤖 @<span style='color:#0a0'>+42</span> <span style='color:#a00'>-8</span> <span style='color:#0a0'>↑3</span> <span style='color:#0a0'>⇡1</span> <span style='color:#0a0'>●</span> | Opus</code>++Add to `~/.claude/settings.json`:++```json+{+ "statusLine": {+ "type": "command",+ "command": "wt list statusline --claude-code"+ }+}+```diff --git a/.claude-plugin/skills/worktrunk/reference/config.md b/.claude-plugin/skills/worktrunk/reference/config.mdnew file mode 100644index 000000000..923d24633--- /dev/null+++ b/.claude-plugin/skills/worktrunk/reference/config.md@@ -0,0 +1,975 @@+# wt config++Manages configuration, shell integration, and runtime settings.++Worktrunk uses two configuration files:++| File | Location | Purpose |+|------|----------|---------|+| **User config** | `~/.config/worktrunk/config.toml` | Personal settings, command defaults, approved project commands |+| **Project config** | `.config/wt.toml` | Lifecycle hooks, checked into version control |++## Examples++Install shell integration (required for directory switching):++```bash+wt config shell install+```++Create user config file with documented examples:++```bash+wt config create+```++Create project config file (`.config/wt.toml`) for hooks:++```bash+wt config create --project+```++Show current configuration and file locations:++```bash+wt config show+```++## User config++The user config stores personal preferences that apply across all repositories. Create it with `wt config create` and view with `wt config show`.++### Worktree path template++Controls where new worktrees are created. The template is relative to the repository root.++**Available variables:**+- `{{ repo }}` — repository directory name+- `{{ branch }}` — raw branch name (e.g., `feature/auth`)+- `{{ branch | sanitize }}` — branch name with `/` and `\` replaced by `-`++**Examples** for a repo at `~/code/myproject` creating branch `feature/login`:++```toml+# Default — siblings in parent directory+# Creates: ~/code/myproject.feature-login+worktree-path = "../{{ repo }}.{{ branch | sanitize }}"++# Inside the repository+# Creates: ~/code/myproject/.worktrees/feature-login+worktree-path = ".worktrees/{{ branch | sanitize }}"++# Namespaced (useful when multiple repos share a parent directory)+# Creates: ~/code/worktrees/myproject/feature-login+worktree-path = "../worktrees/{{ repo }}/{{ branch | sanitize }}"++# Nested bare repo (git clone --bare <url> project/.git)+# Creates: ~/code/project/feature-login (sibling to .git)+worktree-path = "../{{ branch | sanitize }}"+```++### Command settings++Set persistent flag values for commands. These apply unless explicitly overridden on the command line.++**`wt list`:**++```toml+[list]+# All off by default+full = true # --full+branches = true # --branches+remotes = true # --remotes+```++**`wt step commit` and `wt merge` staging:**++```toml+[commit]+stage = "all" # "all" (default), "tracked", or "none"+```++**`wt merge`:**++```toml+[merge]+# These flags are on by default; set to false to disable+squash = false # Preserve individual commits (--no-squash)+commit = false # Skip committing uncommitted changes (also disables squash)+rebase = false # Skip rebase (fails if not already rebased)+remove = false # Keep worktree after merge (--no-remove)+verify = false # Skip hooks (--no-verify)+```++### LLM commit messages++Configure automatic commit message generation. Requires an external tool like [llm](https://llm.datasette.io/):++```toml+[commit-generation]+command = "llm"+args = ["-m", "claude-haiku-4.5"]+```++See [LLM Commit Messages](https://worktrunk.dev/llm-commits/) for setup details and template customization.++### Approved commands++When project hooks run for the first time, Worktrunk prompts for approval. Approved commands are saved here automatically:++```toml+[projects."my-project"]+approved-commands = ["npm ci", "npm test"]+```++Manage approvals with `wt hook approvals add` to review and pre-approve commands, and `wt hook approvals clear` to reset (add `--global` to clear all projects).++### User hooks++Personal hooks that run for all repositories. Use the same syntax as project hooks:++```toml+[post-create]+setup = "echo 'Setting up worktree...'"++[pre-merge]+notify = "notify-send 'Merging {{ branch }}'"+```++User hooks run before project hooks and don't require approval. Skip with `--no-verify`.++See [`wt hook`](https://worktrunk.dev/hook/#user-hooks) for complete documentation.++## Project config++The project config defines lifecycle hooks and project-specific settings. This file is checked into version control and shared across the team.++Create `.config/wt.toml` in the repository root:++```toml+[post-create]+install = "npm ci"++[pre-merge]+test = "npm test"+lint = "npm run lint"+```++See [`wt hook`](https://worktrunk.dev/hook/) for complete documentation on hook types, execution order, template variables, and [JSON context](https://worktrunk.dev/hook/#json-context).++### Dev server URL++The `[list]` section adds a URL column to `wt list`:++```toml+[list]+url = "http://localhost:{{ branch | hash_port }}"+```++URLs are dimmed when the port isn't listening. The template supports `{{ branch }}` with filters `hash_port` (port 10000-19999) and `sanitize` (filesystem-safe).++### CI platform override++The `[ci]` section overrides CI platform detection for GitHub Enterprise or self-hosted GitLab with custom domains:++```toml+[ci]+platform = "github" # or "gitlab"+```++By default, the platform is detected from the remote URL. Use this when URL detection fails (e.g., `git.mycompany.com` instead of `github.mycompany.com`).++## Shell integration++Worktrunk needs shell integration to change directories when switching worktrees. Install with:++```bash+wt config shell install+```++Or manually add to the shell config:++```bash+# For bash: add to ~/.bashrc+eval "$(wt config shell init bash)"++# For zsh: add to ~/.zshrc+eval "$(wt config shell init zsh)"++# For fish: add to ~/.config/fish/config.fish+wt config shell init fish | source+```++Without shell integration, `wt switch` prints the target directory but cannot `cd` into it.++### Skip first-run prompt++On first run without shell integration, Worktrunk offers to install it. Suppress this prompt in CI or automated environments:++```toml+skip-shell-integration-prompt = true+```++Or via environment variable:++```bash+export WORKTRUNK_SKIP_SHELL_INTEGRATION_PROMPT=true+```++## Environment variables++All user config options can be overridden with environment variables using the `WORKTRUNK_` prefix.++### Naming convention++Config keys use kebab-case (`worktree-path`), while env vars use SCREAMING_SNAKE_CASE (`WORKTRUNK_WORKTREE_PATH`). The conversion happens automatically.++For nested config sections, use double underscores to separate levels:++| Config | Environment Variable |+|--------|---------------------|+| `worktree-path` | `WORKTRUNK_WORKTREE_PATH` |+| `commit-generation.command` | `WORKTRUNK_COMMIT_GENERATION__COMMAND` |+| `commit-generation.args` | `WORKTRUNK_COMMIT_GENERATION__ARGS` |++Note the single underscore after `WORKTRUNK` and double underscores between nested keys.++### Array values++Array config values like `args = ["-m", "claude-haiku"]` can be specified as a single string in environment variables:++```bash+export WORKTRUNK_COMMIT_GENERATION__ARGS="-m claude-haiku"+```++### Example: CI/testing override++Override the LLM command in CI to use a mock:++```bash+WORKTRUNK_COMMIT_GENERATION__COMMAND=echo \+WORKTRUNK_COMMIT_GENERATION__ARGS="test: automated commit" \+ wt merge+```++### Other environment variables++| Variable | Purpose |+|----------|---------|+| `WORKTRUNK_BIN` | Override binary path for shell wrappers (useful for testing dev builds) |+| `WORKTRUNK_CONFIG_PATH` | Override user config file location |+| `WORKTRUNK_DIRECTIVE_FILE` | Internal: set by shell wrappers to enable directory changes |+| `WORKTRUNK_SHELL` | Internal: set by shell wrappers to indicate shell type (e.g., `powershell`) |+| `WORKTRUNK_MAX_CONCURRENT_COMMANDS` | Max parallel git commands (default: 32). Lower if hitting file descriptor limits. |+| `NO_COLOR` | Disable colored output ([standard](https://no-color.org/)) |+| `CLICOLOR_FORCE` | Force colored output even when not a TTY |++## Command reference++wt config - Manage configuration and shell integration++Usage: <b><span class=c>wt config</span></b> <span class=c>[OPTIONS]</span> <span class=c><COMMAND></span>++<b><span class=g>Commands:</span></b>+ <b><span class=c>shell</span></b> Shell integration setup+ <b><span class=c>create</span></b> Create configuration file+ <b><span class=c>show</span></b> Show configuration files & locations+ <b><span class=c>state</span></b> Manage internal data and cache++<b><span class=g>Options:</span></b>+ <b><span class=c>-h</span></b>, <b><span class=c>--help</span></b>+ Print help (see a summary with '-h')++<b><span class=g>Global Options:</span></b>+ <b><span class=c>-C</span></b><span class=c> <path></span>+ Working directory for this command++ <b><span class=c>--config</span></b><span class=c> <path></span>+ User config file path++ <b><span class=c>-v</span></b>, <b><span class=c>--verbose</span></b>+ Show commands and debug info++## wt config create++### User config++Creates `~/.config/worktrunk/config.toml` with the following content:++```+# Worktrunk Global Configuration+# Copy to: ~/.config/worktrunk/config.toml (or use `wt config create`)+#+# Alternative locations (XDG Base Directory spec):+# macOS/Linux: $XDG_CONFIG_HOME/worktrunk/config.toml+# Windows: %APPDATA%\worktrunk\config.toml++# Commit Message Generation (Optional)+# For generating commit messages during merge operations (wt merge)+# [commit-generation]+# Example: Simon Willison's llm CLI (https://github.com/simonw/llm)+# Install: pip install llm llm-anthropic+# command = "llm"+# args = ["-m", "claude-haiku-4.5"]++# Alternative: AIChat - Rust-based, supports 20+ providers+# Install from: https://github.com/sigoden/aichat+# command = "aichat"+# args = ["-m", "claude:claude-haiku-4.5"]++# Optional: Load template from file (mutually exclusive with 'template')+# Supports ~ expansion: ~/.config/worktrunk/commit-template.txt+# template-file = "~/.config/worktrunk/commit-template.txt"++# Optional: Load squash template from file (mutually exclusive with 'squash-template')+# Supports ~ expansion: ~/.config/worktrunk/squash-template.txt+# squash-template-file = "~/.config/worktrunk/squash-template.txt"++# See "Custom Prompt Templates" section at end of file for inline template options.++# Worktree Path Template+# Variables:+# {{ repo }} - Repository directory name (e.g., "myproject")+# {{ branch }} - Raw branch name (e.g., "feature/auth")+# {{ branch | sanitize }} - Branch name with / and \ replaced by - (e.g., "feature-auth")+#+# Paths are relative to the main worktree root (original repository directory).+#+# Example paths created (repo at /Users/dev/myproject, branch feature/auth):+# "../{{ repo }}.{{ branch | sanitize }}" → /Users/dev/myproject.feature-auth+# ".worktrees/{{ branch | sanitize }}" → /Users/dev/myproject/.worktrees/feature-auth+worktree-path = "../{{ repo }}.{{ branch | sanitize }}"++# Alternative: Inside repo (useful for bare repos)+# worktree-path = ".worktrees/{{ branch | sanitize }}"++# List Command Defaults+# Configure default behavior for `wt list`+[list]+full = false # Show CI and default-branch merge-base diffstat (`main…±` column) by default+branches = false # Include branches without worktrees by default+remotes = false # Include remote branches by default++# Commit Defaults (shared by `wt step commit`, `wt step squash`, and `wt merge`)+[commit]+stage = "all" # What to stage: "all", "tracked", or "none"++# Merge Command Defaults+# Note: `stage` defaults from [commit] section above+[merge]+squash = true # Squash commits when merging+commit = true # Commit uncommitted changes during merge (disables squash when false)+rebase = true # Rebase onto target before merging+remove = true # Remove worktree after merge+verify = true # Run project hooks++# Select Command Defaults+# Configure pager behavior for `wt select` diff previews+[select]+# Pager command with flags for diff preview (overrides git's core.pager)+# Use this to specify pager flags needed for non-TTY contexts+# Example: pager = "delta --paging=never"++# Approved Commands+# Commands approved for project hooks in this repo+# Auto-populated when approving hooks (prompt on first run) or via `wt hook approvals add`+[projects."github.com/user/repo"]+approved-commands = ["npm ci", "npm test"]++# NOTE: For project-specific hooks (post-create, post-start, pre-merge, etc.),+# use a separate PROJECT config file at <repo>/.config/wt.toml+# Run `wt config create --project` to create one, or see https://worktrunk.dev/hook/++# ============================================================================+# Custom Prompt Templates (Advanced)+# ============================================================================+# These options belong under [commit-generation] section above.+# NOTE: Templates are synced from src/llm.rs by `cargo test readme_sync`++# Optional: Custom prompt template (inline) - Uses minijinja syntax+# Available variables: {{ git_diff }}, {{ git_diff_stat }}, {{ branch }}, {{ recent_commits }}, {{ repo }}+# If not specified, uses the default template shown below:+# <!-- DEFAULT_TEMPLATE_START -->+# template = """+# Write a commit message for the staged changes below.+#+# <format>+# - Subject under 50 chars, blank line, then optional body+# - Output only the commit message, no quotes or code blocks+# </format>+#+# <style>+# - Imperative mood: "Add feature" not "Added feature"+# - Match recent commit style (conventional commits if used)+# - Describe the change, not the intent or benefit+# </style>+#+# <diffstat>+# {{ git_diff_stat }}+# </diffstat>+#+# <diff>+# {{ git_diff }}+# </diff>+#+# <context>+# Branch: {{ branch }}+# {% if recent_commits %}<recent_commits>+# {% for commit in recent_commits %}- {{ commit }}+# {% endfor %}</recent_commits>{% endif %}+# </context>+# """+# <!-- DEFAULT_TEMPLATE_END -->+#+# Example alternative template with different style:+# template = """+# Generate a commit message for {{ repo | upper }}.+#+# Branch: {{ branch }}+# {%- if recent_commits %}+#+# Recent commit style ({{ recent_commits | length }} commits):+# {%- for commit in recent_commits %}+# {{ loop.index }}. {{ commit }}+# {%- endfor %}+# {%- endif %}+#+# Changes to commit:+# ```+# {{ git_diff }}+# ```+#+# Requirements:+# - Follow the style of recent commits above+# - First line under 50 chars+# - Focus on WHY, not HOW+# """++# Optional: Custom squash commit message template (inline) - Uses minijinja syntax+# Available variables: {{ git_diff }}, {{ branch }}, {{ recent_commits }}, {{ repo }}, {{ commits }}, {{ target_branch }}+# If not specified, uses the default template:+# <!-- DEFAULT_SQUASH_TEMPLATE_START -->+# squash-template = """+# Combine these commits into a single commit message.+#+# <format>+# - Subject under 50 chars, blank line, then optional body+# - Output only the commit message, no quotes or code blocks+# </format>+#+# <style>+# - Imperative mood: "Add feature" not "Added feature"+# - Match the style of commits being squashed (conventional commits if used)+# - Describe the change, not the intent or benefit+# </style>+#+# <commits branch="{{ branch }}" target="{{ target_branch }}">+# {% for commit in commits %}- {{ commit }}+# {% endfor %}</commits>+#+# <diffstat>+# {{ git_diff_stat }}+# </diffstat>+#+# <diff>+# {{ git_diff }}+# </diff>+# """+# <!-- DEFAULT_SQUASH_TEMPLATE_END -->+#+# Example alternative template:+# squash-template = """+# Squashing {{ commits | length }} commit(s) from {{ branch }} to {{ target_branch }}.+#+# {% if commits | length > 1 -%}+# Commits being combined:+# {%- for c in commits %}+# {{ loop.index }}/{{ loop.length }}: {{ c }}+# {%- endfor %}+# {%- else -%}+# Single commit: {{ commits[0] }}+# {%- endif %}+#+# Generate one cohesive commit message that captures the overall change.+# Use conventional commit format (feat/fix/docs/refactor).+# """+```++### Project config++With `--project`, creates `.config/wt.toml` in the current repository:++```+# Worktrunk Project Configuration+# Copy to: <repo>/.config/wt.toml+#+# Project-specific hooks that run automatically during worktree operations.+# Check this file into git to share hooks across all developers.++# ============================================================================+# Hook Formats+# ============================================================================+# All hooks support two formats:+#+# Single command:+# post-create = "npm install"+#+# Named table (multiple commands):+# [post-create]+# deps = "npm install"+# build = "npm run build"+#+# Named commands appear in output, making it easier to identify failures.++# ============================================================================+# Template Variables+# ============================================================================+# All hooks support these variables:+# {{ repo }} - Repository directory name (e.g., "myproject")+# {{ branch }} - Branch name (e.g., "feature/auth")+# {{ worktree_path }} - Absolute path to worktree+# {{ main_worktree_path }} - Absolute path to main worktree+# {{ default_branch }} - Default branch name (e.g., "main")+#+# Merge hooks (pre-commit, pre-merge, post-merge) also support:+# {{ target }} - Target branch for the merge+#+# Filters:+# {{ branch | sanitize }} - Replace / and \ with - (e.g., "feature-auth")+# {{ branch | hash_port }} - Deterministic port 10000-19999++# ============================================================================+# Hooks+# ============================================================================++# Post-Create: Runs after worktree creation, BLOCKS until complete+# Use for: installing dependencies, setting up databases, copying configs+#+# [post-create]+# deps = "npm ci"+# env = "cp .env.example .env"++# Post-Start: Runs in BACKGROUND after worktree creation (parallel)+# Use for: dev servers, file watchers, background builds+# Output logged to .git/wt-logs/{branch}-project-post-start-{name}.log+#+# [post-start]+# server = "npm run dev -- --port {{ branch | hash_port }}"+# watch = "npm run watch"++# Post-Switch: Runs in BACKGROUND after every switch (parallel)+# Use for: terminal tab naming, tmux window titles, IDE notifications+#+# post-switch = "echo -ne '\\033]0;{{ branch }}\\007'"++# Pre-Commit: Runs before committing during merge, BLOCKS (fail-fast)+# Use for: formatters, linters, quick checks+#+# [pre-commit]+# format = "npm run format:check"+# lint = "npm run lint"++# Pre-Merge: Runs before merging to target, BLOCKS (fail-fast)+# Use for: tests, build verification+#+# [pre-merge]+# test = "npm test"+# build = "npm run build"++# Post-Merge: Runs after successful merge, BLOCKS+# Use for: deployment, notifications+#+# post-merge = "echo 'Merged {{ branch }} to {{ target }}'"++# Pre-Remove: Runs before worktree removal, BLOCKS (fail-fast)+# Use for: cleanup, stopping services+#+# pre-remove = "docker compose down"++# ============================================================================+# Dev Server URL (shown in `wt list`)+# ============================================================================+# [list]+# url = "http://localhost:{{ branch | hash_port }}"++# ============================================================================+# CI Platform Override+# ============================================================================+# Override CI platform detection for GitHub Enterprise or self-hosted GitLab+# with custom domains where URL detection fails.+#+# [ci]+# platform = "github" # or "gitlab"+```++### Command reference++wt config create - Create configuration file++Usage: <b><span class=c>wt config create</span></b> <span class=c>[OPTIONS]</span>++<b><span class=g>Options:</span></b>+ <b><span class=c>--project</span></b>+ Create project config (<b>.config/wt.toml</b>) instead of user config++ <b><span class=c>-h</span></b>, <b><span class=c>--help</span></b>+ Print help (see a summary with '-h')++<b><span class=g>Global Options:</span></b>+ <b><span class=c>-C</span></b><span class=c> <path></span>+ Working directory for this command++ <b><span class=c>--config</span></b><span class=c> <path></span>+ User config file path++ <b><span class=c>-v</span></b>, <b><span class=c>--verbose</span></b>+ Show commands and debug info++## wt config show++Shows location and contents of user config (`~/.config/worktrunk/config.toml`)+and project config (`.config/wt.toml`).++If a config file doesn't exist, shows defaults that would be used.++### Full diagnostics++Use `--full` to run diagnostic checks:++```bash+wt config show --full+```++This tests:+- **CI tool status** — Whether `gh` (GitHub) or `glab` (GitLab) is installed and authenticated+- **Commit generation** — Whether the LLM command can generate commit messages++### Command reference++wt config show - Show configuration files & locations++Usage: <b><span class=c>wt config show</span></b> <span class=c>[OPTIONS]</span>++<b><span class=g>Options:</span></b>+ <b><span class=c>--full</span></b>+ Run diagnostic checks (CI tools, commit generation)++ <b><span class=c>-h</span></b>, <b><span class=c>--help</span></b>+ Print help (see a summary with '-h')++<b><span class=g>Global Options:</span></b>+ <b><span class=c>-C</span></b><span class=c> <path></span>+ Working directory for this command++ <b><span class=c>--config</span></b><span class=c> <path></span>+ User config file path++ <b><span class=c>-v</span></b>, <b><span class=c>--verbose</span></b>+ Show commands and debug info++## wt config state++State is stored in `.git/` (config entries and log files), separate from configuration files.+Use `wt config show` to view file-based configuration.++### Keys++- **default-branch**: The repository's default branch (main, master, etc.)+- **previous-branch**: Previous branch for `wt switch -`+- **ci-status**: CI/PR status for a branch (passed, running, failed, conflicts, no-ci, error)+- **marker**: Custom status marker for a branch (shown in `wt list`)+- **logs**: Background operation logs++### Examples++Get the default branch:+```bash+wt config state default-branch+```++Set the default branch manually:+```bash+wt config state default-branch set main+```++Set a marker for current branch:+```bash+wt config state marker set "🚧 WIP"+```++Clear all CI status cache:+```bash+wt config state ci-status clear --all+```++Show all stored state:+```bash+wt config state get+```++Clear all stored state:+```bash+wt config state clear+```++### Command reference++wt config state - Manage internal data and cache++Usage: <b><span class=c>wt config state</span></b> <span class=c>[OPTIONS]</span> <span class=c><COMMAND></span>++<b><span class=g>Commands:</span></b>+ <b><span class=c>default-branch</span></b> Default branch setting+ <b><span class=c>previous-branch</span></b> Previous branch (for <b>wt switch -</b>)+ <b><span class=c>ci-status</span></b> CI status cache+ <b><span class=c>marker</span></b> Branch markers+ <b><span class=c>logs</span></b> Background operation logs+ <b><span class=c>hints</span></b> One-time hints shown in this repo+ <b><span class=c>get</span></b> Get all stored state+ <b><span class=c>clear</span></b> Clear all stored state++<b><span class=g>Options:</span></b>+ <b><span class=c>-h</span></b>, <b><span class=c>--help</span></b>+ Print help (see a summary with '-h')++<b><span class=g>Global Options:</span></b>+ <b><span class=c>-C</span></b><span class=c> <path></span>+ Working directory for this command++ <b><span class=c>--config</span></b><span class=c> <path></span>+ User config file path++ <b><span class=c>-v</span></b>, <b><span class=c>--verbose</span></b>+ Show commands and debug info++## wt config state default-branch++### Detection++Worktrunk detects the default branch automatically:++1. **Worktrunk cache** — Checks `git config worktrunk.default-branch` (single command)+2. **Git cache** — Detects primary remote and checks its HEAD (e.g., `origin/HEAD`)+3. **Remote query** — If not cached, queries `git ls-remote` (100ms–2s)+4. **Local inference** — If no remote, infers from local branches++Once detected, the result is cached in `worktrunk.default-branch` for fast access.++The local inference fallback uses these heuristics in order:+- If only one local branch exists, uses it+- For bare repos or empty repos, checks `symbolic-ref HEAD`+- Checks `git config init.defaultBranch`+- Looks for common names: main, master, develop, trunk++### When to use++Most users never need this command — default branch detection is automatic.+Use it to:++- **Debug** — See what worktrunk thinks the default branch is+- **Override** — Set a non-standard default branch with `set`+- **Refresh** — Force re-query with `get --refresh` after remote changes+- **Clear** — Remove cached value with `clear`++Without a subcommand, runs `get`. For `--refresh`, use `get --refresh`.++### Command reference++wt config state default-branch - Default branch setting++Usage: <b><span class=c>wt config state default-branch</span></b> <span class=c>[OPTIONS]</span> <span class=c>[COMMAND]</span>++<b><span class=g>Commands:</span></b>+ <b><span class=c>get</span></b> Get the default branch+ <b><span class=c>set</span></b> Set the default branch+ <b><span class=c>clear</span></b> Clear the default branch cache++<b><span class=g>Options:</span></b>+ <b><span class=c>-h</span></b>, <b><span class=c>--help</span></b>+ Print help (see a summary with '-h')++<b><span class=g>Global Options:</span></b>+ <b><span class=c>-C</span></b><span class=c> <path></span>+ Working directory for this command++ <b><span class=c>--config</span></b><span class=c> <path></span>+ User config file path++ <b><span class=c>-v</span></b>, <b><span class=c>--verbose</span></b>+ Show commands and debug info++## wt config state ci-status++Caches GitHub/GitLab CI status for display in [`wt list`](https://worktrunk.dev/list/#ci-status).++### How it works++1. **Platform detection** — From `[ci] platform` in project config, or detected from remote URL (github.com → GitHub, gitlab.com → GitLab)+2. **CLI requirement** — Requires `gh` (GitHub) or `glab` (GitLab) CLI, authenticated+3. **What's checked** — PRs/MRs first, then branch pipelines for branches with upstream+4. **Caching** — Results cached 30-60 seconds per branch+commit++### Status values++| Status | Meaning |+|--------|---------|+| `passed` | All checks passed |+| `running` | Checks in progress |+| `failed` | Checks failed |+| `conflicts` | PR has merge conflicts |+| `no-ci` | No checks configured |+| `error` | Fetch error (rate limit, network, auth) |++See [`wt list` CI status](https://worktrunk.dev/list/#ci-status) for display symbols and colors.++### When to use++- **Debug** — See cached status and when it was fetched+- **Refresh** — Force re-fetch with `get --refresh`+- **Clear** — Remove stale cache entries++Without a subcommand, runs `get` for the current branch. For `--branch` or `--refresh`, use `get --branch=NAME`.++### Command reference++wt config state ci-status - CI status cache++Usage: <b><span class=c>wt config state ci-status</span></b> <span class=c>[OPTIONS]</span> <span class=c>[COMMAND]</span>++<b><span class=g>Commands:</span></b>+ <b><span class=c>get</span></b> Get CI status for a branch+ <b><span class=c>clear</span></b> Clear CI status cache++<b><span class=g>Options:</span></b>+ <b><span class=c>-h</span></b>, <b><span class=c>--help</span></b>+ Print help (see a summary with '-h')++<b><span class=g>Global Options:</span></b>+ <b><span class=c>-C</span></b><span class=c> <path></span>+ Working directory for this command++ <b><span class=c>--config</span></b><span class=c> <path></span>+ User config file path++ <b><span class=c>-v</span></b>, <b><span class=c>--verbose</span></b>+ Show commands and debug info++## wt config state marker++Custom status text or emoji shown in the `wt list` Status column.++### Display++Markers appear at the start of the Status column:++```+Branch Status Path+main ^ ~/code/myproject+feature 🚧↑ ~/code/myproject.feature+bugfix 🤖!↑⇡ ~/code/myproject.bugfix+```++### Use cases++- **Work status** — `🚧` WIP, `✅` ready for review, `🔥` urgent+- **Agent tracking** — The [Claude Code plugin](https://worktrunk.dev/claude-code/) sets markers automatically+- **Notes** — Any short text: `"blocked"`, `"needs tests"`++### Storage++Stored in git config as `worktrunk.state.<branch>.marker`. Set directly with:++```bash+git config worktrunk.state.feature.marker '{"marker":"🚧","set_at":0}'+```++Without a subcommand, runs `get` for the current branch. For `--branch`, use `get --branch=NAME`.++### Command reference++wt config state marker - Branch markers++Usage: <b><span class=c>wt config state marker</span></b> <span class=c>[OPTIONS]</span> <span class=c>[COMMAND]</span>++<b><span class=g>Commands:</span></b>+ <b><span class=c>get</span></b> Get marker for a branch+ <b><span class=c>set</span></b> Set marker for a branch+ <b><span class=c>clear</span></b> Clear marker for a branch++<b><span class=g>Options:</span></b>+ <b><span class=c>-h</span></b>, <b><span class=c>--help</span></b>+ Print help (see a summary with '-h')++<b><span class=g>Global Options:</span></b>+ <b><span class=c>-C</span></b><span class=c> <path></span>+ Working directory for this command++ <b><span class=c>--config</span></b><span class=c> <path></span>+ User config file path++ <b><span class=c>-v</span></b>, <b><span class=c>--verbose</span></b>+ Show commands and debug info++## wt config state logs++View and manage logs from background operations.++### What's logged++| Operation | Log file |+|-----------|----------|+| post-start hooks | `{branch}-{source}-post-start-{name}.log` |+| Background removal | `{branch}-remove.log` |++Source is `user` or `project` depending on where the hook is defined.++### Location++All logs are stored in `.git/wt-logs/` (in the main worktree's git directory).++### Behavior++- **Overwrites** — Same operation on same branch overwrites previous log+- **Persists** — Logs from deleted branches remain until manually cleared+- **Shared** — All worktrees write to the same log directory++### Examples++List all log files:+```bash+wt config state logs get+```++View a specific log:+```bash+cat "$(git rev-parse --git-dir)/wt-logs/feature-project-post-start-build.log"+```++Clear all logs:+```bash+wt config state logs clear+```++### Command reference++wt config state logs - Background operation logs++Usage: <b><span class=c>wt config state logs</span></b> <span class=c>[OPTIONS]</span> <span class=c>[COMMAND]</span>++<b><span class=g>Commands:</span></b>+ <b><span class=c>get</span></b> List background operation log files+ <b><span class=c>clear</span></b> Clear background operation logs++<b><span class=g>Options:</span></b>+ <b><span class=c>-h</span></b>, <b><span class=c>--help</span></b>+ Print help (see a summary with '-h')++<b><span class=g>Global Options:</span></b>+ <b><span class=c>-C</span></b><span class=c> <path></span>+ Working directory for this command++ <b><span class=c>--config</span></b><span class=c> <path></span>+ User config file path++ <b><span class=c>-v</span></b>, <b><span class=c>--verbose</span></b>+ Show commands and debug infodiff --git a/.claude-plugin/skills/worktrunk/reference/faq.md b/.claude-plugin/skills/worktrunk/reference/faq.mdnew file mode 100644index 000000000..d7d42b57d--- /dev/null+++ b/.claude-plugin/skills/worktrunk/reference/faq.md@@ -0,0 +1,239 @@+# FAQ++## What commands does Worktrunk execute?++Worktrunk executes commands in four contexts:++1. **User hooks** (`~/.config/worktrunk/config.toml`) — Personal automation for all repositories+2. **Project hooks** (`.config/wt.toml`) — Repository-specific automation+3. **LLM commands** (`~/.config/worktrunk/config.toml`) — Commit message generation+4. **--execute flag** — Explicitly provided commands++User hooks don't require approval (you defined them). Commands from project hooks require approval on first run. Approved commands are saved to user config. If a command changes, Worktrunk requires new approval.++### Example approval prompt++```+▲ repo needs approval to execute 3 commands:++○ post-create install:+ echo 'Installing dependencies...'+○ post-create build:+ echo 'Building project...'+○ post-create test:+ echo 'Running tests...'+❯ Allow and remember? [y/N]+```++Use `--yes` to bypass prompts (useful for CI/automation).++## How does Worktrunk compare to alternatives?++### vs. branch switching++Branch switching uses one directory: uncommitted changes from one agent get mixed with the next agent's work, or block switching entirely. Worktrees give each agent its own directory with independent files and index.++### vs. Plain `git worktree`++Git's built-in worktree commands work but require manual lifecycle management:++```bash+# Plain git worktree workflow+git worktree add -b feature-branch ../myapp-feature main+cd ../myapp-feature+# ...work, commit, push...+cd ../myapp+git merge feature-branch+git worktree remove ../myapp-feature+git branch -d feature-branch+```++Worktrunk automates the full lifecycle:++```bash+wt switch --create feature-branch # Creates worktree, runs setup hooks+# ...work...+wt merge # Merges into default branch, cleans up+```++No cd back to main — `wt merge` runs from the feature worktree and merges into the target, like GitHub's merge button.++What `git worktree` doesn't provide:++- Consistent directory naming and cleanup validation+- Project-specific automation (install dependencies, start services)+- Unified status across all worktrees (commits, CI, conflicts, changes)++### vs. git-machete / git-town++Different scopes:++- **git-machete**: Branch stack management in a single directory+- **git-town**: Git workflow automation in a single directory+- **worktrunk**: Multi-worktree management with hooks and status aggregation++These tools can be used together—run git-machete or git-town inside individual worktrees.++### vs. Git TUIs (lazygit, gh-dash, etc.)++Git TUIs operate on a single repository. Worktrunk manages multiple worktrees, runs automation hooks, and aggregates status across branches. TUIs work inside each worktree directory.++## How does Worktrunk determine the default branch?++Worktrunk checks the local git cache first, queries the remote if needed, and falls back to local inference when no remote exists. The result is cached for fast subsequent lookups.++If the remote's default branch has changed (e.g., renamed from master to main), refresh with `wt config state default-branch get --refresh`.++For full details on the detection mechanism, see `wt config state default-branch --help`.++## On Windows, `wt` conflicts with Windows Terminal++Windows Terminal uses `wt` as its command-line launcher, so running `wt` invokes Terminal instead of Worktrunk.++As an immediate workaround, install as `git-wt`:++```bash+cargo install worktrunk --features git-wt+git-wt config shell install+```++This creates a `git-wt` shell function with directory changing and completions.++`git wt` (as a git subcommand) also works but cannot change directories since git runs subcommands as subprocesses.++We're considering better solutions — a better name, anyone?++## Does Worktrunk work on Windows?++**Experimental.** Core functionality works, but some features are unavailable.++| Feature | Git Bash | PowerShell |+|---------|----------|------------|+| Core commands (`list`, `switch`, `merge`, etc.) | ✅ | ✅ |+| Shell integration | ✅ | ✅ |+| Tab completion | ✅ | ✅ |+| Hooks | ✅ | ❌ (bash syntax) |+| `wt select` | ❌ | ❌ |++**Git Bash** (recommended) comes with [Git for Windows](https://gitforwindows.org/). Worktrunk auto-detects it when installed.++**PowerShell** works for basic operations, but hooks fail in pure PowerShell because they use bash syntax. With Git for Windows installed, Worktrunk auto-detects Git Bash for hook execution even when PowerShell is the interactive shell.++**`wt select`** uses [skim](https://github.com/skim-rs/skim), which only supports Unix. Use `wt list` and `wt switch <branch>` instead.++## Installation fails with C compilation errors++Errors related to tree-sitter or C compilation (C99 mode, `le16toh` undefined) can be avoided by installing without syntax highlighting:++```bash+$ cargo install worktrunk --no-default-features+```++This disables bash syntax highlighting in command output but keeps all core functionality. The syntax highlighting feature requires C99 compiler support and can fail on older systems or minimal Docker images.++## What files does Worktrunk create?++Worktrunk creates files in four categories.++### 1. Worktree directories++Created by `wt switch <branch>` (or `wt select`) when switching to a branch that doesn't have a worktree. Use `wt switch --create <branch>` to create a new branch. Default location is `../<repo>.<branch>` (sibling to main repo), configurable via `worktree-path` in user config.++**To remove:** `wt remove <branch>` removes the worktree directory and deletes the branch.++### 2. Config files++| File | Created by | Purpose |+|------|------------|---------|+| `~/.config/worktrunk/config.toml` | `wt config create`, or approving project commands | User preferences, approved commands |+| `.config/wt.toml` | `wt config create --project` | Project hooks (checked into repo) |++User config location: `$XDG_CONFIG_HOME/worktrunk/` (or `~/.config/worktrunk/`) on Linux/macOS, `%APPDATA%\worktrunk\` on Windows.++**To remove:** Delete directly. User config: `rm ~/.config/worktrunk/config.toml`. Project config: `rm .config/wt.toml` (and commit).++### 3. Shell integration++Created by `wt config shell install`:++- **Bash**: adds line to `~/.bashrc`+- **Zsh**: adds line to `~/.zshrc` (or `$ZDOTDIR/.zshrc`)+- **Fish**: creates `~/.config/fish/conf.d/wt.fish` and `~/.config/fish/completions/wt.fish`++**To remove:** `wt config shell uninstall`.++### 4. Metadata in `.git/` (automatic)++Worktrunk stores small amounts of cache and log data in your repository's `.git/` directory:++| Location | Purpose | Created by |+|----------|---------|------------|+| `.git/config` keys under `worktrunk.*` | Cached default branch, switch history, branch markers | Various commands |+| `.git/wt-cache/ci-status/*.json` | CI status cache (~1KB each) | `wt list` when `gh` CLI is installed |+| `.git/wt-logs/*.log` | Background command output | Hooks, background `wt remove` |++None of this is tracked by git or pushed to remotes.++**To remove:** `wt config state clear` removes all worktrunk keys from `.git/config`, deletes CI cache, and clears logs.++### What Worktrunk does NOT create++- No files outside `.git/`, config directories, or worktree directories+- No global git hooks+- No modifications to `~/.gitconfig`+- No background processes or daemons++## What can Worktrunk delete?++Worktrunk can delete **worktrees** and **branches**. Both have safeguards.++### Worktree removal++`wt remove` mirrors `git worktree remove`: it refuses to remove worktrees with uncommitted changes (staged, modified, or untracked files). The `--force` flag overrides the untracked-files check for build artifacts that weren't cleaned up.++For worktrees containing precious ignored data (databases, caches, large assets), use `git worktree lock`:++```bash+git worktree lock ../myproject.feature --reason "Contains local database"+```++Locked worktrees show `⊞` in `wt list`. Neither `git worktree remove` nor `wt remove` (even with `--force`) will delete them. Unlock with `git worktree unlock`.++### Branch deletion++By default, `wt remove` only deletes branches whose content is already in the default branch. Branches showing `_` (same commit) or `⊂` (integrated) in `wt list` are safe to delete.++For the full algorithm, see [Branch cleanup](https://worktrunk.dev/remove/#branch-cleanup) — it handles squash-merge and rebase workflows where commit history differs but file changes match.++Use `-D` to force-delete branches with unmerged changes. Use `--no-delete-branch` to keep the branch regardless of status.++### Other cleanup++- `wt config state clear` — removes cached state from `.git/config` and clears CI cache/logs+- `wt config shell uninstall` — removes shell integration from rc files++See [What files does Worktrunk create?](#what-files-does-worktrunk-create) for details.++## Running tests (for contributors)++### Quick tests++```bash+$ cargo test+```++### Full integration tests++Shell integration tests require bash, zsh, and fish:++```bash+$ cargo test --test integration --features shell-integration-tests+```++## How can I contribute?++- Star the repo+- Try it out and [open an issue](https://github.com/max-sixty/worktrunk/issues) with feedback — even small annoyances+- What worktree friction does Worktrunk not yet solve? [Tell us](https://github.com/max-sixty/worktrunk/issues)+- Send to a friend+- Post about it on [X](https://twitter.com/intent/tweet?text=Worktrunk%20%E2%80%94%20CLI%20for%20git%20worktree%20management&url=https%3A%2F%2Fworktrunk.dev), [Reddit](https://www.reddit.com/submit?url=https%3A%2F%2Fworktrunk.dev&title=Worktrunk%20%E2%80%94%20CLI%20for%20git%20worktree%20management), or [LinkedIn](https://www.linkedin.com/sharing/share-offsite/?url=https%3A%2F%2Fworktrunk.dev)diff --git a/.claude-plugin/skills/worktrunk/reference/hook-types-reference.md b/.claude-plugin/skills/worktrunk/reference/hook-types-reference.mddeleted file mode 100644index fd3601e64..000000000--- a/.claude-plugin/skills/worktrunk/reference/hook-types-reference.md+++ /dev/null@@ -1,377 +0,0 @@-# Hook Types Reference--Detailed behavior and use cases for all seven Worktrunk hook types.--## Hook Type Comparison--| Hook | When | Blocking? | Fail-Fast? | Variables | Execution |-|------|------|-----------|------------|-----------|-----------|-| `post-create` | After creating worktree | Yes | No | Basic + Base | Sequential |-| `post-start` | After creating worktree | No (background) | No | Basic + Base | Parallel |-| `post-switch` | After every switch | No (background) | No | Basic + Base | Parallel |-| `pre-commit` | Before committing during merge | Yes | Yes | Basic + Merge | Sequential |-| `pre-merge` | Before merging to target | Yes | Yes | Basic + Merge | Sequential |-| `post-merge` | After successful merge | Yes | No | Basic + Merge | Sequential |-| `pre-remove` | Before worktree removed | Yes | Yes | Basic | Sequential |--**Basic variables**: `{{ repo }}`, `{{ repo_path }}`, `{{ branch }}`, `{{ worktree_name }}`, `{{ worktree_path }}`, `{{ main_worktree_path }}`, `{{ default_branch }}`, `{{ commit }}`, `{{ short_commit }}`, `{{ remote }}`, `{{ remote_url }}`, `{{ upstream }}`-**Base variables**: `{{ base }}`, `{{ base_worktree_path }}`-**Merge variables**: `{{ target }}`-**Filters**: `{{ branch | sanitize }}` (replace `/` `\` with `-`), `{{ branch | hash_port }}` (port 10000-19999)--## Detailed Behavior--### post-create--**When it runs**: After creating a new worktree, before switching to it.--**Behavior**:-- Blocks until all commands complete-- User cannot use worktree until complete-- Failure shows error but doesn't abort (worktree still created)-- Commands run sequentially--**Use cases**:-- Installing dependencies (npm install, cargo build, poetry install)-- Setting up databases (migrations, seeding)-- Copying required files-- Any setup that must complete before work can begin--**Example**:-```toml-[post-create]-install = "npm install"-migrate = "npm run db:migrate"-env = "cp .env.example .env"-```--**What happens**: User runs `wt switch --create feature-x`. Commands execute sequentially. User sees progress. After all complete, they're switched to the new worktree.--### post-start--**When it runs**: After creating a new worktree (not when switching to existing).--**Behavior**:-- Runs in background, doesn't block user-- Multiple commands run in parallel-- Output logged to `.git/wt-logs/`-- Failure doesn't affect user session--**Use cases**:-- Long builds that can run in background-- Cache warming-- Background sync/pull operations-- Anything slow that doesn't need to block work--**Example**:-```toml-[post-start]-build = "npm run build"-services = "docker-compose up -d"-sync = "git pull origin main"-```--**What happens**: User runs `wt switch --create feature-x`. After creation completes, all three commands start immediately in parallel in background. User can work while they run. Check `.git/wt-logs/` for output.--### post-switch--**When it runs**: After every switch operation (creating new, switching to existing, or switching to current).--**Behavior**:-- Runs in background, doesn't block user-- Multiple commands run in parallel-- Output logged to `.git/wt-logs/`-- Triggers on all switch results--**Use cases**:-- Renaming terminal tabs-- Updating tmux window names-- IDE notifications-- Any per-switch automation--**Example**:-```toml-post-switch = "echo 'Switched to {{ branch }}'"-```--**What happens**: Every time the user runs `wt switch`, this fires in the background. Unlike post-start, it runs on every switch, not just when creating new worktrees.--### pre-commit--**When it runs**: Before committing changes during `wt merge`.--**Behavior**:-- Blocks until all commands complete-- Commands run sequentially-- ANY failure aborts the commit (fail-fast)-- Exit code 0 required from all commands--**Use cases**:-- Linting (must pass before commit)-- Formatting checks-- Type checking-- Quick validation that must pass--**Example**:-```toml-[pre-commit]-lint = "npm run lint"-typecheck = "npm run typecheck"-format = "npm run format:check"-```--**What happens**: User runs `wt merge`. Before creating commit, all three commands run. If any fails, commit is aborted. User fixes issues and tries again.--### pre-merge--**When it runs**: Before merging to target branch during `wt merge`.--**Behavior**:-- Blocks until all commands complete-- Commands run sequentially-- ANY failure aborts the merge (fail-fast)-- Exit code 0 required from all commands-- Runs after commit succeeds--**Use cases**:-- Running tests (must pass before merge)-- Security scans-- Build verification-- Any validation that must pass before merge--**Example**:-```toml-[pre-merge]-test = "npm test"-build = "npm run build"-```--**What happens**: User runs `wt merge`. After commit succeeds, before merging, both commands run. If any fails, merge is aborted but commit remains.--### post-merge--**When it runs**: After successful merge to target branch, before cleanup.--**Behavior**:-- Blocks until all commands complete-- Commands run sequentially-- Runs in main worktree, not feature branch worktree-- Failure shows error but doesn't abort (merge already happened)--**Use cases**:-- Deployment (after merge to main)-- Notifications (Slack, email)-- Cache invalidation-- Triggering CI/CD-- Any post-merge automation--**Example**:-```toml-[post-merge]-deploy = "npm run deploy"-notify = "./scripts/notify-slack.sh"-```--**What happens**: User runs `wt merge`. After merge succeeds and push completes, commands run in main worktree. Then cleanup happens (branch deletion, worktree removal).--### pre-remove--**When it runs**: Before worktree removal during `wt remove`.--**Behavior**:-- Blocks until all commands complete-- Commands run sequentially-- ANY failure aborts the removal (fail-fast)-- Exit code 0 required from all commands--**Use cases**:-- Cleanup tasks (temp files, caches)-- Saving state before removal-- Notifying external systems-- Stopping services--**Example**:-```toml-[pre-remove]-cleanup = "rm -rf /tmp/cache/{{ branch }}"-stop = "docker-compose down"-```--**What happens**: User runs `wt remove`. Before the worktree is removed, commands run. If any fails, removal is aborted.--## Execution Order During Merge--Full sequence when running `wt merge`:--1. Validate working tree is clean-2. **Run `pre-commit`** (fail-fast)-3. Create commit-4. Switch to main worktree-5. Pull latest changes-6. **Run `pre-merge`** (fail-fast)-7. Merge branch into target-8. Push to remote-9. **Run `post-merge`** (best-effort)-10. **Run `pre-remove`** (fail-fast, if cleanup enabled)-11. Clean up (delete branch, remove worktree)--## Format Variants--All hooks support two formats:--### Single Command (String)-```toml-post-create = "npm install"-```--### Multiple Commands (Named Table)-```toml-[post-create]-dependencies = "npm install"-database = "npm run db:migrate"-services = "docker-compose up -d"-```--Behavior:-- `post-create`: Sequential execution-- `post-start`: Parallel execution-- `post-switch`: Parallel execution-- `pre-commit`: Sequential execution-- `pre-merge`: Sequential execution-- `post-merge`: Sequential execution-- `pre-remove`: Sequential execution--Named commands appear in output with their labels, making it easier to identify which command succeeded or failed.--## Template Variables--### Basic Variables (All Hooks)--```toml-post-create = "echo 'Working on {{ branch }} in {{ repo }}'"-```--Available:-- `{{ repo }}` - Repository directory name (e.g., "myproject")-- `{{ repo_path }}` - Absolute path to repository (e.g., "/path/to/myproject")-- `{{ branch }}` - Branch name (e.g., "feature/auth")-- `{{ worktree_name }}` - Worktree directory name (e.g., "myproject.feature-auth")-- `{{ worktree_path }}` - Absolute path to worktree (e.g., "/path/to/myproject.feature-auth")-- `{{ main_worktree_path }}` - Absolute path to main worktree (e.g., "/path/to/myproject")-- `{{ default_branch }}` - Default branch name (e.g., "main")-- `{{ commit }}` - Full HEAD commit SHA-- `{{ short_commit }}` - Short HEAD commit SHA (7 chars)-- `{{ remote }}` - Primary remote name (e.g., "origin")-- `{{ remote_url }}` - Remote URL (e.g., "[email protected]:user/repo.git")-- `{{ upstream }}` - Upstream tracking branch (e.g., "origin/feature")--### Base Variables (Creation Hooks)--```toml-post-create = "echo 'Created from {{ base }} at {{ base_worktree_path }}'"-```--Available in: `post-create`, `post-start`, `post-switch` — only when creating a new worktree (not when switching to existing worktrees).--Additional variables:-- `{{ base }}` - Base branch that new worktree was created from (e.g., "main")-- `{{ base_worktree_path }}` - Absolute path to base branch worktree (empty if base has no worktree)--### Merge Variables (Merge Hooks Only)--```toml-pre-merge = "echo 'Merging {{ branch }} into {{ target }}'"-```--Available in: `pre-commit`, `pre-merge`, `post-merge`--Additional variable:-- `{{ target }}` - Target branch for merge (e.g., "main")--### Conditional Logic--Use shell conditionals with variables:--```toml-pre-merge = """-if [ "{{ target }}" = "main" ]; then- npm run test:full-elif [ "{{ target }}" = "staging" ]; then- npm run test:integration-else- npm run test:unit-fi-"""-```--### JSON Context--Hooks also receive context as JSON on stdin, enabling hooks in any language:--```python-import json, sys-ctx = json.load(sys.stdin)-print(f"Setting up {ctx['repo']} on branch {ctx['branch']}")-```--The JSON includes all template variables plus `hook_type` and `hook_name`. This enables repository-specific behavior in user hooks:--```toml-# ~/.config/worktrunk/config.toml-[post-switch]-notify = """-python3 -c '-import json, sys-ctx = json.load(sys.stdin)-if "work-project" in ctx.get("repo", ""):- print(f"Switched to work project: {ctx[\"branch\"]}")-'-"""-```--## Common Patterns--### Fast Dependencies + Slow Build-```toml-# Blocking: must complete before work starts-post-create = "npm install"--# Background: builds while user works-post-start = "npm run build"-```--### Progressive Validation-```toml-# Quick checks before commit-[pre-commit]-lint = "npm run lint"-typecheck = "npm run typecheck"--# Thorough validation before merge-[pre-merge]-test = "npm test"-build = "npm run build"-```--### Target-Specific Behavior-```toml-post-merge = """-if [ "{{ target }}" = "main" ]; then- npm run deploy:production-elif [ "{{ target }}" = "staging" ]; then- npm run deploy:staging-fi-"""-```--### Monorepo with Multiple Tools-```toml-[post-create]-frontend = "cd frontend && npm install"-backend = "cd backend && cargo build"-database = "docker-compose up -d postgres"--[pre-merge]-frontend-tests = "cd frontend && npm test"-backend-tests = "cd backend && cargo test"-```diff --git a/.claude-plugin/skills/worktrunk/reference/hook.md b/.claude-plugin/skills/worktrunk/reference/hook.mdnew file mode 100644index 000000000..f44ead521--- /dev/null+++ b/.claude-plugin/skills/worktrunk/reference/hook.md@@ -0,0 +1,558 @@+# wt hook++Shell commands that run at key points in the worktree lifecycle.++Hooks run automatically during `wt switch`, `wt merge`, & `wt remove`. `wt hook <type>` runs them on demand. Both user hooks (from `~/.config/worktrunk/config.toml`) and project hooks (from `.config/wt.toml`) are supported.++## Hook types++| Hook | When | Blocking | Fail-fast |+|------|------|----------|-----------|+| `post-create` | After worktree created | Yes | No |+| `post-start` | After worktree created | No (background) | No |+| `post-switch` | After every switch | No (background) | No |+| `pre-commit` | Before commit during merge | Yes | Yes |+| `pre-merge` | Before merging to target | Yes | Yes |+| `post-merge` | After successful merge | Yes | No |+| `pre-remove` | Before worktree removed | Yes | Yes |++**Blocking**: Command waits for hook to complete before continuing.+**Fail-fast**: First failure aborts the operation.++### post-create++Runs after worktree creation, **blocks until complete**. The worktree switch doesn't finish until these commands succeed.++**Use cases**: Installing dependencies, database migrations, copying environment files.++```toml+[post-create]+install = "npm ci"+migrate = "npm run db:migrate"+env = "cp .env.example .env"+```++### post-start++Runs after worktree creation, **in background**. The worktree switch completes immediately; these run in parallel.++**Use cases**: Long builds, dev servers, file watchers, downloading large assets.++```toml+[post-start]+build = "npm run build"+server = "npm run dev"+```++Output logged to `.git/wt-logs/{branch}-{source}-post-start-{name}.log` (source is `user` or `project`).++### post-switch++Runs after **every** switch operation, **in background**. Triggers on all switch results: creating new worktrees, switching to existing ones, or switching to the current worktree.++**Use cases**: Renaming terminal tabs, updating tmux window names, IDE notifications.++```toml+post-switch = "echo 'Switched to {{ branch }}'"+```++Output logged to `.git/wt-logs/{branch}-{source}-post-switch-{name}.log` (source is `user` or `project`).++### pre-commit++Runs before committing during `wt merge`, **fail-fast**. All commands must exit 0 for the commit to proceed.++**Use cases**: Formatters, linters, type checking.++```toml+[pre-commit]+format = "cargo fmt -- --check"+lint = "cargo clippy -- -D warnings"+```++### pre-merge++Runs before merging to target branch, **fail-fast**. All commands must exit 0 for the merge to proceed.++**Use cases**: Tests, security scans, build verification.++```toml+[pre-merge]+test = "cargo test"+build = "cargo build --release"+```++### post-merge++Runs after successful merge in the **worktree for the target branch** if it exists, otherwise the **main worktree**, **best-effort**. Failures are logged but don't abort.++**Use cases**: Deployment, notifications, installing updated binaries.++```toml+post-merge = "cargo install --path ."+```++### pre-remove++Runs before worktree removal during `wt remove`, **fail-fast**. All commands must exit 0 for removal to proceed.++**Use cases**: Cleanup tasks, saving state, notifying external systems.++```toml+[pre-remove]+cleanup = "rm -rf /tmp/cache/{{ branch }}"+```++### Timing during merge++- **pre-commit** — After staging, before squash commit+- **pre-merge** — After rebase, before merge to target+- **pre-remove** — Before removing worktree during cleanup+- **post-merge** — After cleanup completes++See [`wt merge`](https://worktrunk.dev/merge/#pipeline) for the complete pipeline.++## Configuration++Hooks are defined in `.config/wt.toml`. They can be a single command or multiple named commands:++```toml+# Single command (string)+post-create = "npm install"++# Multiple commands (table) — run sequentially in declaration order+[pre-merge]+test = "cargo test"+build = "cargo build --release"+```++### Template variables++Hooks can use template variables that expand at runtime:++| Variable | Example | Description |+|----------|---------|-------------|+| `{{ repo }}` | myproject | Repository directory name |+| `{{ repo_path }}` | /path/to/myproject | Absolute path to repository root |+| `{{ branch }}` | feature/auth | Branch name |+| `{{ worktree_name }}` | myproject.feature-auth | Worktree directory name |+| `{{ worktree_path }}` | /path/to/myproject.feature-auth | Absolute worktree path |+| `{{ main_worktree_path }}` | /path/to/myproject | Default branch worktree |+| `{{ default_branch }}` | main | Default branch name |+| `{{ commit }}` | a1b2c3d4e5f6... | Full HEAD commit SHA |+| `{{ short_commit }}` | a1b2c3d | Short HEAD commit SHA |+| `{{ remote }}` | origin | Primary remote name |+| `{{ remote_url }}` | [email protected]:user/repo.git | Remote URL |+| `{{ upstream }}` | origin/feature | Upstream tracking branch |+| `{{ target }}` | main | Target branch (merge hooks only) |+| `{{ base }}` | main | Base branch (creation hooks only) |+| `{{ base_worktree_path }}` | /path/to/myproject | Base branch worktree (creation hooks only) |++See [Designing effective hooks](#designing-effective-hooks) for `main_worktree_path` patterns.++**Deprecated:** `repo_root` (use `repo_path`), `worktree` (use `worktree_path`), `main_worktree` (use `repo`). These still work but emit warnings.++### Filters++Templates support Jinja2 filters for transforming values:++| Filter | Example | Description |+|--------|---------|-------------|+| `sanitize` | `{{ branch \| sanitize }}` | Replace `/` and `\` with `-` |+| `hash_port` | `{{ branch \| hash_port }}` | Hash to port 10000-19999 |++The `sanitize` filter makes branch names safe for filesystem paths. The `hash_port` filter is useful for running dev servers on unique ports per worktree:++```toml+[post-start]+dev = "npm run dev -- --host {{ branch }}.lvh.me --port {{ branch | hash_port }}"+```++Hash any string, including concatenations:++```toml+# Unique port per repo+branch combination+dev = "npm run dev --port {{ (repo ~ '-' ~ branch) | hash_port }}"+```++### JSON context++Hooks also receive context as JSON on stdin, enabling hooks in any language:++```python+import json, sys+ctx = json.load(sys.stdin)+print(f"Setting up {ctx['repo']} on branch {ctx['branch']}")+```++The JSON includes all template variables plus `hook_type` and `hook_name`.++## Designing effective hooks++### post-create vs post-start++Both run when creating a worktree. The difference:++| Hook | Execution | Best for |+|------|-----------|----------|+| `post-create` | Blocks until complete | Tasks the developer needs before working (dependency install) |+| `post-start` | Background, parallel | Long-running tasks that can finish while you work |++Many tasks work well in `post-start` — they'll likely be ready by the time you need them, especially when the fallback is recompiling. If unsure, prefer `post-start` for faster worktree creation.++### Copying untracked files++Git worktrees share the repository but not untracked files. Common files to copy or link:++- **Dependencies**: `node_modules/`, `.venv/`, `target/`, `vendor/`, `Pods/`+- **Build caches**: `.cache/`, `.next/`, `.parcel-cache/`, `.turbo/`+- **Generated assets**: Images, ML models, binaries too large for git+- **Environment files**: `.env` (if not generated per-worktree)++Three strategies:++| Strategy | Speed | Disk | State |+|----------|-------|------|-------|+| **Symlink** | Instant | Shared | Shared (changes affect all worktrees) |+| **Copy** | Slow | Full duplicate | Isolated |+| **Copy-on-write** | Instant | Shared until modified | Isolated |++### Copy-on-write for disk efficiency++Copy-on-write (CoW) creates instant clones that share disk space until modified. Perfect for large directories.++| OS | Filesystem | Command |+|----|------------|---------|+| macOS | APFS | `cp -c` |+| Linux | Btrfs, XFS | `cp --reflink=auto` |+| Windows | ReFS | No shell equivalent (requires API) |++Cross-platform pattern that auto-detects and falls back gracefully:++```toml+[post-create]+deps = """+if cp -c /dev/null /dev/null 2>/dev/null; then+ cp -c -r {{ main_worktree_path }}/node_modules .+elif cp --reflink=auto /dev/null /dev/null 2>/dev/null; then+ cp --reflink=auto -r {{ main_worktree_path }}/node_modules .+else+ cp -r {{ main_worktree_path }}/node_modules .+fi+"""+```++### Dev servers++Run a dev server per worktree on a deterministic port using `hash_port`:++```toml+[post-start]+server = "npm run dev -- --port {{ branch | hash_port }}"+```++The port is stable across machines and restarts — `feature-api` always gets the same port. Show it in `wt list`:++```toml+[list]+url = "http://localhost:{{ branch | hash_port }}"+```++For subdomain-based routing (useful for cookies/CORS), use `lvh.me` which resolves to 127.0.0.1:++```toml+[post-start]+server = "npm run dev -- --host {{ branch | sanitize }}.lvh.me --port {{ branch | hash_port }}"+```++### Databases++Each worktree can have its own database. Docker containers get unique names and ports:++```toml+[post-start]+db = """+docker run -d --rm \+ --name {{ repo }}-{{ branch | sanitize }}-postgres \+ -p {{ ('db-' ~ branch) | hash_port }}:5432 \+ -e POSTGRES_DB={{ repo }} \+ -e POSTGRES_PASSWORD=dev \+ postgres:16+"""++[pre-remove]+db-stop = "docker stop {{ repo }}-{{ branch | sanitize }}-postgres 2>/dev/null || true"+```++The `('db-' ~ branch)` concatenation hashes differently than plain `branch`, so database and dev server ports don't collide.+Jinja2's operator precedence has pipe `|` with higher precedence than concatenation `~`, meaning expressions need parentheses to filter concatenated values.++Generate `.env.local` with the connection string:++```toml+[post-create]+env = """+cat > .env.local << EOF+DATABASE_URL=postgres://postgres:dev@localhost:{{ ('db-' ~ branch) | hash_port }}/{{ repo }}+DEV_PORT={{ branch | hash_port }}+EOF+"""+```++## Security++Project commands require approval on first run:++```+▲ repo needs approval to execute 3 commands:++○ post-create install:+ echo 'Installing dependencies...'++❯ Allow and remember? [y/N]+```++- Approvals are saved to user config (`~/.config/worktrunk/config.toml`)+- If a command changes, new approval is required+- Use `--yes` to bypass prompts (useful for CI/automation)+- Use `--no-verify` to skip hooks++Manage approvals with `wt hook approvals add` and `wt hook approvals clear`.++## User hooks++Define hooks in `~/.config/worktrunk/config.toml` to run for all repositories. User hooks run before project hooks and don't require approval.++```toml+# ~/.config/worktrunk/config.toml+[post-create]+setup = "echo 'Setting up worktree...'"++[pre-merge]+notify = "notify-send 'Merging {{ branch }}'"+```++User hooks support the same hook types and template variables as project hooks.++**Key differences from project hooks:**++| Aspect | Project hooks | User hooks |+|--------|--------------|------------|+| Location | `.config/wt.toml` | `~/.config/worktrunk/config.toml` |+| Scope | Single repository | All repositories |+| Approval | Required | Not required |+| Execution order | After user hooks | Before project hooks |++Skip hooks with `--no-verify`. To run a specific hook when user and project both define the same name, use `user:name` or `project:name` syntax.++**Use cases:**+- Personal notifications or logging+- Editor/IDE integration+- Repository-agnostic setup tasks+- Filtering by repository using JSON context++**Filtering by repository:**++User hooks receive JSON context on stdin, enabling repository-specific behavior:++```toml+# ~/.config/worktrunk/config.toml+[post-create]+gitlab-setup = """+python3 -c '+import json, sys, subprocess+ctx = json.load(sys.stdin)+if "gitlab" in ctx.get("remote", ""):+ subprocess.run(["glab", "mr", "create", "--fill"])+'+"""+```++## Running hooks manually++`wt hook <type>` runs hooks on demand — useful for testing during development, running in CI pipelines, or re-running after a failure.++```bash+wt hook pre-merge # Run all pre-merge hooks+wt hook pre-merge test # Run hooks named "test" from both sources+wt hook pre-merge user: # Run all user hooks+wt hook pre-merge project: # Run all project hooks+wt hook pre-merge user:test # Run only user's "test" hook+wt hook pre-merge project:test # Run only project's "test" hook+wt hook pre-merge --yes # Skip approval prompts (for CI)+wt hook post-create --var branch=feature/test # Override template variable+```++The `user:` and `project:` prefixes filter by source. Use `user:` or `project:` alone to run all hooks from that source, or `user:name` / `project:name` to run a specific hook.++The `--var KEY=VALUE` flag lets you override built-in template variables — useful for testing hooks with different contexts without switching to that context.++## Language-specific tips++Each ecosystem has quirks that affect hook design. Contributions welcome for languages not listed.++### Rust++The `target/` directory is huge (often 1-10GB) and benefits most from CoW. Worktrunk's own config seeds compiled dependencies:++```toml+[post-start]+deps = """+[ -d {{ main_worktree_path }}/target/debug/deps ] && [ ! -e target ] &&+mkdir -p target/debug/deps &&+cp -c {{ main_worktree_path }}/target/debug/deps/*.rlib {{ main_worktree_path }}/target/debug/deps/*.rmeta target/debug/deps/ &&+cp -cR {{ main_worktree_path }}/target/debug/.fingerprint {{ main_worktree_path }}/target/debug/build target/debug/+"""+```++This cuts first build from ~68s to ~3s by reusing compiled dependencies. The check `[ ! -e target ]` skips if target already exists.++### Python++Virtual environments contain absolute paths and can't be copied between directories. Use `uv sync` to recreate — it's fast enough that copying isn't worth it:++```toml+[post-create]+install = "uv sync"+```++For pip-based projects without uv:++```toml+[post-create]+venv = "python -m venv .venv && .venv/bin/pip install -r requirements.txt"+```++### Node.js++`node_modules/` is large but mostly static. CoW works well:++```toml+[post-create]+deps = "cp -c -r {{ main_worktree_path }}/node_modules . 2>/dev/null || npm ci"+```++If the project has no native dependencies, symlinks are even faster:++```toml+[post-create]+deps = "ln -sf {{ main_worktree_path }}/node_modules ."+```++### Hook flow patterns++**Progressive validation** — Quick checks before commit, thorough validation before merge:++```toml+[pre-commit]+lint = "npm run lint"+typecheck = "npm run typecheck"++[pre-merge]+test = "npm test"+build = "npm run build"+```++**Target-specific behavior** — Different actions for production vs staging:++```toml+post-merge = """+if [ "{{ target }}" = "main" ]; then+ npm run deploy:production+elif [ "{{ target }}" = "staging" ]; then+ npm run deploy:staging+fi+"""+```++## Command reference++wt hook - Run configured hooks++Usage: <b><span class=c>wt hook</span></b> <span class=c>[OPTIONS]</span> <span class=c><COMMAND></span>++<b><span class=g>Commands:</span></b>+ <b><span class=c>show</span></b> Show configured hooks+ <b><span class=c>post-create</span></b> Run post-create hooks+ <b><span class=c>post-start</span></b> Run post-start hooks+ <b><span class=c>post-switch</span></b> Run post-switch hooks+ <b><span class=c>pre-commit</span></b> Run pre-commit hooks+ <b><span class=c>pre-merge</span></b> Run pre-merge hooks+ <b><span class=c>post-merge</span></b> Run post-merge hooks+ <b><span class=c>pre-remove</span></b> Run pre-remove hooks+ <b><span class=c>approvals</span></b> Manage command approvals++<b><span class=g>Options:</span></b>+ <b><span class=c>-h</span></b>, <b><span class=c>--help</span></b>+ Print help (see a summary with '-h')++<b><span class=g>Global Options:</span></b>+ <b><span class=c>-C</span></b><span class=c> <path></span>+ Working directory for this command++ <b><span class=c>--config</span></b><span class=c> <path></span>+ User config file path++ <b><span class=c>-v</span></b>, <b><span class=c>--verbose</span></b>+ Show commands and debug info++## wt hook approvals++### How Approvals Work++Commands from project hooks (`.config/wt.toml`) require approval on first run.+This prevents untrusted projects from running arbitrary commands.++**Approval flow:**+1. Command is shown as a template (variables not expanded)+2. User approves or denies+3. Approved commands are saved to user config under `[projects."project-id"]`++**When re-approval is required:**+- Command template changes (not just variable values)+- Project ID changes (repository moves)++**Bypassing prompts:**+- `--yes` flag on individual commands (e.g., `wt merge --yes`)+- Useful for CI/automation where prompts aren't possible++### Examples++Pre-approve all commands for current project:+```bash+wt hook approvals add+```++Clear approvals for current project:+```bash+wt hook approvals clear+```++Clear global approvals:+```bash+wt hook approvals clear --global+```++### Command reference++wt hook approvals - Manage command approvals++Usage: <b><span class=c>wt hook approvals</span></b> <span class=c>[OPTIONS]</span> <span class=c><COMMAND></span>++<b><span class=g>Commands:</span></b>+ <b><span class=c>add</span></b> Store approvals in config+ <b><span class=c>clear</span></b> Clear approved commands from config++<b><span class=g>Options:</span></b>+ <b><span class=c>-h</span></b>, <b><span class=c>--help</span></b>+ Print help (see a summary with '-h')++<b><span class=g>Global Options:</span></b>+ <b><span class=c>-C</span></b><span class=c> <path></span>+ Working directory for this command++ <b><span class=c>--config</span></b><span class=c> <path></span>+ User config file path++ <b><span class=c>-v</span></b>, <b><span class=c>--verbose</span></b>+ Show commands and debug infodiff --git a/.claude-plugin/skills/worktrunk/reference/list.md b/.claude-plugin/skills/worktrunk/reference/list.mdnew file mode 100644index 000000000..033c68a0d--- /dev/null+++ b/.claude-plugin/skills/worktrunk/reference/list.md@@ -0,0 +1,280 @@+# wt list++Show all worktrees with their status. The table includes uncommitted changes, divergence from the default branch and remote, and optional CI status.++The table renders progressively: branch names, paths, and commit hashes appear immediately, then status, divergence, and other columns fill in as background git operations complete. With `--full`, CI status fetches from the network — the table displays instantly and CI fills in as results arrive.++## Examples++List all worktrees:++<span class="prompt">$</span> <span class="cmd">wt list</span>+ <b>Branch</b> <b>Status</b> <b>HEAD±</b> <b>main↕</b> <b>Remote⇅</b> <b>Commit</b> <b>Age</b> <b>Message</b>+@ feature-api <span class=c>+</span> <span class=d>↕</span><span class=d>⇡</span> <span class=g>+54</span> <span class=r>-5</span> <span class=g>↑4</span> <span class=d><span class=r>↓1</span></span> <span class=g>⇡3</span> <span class=d>ec97decc</span> <span class=d>30m</span> <span class=d>Add API tests</span>+^ main <span class=d>^</span><span class=d>⇅</span> <span class=g>⇡1</span> <span class=d><span class=r>⇣1</span></span> <span class=d>6088adb3</span> <span class=d>4d</span> <span class=d>Merge fix-auth: hardened to…</span>++ fix-auth <span class=d>↕</span><span class=d>|</span> <span class=g>↑2</span> <span class=d><span class=r>↓1</span></span> <span class=d>|</span> <span class=d>127407de</span> <span class=d>5h</span> <span class=d>Add secure token storage</span>++<span class=d>○</span> <span class=d>Showing 3 worktrees, 1 with changes, 2 ahead, 1 column hidden</span>++Include CI status and line diffs:++<span class="prompt">$</span> <span class="cmd">wt list --full</span>+ <b>Branch</b> <b>Status</b> <b>HEAD±</b> <b>main↕</b> <b>main…±</b> <b>Remote⇅</b> <b>CI</b> <b>Commit</b> <b>Age</b> <b>Message</b>+@ feature-api <span class=c>+</span> <span class=d>↕</span><span class=d>⇡</span> <span class=g>+54</span> <span class=r>-5</span> <span class=g>↑4</span> <span class=d><span class=r>↓1</span></span> <span class=g>+234</span> <span class=r>-24</span> <span class=g>⇡3</span> <span class=d><span style='color:var(--blue,#00a)'>●</span></span> <span class=d>ec97decc</span> <span class=d>30m</span> <span class=d>Add API tests</span>+^ main <span class=d>^</span><span class=d>⇅</span> <span class=g>⇡1</span> <span class=d><span class=r>⇣1</span></span> <span class=g>●</span> <span class=d>6088adb3</span> <span class=d>4d</span> <span class=d>Merge fix-au…</span>++ fix-auth <span class=d>↕</span><span class=d>|</span> <span class=g>↑2</span> <span class=d><span class=r>↓1</span></span> <span class=g>+25</span> <span class=r>-11</span> <span class=d>|</span> <span class=g>●</span> <span class=d>127407de</span> <span class=d>5h</span> <span class=d>Add secure t…</span>++<span class=d>○</span> <span class=d>Showing 3 worktrees, 1 with changes, 2 ahead, 1 column hidden</span>++Include branches that don't have worktrees:++<span class="prompt">$</span> <span class="cmd">wt list --branches --full</span>+ <b>Branch</b> <b>Status</b> <b>HEAD±</b> <b>main↕</b> <b>main…±</b> <b>Remote⇅</b> <b>CI</b> <b>Commit</b> <b>Age</b> <b>Message</b>+@ feature-api <span class=c>+</span> <span class=d>↕</span><span class=d>⇡</span> <span class=g>+54</span> <span class=r>-5</span> <span class=g>↑4</span> <span class=d><span class=r>↓1</span></span> <span class=g>+234</span> <span class=r>-24</span> <span class=g>⇡3</span> <span class=d><span style='color:var(--blue,#00a)'>●</span></span> <span class=d>ec97decc</span> <span class=d>30m</span> <span class=d>Add API tests</span>+^ main <span class=d>^</span><span class=d>⇅</span> <span class=g>⇡1</span> <span class=d><span class=r>⇣1</span></span> <span class=g>●</span> <span class=d>6088adb3</span> <span class=d>4d</span> <span class=d>Merge fix-au…</span>++ fix-auth <span class=d>↕</span><span class=d>|</span> <span class=g>↑2</span> <span class=d><span class=r>↓1</span></span> <span class=g>+25</span> <span class=r>-11</span> <span class=d>|</span> <span class=g>●</span> <span class=d>127407de</span> <span class=d>5h</span> <span class=d>Add secure t…</span>+ exp <span class=d>/</span><span class=d>↕</span> <span class=g>↑2</span> <span class=d><span class=r>↓1</span></span> <span class=g>+137</span> <span class=d>99e114de</span> <span class=d>2d</span> <span class=d>Add GraphQL…</span>+ wip <span class=d>/</span><span class=d>↕</span> <span class=g>↑1</span> <span class=d><span class=r>↓1</span></span> <span class=g>+33</span> <span class=d>d62fd0e8</span> <span class=d>3d</span> <span class=d>Start API do…</span>++<span class=d>○</span> <span class=d>Showing 3 worktrees, 2 branches, 1 with changes, 4 ahead, 1 column hidden</span>++Output as JSON for scripting:++```bash+$ wt list --format=json+```++## Columns++| Column | Shows |+|--------|-------|+| Branch | Branch name |+| Status | Compact symbols (see below) |+| HEAD± | Uncommitted changes: +added -deleted lines |+| main↕ | Commits ahead/behind default branch |+| main…± | Line diffs since the merge-base with the default branch (`--full`) |+| Path | Worktree directory |+| Remote⇅ | Commits ahead/behind tracking branch |+| URL | Dev server URL from project config (dimmed if port not listening) |+| CI | Pipeline status (`--full`) |+| Commit | Short hash (8 chars) |+| Age | Time since last commit |+| Message | Last commit message (truncated) |++Note: `main↕` and `main…±` refer to the default branch (header label stays `main` for compactness). `main…±` uses a merge-base (three-dot) diff.++### CI status++The CI column shows GitHub/GitLab pipeline status:++| Indicator | Meaning |+|-----------|---------|+| <span style='color:#0a0'>●</span> green | All checks passed |+| <span style='color:#00a'>●</span> blue | Checks running |+| <span style='color:#a00'>●</span> red | Checks failed |+| <span style='color:#a60'>●</span> yellow | Merge conflicts with base |+| <span style='color:#888'>●</span> gray | No checks configured |+| <span style='color:#a60'>⚠</span> yellow | Fetch error (rate limit, network) |+| (blank) | No upstream or no PR/MR |++CI indicators are clickable links to the PR or pipeline page. Any CI dot appears dimmed when there are unpushed local changes (stale status). PRs/MRs are checked first, then branch workflows/pipelines for branches with an upstream. Local-only branches show blank. Results are cached for 30-60 seconds; use `wt config state` to view or clear.++## Status symbols++The Status column has multiple subcolumns. Within each, only the first matching symbol is shown (listed in priority order):++| Subcolumn | Symbol | Meaning |+|-----------|--------|---------|+| Working tree (1) | `+` | Staged files |+| Working tree (2) | `!` | Modified files (unstaged) |+| Working tree (3) | `?` | Untracked files |+| Worktree | `✘` | Merge conflicts |+| | `⤴` | Rebase in progress |+| | `⤵` | Merge in progress |+| | `/` | Branch without worktree |+| | `⚑` | Branch-worktree mismatch (branch name doesn't match worktree path) |+| | `⊟` | Prunable (directory missing) |+| | `⊞` | Locked worktree |+| Default branch | `^` | Is the default branch |+| | `✗` | Would conflict if merged to the default branch (with `--full`, includes uncommitted changes) |+| | `_` | Same commit as the default branch, clean |+| | `–` | Same commit as the default branch, uncommitted changes |+| | `⊂` | Content [integrated](https://worktrunk.dev/remove/#branch-cleanup) into the default branch or target |+| | `↕` | Diverged from the default branch |+| | `↑` | Ahead of the default branch |+| | `↓` | Behind the default branch |+| Remote | `\|` | In sync with remote |+| | `⇅` | Diverged from remote |+| | `⇡` | Ahead of remote |+| | `⇣` | Behind remote |++Rows are dimmed when [safe to delete](https://worktrunk.dev/remove/#branch-cleanup) (`_` same commit with clean working tree or `⊂` content integrated).++## JSON output++Query structured data with `--format=json`:++```bash+# Current worktree path (for scripts)+wt list --format=json | jq -r '.[] | select(.is_current) | .path'++# Branches with uncommitted changes+wt list --format=json | jq '.[] | select(.working_tree.modified)'++# Worktrees with merge conflicts+wt list --format=json | jq '.[] | select(.operation_state == "conflicts")'++# Branches ahead of main (needs merging)+wt list --format=json | jq '.[] | select(.main.ahead > 0) | .branch'++# Integrated branches (safe to remove)+wt list --format=json | jq '.[] | select(.main_state == "integrated" or .main_state == "empty") | .branch'++# Branches without worktrees+wt list --format=json --branches | jq '.[] | select(.kind == "branch") | .branch'++# Worktrees ahead of remote (needs pushing)+wt list --format=json | jq '.[] | select(.remote.ahead > 0) | {branch, ahead: .remote.ahead}'++# Stale CI (local changes not reflected in CI)+wt list --format=json --full | jq '.[] | select(.ci.stale) | .branch'+```++**Fields:**++| Field | Type | Description |+|-------|------|-------------|+| `branch` | string/null | Branch name (null for detached HEAD) |+| `path` | string | Worktree path (absent for branches without worktrees) |+| `kind` | string | `"worktree"` or `"branch"` |+| `commit` | object | Commit info (see below) |+| `working_tree` | object | Working tree state (see below) |+| `main_state` | string | Relation to the default branch (see below) |+| `integration_reason` | string | Why branch is integrated (see below) |+| `operation_state` | string | `"conflicts"`, `"rebase"`, or `"merge"` (absent when clean) |+| `main` | object | Relationship to the default branch (see below, absent when is_main) |+| `remote` | object | Tracking branch info (see below, absent when no tracking) |+| `worktree` | object | Worktree metadata (see below) |+| `is_main` | boolean | Is the main worktree |+| `is_current` | boolean | Is the current worktree |+| `is_previous` | boolean | Previous worktree from wt switch |+| `ci` | object | CI status (see below, absent when no CI) |+| `url` | string | Dev server URL from project config (absent when not configured) |+| `url_active` | boolean | Whether the URL's port is listening (absent when not configured) |+| `statusline` | string | Pre-formatted status with ANSI colors |+| `symbols` | string | Raw status symbols without colors (e.g., `"!?↓"`) |++### commit object++| Field | Type | Description |+|-------|------|-------------|+| `sha` | string | Full commit SHA (40 chars) |+| `short_sha` | string | Short commit SHA (7 chars) |+| `message` | string | Commit message (first line) |+| `timestamp` | number | Unix timestamp |++### working_tree object++| Field | Type | Description |+|-------|------|-------------|+| `staged` | boolean | Has staged files |+| `modified` | boolean | Has modified files (unstaged) |+| `untracked` | boolean | Has untracked files |+| `renamed` | boolean | Has renamed files |+| `deleted` | boolean | Has deleted files |+| `diff` | object | Lines changed vs HEAD: `{added, deleted}` |+| `diff_vs_main` | object | Lines changed vs the default branch: `{added, deleted}` |++### main object++| Field | Type | Description |+|-------|------|-------------|+| `ahead` | number | Commits ahead of the default branch |+| `behind` | number | Commits behind the default branch |+| `diff` | object | Lines changed vs the default branch: `{added, deleted}` |++### remote object++| Field | Type | Description |+|-------|------|-------------|+| `name` | string | Remote name (e.g., `"origin"`) |+| `branch` | string | Remote branch name |+| `ahead` | number | Commits ahead of remote |+| `behind` | number | Commits behind remote |++### worktree object++| Field | Type | Description |+|-------|------|-------------|+| `state` | string | `"branch_worktree_mismatch"`, `"prunable"`, `"locked"` (absent when normal) |+| `reason` | string | Reason for locked/prunable state |+| `detached` | boolean | HEAD is detached |++### ci object++| Field | Type | Description |+|-------|------|-------------|+| `status` | string | CI status (see below) |+| `source` | string | `"pr"` (PR/MR) or `"branch"` (branch workflow) |+| `stale` | boolean | Local HEAD differs from remote (unpushed changes) |+| `url` | string | URL to the PR/MR page |++### main_state values++These values describe relation to the default branch.++`"is_main"` `"would_conflict"` `"empty"` `"same_commit"` `"integrated"` `"diverged"` `"ahead"` `"behind"`++### integration_reason values++When `main_state == "integrated"`: `"ancestor"` `"trees_match"` `"no_added_changes"` `"merge_adds_nothing"`++### ci.status values++`"passed"` `"running"` `"failed"` `"conflicts"` `"no-ci"` `"error"`++Missing a field that would be generally useful? [Open an issue](https://github.com/max-sixty/worktrunk/issues).++## Command reference++wt list - List worktrees and their status++Usage: <b><span class=c>wt list</span></b> <span class=c>[OPTIONS]</span>+ <b><span class=c>wt list</span></b> <span class=c><COMMAND></span>++<b><span class=g>Commands:</span></b>+ <b><span class=c>statusline</span></b> Single-line status for shell prompts++<b><span class=g>Options:</span></b>+ <b><span class=c>--format</span></b><span class=c> <FORMAT></span>+ Output format (table, json)++ [default: table]++ <b><span class=c>--branches</span></b>+ Include branches without worktrees++ <b><span class=c>--remotes</span></b>+ Include remote branches++ <b><span class=c>--full</span></b>+ Include CI status and diff analysis (slower)++ <b><span class=c>--progressive</span></b>+ Show fast info immediately, update with slow info++ Displays local data (branches, paths, status) first, then updates with+ remote data (CI, upstream) as it arrives. Auto-enabled for TTY.++ <b><span class=c>-h</span></b>, <b><span class=c>--help</span></b>+ Print help (see a summary with '-h')++<b><span class=g>Global Options:</span></b>+ <b><span class=c>-C</span></b><span class=c> <path></span>+ Working directory for this command++ <b><span class=c>--config</span></b><span class=c> <path></span>+ User config file path++ <b><span class=c>-v</span></b>, <b><span class=c>--verbose</span></b>+ Show commands and debug infodiff --git a/.claude-plugin/skills/worktrunk/reference/llm-commits.md b/.claude-plugin/skills/worktrunk/reference/llm-commits.mdnew file mode 100644index 000000000..278d552c7--- /dev/null+++ b/.claude-plugin/skills/worktrunk/reference/llm-commits.md@@ -0,0 +1,169 @@+# LLM Commit Messages++Worktrunk generates commit messages by building a templated prompt and piping it to an external command. This integrates with `wt merge`, `wt step commit`, and `wt step squash`.++## Setup++### Install llm++[llm](https://llm.datasette.io/) from Simon Willison is recommended:++```bash+$ uv tool install -U llm+```++### Configure an API key++For Claude (recommended):++```bash+$ llm install llm-anthropic+$ llm keys set anthropic+```++For OpenAI:++```bash+$ llm keys set openai+```++### Add to user config++Create the config file if it doesn't exist:++```bash+$ wt config create+```++Then add the commit generation settings to `~/.config/worktrunk/config.toml`:++```toml+[commit-generation]+command = "llm"+args = ["-m", "claude-haiku-4.5"]+```++Or for OpenAI:++```toml+[commit-generation]+command = "llm"+args = ["-m", "gpt-5-nano"]+```++## How it works++When worktrunk needs a commit message, it builds a prompt from a template and pipes it to the configured LLM command. The default templates include the git diff and style guidance.++## Usage++These examples assume a feature worktree with changes to commit.++### wt merge++Squashes all changes (uncommitted + existing commits) into one commit with an LLM-generated message, then merges to the default branch:++```bash+$ wt merge+◎ Squashing 3 commits into a single commit (5 files, +48)...+◎ Generating squash commit message...+ feat(auth): Implement JWT authentication system+ ...+```++### wt step commit++Stages and commits with LLM-generated message:++```bash+$ wt step commit+```++### wt step squash++Squashes branch commits into one with LLM-generated message:++```bash+$ wt step squash+```++See [`wt merge`](https://worktrunk.dev/merge/) and [`wt step`](https://worktrunk.dev/step/) for full documentation.++## Prompt templates++Worktrunk uses [minijinja](https://docs.rs/minijinja/) templates (Jinja2-like syntax) to build prompts. There are sensible defaults, but templates are fully customizable.++### Template variables++All variables are available in both templates:++| Variable | Description |+|----------|-------------|+| `{{ git_diff }}` | The diff (staged changes or combined diff for squash) |+| `{{ branch }}` | Current branch name |+| `{{ recent_commits }}` | Recent commit subjects (for style reference) |+| `{{ repo }}` | Repository name |+| `{{ commits }}` | Commit messages being squashed (chronological order) |+| `{{ target_branch }}` | Branch being merged into |++### Custom templates++Override the defaults with inline templates or external files:++```toml+[commit-generation]+command = "llm"+args = ["-m", "claude-haiku-4.5"]++template = """+Write a commit message for this diff. One line, under 50 chars.++Branch: {{ branch }}+Diff:+{{ git_diff }}+"""++squash-template = """+Combine these {{ commits | length }} commits into one message:+{% for c in commits %}+- {{ c }}+{% endfor %}++Diff:+{{ git_diff }}+"""+```++### Template syntax++Templates use [minijinja](https://docs.rs/minijinja/latest/minijinja/syntax/index.html), which supports:++- **Variables**: `{{ branch }}`, `{{ repo | upper }}`+- **Filters**: `{{ commits | length }}`, `{{ repo | upper }}`+- **Conditionals**: `{% if recent_commits %}...{% endif %}`+- **Loops**: `{% for c in commits %}{{ c }}{% endfor %}`+- **Loop variables**: `{{ loop.index }}`, `{{ loop.length }}`+- **Whitespace control**: `{%- ... -%}` strips surrounding whitespace++See `wt config create --help` for the full default templates.++## Alternative tools++Any command that reads a prompt from stdin and outputs a commit message works:++```toml+# aichat+[commit-generation]+command = "aichat"+args = ["-m", "claude:claude-haiku-4.5"]++# Custom script+[commit-generation]+command = "./scripts/generate-commit.sh"+```++See [llm documentation](https://llm.datasette.io/) and [aichat](https://github.com/sigoden/aichat).++## Fallback behavior++When no LLM is configured, worktrunk generates deterministic messages based on changed filenames (e.g., "Changes to auth.rs & config.rs").diff --git a/.claude-plugin/skills/worktrunk/reference/merge.md b/.claude-plugin/skills/worktrunk/reference/merge.mdnew file mode 100644index 000000000..d7299a900--- /dev/null+++ b/.claude-plugin/skills/worktrunk/reference/merge.md@@ -0,0 +1,118 @@+# wt merge++Merge the current branch into the default branch — like clicking "Merge pull request" on GitHub.++## Examples++Merge to the default branch:++```bash+wt merge+```++Merge to a different branch:++```bash+wt merge develop+```++Keep the worktree after merging:++```bash+wt merge --no-remove+```++Preserve commit history (no squash):++```bash+wt merge --no-squash+```++Skip committing/squashing (rebase still runs unless --no-rebase):++```bash+wt merge --no-commit+```++## Pipeline++`wt merge` runs these steps:++1. **Squash** — Stages uncommitted changes, then combines all commits since target into one (like GitHub's "Squash and merge"). Use `--stage` to control what gets staged: `all` (default), `tracked`, or `none`. A backup ref is saved to `refs/wt-backup/<branch>`. With `--no-squash`, uncommitted changes become a separate commit and individual commits are preserved.+2. **Rebase** — Rebases onto target if behind. Skipped if already up-to-date. Conflicts abort immediately.+3. **Pre-merge hooks** — Hooks run after rebase, before merge. Failures abort. See [`wt hook`](https://worktrunk.dev/hook/).+4. **Merge** — Fast-forward merge to the target branch. Non-fast-forward merges are rejected.+5. **Pre-remove hooks** — Hooks run before removing worktree. Failures abort.+6. **Cleanup** — Removes the worktree and branch. Use `--no-remove` to keep the worktree. When already on the target branch or in the main worktree, the worktree is preserved.+7. **Post-merge hooks** — Hooks run after cleanup. Failures are logged but don't abort.++Use `--no-commit` to skip committing uncommitted changes and squashing; rebase still runs by default and can rewrite commits unless `--no-rebase` is passed. Useful after preparing commits manually with `wt step`. Requires a clean working tree.++## Local CI++For personal projects, pre-merge hooks open up the possibility of a workflow with much faster iteration — an order of magnitude more small changes instead of fewer large ones.++Historically, ensuring tests ran before merging was difficult to enforce locally. Remote CI was valuable for the process as much as the checks: it guaranteed validation happened. `wt merge` brings that guarantee local.++The full workflow: start an agent (one of many) on a task, work elsewhere, return when it's ready. Review the diff, run `wt merge`, move on. Pre-merge hooks validate before merging — if they pass, the branch goes to the default branch and the worktree cleans up.++```toml+[pre-merge]+test = "cargo test"+lint = "cargo clippy"+```++## Command reference++wt merge - Merge worktree into target branch++Squash & rebase, fast-forward target, remove the worktree.++Usage: <b><span class=c>wt merge</span></b> <span class=c>[OPTIONS]</span> <span class=c>[TARGET]</span>++<b><span class=g>Arguments:</span></b>+ <span class=c>[TARGET]</span>+ Target branch++ Defaults to default branch.++<b><span class=g>Options:</span></b>+ <b><span class=c>--no-squash</span></b>+ Skip commit squashing++ <b><span class=c>--no-commit</span></b>+ Skip commit and squash++ <b><span class=c>--no-rebase</span></b>+ Skip rebase (fail if not already rebased)++ <b><span class=c>--no-remove</span></b>+ Keep worktree after merge++ <b><span class=c>--no-verify</span></b>+ Skip hooks++ <b><span class=c>-y</span></b>, <b><span class=c>--yes</span></b>+ Skip approval prompts++ <b><span class=c>--stage</span></b><span class=c> <STAGE></span>+ What to stage before committing [default: all]++ Possible values:+ - <b><span class=c>all</span></b>: Stage everything: untracked files + unstaged tracked+ changes+ - <b><span class=c>tracked</span></b>: Stage tracked changes only (like <b>git add -u</b>)+ - <b><span class=c>none</span></b>: Stage nothing, commit only what's already in the index++ <b><span class=c>-h</span></b>, <b><span class=c>--help</span></b>+ Print help (see a summary with '-h')++<b><span class=g>Global Options:</span></b>+ <b><span class=c>-C</span></b><span class=c> <path></span>+ Working directory for this command++ <b><span class=c>--config</span></b><span class=c> <path></span>+ User config file path++ <b><span class=c>-v</span></b>, <b><span class=c>--verbose</span></b>+ Show commands and debug infodiff --git a/.claude-plugin/skills/worktrunk/reference/project-config.md b/.claude-plugin/skills/worktrunk/reference/project-config.mddeleted file mode 100644index 1a566543e..000000000--- a/.claude-plugin/skills/worktrunk/reference/project-config.md+++ /dev/null@@ -1,532 +0,0 @@-# Project Config Reference--Detailed guidance for configuring project-specific Worktrunk hooks at `.config/wt.toml`.--## Guiding Principle: Proactive and Validated--Unlike user config, project config can be created directly since:-- Changes are versioned in git (easily reversible)-- Benefits the entire team-- Standard practice for dev tooling--Always validate commands exist before adding them to config.--## New Project--When users say "set up some hooks for me", follow this discovery process:--### Step 1: Detect Project Type--Check for package manifests:-```bash-ls package.json Cargo.toml pyproject.toml pom.xml go.mod-```--### Step 2: Identify Available Commands--<example type="detecting-npm-scripts">--For npm projects, read `package.json`:-```bash-cat package.json | grep -A 20 '"scripts"'-```--Look for: `lint`, `test`, `typecheck`, `build`, `format`--</example>--<example type="detecting-cargo-commands">--For Rust projects, common commands:-- `cargo build`-- `cargo test`-- `cargo clippy`-- `cargo fmt --check`--</example>--### Step 3: Design Appropriate Hooks--Match hooks to project needs using this decision tree:--- **Dependency installation** (fast, must complete) → `post-create`-- **Tests/linting** (fast, must pass) → `pre-commit` or `pre-merge`-- **Long builds** (slow, optional) → `post-start`-- **Deployment** (after merge) → `post-merge`--### Step 4: Validate Commands Work--Before adding to config, check:-```bash-npm run lint # Check script exists-which cargo # Check tool exists-```--### Step 5: Create `.config/wt.toml`--<example type="npm-project-config">--Typical npm project:-```toml-# Install dependencies when creating new worktrees (blocking)-post-create = "npm install"--# Validate code quality before committing (blocking, fail-fast)-[pre-commit]-lint = "npm run lint"-typecheck = "npm run typecheck"--# Run tests before merging (blocking, fail-fast)-pre-merge = "npm test"-```--</example>--<example type="rust-project-config">--Typical Rust project:-```toml-# Build runs in background (slow)-post-start = "cargo build"--# Format and lint before committing (blocking, fail-fast)-[pre-commit]-format = "cargo fmt --check"-lint = "cargo clippy -- -D warnings"--# Run tests before merging (blocking, fail-fast)-pre-merge = "cargo test"-```--</example>--### Step 6: Add Comments Explaining Choices--Document why each hook exists:-```toml-# Dependencies must be installed before worktree is usable-post-create = "npm install"--# Enforce code quality standards (matches CI checks)-[pre-commit]-lint = "npm run lint"-typecheck = "npm run typecheck"-```--### Step 7: Suggest Testing--```bash-# Create a test worktree to verify hooks work-wt switch --create test-hooks-```--## Add Hook--When users want to add automation to an existing project:--### Step 1: Read Existing Config--```bash-cat .config/wt.toml-```--### Step 2: Determine Appropriate Hook Type--Ask: When should this run?-- Creating worktree (blocking) → `post-create`-- Creating worktree (background) → `post-start`-- Every switch operation → `post-switch`-- Before committing → `pre-commit`-- Before merging → `pre-merge`-- After merging → `post-merge`-- Before worktree removal → `pre-remove`--### Step 3: Handle Format Conversion if Needed--<example type="adding-to-single-command">--Current (single command):-```toml-post-create = "npm install"-```--Adding "npm run db:migrate" — convert to named table:-```toml-[post-create]-install = "npm install"-migrate = "npm run db:migrate"-```--</example>--<example type="adding-to-table">--Current (named table):-```toml-[pre-commit]-lint = "npm run lint"-```--Adding typecheck — just add another entry:-```toml-[pre-commit]-lint = "npm run lint"-typecheck = "npm run typecheck"-```--</example>--### Step 4: Update the File--Preserve existing structure and comments.--## Variables--All hooks support template variables for dynamic behavior.--### Basic Variables (All Hooks)--Available in all hook types:-- `{{ repo }}` - Repository directory name (e.g., "myproject")-- `{{ repo_path }}` - Absolute path to repository (e.g., "/path/to/myproject")-- `{{ branch }}` - Raw branch name (e.g., "feature/auth")-- `{{ worktree_name }}` - Worktree directory name (e.g., "myproject.feature-auth")-- `{{ worktree_path }}` - Absolute path to worktree (e.g., "/path/to/myproject.feature-auth")-- `{{ main_worktree_path }}` - Absolute path to main worktree (e.g., "/path/to/myproject")-- `{{ default_branch }}` - Default branch name (e.g., "main")-- `{{ commit }}` - Full HEAD commit SHA-- `{{ short_commit }}` - Short HEAD commit SHA (7 chars)-- `{{ remote }}` - Primary remote name (e.g., "origin")-- `{{ remote_url }}` - Remote URL (e.g., "[email protected]:user/repo.git")-- `{{ upstream }}` - Upstream tracking branch (e.g., "origin/feature")--### Filters--- `{{ branch | sanitize }}` - Replace `/` and `\` with `-` (e.g., "feature-auth")-- `{{ branch | hash_port }}` - Hash string to deterministic port (10000-19999)--Example:-```toml-[post-start]-dev = "npm run dev --port {{ branch | hash_port }}"-cache = "ln -sf {{ repo_path }}/node_modules.{{ branch | sanitize }} node_modules"-```--<example type="basic-variables">--```toml-post-create = "echo 'Working on {{ branch }} in {{ repo }}'"-```--</example>--### Merge Variables (Merge Hooks Only)--Available in: `pre-commit`, `pre-merge`, `post-merge`--Additional variable:-- `{{ target }}` - Target branch for merge (e.g., "main")--<example type="conditional-with-variables">--Run different tests based on target branch:-```toml-pre-merge = """-if [ "{{ target }}" = "main" ]; then- npm run test:full-else- npm run test:quick-fi-"""-```--</example>--## Formats--All hooks support two command formats.--### Single Command (String)--```toml-post-create = "npm install"-```--### Multiple Commands (Named Table)--```toml-[post-create]-dependencies = "npm install"-database = "npm run db:migrate"-services = "docker-compose up -d"-```--Behavior:-- `post-create`: Sequential-- `post-start`: Parallel-- `post-switch`: Parallel-- `pre-commit`: Sequential-- `pre-merge`: Sequential-- `post-merge`: Sequential-- `pre-remove`: Sequential--Named commands appear in output with their labels, which helps identify which command succeeded or failed.--## Hook Types--Seven hook types with different timing and behavior:--### post-create--**When**: After creating new worktree (blocking, before user switches)-**Blocking**: Yes (user waits)-**Fail-fast**: No (shows error but continues)-**Execution**: Sequential--**Use for**:-- Installing dependencies (npm install, cargo build)-- Database migrations-- Any setup that must complete before work begins--<example type="post-create">--```toml-[post-create]-install = "npm install"-migrate = "npm run db:migrate"-```--</example>--### post-start--**When**: After creating new worktree (background, after user switches)-**Blocking**: No (runs in background)-**Fail-fast**: No-**Execution**: Parallel--**Use for**:-- Long builds-- Cache warming-- Background sync--<example type="post-start">--```toml-[post-start]-build = "npm run build"-services = "docker-compose up -d"-```--</example>--### post-switch--**When**: After every switch operation (background)-**Blocking**: No (runs in background)-**Fail-fast**: No-**Execution**: Parallel--**Use for**:-- Renaming terminal tabs-- Updating tmux window names-- IDE notifications--<example type="post-switch">--```toml-post-switch = "echo 'Switched to {{ branch }}'"-```--</example>--### pre-commit--**When**: Before committing during merge-**Blocking**: Yes-**Fail-fast**: Yes (any failure aborts commit)-**Execution**: Sequential--**Use for**:-- Linting-- Formatting checks-- Type checking--<example type="pre-commit">--```toml-[pre-commit]-lint = "npm run lint"-typecheck = "npm run typecheck"-```--</example>--### pre-merge--**When**: Before merging to target branch-**Blocking**: Yes-**Fail-fast**: Yes (any failure aborts merge)-**Execution**: Sequential--**Use for**:-- Running tests-- Build verification-- Security scans--<example type="pre-merge">--```toml-pre-merge = "npm test"-```--</example>--### post-merge--**When**: After successful merge, before cleanup-**Blocking**: Yes-**Fail-fast**: No (merge already complete)-**Execution**: Sequential--**Use for**:-- Deployment-- Notifications-- Cache invalidation--<example type="post-merge">--```toml-post-merge = "npm run deploy"-```--</example>--### pre-remove--**When**: Before worktree removal during `wt remove`-**Blocking**: Yes-**Fail-fast**: Yes (any failure aborts removal)-**Execution**: Sequential--**Use for**:-- Cleanup tasks (temp files, caches)-- Saving state-- Notifying external systems-- Stopping services--<example type="pre-remove">--```toml-[pre-remove]-cleanup = "rm -rf /tmp/cache/{{ branch }}"-```--</example>--See `hook-types-reference.md` for complete behavioral details.--## Validation & Safety--### Before Adding Commands--Check commands are safe and exist:--<example type="validation-checks">--```bash-# Verify command exists-which npm-which cargo--# For npm, verify script exists-npm run lint --dry-run--# For shell commands, check syntax-bash -n -c "if [ true ]; then echo ok; fi"-```--</example>--### Dangerous Patterns--Warn before creating hooks with:-- Destructive commands: `rm -rf`, `DROP TABLE`-- External dependencies: `curl http://...`-- Privilege escalation: `sudo`--Reject obviously dangerous commands:-- `rm -rf /`-- Fork bombs-- Arbitrary code execution--## Troubleshooting--### Hook Not Running--Check sequence:-1. Verify `.config/wt.toml` exists: `ls -la .config/wt.toml`-2. Check TOML syntax: `cat .config/wt.toml`-3. Verify hook name spelling matches one of the seven types-4. Test command manually in terminal--### Hook Failing--Debug steps:-1. Run command manually in worktree-2. Check for missing dependencies (npm packages, system tools)-3. Verify template variables expand correctly-4. For background hooks, check `.git/wt-logs/` for output--### Slow Blocking Hooks--Move long-running commands to background:--<example type="blocking-to-background">--Before (blocks for minutes):-```toml-post-create = "npm run build"-```--After (runs in background):-```toml-post-create = "npm install" # Fast, blocking-post-start = "npm run build" # Slow, background-```--</example>--## Key Commands--```bash-wt config show # View project config-cat .config/wt.toml # Read config directly-wt switch --create test-hooks # Test hooks work-```--## Dev Server URL--Add a URL column to `wt list` showing dev server links per worktree:--```toml-[list]-url = "http://localhost:{{ branch | hash_port }}"-```--URLs are dimmed when the port isn't listening. The template supports all variables plus filters.--Example with subdomain:-```toml-[list]-url = "http://{{ branch }}.lvh.me:3000"-```--## Config File Location--- **Always at**: `<repo>/.config/wt.toml` (checked into git)-- **Background logs**: `.git/wt-logs/` (in git directory, not tracked)--## Example Config--See `dev/wt.example.toml` in the worktrunk repository for a complete annotated example.diff --git a/.claude-plugin/skills/worktrunk/reference/remove.md b/.claude-plugin/skills/worktrunk/reference/remove.mdnew file mode 100644index 000000000..079d3704a--- /dev/null+++ b/.claude-plugin/skills/worktrunk/reference/remove.md@@ -0,0 +1,101 @@+# wt remove++Removes worktrees and their branches (if merged), returning to the main worktree. Defaults to removing the current worktree.++## Examples++Remove current worktree:++```bash+wt remove+```++Remove specific worktrees:++```bash+wt remove feature-branch+wt remove old-feature another-branch+```++Keep the branch:++```bash+wt remove --no-delete-branch feature-branch+```++Force-delete an unmerged branch:++```bash+wt remove -D experimental+```++## Branch cleanup++By default, branches are deleted when merging them would add nothing. This works with squash-merge and rebase workflows where commit history differs but file changes match.++Worktrunk checks five conditions (in order of cost):++1. **Same commit** — Branch HEAD equals the default branch. Shows `_` in `wt list`.+2. **Ancestor** — Branch is in target's history (fast-forward or rebase case). Shows `⊂`.+3. **No added changes** — Three-dot diff (`target...branch`) is empty. Shows `⊂`.+4. **Trees match** — Branch tree SHA equals target tree SHA. Shows `⊂`.+5. **Merge adds nothing** — Simulated merge produces the same tree as target. Handles squash-merged branches where target has advanced. Shows `⊂`.++The "same commit" check uses the local default branch; for other checks, **target** means the default branch, or its upstream (e.g., `origin/main`) when strictly ahead.++Branches showing `_` or `⊂` are dimmed as safe to delete.++Use `-D` to force-delete branches with unmerged changes. Use `--no-delete-branch` to keep the branch regardless of status.++## Background removal++Removal runs in the background by default (returns immediately). Logs are written to `.git/wt-logs/{branch}-remove.log`. Use `--no-background` to run in the foreground.++## Shortcuts++`@` (current), `-` (previous), `^` (default branch). See [`wt switch`](https://worktrunk.dev/switch/#shortcuts).++## Command reference++wt remove - Remove worktree; delete branch if merged++Usage: <b><span class=c>wt remove</span></b> <span class=c>[OPTIONS]</span> <span class=c>[BRANCHES]...</span>++<b><span class=g>Arguments:</span></b>+ <span class=c>[BRANCHES]...</span>+ Branch name [default: current]++<b><span class=g>Options:</span></b>+ <b><span class=c>--no-delete-branch</span></b>+ Keep branch after removal++ <b><span class=c>-D</span></b>, <b><span class=c>--force-delete</span></b>+ Delete unmerged branches++ <b><span class=c>--no-background</span></b>+ Run removal in foreground++ <b><span class=c>--no-verify</span></b>+ Skip hooks++ <b><span class=c>-y</span></b>, <b><span class=c>--yes</span></b>+ Skip approval prompts++ <b><span class=c>-f</span></b>, <b><span class=c>--force</span></b>+ Force worktree removal++ Remove worktrees even if they contain untracked files (like build+ artifacts). Without this flag, removal fails if untracked files exist.++ <b><span class=c>-h</span></b>, <b><span class=c>--help</span></b>+ Print help (see a summary with '-h')++<b><span class=g>Global Options:</span></b>+ <b><span class=c>-C</span></b><span class=c> <path></span>+ Working directory for this command++ <b><span class=c>--config</span></b><span class=c> <path></span>+ User config file path++ <b><span class=c>-v</span></b>, <b><span class=c>--verbose</span></b>+ Show commands and debug infodiff --git a/.claude-plugin/skills/worktrunk/reference/select.md b/.claude-plugin/skills/worktrunk/reference/select.mdnew file mode 100644index 000000000..99d25cf4f--- /dev/null+++ b/.claude-plugin/skills/worktrunk/reference/select.md@@ -0,0 +1,69 @@+# wt select++Interactive worktree picker with live preview. Navigate worktrees with keyboard shortcuts and press Enter to switch.++## Examples++Open the selector:++```bash+wt select+```++## Preview tabs++Toggle between views with number keys:++1. **HEAD±** — Diff of uncommitted changes+2. **log** — Recent commits; commits already on the default branch have dimmed hashes+3. **main…±** — Diff of changes since the merge-base with the default branch+4. **remote⇅** — Diff vs upstream tracking branch (ahead/behind)++## Keybindings++| Key | Action |+|-----|--------|+| `↑`/`↓` | Navigate worktree list |+| `Enter` | Switch to selected worktree |+| `Esc` | Cancel |+| (type) | Filter worktrees |+| `1`/`2`/`3`/`4` | Switch preview tab |+| `Alt-p` | Toggle preview panel |+| `Ctrl-u`/`Ctrl-d` | Scroll preview up/down |++Branches without worktrees are included — selecting one creates a worktree. (`wt list` requires `--branches` to show them.)++## Configuration++### Pager++The preview panel pipes diff output through git's pager (typically `less` or `delta`). Override pager behavior in user config:++```toml+[select]+pager = "delta --paging=never"+```++This is useful when the default pager doesn't render correctly in the embedded preview panel.++## Command reference++wt select - Interactive worktree selector++Browse and switch worktrees with live preview.++Usage: <b><span class=c>wt select</span></b> <span class=c>[OPTIONS]</span>++<b><span class=g>Options:</span></b>+ <b><span class=c>-h</span></b>, <b><span class=c>--help</span></b>+ Print help (see a summary with '-h')++<b><span class=g>Global Options:</span></b>+ <b><span class=c>-C</span></b><span class=c> <path></span>+ Working directory for this command++ <b><span class=c>--config</span></b><span class=c> <path></span>+ User config file path++ <b><span class=c>-v</span></b>, <b><span class=c>--verbose</span></b>+ Show commands and debug infodiff --git a/.claude-plugin/skills/worktrunk/reference/step.md b/.claude-plugin/skills/worktrunk/reference/step.mdnew file mode 100644index 000000000..036493559--- /dev/null+++ b/.claude-plugin/skills/worktrunk/reference/step.md@@ -0,0 +1,172 @@+# wt step++Run individual git workflow operations: commits, squashes, rebases, and pushes.++## Examples++Commit with LLM-generated message:++```bash+wt step commit+```++Manual merge workflow with review between steps:++```bash+wt step commit+wt step squash+# Review the squashed commit+wt step rebase+wt step push+```++## Operations++- `commit` — Stage and commit with [LLM-generated message](https://worktrunk.dev/llm-commits/)+- `squash` — Squash all branch commits into one with [LLM-generated message](https://worktrunk.dev/llm-commits/)+- `rebase` — Rebase onto target branch+- `push` — Fast-forward target to current branch+- `for-each` — [experimental] Run a command in every worktree++## Options++### `--stage`++Controls what to stage before committing. Available for `commit` and `squash`:++| Value | Behavior |+|-------|----------|+| `all` | Stage all changes including untracked files (default) |+| `tracked` | Stage only modified tracked files |+| `none` | Don't stage anything, commit only what's already staged |++```bash+wt step commit --stage=tracked+wt step squash --stage=none+```++Configure the default in user config:++```toml+[commit]+stage = "tracked"+```++### `--show-prompt`++Output the rendered LLM prompt to stdout without running the command. Useful for inspecting prompt templates or piping to other tools:++```bash+# Inspect the rendered prompt+wt step commit --show-prompt | less++# Pipe to a different LLM+wt step commit --show-prompt | llm -m gpt-5-nano+```++## Command reference++wt step - Run individual operations++Usage: <b><span class=c>wt step</span></b> <span class=c>[OPTIONS]</span> <span class=c><COMMAND></span>++<b><span class=g>Commands:</span></b>+ <b><span class=c>commit</span></b> Commit changes with LLM commit message+ <b><span class=c>squash</span></b> Squash commits since branching+ <b><span class=c>push</span></b> Fast-forward target to current branch+ <b><span class=c>rebase</span></b> Rebase onto target+ <b><span class=c>for-each</span></b> [experimental] Run command in each worktree++<b><span class=g>Options:</span></b>+ <b><span class=c>-h</span></b>, <b><span class=c>--help</span></b>+ Print help (see a summary with '-h')++<b><span class=g>Global Options:</span></b>+ <b><span class=c>-C</span></b><span class=c> <path></span>+ Working directory for this command++ <b><span class=c>--config</span></b><span class=c> <path></span>+ User config file path++ <b><span class=c>-v</span></b>, <b><span class=c>--verbose</span></b>+ Show commands and debug info++## wt step for-each++Executes a command sequentially in every worktree with real-time output. Continues on failure and shows a summary at the end.++Context JSON is piped to stdin for scripts that need structured data.++### Template variables++All variables are shell-escaped:++| Variable | Description |+|----------|-------------|+| `{{ branch }}` | Branch name (raw, e.g., `feature/auth`) |+| `{{ branch \| sanitize }}` | Branch name with `/` and `\` replaced by `-` |+| `{{ repo }}` | Repository directory name (e.g., `myproject`) |+| `{{ repo_path }}` | Absolute path to repository root |+| `{{ worktree_name }}` | Worktree directory name |+| `{{ worktree_path }}` | Absolute path to current worktree |+| `{{ main_worktree_path }}` | Default branch worktree path |+| `{{ commit }}` | Current HEAD commit SHA (full) |+| `{{ short_commit }}` | Current HEAD commit SHA (7 chars) |+| `{{ default_branch }}` | Default branch name (e.g., "main") |+| `{{ remote }}` | Primary remote name (e.g., "origin") |+| `{{ remote_url }}` | Primary remote URL |+| `{{ upstream }}` | Upstream tracking branch, if configured |++**Deprecated:** `repo_root` (use `repo_path`), `worktree` (use `worktree_path`), `main_worktree` (use `repo`).++### Examples++Check status across all worktrees:++```bash+wt step for-each -- git status --short+```++Run npm install in all worktrees:++```bash+wt step for-each -- npm install+```++Use branch name in command:++```bash+wt step for-each -- "echo Branch: {{ branch }}"+```++Pull updates in worktrees with upstreams (skips others):++```bash+git fetch --prune && wt step for-each -- '[ "$(git rev-parse @{u} 2>/dev/null)" ] || exit 0; git pull --autostash'+```++Note: This command is experimental and may change in future versions.++### Command reference++wt step for-each - [experimental] Run command in each worktree++Usage: <b><span class=c>wt step for-each</span></b> <span class=c>[OPTIONS]</span> <b><span class=c>--</span></b> <span class=c><ARGS>...</span>++<b><span class=g>Arguments:</span></b>+ <span class=c><ARGS>...</span>+ Command template (see --help for all variables)++<b><span class=g>Options:</span></b>+ <b><span class=c>-h</span></b>, <b><span class=c>--help</span></b>+ Print help (see a summary with '-h')++<b><span class=g>Global Options:</span></b>+ <b><span class=c>-C</span></b><span class=c> <path></span>+ Working directory for this command++ <b><span class=c>--config</span></b><span class=c> <path></span>+ User config file path++ <b><span class=c>-v</span></b>, <b><span class=c>--verbose</span></b>+ Show commands and debug infodiff --git a/.claude-plugin/skills/worktrunk/reference/switch.md b/.claude-plugin/skills/worktrunk/reference/switch.mdnew file mode 100644index 000000000..dfffba366--- /dev/null+++ b/.claude-plugin/skills/worktrunk/reference/switch.md@@ -0,0 +1,123 @@+# wt switch++Change directory to a worktree, creating one if needed.++Worktrees are addressed by branch name; paths are computed from a configurable template. Unlike `git switch`, this navigates between worktrees rather than changing branches in place.++## Examples++```bash+wt switch feature-auth # Switch to worktree+wt switch - # Previous worktree (like cd -)+wt switch --create new-feature # Create new branch and worktree+wt switch --create hotfix --base production+```++## Creating a branch++The `--create` flag creates a new branch from the `--base` branch (defaults to default branch). Without `--create`, the branch must already exist.++## Creating worktrees++If the branch already has a worktree, `wt switch` changes directories to it. Otherwise, it creates one, running [hooks](https://worktrunk.dev/hook/).++When creating a worktree, worktrunk:++1. Creates worktree at configured path+2. Switches to new directory+3. Runs [post-create hooks](https://worktrunk.dev/hook/#post-create) (blocking)+4. Spawns [post-start hooks](https://worktrunk.dev/hook/#post-start) (background)++```bash+wt switch feature # Existing branch → creates worktree+wt switch --create feature # New branch and worktree+wt switch --create fix --base release # New branch from release+wt switch --create temp --no-verify # Skip hooks+```++## Shortcuts++| Shortcut | Meaning |+|----------|---------|+| `^` | Default branch (main/master) |+| `@` | Current branch/worktree |+| `-` | Previous worktree (like `cd -`) |++```bash+wt switch - # Back to previous+wt switch ^ # Default branch worktree+wt switch --create fix --base=@ # Branch from current HEAD+```++## When wt switch fails++- **Branch doesn't exist** — Use `--create`, or check `wt list --branches`+- **Path occupied** — Another worktree is at the target path; switch to it or remove it+- **Stale directory** — Use `--clobber` to remove a non-worktree directory at the target path++To change which branch a worktree is on, use `git switch` inside that worktree.++## Command reference++wt switch - Switch to a worktree++Usage: <b><span class=c>wt switch</span></b> <span class=c>[OPTIONS]</span> <span class=c><BRANCH></span> <b><span class=c>[--</span></b> <span class=c><EXECUTE_ARGS>...</span><b><span class=c>]</span></b>++<b><span class=g>Arguments:</span></b>+ <span class=c><BRANCH></span>+ Branch name++ Shortcuts: '^' (default branch), '-' (previous), '@' (current)++ <span class=c>[EXECUTE_ARGS]...</span>+ Additional arguments for --execute command (after --)++ Arguments after <b>--</b> are appended to the execute command. Each argument+ is POSIX shell-escaped before appending.++<b><span class=g>Options:</span></b>+ <b><span class=c>-c</span></b>, <b><span class=c>--create</span></b>+ Create a new branch++ <b><span class=c>-b</span></b>, <b><span class=c>--base</span></b><span class=c> <BASE></span>+ Base branch++ Defaults to default branch.++ <b><span class=c>-x</span></b>, <b><span class=c>--execute</span></b><span class=c> <EXECUTE></span>+ Command to run after switch++ Replaces the wt process with the command after switching, giving it+ full terminal control. Useful for launching editors, AI agents, or+ other interactive tools.++ Especially useful with shell aliases:++ <b>alias wsc='wt switch --create -x claude'</b>+ <b>wsc feature-branch -- 'Fix GH #322'</b>++ Then <b>wsc feature-branch</b> creates the worktree and launches Claude Code.+ Arguments after <b>--</b> are passed to the command, so <b>wsc feature -- 'Fix</b>+ GH #322' runs <b>claude 'Fix GH #322'</b>, starting Claude with a prompt.++ <b><span class=c>-y</span></b>, <b><span class=c>--yes</span></b>+ Skip approval prompts++ <b><span class=c>--clobber</span></b>+ Remove stale paths at target++ <b><span class=c>--no-verify</span></b>+ Skip hooks++ <b><span class=c>-h</span></b>, <b><span class=c>--help</span></b>+ Print help (see a summary with '-h')++<b><span class=g>Global Options:</span></b>+ <b><span class=c>-C</span></b><span class=c> <path></span>+ Working directory for this command++ <b><span class=c>--config</span></b><span class=c> <path></span>+ User config file path++ <b><span class=c>-v</span></b>, <b><span class=c>--verbose</span></b>+ Show commands and debug infodiff --git a/.claude-plugin/skills/worktrunk/reference/tips-patterns.md b/.claude-plugin/skills/worktrunk/reference/tips-patterns.mdnew file mode 100644index 000000000..0df7c7e57--- /dev/null+++ b/.claude-plugin/skills/worktrunk/reference/tips-patterns.md@@ -0,0 +1,218 @@+# Tips & Patterns++Practical recipes for common Worktrunk workflows.++## Alias for new worktree + agent++Create a worktree and launch Claude in one command:++```bash+alias wsc='wt switch --create --execute=claude'+wsc new-feature # Creates worktree, runs hooks, launches Claude+wsc feature -- 'Fix GH #322' # Runs `claude 'Fix GH #322'`+```++## Eliminate cold starts++`post-create` hooks install deps and copy caches. On macOS, use copy-on-write for instant cache cloning:++```toml+[post-create]+"cache" = "cp -c -r ../.cache .cache" # APFS clones (instant, no disk space)+"install" = "npm ci"+```++See [Designing effective hooks](https://worktrunk.dev/hook/#designing-effective-hooks) for cross-platform CoW commands, language-specific tips, and more patterns.++## Dev server per worktree++Each worktree runs its own dev server on a deterministic port. The `hash_port` filter generates a stable port (10000-19999) from the branch name:++```toml+# .config/wt.toml+[post-start]+server = "npm run dev -- --port {{ branch | hash_port }}"++[list]+url = "http://localhost:{{ branch | hash_port }}"++[pre-remove]+server = "lsof -ti :{{ branch | hash_port }} | xargs kill 2>/dev/null || true"+```++The URL column in `wt list` shows each worktree's dev server:++<span class="prompt">$</span> <span class="cmd">wt list</span>+ <b>Branch</b> <b>Status</b> <b>HEAD±</b> <b>main↕</b> <b>Remote⇅</b> <b>URL</b> <b>Commit</b> <b>Age</b>+@ main <span class=c>?</span> <span class=d>^</span><span class=d>⇅</span> <span class=g>⇡1</span> <span class=d><span class=r>⇣1</span></span> <span class=d>http://localhost:12107</span> <span class=d>6088adb3</span> <span class=d>4d</span>++ feature-api <span class=c>+</span> <span class=d>↕</span><span class=d>⇡</span> <span class=g>+54</span> <span class=r>-5</span> <span class=g>↑4</span> <span class=d><span class=r>↓1</span></span> <span class=g>⇡3</span> <span class=d>http://localhost:10703</span> <span class=d>ec97decc</span> <span class=d>30m</span>++ fix-auth <span class=d>↕</span><span class=d>|</span> <span class=g>↑2</span> <span class=d><span class=r>↓1</span></span> <span class=d>|</span> <span class=d>http://localhost:16460</span> <span class=d>127407de</span> <span class=d>5h</span>++<span class=d>○</span> <span class=d>Showing 3 worktrees, 2 with changes, 2 ahead, 2 columns hidden</span>++Ports are deterministic — `fix-auth` always gets port 16460, regardless of which machine or when. The URL dims if the server isn't running.++For subdomain-based routing (useful for cookies and CORS), use `lvh.me` which resolves to 127.0.0.1:++```toml+[post-start]+server = "npm run dev -- --host {{ branch | sanitize }}.lvh.me --port {{ branch | hash_port }}"+```++## Database per worktree++Each worktree can have its own isolated database. Docker containers get unique names and ports:++```toml+[post-start]+db = """+docker run -d --rm \+ --name {{ repo }}-{{ branch | sanitize }}-postgres \+ -p {{ ('db-' ~ branch) | hash_port }}:5432 \+ -e POSTGRES_DB={{ repo }} \+ -e POSTGRES_PASSWORD=dev \+ postgres:16+"""++[pre-remove]+db-stop = "docker stop {{ repo }}-{{ branch | sanitize }}-postgres 2>/dev/null || true"+```++The `('db-' ~ branch)` concatenation hashes differently than plain `branch`, so database and dev server ports don't collide.+Jinja2's operator precedence has pipe `|` with higher precedence than concatenation `~`, meaning expressions need parentheses to filter concatenated values.++Generate `.env.local` with the correct `DATABASE_URL` using a `post-create` hook:++```toml+[post-create]+env = """+cat > .env.local << EOF+DATABASE_URL=postgres://postgres:dev@localhost:{{ ('db-' ~ branch) | hash_port }}/{{ repo }}+DEV_PORT={{ branch | hash_port }}+EOF+"""+```++## Local CI gate++`pre-merge` hooks run before merging. Failures abort the merge:++```toml+[pre-merge]+"lint" = "uv run ruff check"+"test" = "uv run pytest"+```++This catches issues locally before pushing — like running CI locally.++## Track agent status++Custom emoji markers show agent state in `wt list`. The Claude Code plugin sets these automatically:++```++ feature-api ↑ 🤖 ↑1 ./repo.feature-api++ review-ui ? ↑ 💬 ↑1 ./repo.review-ui+```++- `🤖` — Claude is working+- `💬` — Claude is waiting for input++Set status manually for any workflow:++```bash+wt config state marker set "🚧" # Current branch+wt config state marker set "✅" --branch feature # Specific branch+git config worktrunk.state.feature.marker '{"marker":"💬","set_at":0}' # Direct+```++See [Claude Code Integration](https://worktrunk.dev/claude-code/#installation) for plugin installation.++## Monitor CI across branches++```bash+wt list --full --branches+```++Shows PR/CI status for all branches, including those without worktrees. CI indicators are clickable links to the PR page.++## JSON API++```bash+wt list --format=json+```++Structured output for dashboards, statuslines, and scripts. See [`wt list`](https://worktrunk.dev/list/) for query examples.++## Reuse `default-branch`++Worktrunk maintains useful state. Default branch [detection](https://worktrunk.dev/config/#wt-config-state-default-branch), for instance, means scripts work on any repo — no need to hardcode `main` or `master`:++```bash+git rebase $(wt config state default-branch)+```++## Task runners in hooks++Reference Taskfile/Justfile/Makefile in hooks:++```toml+[post-create]+"setup" = "task install"++[pre-merge]+"validate" = "just test lint"+```++## Shortcuts++Special arguments work across all commands—see [`wt switch`](https://worktrunk.dev/switch/#shortcuts) for the full list.++```bash+wt switch --create hotfix --base=@ # Branch from current HEAD+wt switch - # Switch to previous worktree+wt remove @ # Remove current worktree+```++## Stacked branches++Branch from current HEAD instead of the default branch:++```bash+wt switch --create feature-part2 --base=@+```++Creates a worktree that builds on the current branch's changes.++## Bare repository layout++An alternative to the default sibling layout (`myproject.feature/`) uses a bare repository with worktrees as subdirectories:++```+myproject/+├── .git/ # bare repository+├── main/ # main branch+├── feature/ # feature branch+└── bugfix/ # bugfix branch+```++Setup:++```bash+git clone --bare <url> myproject/.git+cd myproject+```++Configure worktrunk to create worktrees as subdirectories:++```toml+# ~/.config/worktrunk/config.toml+worktree-path = "{{ branch | sanitize }}"+```++Create the first worktree:++```bash+wt switch --create main+```++Now `wt switch --create feature` creates `myproject/feature/`.diff --git a/.claude-plugin/skills/worktrunk/reference/troubleshooting.md b/.claude-plugin/skills/worktrunk/reference/troubleshooting.mdnew file mode 100644index 000000000..de8dbfddb--- /dev/null+++ b/.claude-plugin/skills/worktrunk/reference/troubleshooting.md@@ -0,0 +1,72 @@+# Troubleshooting++Claude-specific troubleshooting guidance for common worktrunk issues.++## LLM Commit Messages++### LLM command not found++```bash+$ which llm+```++If empty, the tool isn't installed or not in PATH. Install with `uv tool install -U llm`.++### LLM returns an error++Test the command directly:++```bash+$ echo "say hello" | llm+```++Common issues:+- **API key not set**: Run `llm keys set anthropic` (or `openai`)+- **Model not available**: Check model name with `llm models`+- **Network issues**: Check internet connectivity++### Config not loading++1. View config path: `wt config show` shows location+2. Verify file exists: `ls -la ~/.config/worktrunk/config.toml`+3. Check TOML syntax: `cat ~/.config/worktrunk/config.toml`+4. Look for validation errors (path must be relative, not absolute)++### Template conflicts++Check for mutually exclusive options:+- `template` and `template-file` cannot both be set+- `squash-template` and `squash-template-file` cannot both be set++If a template file is used, verify it exists at the specified path.++## Hooks++### Hook not running++Check sequence:+1. Verify `.config/wt.toml` exists: `ls -la .config/wt.toml`+2. Check TOML syntax (use `wt hook show` to see parsed config)+3. Verify hook type spelling matches one of the seven types+4. Test command manually in the worktree++### Hook failing++Debug steps:+1. Run the command manually in the worktree to see errors+2. Check for missing dependencies (npm packages, system tools)+3. Verify template variables expand correctly (`wt hook show --verbose`)+4. For background hooks, check `.git/wt-logs/` for output++### Slow blocking hooks++Move long-running commands to background:++```toml+# Before — blocks for minutes+post-create = "npm run build"++# After — fast setup, build in background+post-create = "npm install"+post-start = "npm run build"+```diff --git a/.claude-plugin/skills/worktrunk/reference/user-config.md b/.claude-plugin/skills/worktrunk/reference/user-config.mddeleted file mode 100644index 31c599818..000000000--- a/.claude-plugin/skills/worktrunk/reference/user-config.md+++ /dev/null@@ -1,383 +0,0 @@-# User Config Reference--Detailed guidance for configuring personal Worktrunk settings at `~/.config/worktrunk/config.toml`.--## Guiding Principle: Propose, Never Impose--Never edit user config files without explicit consent. Always:-1. Show the proposed change-2. Explain what it does-3. Wait for approval-4. Then apply--Never install tools (llm, aichat) automatically. Provide installation commands for users to run themselves.--## LLM Setup--Most users want this for LLM commit messages. Follow this sequence:--### Step 1: Check if LLM Tool Exists--```bash-which llm-# or-which aichat-```--### Step 2: Guide Installation (Don't Run It)--<example type="llm-install-guide">--For `llm` (Python-based, recommended):-```bash-uv tool install -U llm-```--For `aichat` (Rust-based, 20+ providers):-```bash-# See: https://github.com/sigoden/aichat-```--</example>--### Step 3: Guide API Key Setup (Don't Run It)--<example type="api-key-setup">--For Claude (via llm):-```bash-llm install llm-anthropic-llm keys set anthropic-# User pastes API key from: https://console.anthropic.com/settings/keys-llm models default claude-haiku-4.5-```--For OpenAI (via llm):-```bash-llm keys set openai-# User pastes API key from: https://platform.openai.com/api-keys-```--</example>--### Step 4: Propose Config Change--Show what will be added:--<example type="config-proposal">--```toml-[commit-generation]-command = "llm"-```--Ask: "Should I add this to your config at `~/.config/worktrunk/config.toml`?"--</example>--### Step 5: After Approval, Check if Config Exists--```bash-wt config show-```--If not: guide through `wt config create` first.--### Step 6: Apply the Change--Read existing config, add the `[commit-generation]` section, preserve existing structure and comments.--### Step 7: Suggest Testing--```bash-# Test LLM works-llm "say hello"--# Test with worktrunk (in a repo with uncommitted changes)-wt merge-```--## Worktree Paths--Users may want different worktree organization patterns.--### Common Patterns--<example type="worktree-patterns">--Default (parent siblings):-```toml-worktree-path = "../{{ repo }}.{{ branch | sanitize }}"-```-Result: `~/code/myproject` → `~/code/myproject.feature-auth`--Inside repo:-```toml-worktree-path = ".worktrees/{{ branch | sanitize }}"-```-Result: `~/code/myproject/.worktrees/feature-auth`--</example>--### Workflow--1. Show current setting from `wt config show`-2. Explain the new pattern with concrete example-3. Warn: "Existing worktrees won't move automatically"-4. Propose change-5. After approval, update config--### Available Variables--- `{{ repo }}` - Repository directory name-- `{{ branch }}` - Raw branch name (e.g., `feature/auth`)--### Filters--- `{{ branch | sanitize }}` - Replace `/` and `\` with `-` (e.g., `feature-auth`)-- `{{ branch | hash_port }}` - Hash string to deterministic port (10000-19999)--### Validation Rules--- Path must be relative, not absolute-- Path cannot be empty--## Templates--Users may want to customize the prompt sent to their LLM.--### Two Options--<example type="template-options">--Inline template:-```toml-[commit-generation]-command = "llm"-template = """-Write a commit message <50 chars.-Focus on WHAT changed.--Changes:-{{ git_diff }}-"""-```--Template file:-```toml-[commit-generation]-command = "llm"-template-file = "~/.config/worktrunk/commit-template.txt"-```--</example>--### Available Variables--**Commit message templates**:-- `{{ git_diff }}` - Staged changes-- `{{ branch }}` - Current branch-- `{{ recent_commits }}` - Recent commit titles-- `{{ repo }}` - Repository directory name--**Squash commit templates**:-- `{{ commits }}` - List of commits being squashed-- `{{ target_branch }}` - Target branch for merge-- `{{ branch }}` - Current branch-- `{{ repo }}` - Repository directory name--### Validation Rules--- `template` and `template-file` are mutually exclusive-- `squash-template` and `squash-template-file` are mutually exclusive-- Template files support tilde expansion: `~/...`--### Workflow--1. Understand what the user wants different-2. Propose template (inline or file-based)-3. Show available variables-4. After approval, update config--## Configuration Structure--Complete reference:--```toml-# Worktree Path Template-worktree-path = "../{{ repo }}.{{ branch | sanitize }}"--# LLM Commit Generation (Optional)-[commit-generation]-command = "llm"-args = ["-m", "claude-haiku-4.5"]--# Command Settings (configure default flags)-[list]-full = true # --full-branches = true # --branches-remotes = true # --remotes--[commit]-stage = "all" # "all", "tracked", or "none"--[merge]-squash = true # Squash commits (default: true)-commit = true # Commit uncommitted changes (default: true)-rebase = true # Rebase onto target (default: true)-remove = true # Remove worktree after merge (default: true)-verify = true # Run hooks (default: true)--# User Hooks (run for all repositories, no approval required)-[post-create]-setup = "echo 'Setting up worktree...'"--[pre-merge]-notify = "notify-send 'Merging {{ branch }}'"--# Optional: Custom prompt template (inline, Jinja2 syntax)-template = "..."--# Optional: Load template from file (mutually exclusive with 'template')-template-file = "~/.config/worktrunk/commit-template.txt"--# Optional: Custom squash commit template-squash-template = "..."--# Optional: Load squash template from file-squash-template-file = "~/.config/worktrunk/squash-template.txt"--# Approved Commands (auto-populated by wt switch --execute --yes)-[projects."github.com/user/repo"]-approved-commands = ["npm install"]-```--## Troubleshooting--### LLM Integration Not Working--**Check sequence:**-1. Verify command exists: `which llm`-2. Test command directly: `llm "test"`-3. View config: `wt config show`-4. Check for template conflicts (both `template` and `template-file` set)-5. If template file is used, verify it exists--### Config Not Loading--**Check sequence:**-1. View config path: `wt config show` shows location-2. Verify file exists: `ls -la ~/.config/worktrunk/config.toml`-3. Check TOML syntax: `cat ~/.config/worktrunk/config.toml`-4. Look for validation errors (path must be relative, not absolute)--### Approved Commands Not Persisting--- Approved commands are auto-populated when using `wt switch --execute "cmd" --yes`-- Manual editing is possible but discouraged (use the tool's approval system)--## User Hooks--Personal hooks that run for all repositories. These don't require approval and run before project hooks.--```toml-[post-create]-setup = "echo 'Setting up worktree...'"--[pre-merge]-notify = "notify-send 'Merging {{ branch }}'"-```--User hooks support the same hook types and template variables as project hooks. Use `--no-verify` to skip.--**Key differences from project hooks:**--| Aspect | User hooks | Project hooks |-|--------|------------|--------------|-| Location | `~/.config/worktrunk/config.toml` | `.config/wt.toml` |-| Scope | All repositories | Single repository |-| Approval | Not required | Required |-| Execution order | Before project hooks | After user hooks |--**Filtering by repository:**--User hooks receive JSON context on stdin, enabling repository-specific behavior:--```toml-[post-switch]-notify = """-python3 -c '-import json, sys-ctx = json.load(sys.stdin)-if "work-project" in ctx.get("repo", ""):- print(f"Switched to work project: {ctx[\"branch\"]}")-'-"""-```--## Command Settings--Configure default flag values for commands. These apply unless explicitly overridden.--### `[list]` section--```toml-[list]-full = false # Show CI and main-diffstat columns (--full)-branches = false # Include branches without worktrees (--branches)-remotes = false # Include remote branches (--remotes)-```--### `[commit]` section--Shared by `wt step commit`, `wt step squash`, and `wt merge`:--```toml-[commit]-stage = "all" # What to stage: "all", "tracked", or "none"-```--### `[merge]` section--```toml-[merge]-squash = true # Squash commits when merging-commit = true # Commit uncommitted changes (disables squash when false)-rebase = true # Rebase onto target before merging-remove = true # Remove worktree after merge-verify = true # Run project hooks-```--## Key Commands--```bash-wt config show # View current config-wt config create # Create initial config file-wt config --help # Show LLM setup guide-```--## Config File Location--- **macOS/Linux**: `~/.config/worktrunk/config.toml` (or `$XDG_CONFIG_HOME/worktrunk/config.toml`)-- **Windows**: `%APPDATA%\worktrunk\config.toml`--## Environment Variable Overrides--All config options can be overridden via environment variables with the `WORKTRUNK_` prefix:--- Single underscore after prefix: `WORKTRUNK_WORKTREE_PATH`-- Double underscore for nested keys: `WORKTRUNK_COMMIT_GENERATION__COMMAND`-- Snake_case env vars convert to kebab-case config keys automatically--```bash-# Override LLM in CI/testing-WORKTRUNK_COMMIT_GENERATION__COMMAND=echo \-WORKTRUNK_COMMIT_GENERATION__ARGS="test: mock commit" \- wt merge-```--Array values like `args` can be specified as single strings in env vars.--## Example Config--See `dev/config.example.toml` in the worktrunk repository for a complete annotated example.diff --git a/.claude-plugin/skills/worktrunk/reference/worktrunk.md b/.claude-plugin/skills/worktrunk/reference/worktrunk.mdnew file mode 100644index 000000000..ee2ee3648--- /dev/null+++ b/.claude-plugin/skills/worktrunk/reference/worktrunk.md@@ -0,0 +1,108 @@+# Worktrunk++Worktrunk is a CLI for git worktree management, designed for running AI agents+in parallel.++Worktrunk's three core commands make worktrees as easy as branches.+Plus, Worktrunk has a bunch of quality-of-life features to simplify working+with many parallel changes, including hooks to automate local workflows.++Scaling agents becomes trivial. A quick demo:++## Context: git worktrees++AI agents like Claude Code and Codex can handle longer tasks without+supervision, such that it's possible to manage 5-10+ in parallel. Git's native+worktree feature give each agent its own working directory, so they don't step+on each other's changes.++But the git worktree UX is clunky. Even a task as small as starting a new+worktree requires typing the branch name three times: `git worktree add -b feat+../repo.feat`, then `cd ../repo.feat`.++## Worktrunk makes git worktrees as easy as branches++Worktrees are addressed by branch name; paths are computed from a configurable template.++> Start with the core commands++**Core commands:**++<table class="cmd-compare">+ <thead>+ <tr>+ <th>Task</th>+ <th>Worktrunk</th>+ <th>Plain git</th>+ </tr>+ </thead>+ <tbody>+ <tr>+ <td>Switch worktrees</td>+ <td>{% rawcode() %}wt switch feat{% end %}</td>+ <td>{% rawcode() %}cd ../repo.feat{% end %}</td>+ </tr>+ <tr>+ <td>Create + start Claude</td>+ <td>{% rawcode() %}wt switch -c -x claude feat{% end %}</td>+ <td>{% rawcode() %}git worktree add -b feat ../repo.feat && \+cd ../repo.feat && \+claude{% end %}</td>+ </tr>+ <tr>+ <td>Clean up</td>+ <td>{% rawcode() %}wt remove{% end %}</td>+ <td>{% rawcode() %}cd ../repo && \+git worktree remove ../repo.feat && \+git branch -d feat{% end %}</td>+ </tr>+ <tr>+ <td>List with status</td>+ <td>{% rawcode() %}wt list{% end %}</td>+ <td>{% rawcode() %}git worktree list{% end %} (paths only)</td>+ </tr>+ </tbody>+</table>++**Workflow automation:**++> Expand into the more advanced commands as needed++- **[Hooks](https://worktrunk.dev/hook/)** — run commands on create, pre-merge, post-merge, etc+- **[LLM commit messages](https://worktrunk.dev/llm-commits/)** — generate commit messages from diffs via [llm](https://llm.datasette.io/)+- **[Merge workflow](https://worktrunk.dev/merge/)** — squash, rebase, merge, clean up in one command+- ...and **[lots more](#next-steps)**++A demo with some advanced features:++## Install++**Homebrew (macOS & Linux):**++```bash+brew install max-sixty/worktrunk/wt && wt config shell install+```++Shell integration allows commands to change directories.++**Cargo:**++```bash+cargo install worktrunk && wt config shell install+```++## Next steps++- Learn the core commands: [`wt switch`](https://worktrunk.dev/switch/), [`wt list`](https://worktrunk.dev/list/), [`wt merge`](https://worktrunk.dev/merge/), [`wt remove`](https://worktrunk.dev/remove/)+- Set up [project hooks](https://worktrunk.dev/hook/) for automated setup+- Explore [LLM commit messages](https://worktrunk.dev/llm-commits/), [fzf-like+ selector](https://worktrunk.dev/select/), [Claude Code integration](https://worktrunk.dev/claude-code/), [CI+ status & PR links](https://worktrunk.dev/list/#ci-status)+- Run `wt --help` or `wt <command> --help` for quick CLI reference++## Further reading++- [Claude Code: Best practices for agentic coding](https://www.anthropic.com/engineering/claude-code-best-practices) — Anthropic's official guide, including the worktree pattern+- [Shipping faster with Claude Code and Git Worktrees](https://incident.io/blog/shipping-faster-with-claude-code-and-git-worktrees) — incident.io's workflow for parallel agents+- [Git worktree pattern discussion](https://github.com/anthropics/claude-code/issues/1052) — Community discussion in the Claude Code repo+- [git-worktree documentation](https://git-scm.com/docs/git-worktree) — Official git referencediff --git a/tests/integration_tests/readme_sync.rs b/tests/integration_tests/readme_sync.rsindex 72c96e5ab..2459340f0 100644--- a/tests/integration_tests/readme_sync.rs+++ b/tests/integration_tests/readme_sync.rs@@ -1289,3 +1289,231 @@ fn strip_html_tags(s: &str) -> String {}result}++// =============================================================================+// Docs to Skill File Sync+// =============================================================================++/// Regex to match Zola frontmatter and extract title+static ZOLA_FRONTMATTER_PATTERN: LazyLock<Regex> =+ LazyLock::new(|| Regex::new(r"(?s)^\+\+\+\n(.*?)\n\+\+\+\n*").unwrap());++/// Regex to extract title from frontmatter+static ZOLA_TITLE_PATTERN: LazyLock<Regex> =+ LazyLock::new(|| Regex::new(r#"title\s*=\s*"([^"]+)""#).unwrap());++/// Regex to strip Zola terminal shortcodes ({% terminal() %}...{% end %})+static ZOLA_TERMINAL_PATTERN: LazyLock<Regex> =+ LazyLock::new(|| Regex::new(r"(?s)\{% terminal\(\) %\}\n?(.*?)\{% end %\}").unwrap());++/// Regex to strip AUTO-GENERATED marker comments (just the comments, not content)+static AUTO_GENERATED_MARKER_PATTERN: LazyLock<Regex> = LazyLock::new(|| {+ Regex::new(r"<!-- ⚠️ AUTO-GENERATED[^>]*-->\n*|<!-- END AUTO-GENERATED[^>]*-->\n*").unwrap()+});++/// Regex to strip HTML figure/picture elements (demo GIFs)+static HTML_FIGURE_PATTERN: LazyLock<Regex> =+ LazyLock::new(|| Regex::new(r"(?s)<figure[^>]*>.*?</figure>\n*").unwrap());++/// Transform docs content for skill file consumption+///+/// Transforms:+/// - Extracts title from Zola frontmatter and prepends as H1+/// - Strips Zola terminal shortcodes ({% terminal() %}...{% end %}) - keeps inner content+/// - Strips AUTO-GENERATED marker comments (keeps content)+/// - Strips HTML figure elements (demo GIFs not useful for skill)+/// - Converts Zola internal links (@/page.md) -> full URLs+/// - Removes "See also" section (just links to other docs pages)+fn transform_docs_for_skill(content: &str) -> String {+ // Extract title from frontmatter+ let title = ZOLA_FRONTMATTER_PATTERN+ .captures(content)+ .and_then(|caps| caps.get(1))+ .and_then(|fm| ZOLA_TITLE_PATTERN.captures(fm.as_str()))+ .and_then(|caps| caps.get(1))+ .map(|m| m.as_str().to_string());++ // Strip frontmatter+ let content = ZOLA_FRONTMATTER_PATTERN.replace(content, "");++ // Strip terminal shortcodes, keeping inner content+ let content = ZOLA_TERMINAL_PATTERN.replace_all(&content, "$1");++ // Strip AUTO-GENERATED marker comments (keep content)+ let content = AUTO_GENERATED_MARKER_PATTERN.replace_all(&content, "");++ // Strip HTML figure elements (demo GIFs)+ let content = HTML_FIGURE_PATTERN.replace_all(&content, "");++ // Transform Zola internal links to full URLs+ let content = ZOLA_LINK_PATTERN+ .replace_all(&content, |caps: ®ex::Captures| {+ let text = caps.get(1).unwrap().as_str();+ let page = caps.get(2).unwrap().as_str();+ let anchor = caps.get(3).map_or("", |m| m.as_str());+ format!("[{text}](https://worktrunk.dev/{page}/{anchor})")+ })+ .into_owned();++ // Remove "See also" section (just contains links to other pages)+ let content = remove_section(&content, "## See also");++ // Clean up multiple consecutive blank lines+ let content = content+ .lines()+ .fold((Vec::new(), false), |(mut acc, prev_blank), line| {+ let is_blank = line.trim().is_empty();+ if !(is_blank && prev_blank) {+ acc.push(line);+ }+ (acc, is_blank)+ })+ .0+ .join("\n");++ // Prepend title as H1 if extracted+ if let Some(title) = title {+ format!("# {}\n\n{}", title, content.trim())+ } else {+ content.trim().to_string()+ }+}++/// Remove a section from markdown content (from heading to next same-level heading)+fn remove_section(content: &str, heading: &str) -> String {+ let lines: Vec<&str> = content.lines().collect();+ let heading_level = heading.chars().take_while(|&c| c == '#').count();++ if let Some(start_idx) = lines.iter().position(|line| line.starts_with(heading)) {+ // Find end: next heading at same or higher level+ let end_idx = lines+ .iter()+ .skip(start_idx + 1)+ .position(|line| {+ let level = line.chars().take_while(|&c| c == '#').count();+ level > 0 && level <= heading_level+ })+ .map(|i| i + start_idx + 1)+ .unwrap_or(lines.len());++ let mut result: Vec<&str> = lines[..start_idx].to_vec();+ result.extend(&lines[end_idx..]);+ result.join("\n")+ } else {+ content.to_string()+ }+}++/// Skill files to sync from docs+/// Format: (docs_path, skill_path)+/// Files are synced with content transformed for skill consumption+const SKILL_SYNC_FILES: &[(&str, &str)] = &[+ (+ "docs/content/hook.md",+ ".claude-plugin/skills/worktrunk/reference/hook.md",+ ),+ (+ "docs/content/config.md",+ ".claude-plugin/skills/worktrunk/reference/config.md",+ ),+ (+ "docs/content/switch.md",+ ".claude-plugin/skills/worktrunk/reference/switch.md",+ ),+ (+ "docs/content/merge.md",+ ".claude-plugin/skills/worktrunk/reference/merge.md",+ ),+ (+ "docs/content/list.md",+ ".claude-plugin/skills/worktrunk/reference/list.md",+ ),+ (+ "docs/content/select.md",+ ".claude-plugin/skills/worktrunk/reference/select.md",+ ),+ (+ "docs/content/step.md",+ ".claude-plugin/skills/worktrunk/reference/step.md",+ ),+ (+ "docs/content/remove.md",+ ".claude-plugin/skills/worktrunk/reference/remove.md",+ ),+ (+ "docs/content/llm-commits.md",+ ".claude-plugin/skills/worktrunk/reference/llm-commits.md",+ ),+ (+ "docs/content/tips-patterns.md",+ ".claude-plugin/skills/worktrunk/reference/tips-patterns.md",+ ),+ (+ "docs/content/worktrunk.md",+ ".claude-plugin/skills/worktrunk/reference/worktrunk.md",+ ),+ (+ "docs/content/faq.md",+ ".claude-plugin/skills/worktrunk/reference/faq.md",+ ),+ (+ "docs/content/claude-code.md",+ ".claude-plugin/skills/worktrunk/reference/claude-code.md",+ ),+];++#[test]+fn test_skill_files_are_in_sync_with_docs() {+ let project_root = Path::new(env!("CARGO_MANIFEST_DIR"));+ let mut errors = Vec::new();+ let mut updated = 0;++ for (docs_path, skill_path) in SKILL_SYNC_FILES {+ let docs_file = project_root.join(docs_path);+ let skill_file = project_root.join(skill_path);++ if !docs_file.exists() {+ errors.push(format!("Missing docs file: {}", docs_file.display()));+ continue;+ }++ let docs_content = fs::read_to_string(&docs_file)+ .unwrap_or_else(|e| panic!("Failed to read {}: {}", docs_file.display(), e));++ // Transform and use content directly (docs already have proper H1 titles)+ let expected = transform_docs_for_skill(&docs_content);+ let expected = trim_lines(&expected);++ let current = if skill_file.exists() {+ fs::read_to_string(&skill_file)+ .unwrap_or_else(|e| panic!("Failed to read {}: {}", skill_file.display(), e))+ } else {+ String::new()+ };+ let current = trim_lines(¤t);++ if current != expected {+ // Ensure parent directory exists+ if let Some(parent) = skill_file.parent() {+ fs::create_dir_all(parent).unwrap_or_else(|e| {+ panic!("Failed to create directory {}: {}", parent.display(), e)+ });+ }+ fs::write(&skill_file, format!("{}\n", expected))+ .unwrap_or_else(|e| panic!("Failed to write {}: {}", skill_file.display(), e));+ updated += 1;+ }+ }++ if !errors.is_empty() {+ panic!("Skill sync errors:\n\n{}\n", errors.join("\n"));+ }++ if updated > 0 {+ panic!(+ "Skill files out of sync with docs: updated {} file(s). \+ Run tests locally and commit the changes.",+ updated+ );+ }+}