Skip to content

Worktrunk is a CLI for Git worktree management, designed for parallel AI agent workflows

feat(skill): Add worktrunk config guidance skill

Maximilian Roosa3c173b7d171
diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json
new file mode 100644
index 000000000..2c7a25526
--- /dev/null
+++ b/.claude-plugin/marketplace.json
@@ -0,0 +1,22 @@
+{
+ "name": "worktrunk-skills",
+ "owner": {
+ "name": "Worktrunk",
+ "email": "[email protected]"
+ },
+ "metadata": {
+ "description": "Configuration guidance skills for Worktrunk git worktree workflow tool",
+ "version": "1.0.0"
+ },
+ "plugins": [
+ {
+ "name": "worktrunk-config",
+ "description": "Configuration guidance for Worktrunk - helps set up LLM integration and project automation hooks",
+ "source": "./",
+ "strict": false,
+ "skills": [
+ "./skills/worktrunk-config"
+ ]
+ }
+ ]
+}
diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json
new file mode 100644
index 000000000..ad05b6be9
--- /dev/null
+++ b/.claude-plugin/plugin.json
@@ -0,0 +1,8 @@
+{
+ "name": "worktrunk-config",
+ "description": "Configuration guidance for Worktrunk - helps set up LLM integration and project automation hooks",
+ "version": "1.0.0",
+ "author": {
+ "name": "Worktrunk"
+ }
+}
diff --git a/skills/worktrunk-config/README.md b/skills/worktrunk-config/README.md
new file mode 100644
index 000000000..3d08cdf86
--- /dev/null
+++ b/skills/worktrunk-config/README.md
@@ -0,0 +1,94 @@
+# Worktrunk Configuration Skill
+
+A unified skill for helping users configure Worktrunk, covering both personal settings and project-specific automation.
+
+## Structure
+
+```
+worktrunk-config/
+├── SKILL.md # Main skill file (loaded when skill activates)
+├── README.md # This file
+└── references/ # Detailed reference documentation
+ ├── user-config.md # User config (~/.config/worktrunk/config.toml)
+ ├── project-config.md # Project config (.config/wt.toml)
+ └── hook-types-reference.md # Detailed hook behavior reference
+```
+
+## When This Skill Activates
+
+Claude loads this skill when users ask to:
+- Configure LLM integration ("set up LLM", "configure commit generation")
+- Set up project hooks ("set up hooks", "automate npm install", "run tests before merge")
+- Customize worktree paths
+- Troubleshoot configuration issues
+
+## Two Config Types
+
+### User Config (`~/.config/worktrunk/config.toml`)
+- **Scope**: Personal developer preferences
+- **Git**: Never checked in
+- **Permission model**: Conservative (always propose, get consent)
+- **Contains**: LLM integration, worktree path templates, approved commands
+- **Reference**: `references/user-config.md`
+
+### Project Config (`.config/wt.toml`)
+- **Scope**: Team-wide automation
+- **Git**: Checked into repository
+- **Permission model**: Proactive (create directly, easily reversible)
+- **Contains**: Lifecycle hooks (post-create, pre-merge, etc.)
+- **Reference**: `references/project-config.md`
+
+## Progressive Disclosure Pattern
+
+This skill follows the recommended pattern:
+
+1. **SKILL.md** (~1-2k words)
+ - High-level overview
+ - Quick workflows for common tasks
+ - When to use each config type
+ - References to detailed docs
+
+2. **references/*.md** (detailed)
+ - Complete step-by-step procedures
+ - All configuration options
+ - Troubleshooting guides
+ - Examples and patterns
+
+Claude loads reference files only when needed, keeping context usage efficient.
+
+## Key Workflows
+
+### LLM Setup (User Config)
+1. Check if LLM tool exists
+2. Guide installation (user runs commands)
+3. Propose config change
+4. After approval, apply
+
+### Project Hooks (Project Config)
+1. Detect project type (npm, cargo, etc.)
+2. Identify available commands
+3. Design appropriate hooks
+4. Validate commands exist
+5. Create `.config/wt.toml` with comments
+
+## Examples
+
+**User asks**: "Help me set up LLM for commit messages"
+→ Loads `reference/user-config.md`, follows LLM setup workflow
+
+**User asks**: "Set up some hooks for this project"
+→ Loads `reference/project-config.md`, detects project type, proposes hooks
+
+**User asks**: "Why isn't my pre-merge hook running?"
+→ Loads `reference/project-config.md#troubleshooting` or `reference/hook-types-reference.md`
+
+## Distribution
+
+Users install this skill by cloning the entire Worktrunk repository as a marketplace:
+
+```bash
+cd ~/.claude/plugins/marketplaces
+git clone https://github.com/max-sixty/worktrunk.git worktrunk-skills
+```
+
+Then restart Claude Code. The skill will be available as `worktrunk-config@worktrunk-skills`.
diff --git a/skills/worktrunk-config/SKILL.md b/skills/worktrunk-config/SKILL.md
new file mode 100644
index 000000000..ba57bd5b7
--- /dev/null
+++ b/skills/worktrunk-config/SKILL.md
@@ -0,0 +1,192 @@
+---
+name: worktrunk-config
+description: This skill should be used when helping users configure Worktrunk, either personal settings (user config at ~/.config/worktrunk/config.toml) or project-specific hooks (project config at .config/wt.toml). Use when users ask to "set up LLM", "configure hooks", "automate npm install", or similar configuration tasks.
+---
+
+# Worktrunk Configuration
+
+This skill guides configuration of Worktrunk for both personal settings and project-specific automation.
+
+## Two Types of Configuration
+
+Worktrunk uses two separate config files with different scopes and behaviors:
+
+### User Config (`~/.config/worktrunk/config.toml`)
+- **Scope**: Personal preferences for the individual developer
+- **Location**: `~/.config/worktrunk/config.toml` (never checked into git)
+- **Contains**: LLM integration, worktree path templates, approved commands
+- **Permission model**: Always propose changes and get consent before editing
+- **See**: `references/user-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**: `references/project-config.md` for detailed guidance
+
+## Determining Which Config to Use
+
+When a user asks for configuration help, determine which type based on:
+
+**User config indicators**:
+- "set up LLM" or "configure commit generation"
+- "change where worktrees are created"
+- "customize commit message templates"
+- Affects only their environment
+
+**Project config indicators**:
+- "set up hooks for this project"
+- "automate npm install"
+- "run tests before merge"
+- Affects the entire team
+
+**Both configs may be needed**: For example, setting up LLM integration requires user config, but automating quality checks requires project config.
+
+## Core Workflows
+
+### Setting Up LLM Integration (User Config)
+
+Most common request. Follow this sequence:
+
+1. **Check if LLM tool exists**
+ ```bash
+ which llm # or: which aichat
+ ```
+
+2. **If not installed, guide installation (don't run it)**
+ ```bash
+ uv tool install -U llm
+ ```
+
+3. **Guide API key setup (don't run it)**
+ ```bash
+ llm install llm-anthropic
+ llm keys set anthropic
+ llm models default claude-3.5-sonnet
+ ```
+
+4. **Propose config change**
+ ```toml
+ [commit-generation]
+ command = "llm"
+ ```
+ Ask: "Should I add this to your config?"
+
+5. **After approval, apply**
+ - Check if config exists: `wt config list`
+ - If not, guide through `wt config init`
+ - Read, modify, write preserving structure
+
+6. **Suggest testing**
+ ```bash
+ llm "say hello"
+ wt merge --auto-commit # in a repo with changes
+ ```
+
+**See `references/user-config.md` for complete details.**
+
+### Setting Up Project Hooks (Project Config)
+
+Common request for workflow automation. Follow discovery process:
+
+1. **Detect project type**
+ ```bash
+ ls package.json Cargo.toml pyproject.toml
+ ```
+
+2. **Identify available commands**
+ - For npm: Read `package.json` scripts
+ - For Rust: Common cargo commands
+ - For Python: Check pyproject.toml
+
+3. **Design appropriate hooks**
+ - Dependencies (fast, must complete) → `post-create-command`
+ - Tests/linting (must pass) → `pre-commit-command` or `pre-merge-command`
+ - Long builds → `post-start-command`
+
+4. **Validate commands work**
+ ```bash
+ npm run lint # verify exists
+ which cargo # verify tool exists
+ ```
+
+5. **Create `.config/wt.toml`**
+ ```toml
+ # Install dependencies when creating worktrees
+ post-create-command = "npm install"
+
+ # Validate code quality before committing
+ pre-commit-command = ["npm run lint", "npm run typecheck"]
+
+ # Run tests before merging
+ pre-merge-command = "npm test"
+ ```
+
+6. **Add comments explaining choices**
+
+7. **Suggest testing**
+ ```bash
+ wt switch --create test-hooks
+ ```
+
+**See `references/project-config.md` for complete details.**
+
+## Permission Models
+
+### User Config: Conservative
+- **Never edit without consent** - Always show proposed change and wait for approval
+- **Never install tools** - Provide commands for users to run themselves
+- **Preserve structure** - Keep existing comments and organization
+- **Validate first** - Ensure TOML is valid before writing
+
+### Project Config: Proactive
+- **Create directly** - Changes are versioned, easily reversible
+- **Validate commands** - Check commands exist before adding
+- **Explain choices** - Add comments documenting why hooks exist
+- **Warn on danger** - Flag destructive operations before adding
+
+## Common Tasks Reference
+
+### User Config Tasks
+- Set up LLM integration → `references/user-config.md#llm-setup`
+- Customize worktree paths → `references/user-config.md#worktree-paths`
+- Custom commit templates → `references/user-config.md#templates`
+- Troubleshoot LLM issues → `references/user-config.md#troubleshooting`
+
+### Project Config Tasks
+- Set up hooks for new project → `references/project-config.md#new-project`
+- Add hook to existing config → `references/project-config.md#add-hook`
+- Use template variables → `references/project-config.md#variables`
+- Convert command formats → `references/project-config.md#formats`
+- Troubleshoot hook execution → `references/project-config.md#troubleshooting`
+
+## Key Commands
+
+```bash
+# View all configuration
+wt config list
+
+# Create initial user config
+wt config init
+
+# LLM setup guide
+wt config help
+```
+
+## When to Load Reference Files
+
+Reference files contain detailed procedures. Load them when:
+- User asks about specific configuration aspects
+- Troubleshooting configuration issues
+- Need detailed examples or validation rules
+- Want comprehensive hook type reference
+
+Use grep patterns to find specific sections:
+```bash
+# Find LLM setup details
+grep -A 20 "## LLM Setup" references/user-config.md
+
+# Find hook type details
+grep -A 30 "### post-create-command" references/project-config.md
+```
diff --git a/skills/worktrunk-config/reference/hook-types-reference.md b/skills/worktrunk-config/reference/hook-types-reference.md
new file mode 100644
index 000000000..f4f45ec4a
--- /dev/null
+++ b/skills/worktrunk-config/reference/hook-types-reference.md
@@ -0,0 +1,286 @@
+# Hook Types Reference
+
+Detailed behavior and use cases for all five Worktrunk hook types.
+
+## Hook Type Comparison
+
+| Hook | When | Blocking? | Fail-Fast? | Variables | Execution |
+|------|------|-----------|------------|-----------|-----------|
+| `post-create-command` | After creating worktree | Yes | No | Basic | Sequential |
+| `post-start-command` | When switching to worktree | No | No | Basic | Parallel |
+| `pre-commit-command` | Before committing during merge | Yes | Yes | Basic + Merge | Sequential |
+| `pre-merge-command` | Before merging to target | Yes | Yes | Basic + Merge | Sequential |
+| `post-merge-command` | After successful merge | Yes | No | Basic + Merge | Sequential |
+
+**Basic variables**: `{repo}`, `{branch}`, `{worktree}`, `{repo_root}`
+**Merge variables**: Basic + `{target}`
+
+## Detailed Behavior
+
+### post-create-command
+
+**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 (even if using array format)
+
+**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-command = [
+ "npm install",
+ "npm run db:migrate",
+ "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-command
+
+**When it runs**: After switching to an existing worktree (not on creation).
+
+**Behavior**:
+- Runs in background, doesn't block user
+- Multiple commands run in parallel
+- Output logged to `.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-command = [
+ "npm run build",
+ "docker-compose up -d",
+ "git pull origin main"
+]
+```
+
+**What happens**: User runs `wt switch feature-x`. All three commands start immediately in parallel. User can work while they run. Check `.wt-logs/` for output.
+
+### pre-commit-command
+
+**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-command = [
+ "npm run lint",
+ "npm run typecheck",
+ "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-command
+
+**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-command = [
+ "npm test",
+ "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-command
+
+**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-command = [
+ "npm run deploy",
+ "./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).
+
+## Execution Order During Merge
+
+Full sequence when running `wt merge`:
+
+1. Validate working tree is clean
+2. **Run `pre-commit-command`** (fail-fast)
+3. Create commit
+4. Switch to main worktree
+5. Pull latest changes
+6. **Run `pre-merge-command`** (fail-fast)
+7. Merge branch into target
+8. Push to remote
+9. **Run `post-merge-command`** (best-effort)
+10. Clean up (delete branch, remove worktree)
+
+## Format Variants
+
+All hooks support three formats:
+
+### Single Command (String)
+```toml
+post-create-command = "npm install"
+```
+
+### Multiple Commands (Array)
+```toml
+post-create-command = [
+ "npm install",
+ "npm run build"
+]
+```
+
+Behavior:
+- `post-create-command`: Sequential execution
+- `post-start-command`: Parallel execution
+- `pre-commit-command`: Sequential execution
+- `pre-merge-command`: Sequential execution
+- `post-merge-command`: Sequential execution
+
+### Named Commands (Table)
+```toml
+[post-create-command]
+dependencies = "npm install"
+database = "npm run db:migrate"
+services = "docker-compose up -d"
+```
+
+Behavior same as array format, but with descriptive names.
+
+## Template Variables
+
+### Basic Variables (All Hooks)
+
+```toml
+post-create-command = "echo 'Working on {branch} in {repo}'"
+```
+
+Available:
+- `{repo}` - Repository name (e.g., "my-project")
+- `{branch}` - Branch name (e.g., "feature-auth")
+- `{worktree}` - Absolute path to worktree
+- `{repo_root}` - Absolute path to repository root
+
+### Merge Variables (Merge Hooks Only)
+
+```toml
+pre-merge-command = "echo 'Merging {branch} into {target}'"
+```
+
+Available in: `pre-commit-command`, `pre-merge-command`, `post-merge-command`
+
+Additional variable:
+- `{target}` - Target branch for merge (e.g., "main")
+
+### Conditional Logic
+
+Use shell conditionals with variables:
+
+```toml
+pre-merge-command = """
+if [ "{target}" = "main" ]; then
+ npm run test:full
+elif [ "{target}" = "staging" ]; then
+ npm run test:integration
+else
+ npm run test:unit
+fi
+"""
+```
+
+## Common Patterns
+
+### Fast Dependencies + Slow Build
+```toml
+# Blocking: must complete before work starts
+post-create-command = "npm install"
+
+# Background: builds while user works
+post-start-command = "npm run build"
+```
+
+### Progressive Validation
+```toml
+# Quick checks before commit
+pre-commit-command = ["npm run lint", "npm run typecheck"]
+
+# Thorough validation before merge
+pre-merge-command = ["npm test", "npm run build"]
+```
+
+### Target-Specific Behavior
+```toml
+post-merge-command = """
+if [ "{target}" = "main" ]; then
+ npm run deploy:production
+elif [ "{target}" = "staging" ]; then
+ npm run deploy:staging
+fi
+"""
+```
+
+### Monorepo with Multiple Tools
+```toml
+[post-create-command]
+frontend = "cd frontend && npm install"
+backend = "cd backend && cargo build"
+database = "docker-compose up -d postgres"
+
+[pre-merge-command]
+frontend-tests = "cd frontend && npm test"
+backend-tests = "cd backend && cargo test"
+```
diff --git a/skills/worktrunk-config/reference/project-config.md b/skills/worktrunk-config/reference/project-config.md
new file mode 100644
index 000000000..67813ae61
--- /dev/null
+++ b/skills/worktrunk-config/reference/project-config.md
@@ -0,0 +1,462 @@
+# 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-command`
+- **Tests/linting** (fast, must pass) → `pre-commit-command` or `pre-merge-command`
+- **Long builds** (slow, optional) → `post-start-command`
+- **Deployment** (after merge) → `post-merge-command`
+
+### 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-command = "npm install"
+
+# Validate code quality before committing (blocking, fail-fast)
+pre-commit-command = [
+ "npm run lint",
+ "npm run typecheck"
+]
+
+# Run tests before merging (blocking, fail-fast)
+pre-merge-command = "npm test"
+```
+
+</example>
+
+<example type="rust-project-config">
+
+Typical Rust project:
+```toml
+# Build runs in background (slow)
+post-start-command = "cargo build"
+
+# Format and lint before committing (blocking, fail-fast)
+pre-commit-command = [
+ "cargo fmt --check",
+ "cargo clippy -- -D warnings"
+]
+
+# Run tests before merging (blocking, fail-fast)
+pre-merge-command = "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-command = "npm install"
+
+# Enforce code quality standards (matches CI checks)
+pre-commit-command = ["npm run lint", "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 → `post-create-command`
+- Switching to worktree → `post-start-command`
+- Before committing → `pre-commit-command`
+- Before merging → `pre-merge-command`
+- After merging → `post-merge-command`
+
+### Step 3: Handle Format Conversion if Needed
+
+<example type="adding-to-single-command">
+
+Current:
+```toml
+post-create-command = "npm install"
+```
+
+Adding "npm run db:migrate":
+```toml
+post-create-command = [
+ "npm install",
+ "npm run db:migrate"
+]
+```
+
+</example>
+
+<example type="adding-to-array">
+
+Current:
+```toml
+pre-commit-command = ["npm run lint"]
+```
+
+Adding typecheck:
+```toml
+pre-commit-command = [
+ "npm run lint",
+ "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 name (e.g., "my-project")
+- `{branch}` - Branch name (e.g., "feature-auth")
+- `{worktree}` - Absolute path to worktree
+- `{repo_root}` - Absolute path to repository root
+
+<example type="basic-variables">
+
+```toml
+post-create-command = "echo 'Working on {branch} in {repo}'"
+```
+
+</example>
+
+### Merge Variables (Merge Hooks Only)
+
+Available in: `pre-commit-command`, `pre-merge-command`, `post-merge-command`
+
+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-command = """
+if [ "{target}" = "main" ]; then
+ npm run test:full
+else
+ npm run test:quick
+fi
+"""
+```
+
+</example>
+
+## Formats
+
+All hooks support three command formats.
+
+### Single Command (String)
+
+```toml
+post-create-command = "npm install"
+```
+
+### Multiple Commands (Array)
+
+```toml
+post-create-command = [
+ "npm install",
+ "npm run build"
+]
+```
+
+Behavior:
+- `post-create-command`: Sequential
+- `post-start-command`: Parallel
+- `pre-commit-command`: Sequential
+- `pre-merge-command`: Sequential
+- `post-merge-command`: Sequential
+
+### Named Commands (Table)
+
+```toml
+[post-create-command]
+dependencies = "npm install"
+database = "npm run db:migrate"
+services = "docker-compose up -d"
+```
+
+Behavior same as array format, but with descriptive names.
+
+## Hook Types
+
+Five hook types with different timing and behavior:
+
+### post-create-command
+
+**When**: After creating new worktree, before switching to it
+**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-command = [
+ "npm install",
+ "npm run db:migrate"
+]
+```
+
+</example>
+
+### post-start-command
+
+**When**: After switching to existing worktree
+**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-command = [
+ "npm run build",
+ "docker-compose up -d"
+]
+```
+
+</example>
+
+### pre-commit-command
+
+**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-command = [
+ "npm run lint",
+ "npm run typecheck"
+]
+```
+
+</example>
+
+### pre-merge-command
+
+**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-command = "npm test"
+```
+
+</example>
+
+### post-merge-command
+
+**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-command = "npm run deploy"
+```
+
+</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 five 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 `.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-command = "npm run build"
+```
+
+After (runs in background):
+```toml
+post-create-command = "npm install" # Fast, blocking
+post-start-command = "npm run build" # Slow, background
+```
+
+</example>
+
+## Key Commands
+
+```bash
+wt config list # View project config
+cat .config/wt.toml # Read config directly
+wt switch --create test-hooks # Test hooks work
+```
+
+## Config File Location
+
+- **Always at**: `<repo>/.config/wt.toml` (checked into git)
+- **Background logs**: `.wt-logs/` (gitignored)
+
+## Example Config
+
+See `.config/wt.example.toml` in the worktrunk repository for a complete annotated example.
diff --git a/skills/worktrunk-config/reference/user-config.md b/skills/worktrunk-config/reference/user-config.md
new file mode 100644
index 000000000..ba02320c2
--- /dev/null
+++ b/skills/worktrunk-config/reference/user-config.md
@@ -0,0 +1,273 @@
+# 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-powered 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-3.5-sonnet
+```
+
+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 list
+```
+
+If not: guide through `wt config init` 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 changes)
+wt merge --auto-commit
+```
+
+## Worktree Paths
+
+Users may want different worktree organization patterns.
+
+### Common Patterns
+
+<example type="worktree-patterns">
+
+Default (parent siblings):
+```toml
+worktree-path = "../{main-worktree}.{branch}"
+```
+Result: `~/code/myproject` → `~/code/myproject.feature-auth`
+
+Inside repo:
+```toml
+worktree-path = ".worktrees/{branch}"
+```
+Result: `~/code/myproject/.worktrees/feature-auth`
+
+Shared directory:
+```toml
+worktree-path = "../worktrees/{main-worktree}/{branch}"
+```
+Result: `~/code/worktrees/myproject/feature-auth`
+
+</example>
+
+### Workflow
+
+1. Show current setting from `wt config list`
+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
+
+- `{main-worktree}` - Main worktree directory name
+- `{branch}` - Branch name (slashes replaced with dashes)
+
+### 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 name
+
+**Squash commit templates**:
+- `{{ commits }}` - List of commits being squashed
+- `{{ target_branch }}` - Target branch for merge
+- `{{ branch }}` - Current branch
+- `{{ repo }}` - Repository 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 = "../{main-worktree}.{branch}"
+
+# LLM Commit Generation (Optional)
+[commit-generation]
+command = "llm"
+args = ["-m", "claude-haiku-4.5"]
+
+# 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 --force)
+[[approved-commands]]
+project = "github.com/user/repo"
+command = "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 list`
+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 list` 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" --force`
+- Manual editing is possible but discouraged (use the tool's approval system)
+
+## Key Commands
+
+```bash
+wt config list # View current config
+wt config init # 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`
+
+## Example Config
+
+See `config.example.toml` in the worktrunk repository for a complete annotated example.