refactor: enhance adapter management and command structure

- Introduced a new adapter loading infrastructure in `lib/adapters.sh`, consolidating editor and AI adapter definitions into registries for improved maintainability.
- Updated the `bin/gtr` script to source command handlers dynamically, streamlining command execution.
- Added new commands for listing available adapters and starting AI tools, enhancing user interaction and functionality.
- Removed outdated individual adapter scripts, transitioning to a registry-based approach for standard adapters, which simplifies the addition of new tools.
- Improved documentation in various instruction files to clarify when to use registry entries versus custom adapter files.

Author: helizaga

.github/instructions/ai.instructions.md

@@ -2,11 +2,26 @@
 applyTo: adapters/ai/**/*.sh
 ---
 
-# AI Instructions
+# AI Adapter Instructions
 
-## Adding Features
+## When to Use a File vs Registry
 
-### New AI Tool Adapter (`adapters/ai/<name>.sh`)
+Most AI tools are defined as **registry entries** in `lib/adapters.sh` — no adapter file needed.
+Only create an adapter file in `adapters/ai/` for tools that need **custom behavior** beyond the standard builder (see `claude.sh` or `cursor.sh` for examples).
+
+## Adding a Standard AI Tool (Registry)
+
+Add a line to `_AI_REGISTRY` in `lib/adapters.sh`:
+
+```
+yourname|yourcmd|ToolName not found. Install with: ...|Extra info;More info
+```
+
+Format: `name|cmd|err_msg|info_lines` (info lines are semicolon-separated)
+
+## Adding a Custom AI Tool (File Override)
+
+Create `adapters/ai/<name>.sh` implementing:
 
 ```bash
 #!/usr/bin/env bash
@@ -27,7 +42,9 @@ ai_start() {
 }
 ```
 
-**Also update**: Same as editor adapters (README, completions, help text)
+File-based adapters take precedence over registry entries of the same name.
+
+**Also update**: README, completions (bash/zsh/fish), help text in `lib/commands/help.sh`
 
 ## Contract & Guidelines
 
