ace-git-worktree 0.19.0

data/handbook/agents/worktree.ag.md

@@ -0,0 +1,189 @@
+---
+doc-type: agent
+title: Worktree Agent
+purpose: Documentation for ace-git-worktree/handbook/agents/worktree.ag.md
+ace-docs:
+  last-updated: 2025-12-27
+  last-checked: 2026-03-21
+---
+
+# Worktree Agent
+
+A specialized agent for managing git worktrees with task-aware automation. Handles creation, listing, switching, removal, and cleanup of worktrees integrated with ACE's task management system.
+
+## Capabilities
+
+### Task-Aware Operations
+- Create worktrees for specific tasks with automatic metadata integration
+- Fetch task information from ace-taskflow
+- Update task status and add worktree metadata
+- Commit task changes before worktree creation
+
+### Traditional Worktree Operations
+- Create worktrees for traditional branch-based development
+- List all worktrees with filtering and formatting options
+- Switch between worktrees using various identifiers
+- Remove worktrees with safety checks and cleanup
+- Prune deleted worktrees and orphaned directories
+
+### Configuration Management
+- Show and validate worktree configuration
+- Display configuration file locations and settings
+- Support for custom naming conventions and behaviors
+
+## Usage Examples
+
+### Task-Aware Workflow
+```bash
+# Create worktree for task 081
+@worktree create --task 081
+
+# Switch to task worktree
+@worktree switch 081
+
+# Remove task worktree
+@worktree remove --task 081
+```
+
+### Traditional Workflow
+```bash
+# Create worktree for feature branch
+@worktree create feature-branch
+
+# List all worktrees
+@worktree list --show-tasks
+
+# Switch to worktree
+@worktree switch feature-branch
+```
+
+### Management Operations
+```bash
+# List with filtering
+@worktree list --task-associated --format json
+
+# Clean up deleted worktrees
+@worktree prune --cleanup-directories
+
+# Show configuration
+@worktree config --validate
+```
+
+## Configuration
+
+The worktree agent uses configuration from `.ace/git/worktree.yml`:
+
+```yaml
+git:
+  worktree:
+    root_path: ".ace-wt"
+    mise_trust_auto: true
+    task:
+      directory_format: "task.{id}"
+      branch_format: "{id}-{slug}"
+      auto_mark_in_progress: true
+      auto_commit_task: true
+      add_worktree_metadata: true
+```
+
+## Integration Points
+
+- **ace-taskflow**: Task metadata fetching and status updates
+- **ace-git-commit**: Consistent commit message generation
+- **ace-git**: Safe git command execution
+- **ace-core**: Configuration cascade management
+
+## Expected Parameters
+
+The worktree agent accepts standard CLI parameters:
+
+### create
+- `--task <task-id>`: Create worktree for specific task
+- `--path <path>`: Custom worktree path
+- `--dry-run`: Preview without creating
+- `--no-mise-trust`: Skip automatic mise trust
+- `--no-status-update`: Skip task status update
+- `--no-commit`: Skip committing task changes
+
+### list
+- `--format <format>`: Output format (table, json, simple)
+- `--show-tasks`: Include task associations
+- `--task-associated`: Filter by task association
+- `--search <pattern>`: Filter by search pattern
+
+### switch
+- `identifier`: Worktree identifier (task ID, branch name, directory, path)
+- `--verbose`: Show detailed information
+
+### remove
+- `--task <task-id>`: Remove task worktree
+- `--force`: Force removal with uncommitted changes
+- `--keep-directory`: Keep worktree directory
+- `--dry-run`: Preview without removing
+
+### prune
+- `--cleanup-directories`: Remove orphaned directories
+- `--dry-run`: Preview changes
+- `--verbose`: Detailed output
+
+### config
+- `--show`: Show current configuration
+- `--validate`: Validate configuration
+- `--files`: Show configuration file locations
+
+## Error Handling
+
+The worktree agent handles common error conditions:
+
+- **Task not found**: Validates task ID existence before creation
+- **Not in git repository**: Checks git repository status
+- **Configuration invalid**: Validates configuration before operations
+- **Worktree conflicts**: Detects existing worktrees and provides alternatives
+- **Permission issues**: Validates directory permissions and access
+- **Uncommitted changes**: Warns about changes before removal
+
+## Output Formats
+
+### Table Format
+Human-readable table with columns for Task, Branch, Path, and Status.
+
+### JSON Format
+Machine-readable JSON with complete worktree metadata for scripting and automation.
+
+### Simple Format
+Concise format for quick overviews and scripting.
+
+## Response Template
+
+**Operation:** [create/list/switch/remove/prune/config]
+**Worktree(s):** [Worktree information]
+**Status:** [Success/Failure with details]
+**Location(s):** [Relevant paths]
+**Next Steps:** [Recommended follow-up actions]
+
+## Best Practices
+
+1. **Use task-aware creation** for ACE workflow integration
+2. **Validate configuration** before operations
+3. **Use dry-run** to preview changes
+4. **Clean up worktrees** when tasks are complete
+5. **Prune regularly** to maintain clean repository state
+6. **Check git status** before removing worktrees with changes
+
+## Integration with AI Agents
+
+The worktree agent provides deterministic output suitable for AI automation:
+
+```bash
+# Get worktree path for task
+WORKTREE_PATH=$(ace-git-worktree switch 081)
+
+# Get worktree status as JSON
+STATUS=$(ace-git-worktree list --format json --show-tasks)
+
+# Create worktree and verify creation
+RESULT=$(ace-git-worktree create --task 081 --dry-run --format json)
+if echo "$RESULT" | jq -e '.success'; then
+  echo "Worktree creation would succeed"
+fi
+```

