refactor: enhance testing documentation and command help

- Updated CLAUDE.md to reflect the introduction of BATS tests for core functions and clarified the manual testing process.
- Enhanced CONTRIBUTING.md with detailed instructions for running automated tests and manual testing across different platforms.
- Added help command functionality to various command scripts, providing users with guidance on command usage.
- Introduced a new launch.sh script for managing editor and AI tool interactions, improving the overall command structure and user experience.
- Merged copy pattern handling into a single function for better maintainability and clarity in the copy command workflow.

Author: helizaga

CLAUDE.md

@@ -12,9 +12,12 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 - **Development/testing**: `./bin/gtr <command>` (direct execution)
 - **User-facing docs**: Always reference `git gtr`, never `./bin/gtr`
 
-## CRITICAL: No Automated Tests
+## Testing
 
-This project has **no test suite**. All testing is manual. After any change, run the relevant smoke tests:
+This project uses **BATS tests** for core functions and **manual smoke tests** for end-to-end workflows. After any change:
+
+1. Run automated tests: `bats tests/`
+2. Run relevant manual smoke tests:
 
 ```bash
 ./bin/gtr new test-feature          # Create worktree
@@ -25,7 +28,7 @@ This project has **no test suite**. All testing is manual. After any change, run
 ./bin/gtr rm test-feature           # Clean up
 ```
 
-For exhaustive testing (hooks, copy patterns, adapters, `--force`, `--from-current`, etc.), see the full checklist in CONTRIBUTING.md or `.github/instructions/testing.instructions.md`.
+For exhaustive manual testing (hooks, copy patterns, adapters, `--force`, `--from-current`, etc.), see the full checklist in CONTRIBUTING.md or `.github/instructions/testing.instructions.md`.
 
 **Tip**: Use a disposable repo for testing to avoid polluting your working tree:
 

CONTRIBUTING.md

@@ -150,7 +150,20 @@ For changes to core functionality (`lib/*.sh`):
 
 ### Testing
 
-Currently, testing is manual. Please test your changes on:
+#### Automated Tests (BATS)
+
+Run the test suite before submitting PRs:
+
+```bash
+bats tests/            # Run all tests
+bats tests/copy_safety.bats  # Run a specific test file
+```
+
+CI runs ShellCheck + BATS automatically on all PRs (`.github/workflows/lint.yml`).
+
+#### Manual Testing
+
+Please also test your changes manually on:
 
 1. **macOS** (if available)
 2. **Linux** (Ubuntu, Fedora, or Arch recommended)

bin/gtr

