Commit 05d5057bdff2

@@ -17,6 +17,8 @@ Git worktrees create isolated working directories that share the same repository
 
 **Core principle:** All worktrees live in `~/.local/share/worktrees/` following XDG conventions, consistent with lazyworktree.
 
+**Default tool:** Use `lazyworktree` when available (preferred). Fall back to raw `git worktree` commands only when lazyworktree is not installed.
+
 **Announce at start:** "I'm using the UsingGitWorktrees skill to set up an isolated workspace."
 
 ## XDG Data Layout
@@ -27,50 +29,108 @@ All worktrees are organized under `~/.local/share/worktrees/`:
 ~/.local/share/worktrees/
 ├── vdemeester/
 │   ├── home/
-│   │   ├── main/
-│   │   └── feature-new-host/
+│   │   ├── main-lively-panda/
+│   │   └── sakhalin-upgrade-bold-oak/
 │   └── tektoncd-plumbing/
-│       ├── main/
-│       └── feature-terraform-branch-protection/
+│       └── terraform-persistent-state/
 └── tektoncd/
     └── pipeline/
-        ├── main/
-        └── feature-new-resolver/
+        └── feature-new-resolver-calm-quartz/
 ```
 
-Structure: `~/.local/share/worktrees/<org>/<repo>/<branch>/`
+Structure: `~/.local/share/worktrees/<org>/<repo>/<name>/`
 
-### Benefits
+**Note:** lazyworktree auto-generates names like `<branch>-<adjective>-<noun>`. The org/repo is resolved automatically from the git remote.
 
-- **XDG compliant:** Follows standard data directory conventions
-- **Centralized:** All worktrees in one global location
-- **No .gitignore needed:** Worktrees aren't inside any repo
-- **Consistent with lazyworktree:** Same layout as lazyworktree's default
-- **Organization aware:** Grouped by org/owner and repo
-- **Clean source directories:** Your `~/src/` stays clean
+## Creating Worktrees with lazyworktree (Preferred)
 
-### vs. Other Layouts (NOT used)
+### Check availability
 
-| Aspect | XDG Data Layout | Nested Layout | Sibling Layout |
-|--------|-----------------|---------------|----------------|
-| Location | `~/.local/share/worktrees/` | Inside repo (`.worktrees/`) | Project parent folder |
-| Requires .gitignore | No | Yes | No |
-| Centralized | Yes | No | No |
-| lazyworktree compatible | Yes (default) | No | Partial |
+```bash
+command -v lazyworktree >/dev/null 2>&1
+```
 
-## Determining Org and Repo
+### Create a worktree
+
+```bash
+# Non-interactive creation — prints the worktree path to stdout
+WORKTREE_PATH=$(lazyworktree create --from-branch <branch> --silent)
+cd "$WORKTREE_PATH"
+```
+
+**Examples:**
+
+```bash
+# From an existing branch
+WORKTREE_PATH=$(lazyworktree create --from-branch main --silent)
+# → ~/.local/share/worktrees/public/home/main-lively-panda
+
+# From a feature branch
+WORKTREE_PATH=$(lazyworktree create --from-branch feature/sakhalin-upgrade --silent)
+# → ~/.local/share/worktrees/public/home/feature-sakhalin-upgrade-bold-oak
+
+# From a PR
+WORKTREE_PATH=$(lazyworktree create --from-pr 42 --silent)
+
+# Carry uncommitted changes to the new worktree
+WORKTREE_PATH=$(lazyworktree create --from-branch feature-x --with-change --silent)
+
+# With post-create setup command (runs inside new worktree)
+WORKTREE_PATH=$(lazyworktree create --from-branch feature-x --silent --exec "go mod download")
+```
+
+### Run commands in a worktree
+
+```bash
+# Execute a command inside a worktree without cd-ing
+lazyworktree exec -w <worktree-name> "go test ./..."
+lazyworktree exec -w <worktree-name> "make build"
+```
+
+### List worktrees
+
+```bash
+# JSON output (richest — includes dirty, ahead/behind, last_active)
+lazyworktree list --json
+
+# Paths only (for scripting)
+lazyworktree list --pristine
+
+# Standard git output
+git worktree list
+
+# Interactive TUI
+lazyworktree
+```
+
+### Delete a worktree
+
+```bash
+# Removes worktree and cleans up the branch
+lazyworktree delete --silent <worktree-path>
+```
+
+### Rename a worktree
+
+```bash
+# From inside the worktree
+lazyworktree rename <new-name> --silent
+
+# Explicit worktree
+lazyworktree rename <worktree-path> <new-name> --silent
+```
+
+## Fallback: Raw Git Commands
+
+Only use when `lazyworktree` is not available.
+
+### Determining Org and Repo
 
 Extract organization and repository name from git remote:
 
 ```bash