data/handbook/skills/as-git-worktree/SKILL.md

@@ -0,0 +1,27 @@
+---
+name: as-git-worktree
+description: Manage git worktrees with task-aware automation
+# bundle: wfi://git/worktree
+# agent: Bash
+user-invocable: true
+allowed-tools:
+  - Bash(ace-git-worktree:*)
+  - Bash(ace-bundle:*)
+  - Read
+argument-hint: "[create|list|switch|remove|prune|config] [options]"
+last_modified: 2026-01-09
+source: ace-git-worktree
+integration:
+  targets:
+    - claude
+    - codex
+    - gemini
+    - opencode
+    - pi
+skill:
+  kind: workflow
+  execution:
+    workflow: wfi://git/worktree
+---
+
+Load and run `ace-bundle wfi://git/worktree` in the current project, then follow the loaded workflow as the source of truth and execute it end-to-end instead of only summarizing it.

data/handbook/skills/as-git-worktree-create/SKILL.md

@@ -0,0 +1,21 @@
+---
+name: as-git-worktree-create
+description: Create task-aware or branch-based git worktrees with guided automation
+# bundle: wfi://git/worktree-create
+# context: no-fork
+# agent: Bash
+user-invocable: true
+allowed-tools:
+  - Bash(ace-git-worktree:*)
+  - Bash(ace-bundle:*)
+  - Read
+argument-hint: [--task TASK_ID|--branch BRANCH]
+last_modified: 2026-03-12
+source: ace-git-worktree
+skill:
+  kind: workflow
+  execution:
+    workflow: wfi://git/worktree-create
+---
+
+Load and run `ace-bundle wfi://git/worktree-create` in the current project, then follow the loaded workflow as the source of truth and execute it end-to-end instead of only summarizing it.

data/handbook/skills/as-git-worktree-manage/SKILL.md

@@ -0,0 +1,20 @@
+---
+name: as-git-worktree-manage
+description: Manage existing git worktrees for listing, switching, cleanup, and removal
+# bundle: wfi://git/worktree-manage
+# agent: Bash
+user-invocable: true
+allowed-tools:
+  - Bash(ace-git-worktree:*)
+  - Bash(ace-bundle:*)
+  - Read
+argument-hint: [list|switch|remove|prune|config]
+last_modified: 2026-03-12
+source: ace-git-worktree
+skill:
+  kind: workflow
+  execution:
+    workflow: wfi://git/worktree-manage
+---
+
+Load and run `ace-bundle wfi://git/worktree-manage` in the current project, then follow the loaded workflow as the source of truth and execute it end-to-end instead of only summarizing it.

data/handbook/workflow-instructions/git/worktree-create.wf.md

