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.jsonnew file mode 100644index 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.jsonnew file mode 100644index 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.mdnew file mode 100644index 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.mdnew file mode 100644index 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.mdnew file mode 100644index 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.mdnew file mode 100644index 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.mdnew file mode 100644index 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.