@@ -38,5 +55,4 @@ ai_start() {
 - Accept extra args after `--`: preserve ordering (`ai_start` receives already-shifted args).
 - Prefer fast startup; heavy initialization belongs in hooks (`postCreate`), not adapters.
 - When adding adapter: update `cmd_help`, README tool list, and completions (bash/zsh/fish).
-- Test manually: `bash -c 'source adapters/ai/<tool>.sh && ai_can_start && echo OK'`.
 - Inspect function definition if needed: `declare -f ai_start`.

.github/instructions/editor.instructions.md

@@ -2,11 +2,28 @@
 applyTo: adapters/editor/**/*.sh
 ---
 
-# Editor Instructions
+# Editor Adapter Instructions
 
-## Adding Features
+## When to Use a File vs Registry
 
-### New Editor Adapter (`adapters/editor/<name>.sh`)
+Most editors are defined as **registry entries** in `lib/adapters.sh` — no adapter file needed.
+Only create an adapter file in `adapters/editor/` for editors that need **custom behavior** beyond what the standard/terminal builders provide (see `nano.sh` for an example).
+
+## Adding a Standard Editor (Registry)
+
+Add a line to `_EDITOR_REGISTRY` in `lib/adapters.sh`:
+
+```
+yourname|yourcmd|standard|EditorName not found. Install from https://...|flags
+```
+
+Format: `name|cmd|type|err_msg|flags`
+- `type`: `standard` (GUI app) or `terminal` (runs in terminal)
+- `flags`: comma-separated — `workspace` (supports .code-workspace), `background` (terminal bg)
+
+## Adding a Custom Editor (File Override)
+
+Create `adapters/editor/<name>.sh` implementing:
 
 ```bash
 #!/usr/bin/env bash
@@ -26,20 +43,21 @@ editor_open() {
 }
 ```
 
+File-based adapters take precedence over registry entries of the same name.
+
 **Also update**:
 
 - README.md (setup instructions)
 - All three completion files: `completions/gtr.bash`, `completions/_git-gtr`, `completions/gtr.fish`
-- Help text in `bin/gtr` (`cmd_help` function)
+- Help text in `lib/commands/help.sh` (`cmd_help` function)
 
 ## Contract & Guidelines
 
 - Required functions: `editor_can_open` (probe via `command -v`), `editor_open <path>`.
 - Quote all paths; support spaces. Avoid changing PWD globally—no subshell needed (editor opens path).
 - Use `log_error` with actionable install guidance if command missing.
 - Keep adapter lean: no project scans, no blocking prompts.
-- Naming: file name = tool name (`zed.sh` → `zed` flag). Avoid uppercase.
+- Naming: file/registry name = tool name (`zed` → `zed` flag). Avoid uppercase.
 - Update: README editor list, completions (bash/zsh/fish), help (`Available editors:`), optional screenshots.
-- Manual test: `bash -c 'source adapters/editor/<tool>.sh && editor_can_open && editor_open . || echo fail'`.
 - Fallback behavior: if editor absent, fail clearly; do NOT silently defer to file browser.
 - Inspect function definition if needed: `declare -f editor_open`.

.github/instructions/lib.instructions.md

@@ -21,7 +21,7 @@ applyTo: lib/**/*.sh
 
 ## Change Guidelines
 
-- Preserve adapter contracts; do not rename exported functions used by `bin/gtr`.
+- Preserve adapter contracts; do not rename exported functions used by command handlers in `lib/commands/`.
 - Add new config keys with `gtr.<name>` prefix; avoid collisions.
 - For performance-sensitive loops (e.g. directory scans) prefer built-ins (`find`, `grep`) with minimal subshells.
 - Any new Git command: add fallback for older versions or guard with detection.

.github/workflows/lint.yml

@@ -18,7 +18,7 @@ jobs:
 
       - name: Run ShellCheck
         run: |
-          shellcheck bin/gtr bin/git-gtr lib/*.sh adapters/editor/*.sh adapters/ai/*.sh
+          shellcheck bin/gtr bin/git-gtr lib/*.sh lib/commands/*.sh adapters/editor/*.sh adapters/ai/*.sh
 
   test:
     name: Tests

CLAUDE.md

@@ -39,28 +39,30 @@ mkdir -p /tmp/gtr-test && cd /tmp/gtr-test && git init && git commit --allow-emp
 ### Binary Structure
 
 - `bin/git-gtr` — Thin wrapper enabling `git gtr` subcommand invocation
-- `bin/gtr` — Main script (~1960 lines), contains `main()` dispatcher + all `cmd_*` handlers
+- `bin/gtr` — Entry point (~105 lines): sources libraries and commands, contains `main()` dispatcher
 
 ### Module Structure
 
-| File              | Purpose                                                                                                     |
-| ----------------- | ----------------------------------------------------------------------------------------------------------- |
-| `lib/core.sh`     | Worktree CRUD: `create_worktree`, `remove_worktree`, `list_worktrees`, `resolve_target`, `resolve_base_dir` |
-| `lib/config.sh`   | Git config wrapper with precedence: `cfg_get`, `cfg_default`, `cfg_get_all`                                 |
-| `lib/copy.sh`     | File/directory copying with glob patterns: `copy_patterns`, `copy_directories`                              |
-| `lib/hooks.sh`    | Hook execution: `run_hooks_in` for postCreate/preRemove/postRemove                                          |
-| `lib/ui.sh`       | Logging (`log_error`, `log_info`, `log_warn`), prompts, formatting                                          |
-| `lib/platform.sh` | OS detection, GUI helpers                                                                                   |
+| File               | Purpose                                                                                                     |
+| ------------------ | ----------------------------------------------------------------------------------------------------------- |
+| `lib/core.sh`      | Worktree CRUD: `create_worktree`, `remove_worktree`, `list_worktrees`, `resolve_target`, `resolve_base_dir` |
+| `lib/config.sh`    | Git config wrapper with precedence: `cfg_get`, `cfg_default`, `cfg_get_all`                                 |
+| `lib/copy.sh`      | File/directory copying with glob patterns: `copy_patterns`, `copy_directories`                              |
+| `lib/hooks.sh`     | Hook execution: `run_hooks_in` for postCreate/preRemove/postRemove                                          |
+| `lib/ui.sh`        | Logging (`log_error`, `log_info`, `log_warn`), prompts, formatting                                          |
+| `lib/platform.sh`  | OS detection, GUI helpers                                                                                   |
+| `lib/adapters.sh`  | Adapter registry, builder functions, generic fallbacks, loader functions                                    |
+| `lib/commands/*.sh` | One file per subcommand: `cmd_create`, `cmd_remove`, etc. (16 files)                                       |
 
 ### Adapters
 
-Editor adapters in `adapters/editor/` and AI adapters in `adapters/ai/` are dynamically sourced via `load_editor_adapter()` and `load_ai_adapter()` in `bin/gtr`.
+Most adapters are defined declaratively in the **adapter registry** (`lib/adapters.sh`) using pipe-delimited entries. Custom adapters that need special logic remain as override files in `adapters/editor/` and `adapters/ai/`.
 
-**Editor adapters** (atom, cursor, emacs, idea, nano, nvim, pycharm, sublime, vim, vscode, webstorm, zed): implement `editor_can_open()` + `editor_open(path)`.
+**Registry-defined adapters**: atom, cursor, emacs, idea, nvim, pycharm, sublime, vim, vscode, webstorm, zed (editors) and aider, auggie, codex, continue, copilot, gemini, opencode (AI).
 
-**AI adapters** (aider, auggie, claude, codex, continue, copilot, cursor, gemini, opencode): implement `ai_can_start()` + `ai_start(path, args...)`.
+**Custom adapter files**: `adapters/editor/nano.sh`, `adapters/ai/claude.sh`, `adapters/ai/cursor.sh` — these implement `editor_can_open()`/`editor_open()` or `ai_can_start()`/`ai_start()` directly.
 
-**Generic fallback**: `GTR_EDITOR_CMD` / `GTR_AI_CMD` env vars allow custom tools without adapter files.
+**Loading order**: file override → registry → generic PATH fallback. `GTR_EDITOR_CMD` / `GTR_AI_CMD` env vars allow custom tools without adapters.
 
 ### Command Flow
 
@@ -106,15 +108,17 @@ cmd_editor() → resolve_target() → load_editor_adapter() → editor_open()
 
 ### Adding a New Command
 
-1. Add `cmd_<name>()` function in `bin/gtr`
-2. Add case entry in `main()` dispatcher (around line 71)
-3. Add help text in `cmd_help()`
+1. Create `lib/commands/<name>.sh` with `cmd_<name>()` function
+2. Add case entry in `main()` dispatcher in `bin/gtr`
+3. Add help text in `lib/commands/help.sh`
 4. Update all three completion files: `completions/gtr.bash`, `completions/_git-gtr`, `completions/git-gtr.fish`
 5. Update README.md
 
 ### Adding an Adapter
 
-Create `adapters/{editor,ai}/<name>.sh` implementing the two required functions (see existing adapters for patterns). Then update: help text in `cmd_help()` and `load_*_adapter()`, all three completions, README.md.
+**Standard adapters** (just a command name + error message): Add an entry to `_EDITOR_REGISTRY` or `_AI_REGISTRY` in `lib/adapters.sh`. Then update: help text in `lib/commands/help.sh`, all three completions, README.md.
+
+**Custom adapters** (special logic needed): Create `adapters/{editor,ai}/<name>.sh` implementing the two required functions (see `adapters/ai/claude.sh` for an example). File-based adapters take priority over registry entries.
 
 ### Updating the Version
 

CONTRIBUTING.md

@@ -32,17 +32,25 @@ We welcome feature suggestions! Please:
 
 ```
 git-worktree-runner/
-├── bin/gtr              # Main executable dispatcher
+├── bin/gtr              # Main executable (~105 lines: sources libs, dispatches commands)
 ├── lib/                 # Core functionality
-│   ├── core.sh         # Git worktree operations
+│   ├── ui.sh           # User interface (logging, prompts)
 │   ├── config.sh       # Configuration (git-config wrapper)
 │   ├── platform.sh     # OS-specific utilities
-│   ├── ui.sh           # User interface (logging, prompts)
+│   ├── core.sh         # Git worktree operations
 │   ├── copy.sh         # File copying logic
-│   └── hooks.sh        # Hook execution
-├── adapters/           # Pluggable integrations
-│   ├── editor/         # Editor adapters (cursor, vscode, zed)
-│   └── ai/             # AI tool adapters (aider)
+│   ├── hooks.sh        # Hook execution
+│   ├── provider.sh     # GitHub/GitLab provider detection
+│   ├── adapters.sh     # Adapter registries, builders, and loaders
+│   └── commands/       # Command handlers (one file per command)
+│       ├── create.sh   # cmd_create + helpers
+│       ├── remove.sh   # cmd_remove
+│       ├── rename.sh   # cmd_rename
+│       ├── ...         # (16 files total, one per command)
+│       └── help.sh     # cmd_help
+├── adapters/           # Custom adapter overrides (non-registry)
+│   ├── editor/nano.sh  # nano (custom terminal behavior)
+│   └── ai/             # claude.sh, cursor.sh (custom logic)
 ├── completions/        # Shell completions (bash, zsh, fish)
 └── templates/          # Example configs and scripts
 ```
@@ -92,60 +100,43 @@ do_something() {
 
 #### Adding an Editor Adapter
 
-1. Create `adapters/editor/yourname.sh`:
+Most editors follow a standard pattern and can be added as a **registry entry** in `lib/adapters.sh` (no separate file needed).
 
-```bash
-#!/usr/bin/env bash
-# YourEditor adapter
+**Option A: Registry entry** (preferred for standard editors)
 
-editor_can_open() {
-  command -v yourcommand >/dev/null 2>&1
-}
+Add a line to `_EDITOR_REGISTRY` in `lib/adapters.sh`:
 
-editor_open() {
-  local path="$1"
+```
+yourname|yourcmd|standard|YourEditor not found. Install from https://...|flags
+```
 
-  if ! editor_can_open; then
-    log_error "YourEditor not found. Install from https://..."
-    return 1
-  fi
+Format: `name|cmd|type|err_msg|flags` where:
+- `type`: `standard` (GUI app) or `terminal` (runs in current terminal)
+- `flags`: comma-separated — `workspace` (supports .code-workspace files), `background` (run in background)
 
-  yourcommand "$path"
-}
-```
+**Option B: Custom adapter file** (for editors with non-standard behavior)
+
+Create `adapters/editor/yourname.sh` implementing `editor_can_open()` and `editor_open()`. See `adapters/editor/nano.sh` for an example.
 
-2. Update README.md with setup instructions
-3. Update completions to include new editor
-4. Test on macOS, Linux, and Windows if possible
+**Also update**: README.md, all three completion files, help text in `lib/commands/help.sh`.
 
 #### Adding an AI Tool Adapter
 
-1. Create `adapters/ai/yourtool.sh`:
+**Option A: Registry entry** (preferred for standard CLI tools)
 
-```bash
-#!/usr/bin/env bash
-# YourTool AI adapter
+Add a line to `_AI_REGISTRY` in `lib/adapters.sh`:
 
-ai_can_start() {
-  command -v yourtool >/dev/null 2>&1
-}
+```
+yourname|yourcmd|YourTool not found. Install with: ...|Extra info line 1;Extra info line 2
+```
 
-ai_start() {
-  local path="$1"
-  shift
+Format: `name|cmd|err_msg|info_lines` (info lines are semicolon-separated).
 
-  if ! ai_can_start; then
-    log_error "YourTool not found. Install with: ..."
-    return 1
-  fi
+**Option B: Custom adapter file** (for tools with non-standard behavior)
 
-  (cd "$path" && yourtool "$@")
-}
-```
+Create `adapters/ai/yourname.sh` implementing `ai_can_start()` and `ai_start()`. See `adapters/ai/claude.sh` for an example.
 
-2. Update README.md
-3. Update completions
-4. Add example usage
+**Also update**: README.md, completions, help text.
 
 #### Adding Core Features