@@ -0,0 +1,262 @@
+---
+doc-type: workflow
+title: Create Worktree Workflow Instruction
+purpose: Documentation for ace-git-worktree/handbook/workflow-instructions/git/worktree-create.wf.md
+ace-docs:
+  last-updated: 2026-02-22
+  last-checked: 2026-03-21
+---
+
+# Create Worktree Workflow Instruction
+
+## Purpose
+
+Create git worktrees with task-aware automation or traditional branch-based creation. This workflow provides isolated development environments integrated with ACE's task management system.
+
+## Prerequisites
+
+- Git repository initialized and accessible
+- ace-taskflow available (for task-aware creation)
+- Configuration available in `.ace/git/worktree.yml`
+- Write permissions for worktree root directory
+
+## Variables
+
+$task_id: Task identifier (optional, for task-aware creation)
+$branch_name: Branch name (for traditional creation)
+$path: Custom worktree path (optional)
+
+## Instructions
+
+### 1. Preparation
+
+Load and validate worktree configuration:
+
+```bash
+# Show current configuration
+ace-git-worktree config
+
+# Validate configuration
+ace-git-worktree config --validate
+
+# Check available worktrees
+ace-git-worktree list
+```
+
+### 2. Choose Creation Method
+
+**Task-Aware Creation (Recommended for ACE workflow):**
+
+```bash
+ace-git-worktree create --task <task-id>
+```
+
+**Traditional Creation (For non-task work):**
+
+```bash
+ace-git-worktree create <branch-name>
+```
+
+### 3. Execute Creation
+
+**Task-Aware Creation:**
+
+```bash
+# Create worktree for task
+ace-git-worktree create --task 081
+
+# With dry-run to preview
+ace-git-worktree create --task 081 --dry-run
+
+# With custom path
+ace-git-worktree create --task 081 --path ~/worktrees
+```
+
+**Traditional Creation:**
+
+```bash
+# Create worktree for branch
+ace-git-worktree create feature-branch
+
+# With custom path
+ace-git-worktree create feature-branch --path ~/dev-work
+```
+
+### 4. Verify Creation
+
+```bash
+# List all worktrees
+ace-git-worktree list --show-tasks
+
+# Switch to the worktree
+cd $(ace-git-worktree switch 081)
+# or
+cd $(ace-git-worktree switch feature-branch)
+```
+
+### 5. Work in Isolated Environment
+
+```bash
+# Verify you're in the correct worktree
+git status
+git branch
+
+# Work on your task/feature...
+git add .
+git commit -m "Your commit message"
+```
+
+### 6. Cleanup When Done
+
+```bash
+# Return to main directory
+cd ..
+
+# Remove worktree (optional)
+ace-git-worktree remove --task 081
+# or
+ace-git-worktree remove feature-branch
+```
+
+## Advanced Options
+
+### Custom Configuration
+
+```bash
+# Skip automatic mise trust
+ace-git-worktree create --task 081 --no-mise-trust
+
+# Skip task status update
+ace-git-worktree create --task 081 --no-status-update
+
+# Skip automatic commit
+ace-git-worktree create --task 081 --no-commit
+
+# Custom commit message
+ace-git-worktree create --task 081 --commit-message "Custom message"
+```
+
+### Configuration Templates
+
+Customize worktree behavior in `.ace/git/worktree.yml`:
+
+```yaml
+git:
+  worktree:
+    root_path: ".ace-wt"
+    mise_trust_auto: true
+
+    task:
+      directory_format: "task.{id}"        # task.081
+      branch_format: "{id}-{slug}"         # 081-fix-authentication-bug
+      auto_mark_in_progress: true          # Mark task as in-progress
+      auto_commit_task: true                # Commit task changes
+      add_worktree_metadata: true          # Add metadata to task
+```
+
+### Template Variables
+
+Available for directory and branch naming:
+- `{id}` - Task numeric ID (e.g., `081`)
+- `{task_id}` - Full task ID (e.g., `task.081`)
+- `{slug}` - URL-safe slug from task title
+
+## Examples
+
+### Task-Aware Development Workflow
+
+```bash
+# 1. Create worktree for task 081
+ace-git-worktree create --task 081
+# Output: Worktree created at .ace-wt/task.081 with branch 081-fix-auth-bug
+
+# 2. Switch to worktree
+cd $(ace-git-worktree switch 081)
+
+# 3. Work on task
+git add .
+git commit -m "Implement authentication fix"
+
+# 4. When complete, return and cleanup
+cd ..
+ace-git-worktree remove --task 081
+```
+
+### Feature Branch Workflow
+
+```bash
+# 1. Create traditional worktree
+ace-git-worktree create feature-authentication
+# Output: Worktree created at .ace-wt/feature-authentication
+
+# 2. Switch to worktree
+cd $(ace-git-worktree switch feature-authentication)
+
+# 3. Work on feature
+git add .
+git commit -m "Add authentication feature"
+
+# 4. Merge and cleanup
+git checkout main
+git merge feature-authentication
+ace-git-worktree remove feature-authentication
+```
+
+### Bulk Operations
+
+```bash
+# List all task worktrees
+ace-git-worktree list --task-associated
+
+# Clean up orphaned worktrees
+ace-git-worktree prune --cleanup-directories
+
+# Get status in JSON for scripts
+ace-git-worktree list --format json --show-tasks
+```
+
+## Error Handling
+
+| Error | Check | Fix |
+|-------|-------|-----|
+| Task not found | `ace-task show <id>` | Verify task ID exists |
+| Not in git repo | `git status` | Run from git repository |
+| Invalid config | `ace-git-worktree config --validate` | Fix configuration errors |
+| Permission denied | `ls -la <worktree-root>` | Fix directory permissions |
+| Worktree exists | `ace-git-worktree list` | Use different name or remove existing |
+
+## Integration with AI Agents
+
+AI agents can programmatically create and manage worktrees:
+
+```bash
+# Find worktree path for task
+WORKTREE_PATH=$(ace-git-worktree switch --task 081)
+
+# Create worktree and get details
+RESULT=$(ace-git-worktree create --task 081 --dry-run --format json)
+echo "$RESULT" | jq '.worktree_path'
+
+# List worktrees with task associations
+STATUS=$(ace-git-worktree list --format json --show-tasks)
+echo "$STATUS" | jq '.worktrees[] | select(.task_associated == true)'
+```
+
+## Success Criteria
+
+- Worktree created successfully with correct naming
+- Task status updated (if task-aware creation)
+- Worktree metadata added to task (if configured)
+- mise configuration trusted (if present and configured)
+- Worktree is accessible and functional
+- Git branch created correctly
+- All automated steps completed successfully
+
+## Response Template
+
+**Worktree Type:** [Task-aware/Traditional]
+**Location:** [Worktree path]
+**Branch:** [Branch name]
+**Task ID:** [Task ID if applicable]
+**Configuration:** [Key settings applied]
+**Automation Steps:** [Completed automated actions]