@@ -29,6 +29,7 @@ resolve_script_dir() {
 . "$GTR_DIR/lib/hooks.sh"
 . "$GTR_DIR/lib/provider.sh"
 . "$GTR_DIR/lib/adapters.sh"
+. "$GTR_DIR/lib/launch.sh"
 
 # Source command handlers
 for _cmd_file in "$GTR_DIR"/lib/commands/*.sh; do

completions/_git-gtr

@@ -172,15 +172,15 @@ _git-gtr() {
                 '--local[Use local git config]' \
                 '--global[Use global git config]' \
                 '--system[Use system git config]' \
-                '*:config key:(gtr.worktrees.dir gtr.worktrees.prefix gtr.defaultBranch gtr.editor.default gtr.ai.default gtr.provider gtr.copy.include gtr.copy.exclude gtr.copy.includeDirs gtr.copy.excludeDirs gtr.hook.postCreate gtr.hook.preRemove gtr.hook.postRemove gtr.hook.postCd)'
+                '*:config key:(gtr.worktrees.dir gtr.worktrees.prefix gtr.defaultBranch gtr.editor.default gtr.editor.workspace gtr.ai.default gtr.provider gtr.copy.include gtr.copy.exclude gtr.copy.includeDirs gtr.copy.excludeDirs gtr.hook.postCreate gtr.hook.preRemove gtr.hook.postRemove gtr.hook.postCd)'
               ;;
             set|add|unset)
               # Write operations only support --local and --global
               # (--system may require root or appropriate file permissions)
               _arguments \
                 '--local[Use local git config]' \
                 '--global[Use global git config]' \
-                '*:config key:(gtr.worktrees.dir gtr.worktrees.prefix gtr.defaultBranch gtr.editor.default gtr.ai.default gtr.provider gtr.copy.include gtr.copy.exclude gtr.copy.includeDirs gtr.copy.excludeDirs gtr.hook.postCreate gtr.hook.preRemove gtr.hook.postRemove gtr.hook.postCd)'
+                '*:config key:(gtr.worktrees.dir gtr.worktrees.prefix gtr.defaultBranch gtr.editor.default gtr.editor.workspace gtr.ai.default gtr.provider gtr.copy.include gtr.copy.exclude gtr.copy.includeDirs gtr.copy.excludeDirs gtr.hook.postCreate gtr.hook.preRemove gtr.hook.postRemove gtr.hook.postCd)'
               ;;
           esac
         fi

completions/git-gtr.fish

@@ -136,6 +136,7 @@ complete -f -c git -n '__fish_git_gtr_using_command config' -a "
   gtr.worktrees.prefix\t'Worktree folder prefix'
   gtr.defaultBranch\t'Default branch'
   gtr.editor.default\t'Default editor'
+  gtr.editor.workspace\t'Path to workspace file (.code-workspace)'
   gtr.ai.default\t'Default AI tool'
   gtr.provider\t'Hosting provider (github, gitlab)'
   gtr.copy.include\t'Files to copy'

completions/gtr.bash

@@ -128,15 +128,15 @@ _git_gtr() {
             if [[ "$cur" == -* ]]; then
               COMPREPLY=($(compgen -W "--local --global --system" -- "$cur"))
             else
-              COMPREPLY=($(compgen -W "gtr.worktrees.dir gtr.worktrees.prefix gtr.defaultBranch gtr.editor.default gtr.ai.default gtr.provider gtr.copy.include gtr.copy.exclude gtr.copy.includeDirs gtr.copy.excludeDirs gtr.hook.postCreate gtr.hook.preRemove gtr.hook.postRemove gtr.hook.postCd" -- "$cur"))
+              COMPREPLY=($(compgen -W "gtr.worktrees.dir gtr.worktrees.prefix gtr.defaultBranch gtr.editor.default gtr.editor.workspace gtr.ai.default gtr.provider gtr.copy.include gtr.copy.exclude gtr.copy.includeDirs gtr.copy.excludeDirs gtr.hook.postCreate gtr.hook.preRemove gtr.hook.postRemove gtr.hook.postCd" -- "$cur"))
             fi
             ;;
           set|add|unset)
             # Write operations only support --local and --global (--system requires root)
             if [[ "$cur" == -* ]]; then
               COMPREPLY=($(compgen -W "--local --global" -- "$cur"))
             else
-              COMPREPLY=($(compgen -W "gtr.worktrees.dir gtr.worktrees.prefix gtr.defaultBranch gtr.editor.default gtr.ai.default gtr.provider gtr.copy.include gtr.copy.exclude gtr.copy.includeDirs gtr.copy.excludeDirs gtr.hook.postCreate gtr.hook.preRemove gtr.hook.postRemove gtr.hook.postCd" -- "$cur"))
+              COMPREPLY=($(compgen -W "gtr.worktrees.dir gtr.worktrees.prefix gtr.defaultBranch gtr.editor.default gtr.editor.workspace gtr.ai.default gtr.provider gtr.copy.include gtr.copy.exclude gtr.copy.includeDirs gtr.copy.excludeDirs gtr.hook.postCreate gtr.hook.preRemove gtr.hook.postRemove gtr.hook.postCd" -- "$cur"))
             fi
             ;;
         esac

docs/troubleshooting.md

@@ -165,7 +165,7 @@ git gtr config get gtr.copy.exclude
 git-worktree-runner/
 ├── bin/
 │   ├── git-gtr         # Git subcommand entry point (wrapper)
-│   └── gtr             # Core implementation (1000+ lines)
+│   └── gtr             # Entry point (~105 lines, sources lib/*.sh)
 ├── lib/                 # Core libraries
 │   ├── core.sh         # Git worktree operations
 │   ├── config.sh       # Configuration management
@@ -211,9 +211,10 @@ git-worktree-runner/
 
 ### Testing Approach
 
-- Core functionality tested across macOS, Linux, WSL2
-- Manual testing with Cursor, VS Code, Aider, Claude Code
-- Used in production for parallel agent workflows
+- **Automated tests**: BATS test suite (`tests/`) covers core functions
+- **CI**: ShellCheck linting + BATS tests run on all PRs
+- **Manual testing**: End-to-end workflows tested across macOS, Linux, WSL2
+- **Production use**: Battle-tested with Cursor, VS Code, Aider, Claude Code
 - Community testing appreciated - please report issues!
 
 ### Experimental Features

lib/commands/adapter.sh

@@ -1,87 +1,67 @@
 #!/usr/bin/env bash
 
 # Adapter command (list available adapters)
-cmd_adapter() {
-  echo "Available Adapters"
-  echo ""
 
-  # Editor adapters
-  echo "Editor Adapters:"
+# Print adapter listing for a given type
+# Usage: _print_adapter_list <label> <registry> <subdir> <can_func> <load_func>
+_print_adapter_list() {
+  local label="$1" registry="$2" subdir="$3" can_func="$4" load_func="$5"
+
+  echo "$label:"
   echo ""
   printf "%-15s %-15s %s\n" "NAME" "STATUS" "NOTES"
   printf "%-15s %-15s %s\n" "---------------" "---------------" "-----"
 
-  # Registry-defined editor adapters
-  local listed_editors=" " line adapter_name
+  # Registry-defined adapters
+  local listed=" " line adapter_name
   while IFS= read -r line; do
     [ -z "$line" ] && continue
     adapter_name="${line%%|*}"
-    listed_editors="$listed_editors$adapter_name "
-    _load_from_editor_registry "$line"
-    if editor_can_open 2>/dev/null; then
+    listed="$listed$adapter_name "
+    "$load_func" "$line"
+    if $can_func 2>/dev/null; then
       printf "%-15s %-15s %s\n" "$adapter_name" "[ready]" ""
     else
       printf "%-15s %-15s %s\n" "$adapter_name" "[missing]" "Not found in PATH"
     fi
   done <<EOF
-$_EDITOR_REGISTRY
+$registry
 EOF
 
-  # File-only editor adapters (custom ones not in registry)
+  # File-only adapters (custom ones not in registry)
   local adapter_file
-  for adapter_file in "$GTR_DIR"/adapters/editor/*.sh; do
+  for adapter_file in "$GTR_DIR/adapters/$subdir"/*.sh; do
     [ -f "$adapter_file" ] || continue
     adapter_name=$(basename "$adapter_file" .sh)
-    case "$listed_editors" in *" $adapter_name "*) continue ;; esac
+    case "$listed" in *" $adapter_name "*) continue ;; esac
     # shellcheck disable=SC1090
     . "$adapter_file"
-    if editor_can_open 2>/dev/null; then
+    if $can_func 2>/dev/null; then
       printf "%-15s %-15s %s\n" "$adapter_name" "[ready]" ""
     else
       printf "%-15s %-15s %s\n" "$adapter_name" "[missing]" "Not found in PATH"
     fi
   done
+}
 
+cmd_adapter() {
+  if [ "${1:-}" = "-h" ] || [ "${1:-}" = "--help" ]; then
+    show_command_help
+  fi
+
+  echo "Available Adapters"
   echo ""
+
+  _print_adapter_list "Editor Adapters" "$_EDITOR_REGISTRY" "editor" "editor_can_open" "_load_from_editor_registry"
+
   echo ""
-  echo "AI Tool Adapters:"
   echo ""
-  printf "%-15s %-15s %s\n" "NAME" "STATUS" "NOTES"
-  printf "%-15s %-15s %s\n" "---------------" "---------------" "-----"
-
-  # Registry-defined AI adapters
-  local listed_ais=" "
-  while IFS= read -r line; do
-    [ -z "$line" ] && continue
-    adapter_name="${line%%|*}"
-    listed_ais="$listed_ais$adapter_name "
-    _load_from_ai_registry "$line"
-    if ai_can_start 2>/dev/null; then
-      printf "%-15s %-15s %s\n" "$adapter_name" "[ready]" ""
-    else
-      printf "%-15s %-15s %s\n" "$adapter_name" "[missing]" "Not found in PATH"
-    fi
-  done <<EOF
-$_AI_REGISTRY
-EOF
 
-  # File-only AI adapters (custom ones not in registry)
-  for adapter_file in "$GTR_DIR"/adapters/ai/*.sh; do
-    [ -f "$adapter_file" ] || continue
-    adapter_name=$(basename "$adapter_file" .sh)
-    case "$listed_ais" in *" $adapter_name "*) continue ;; esac
-    # shellcheck disable=SC1090
-    . "$adapter_file"
-    if ai_can_start 2>/dev/null; then
-      printf "%-15s %-15s %s\n" "$adapter_name" "[ready]" ""
-    else
-      printf "%-15s %-15s %s\n" "$adapter_name" "[missing]" "Not found in PATH"
-    fi
-  done
+  _print_adapter_list "AI Tool Adapters" "$_AI_REGISTRY" "ai" "ai_can_start" "_load_from_ai_registry"
 
   echo ""
   echo ""
   echo "Tip: Set defaults with:"
   echo "   git gtr config set gtr.editor.default <name>"
   echo "   git gtr config set gtr.ai.default <name>"
-}
+}

lib/commands/ai.sh

@@ -18,6 +18,9 @@ cmd_ai() {
         ai_args=("$@")
         break
         ;;
+      -h|--help)
+        show_command_help
+        ;;
       -*)
         log_error "Unknown flag: $1"
         exit 1
@@ -48,13 +51,13 @@ cmd_ai() {
     exit 1
   fi
 
-  # Load AI adapter
-  load_ai_adapter "$ai_tool" || exit 1
-
   resolve_repo_context || exit 1
   # shellcheck disable=SC2154
   local repo_root="$_ctx_repo_root" base_dir="$_ctx_base_dir" prefix="$_ctx_prefix"
 
+  # Load AI adapter (after context — fail fast on bad repo first)
+  load_ai_adapter "$ai_tool" || exit 1
+
   # Resolve target branch
   local worktree_path branch
   resolve_worktree "$identifier" "$repo_root" "$base_dir" "$prefix" || exit 1

lib/commands/clean.sh

@@ -131,6 +131,9 @@ cmd_clean() {
         dry_run=1
         shift
         ;;
+      -h|--help)
+        show_command_help
+        ;;
       -*)
         log_error "Unknown flag: $1"
         exit 1