-# Get remote URL
 REMOTE_URL=$(git remote get-url origin)
 
-# Parse org/repo from various URL formats
-# SSH: git@github.com:tektoncd/pipeline.git
-# HTTPS: https://github.com/tektoncd/pipeline.git
-# HTTPS with auth: https://user@github.com/tektoncd/pipeline.git
-
 if [[ "$REMOTE_URL" =~ git@[^:]+:([^/]+)/([^/.]+) ]]; then
     ORG="${BASH_REMATCH[1]}"
     REPO="${BASH_REMATCH[2]}"
@@ -78,104 +138,68 @@ elif [[ "$REMOTE_URL" =~ https://[^/]+/([^/]+)/([^/.]+) ]]; then
     ORG="${BASH_REMATCH[1]}"
     REPO="${BASH_REMATCH[2]}"
 fi
-
-# Remove .git suffix if present
 REPO="${REPO%.git}"
 ```
 
-## Worktree Creation
-
-### Step 1: Determine Paths
+### Create worktree manually
 
 ```bash
-# Base directory for all worktrees
 WORKTREE_BASE="$HOME/.local/share/worktrees"
-
-# Get org and repo from remote
-REMOTE_URL=$(git remote get-url origin)
-# ... parse ORG and REPO as above ...
-
-# Sanitize branch name for filesystem
 BRANCH_NAME="feature/user-authentication"
-BRANCH_PATH=$(echo "$BRANCH_NAME" | tr '/' '-')  # feature-user-authentication
-
-# Full worktree path
+BRANCH_PATH=$(echo "$BRANCH_NAME" | tr '/' '-')
 WORKTREE_PATH="$WORKTREE_BASE/$ORG/$REPO/$BRANCH_PATH"
-```
 
-### Step 2: Create Worktree
-
-```bash
-# Create directory structure
 mkdir -p "$WORKTREE_BASE/$ORG/$REPO"
-
-# Create worktree and branch in one command
 git worktree add "$WORKTREE_PATH" -b "$BRANCH_NAME"
-
-# Navigate to new worktree
 cd "$WORKTREE_PATH"
 ```
 
-**Alternative - checkout existing branch:**
+### Remove worktree manually
+
 ```bash
-# If branch already exists
-git worktree add "$WORKTREE_PATH" "$BRANCH_NAME"
+git worktree remove ~/.local/share/worktrees/<org>/<repo>/<name>
+# Or force:
+git worktree remove --force ~/.local/share/worktrees/<org>/<repo>/<name>
 ```
 
-### Step 3: Auto-Detect and Run Project Setup
+## After Creation: Setup and Verify
 
-Detect project type and install dependencies:
+Use `--exec` on create or `exec -w` after creation to run setup and verification.
+
+### Auto-Detect and Run Project Setup
+
+**Preferred:** Use `--exec` during creation:
 
 ```bash
-# Node.js / JavaScript
-if [ -f package.json ]; then
-    npm install
-fi
-
-# Rust
-if [ -f Cargo.toml ]; then
-    cargo build
-fi
-
-# Python
-if [ -f pyproject.toml ]; then
-    uv sync  # Prefer uv over pip
-elif [ -f requirements.txt ]; then
-    uv pip install -r requirements.txt
-fi
-
 # Go
-if [ -f go.mod ]; then
-    go mod download
-fi
+WORKTREE_PATH=$(lazyworktree create --from-branch feature-x --silent --exec "go mod download")
 
-# NixOS (from home repository pattern)
-if [ -f flake.nix ]; then
-    nix develop --command bash -c "echo 'Development environment ready'"
-fi
-```
-
-### Step 4: Verify Clean Baseline
-
-Run tests to ensure worktree starts in working state:
-
-```bash
 # Node.js
-npm test
-
-# Rust
-cargo test
+WORKTREE_PATH=$(lazyworktree create --from-branch feature-x --silent --exec "npm install")
 
 # Python
-pytest
+WORKTREE_PATH=$(lazyworktree create --from-branch feature-x --silent --exec "uv sync")
 
-# Go
-go test ./...
+# NixOS (home repository)
+WORKTREE_PATH=$(lazyworktree create --from-branch feature-x --silent --exec "make dry-build")
+```
 
-# NixOS
-nix build
-# OR
-make build
+**Or after creation with exec:**
+
+```bash
+lazyworktree exec -w <worktree-name> "go mod download"
+```
+
+### Verify Clean Baseline
+
+Run tests without switching directories:
+
+```bash
+lazyworktree exec -w <worktree-name> "go test ./..."
+lazyworktree exec -w <worktree-name> "cargo test"
+lazyworktree exec -w <worktree-name> "pytest"
+lazyworktree exec -w <worktree-name> "npm test"
+lazyworktree exec -w <worktree-name> "make build"
 ```
 
 **If tests fail:**
@@ -184,20 +208,19 @@ make build
 - Document known issues
 
 **If tests pass:**
-- Report success
-- Show test count and duration
+- Report success, show test count and duration
 - Confirm ready for work
 
-### Step 5: Report Worktree Ready
+### Report Worktree Ready
 
 ```
 Worktree created successfully
 
-Location: ~/.local/share/worktrees/myorg/myrepo/feature-user-authentication
-Branch: feature/user-authentication
+Location: ~/.local/share/worktrees/myorg/myrepo/feature-auth-calm-willow
+Branch: feature/auth
 Tests: ✓ 47 passing (2.3s)
 
-Ready to implement user authentication feature
+Ready to implement feature
 ```
 
 ## Managing Worktrees
@@ -208,141 +231,79 @@ Ready to implement user authentication feature
 git worktree list
 ```
 
-**Output:**
-```
-/home/user/src/myorg/myrepo                                           abc1234 [main]
-/home/user/.local/share/worktrees/myorg/myrepo/feature-auth           def5678 [feature/auth]
-/home/user/.local/share/worktrees/myorg/myrepo/bugfix-db              ghi9012 [bugfix/database]
-```
-
-### Navigate to Worktree
+### Navigate Between Worktrees
 
 ```bash
 # Direct path
-cd ~/.local/share/worktrees/myorg/myrepo/feature-auth
+cd ~/.local/share/worktrees/myorg/myrepo/<name>
 
-# Or use lazyworktree for interactive selection
+# Interactive selection via lazyworktree TUI
 lazyworktree
 ```
 
-### Remove Worktree
-
-```bash
-# Remove worktree (keeps branch)
-git worktree remove ~/.local/share/worktrees/myorg/myrepo/feature-auth
-
-# Force remove (even with uncommitted changes)
-git worktree remove --force ~/.local/share/worktrees/myorg/myrepo/feature-auth
-```
-
 ### Prune Deleted Worktrees
 
 ```bash
-# Clean up references to manually deleted worktrees
 git worktree prune
 ```
 
 ## Quick Reference
 
-| Situation | Action |
-|-----------|--------|
-| Create new worktree | `git worktree add ~/.local/share/worktrees/<org>/<repo>/<branch> -b <branch>` |
-| Navigate to worktree | `cd ~/.local/share/worktrees/<org>/<repo>/<branch>` or use `lazyworktree` |
-| List worktrees | `git worktree list` |
-| Remove worktree | `git worktree remove <path>` |
-| Cleanup references | `git worktree prune` |
-| Check current branch | `git branch --show-current` |
+| Situation | lazyworktree | Raw git |
+|-----------|-------------|---------|
+| Create | `lazyworktree create --from-branch <b> --silent` | `git worktree add <path> -b <b>` |
+| Create + setup | `lazyworktree create --from-branch <b> --silent --exec "cmd"` | N/A |
+| Create from PR | `lazyworktree create --from-pr <n> --silent` | N/A |
+| Exec in worktree | `lazyworktree exec -w <name> "cmd"` | `cd <path> && cmd` |
+| List (JSON) | `lazyworktree list --json` | N/A |
+| List (paths) | `lazyworktree list --pristine` | `git worktree list` |
+| Delete | `lazyworktree delete --silent <path>` | `git worktree remove <path>` |
+| Rename | `lazyworktree rename <new-name> --silent` | N/A |
+| Navigate | `lazyworktree` (TUI) | `cd <path>` |
+| Prune | `git worktree prune` | `git worktree prune` |
 
-## Common Patterns for Your Home Repository
-
-Based on your NixOS home repository structure:
+## Common Patterns for the Home Repository
 
 ### Building a NixOS Configuration
 
 ```bash
-# From your main home repo at ~/src/home
-git worktree add ~/.local/share/worktrees/vdemeester/home/sakhalin-upgrade -b feature/sakhalin-upgrade
-
-cd ~/.local/share/worktrees/vdemeester/home/sakhalin-upgrade
-
-# Build without affecting main worktree
+cd ~/src/home
+WORKTREE_PATH=$(lazyworktree create --from-branch feature/sakhalin-upgrade --silent)
+cd "$WORKTREE_PATH"
 make host/sakhalin/build
-
-# If successful, deploy
-make host/sakhalin/switch
 ```
 
 ### Working on Multiple Hosts
 
 ```bash
-# Multiple worktrees for different hosts
-git worktree add ~/.local/share/worktrees/vdemeester/home/rhea-jellyfin -b feature/rhea-jellyfin
-git worktree add ~/.local/share/worktrees/vdemeester/home/aion-audio -b feature/aion-audio
+cd ~/src/home
+WT1=$(lazyworktree create --from-branch feature/rhea-jellyfin --silent)
+WT2=$(lazyworktree create --from-branch feature/aion-audio --silent)
 
-# Work on both simultaneously
-cd ~/.local/share/worktrees/vdemeester/home/rhea-jellyfin
-make host/rhea/build
-
-cd ~/.local/share/worktrees/vdemeester/home/aion-audio
-make host/aion/build
+cd "$WT1" && make host/rhea/build
+cd "$WT2" && make host/aion/build
 ```
 
 ### Working on Tekton Pipeline
 
 ```bash
-# Create worktree for pipeline feature
 cd ~/src/tektoncd/pipeline/main
-git worktree add ~/.local/share/worktrees/tektoncd/pipeline/feature-new-resolver -b feature/new-resolver
-
-cd ~/.local/share/worktrees/tektoncd/pipeline/feature-new-resolver
+WORKTREE_PATH=$(lazyworktree create --from-branch feature/new-resolver --silent)
+cd "$WORKTREE_PATH"
 go test ./...
 ```
 
-## Integration with lazyworktree
+## Integration with Pi Extension
 
-The XDG data layout is consistent with lazyworktree's default behavior:
+The pi git extension (`~/.pi/agent/extensions/git/`) provides:
+- **Tool:** `git_worktree` — AI can create/remove/list/exec in worktrees programmatically
+  - `action: "list"` — lists worktrees with dirty/ahead/behind/last_active from lazyworktree
+  - `action: "create"` + `exec: "cmd"` — creates worktree and runs setup command
+  - `action: "exec"` + `branch: "<name>"` + `exec: "cmd"` — runs command inside a worktree
+  - `action: "remove"` — removes worktree (lazyworktree also cleans up the branch)
+- **Commands:** `/worktree` or `/wt` — interactive worktree management
 
-```bash
-# Use lazyworktree to navigate between worktrees
-lazyworktree
-
-# Use aliases defined in your config
-wh   # Jump to home worktrees
-wtp  # Jump to tekton pipeline worktrees
-```
-
-lazyworktree provides:
-- Interactive worktree selection
-- PR/issue integration
-- Quick branch creation
-- Worktree management UI
-
-## Common Mistakes
-
-### ❌ Creating Worktrees in Random Locations
-
-**Problem:** Worktrees scattered across filesystem
-**Fix:** Always use `~/.local/share/worktrees/<org>/<repo>/`
-
-### ❌ Forgetting Org/Repo Structure
-
-**Problem:** Flat structure makes it hard to find worktrees
-**Fix:** Always include org and repo in path
-
-### ❌ Proceeding with Failing Tests
-
-**Problem:** Can't distinguish new bugs from pre-existing issues
-**Fix:** Report failures, get explicit permission to proceed
-
-### ❌ Forgetting to Remove Old Worktrees
-
-**Problem:** Disk space waste, confusion about active work
-**Fix:** Regularly run `git worktree list` and remove completed work
-
-### ❌ Committing from Wrong Worktree
-
-**Problem:** Changes go to wrong branch
-**Fix:** Always verify current branch before committing: `git branch --show-current`
+Both the tool and commands use lazyworktree when available, falling back to raw git.
 
 ## Integration with Other Skills
 
@@ -360,61 +321,40 @@ lazyworktree provides:
 # From main repo, merge work back
 git merge feature/user-authentication
 
-# Remove worktree
-git worktree remove ~/.local/share/worktrees/myorg/myrepo/feature-user-authentication
+# Remove worktree (lazyworktree also deletes the branch)
+lazyworktree delete --silent ~/.local/share/worktrees/myorg/myrepo/<name>
 
-# Delete branch if done
+# Or with raw git (branch cleanup is manual)
+git worktree remove ~/.local/share/worktrees/myorg/myrepo/<name>
 git branch -d feature/user-authentication
 ```
 
-## Examples
+## Common Mistakes
 
-**Example 1: Creating a worktree for a new feature**
-```
-User: "Set up worktree for new authentication feature"
+### ❌ Creating Worktrees in Random Locations
 
-→ Invoke UsingGitWorktrees skill
-→ Announce: "I'm using the UsingGitWorktrees skill to set up an isolated workspace"
-→ Parse remote: git@github.com:myorg/myrepo.git → org=myorg, repo=myrepo
-→ Create: git worktree add ~/.local/share/worktrees/myorg/myrepo/feature-auth -b feature/auth
-→ Setup: npm install
-→ Test: npm test → 47 passing
-→ Report: "Worktree ready at ~/.local/share/worktrees/myorg/myrepo/feature-auth"
-```
+**Problem:** Worktrees scattered across filesystem
+**Fix:** Always use lazyworktree or `~/.local/share/worktrees/<org>/<repo>/`
 
-**Example 2: Working on home repository**
-```
-User: "Create worktree for sakhalin upgrade"
+### ❌ Using raw git when lazyworktree is available
 
-→ Invoke UsingGitWorktrees skill
-→ Parse remote: git@github.com:vdemeester/home.git → org=vdemeester, repo=home
-→ Create: git worktree add ~/.local/share/worktrees/vdemeester/home/sakhalin-upgrade -b feature/sakhalin-upgrade
-→ Setup: nix develop
-→ Build: make dry-build → success
-→ Report: "Worktree ready at ~/.local/share/worktrees/vdemeester/home/sakhalin-upgrade"
-```
+**Problem:** Inconsistent naming, no org/repo detection via gh/glab
+**Fix:** Default to `lazyworktree create --from-branch <b> --silent`
 
-**Example 3: Parallel host configurations**
-```
-User: "I need to work on both rhea and aion configurations simultaneously"
+### ❌ Proceeding with Failing Tests
 
-→ Invoke UsingGitWorktrees skill
-→ Create: ~/.local/share/worktrees/vdemeester/home/rhea-jellyfin
-→ Create: ~/.local/share/worktrees/vdemeester/home/aion-audio
-→ Both worktrees have clean baselines
-→ Can build and test both in parallel
-→ Use lazyworktree to switch between them
-```
+**Problem:** Can't distinguish new bugs from pre-existing issues
+**Fix:** Report failures, get explicit permission to proceed
 
-**Example 4: Cleanup after merge**
-```
-User: "Clean up the authentication worktree now that it's merged"
+### ❌ Forgetting to Remove Old Worktrees
 
-→ Verify feature branch merged: git branch --merged
-→ Remove: git worktree remove ~/.local/share/worktrees/myorg/myrepo/feature-auth
-→ Delete branch: git branch -d feature/auth
-→ Confirm: git worktree list shows worktree removed
-```
+**Problem:** Disk space waste, confusion about active work
+**Fix:** Regularly run `git worktree list` and remove completed work
+
+### ❌ Committing from Wrong Worktree
+
+**Problem:** Changes go to wrong branch
+**Fix:** Always verify current branch before committing: `git branch --show-current`
 
 ## Red Flags
 
@@ -426,10 +366,10 @@ User: "Clean up the authentication worktree now that it's merged"
 - Commit to wrong branch (verify with `git branch --show-current`)
 
 **Always:**
-- Use XDG data directory: `~/.local/share/worktrees/<org>/<repo>/<branch>`
-- Parse org/repo from git remote
+- Prefer lazyworktree over raw git commands
+- Use `--silent` flag for non-interactive scripting
+- Capture the output path: `WORKTREE_PATH=$(lazyworktree create ...)`
 - Auto-detect and run project setup
 - Verify clean test baseline
 - Report clear status when worktree is ready
 - Clean up worktrees when work is merged
-- Use lazyworktree for navigation when available