timmy-config/wizards/allegro-primus/git_tools/README.md

AP Git Worktree Automation

Allegro-Primus Git Worktree Automation - Enable parallel task execution across multiple git worktrees.

Overview

This system allows you to work on multiple GitHub issues simultaneously by leveraging git worktrees. Each issue gets its own isolated worktree, enabling true parallel development without branch switching overhead.

Components

1. worktree_manager.py

Manages git worktree operations:

• create_worktree(issue_number, description) - Create worktree for issue
• list_worktrees() - List active worktrees
• clean_stale_worktrees(days) - Remove old worktrees
• sync_changes(source, target) - Sync between worktrees
• generate_branch_name(issue, description) - Auto-generate branch names

2. task_runner.py

Executes tasks in isolated worktrees:

• run_command() - Run shell commands
• run_script() - Execute Python scripts
• run_python_function() - Run Python functions
• auto_commit() - Auto-commit on success
• generate_report() - Task execution reports

3. parallel_agent.py

Manages parallel execution:

• ParallelAgent - Execute tasks across multiple worktrees
• IssueParallelizer - High-level issue-based interface
• TaskQueue - Priority queue with dependency resolution
• ConflictDetector - Detect file conflicts between worktrees

4. cli.py

Command-line interface:

# Worktree operations
python cli.py worktree list
python cli.py worktree create <issue> [--description <desc>]
python cli.py worktree clean [--days 7]
python cli.py worktree remove <issue>
python cli.py worktree status <issue>

# Parallel execution
python cli.py parallel run --issues 101 102 103 --command echo "test"
python cli.py parallel run -f tasks.json

# Demo
python cli.py demo

Quick Start

Working on 3 Issues Simultaneously

from git_tools import IssueParallelizer

# Create parallelizer
parallelizer = IssueParallelizer()

# Register 3 issues
parallelizer.register_issue("101", "Fix login bug")
parallelizer.register_issue("102", "Add API endpoint")
parallelizer.register_issue("103", "Update docs")

# Add tasks to each
parallelizer.add_task_to_issue("101", ["pytest", "tests/auth/"])
parallelizer.add_task_to_issue("102", ["python", "build_api.py"])
parallelizer.add_task_to_issue("103", ["mkdocs", "build"])

# Run all in parallel
results = parallelizer.run()

Using the CLI

# Create worktrees for 3 issues
python cli.py worktree create 101 --description "Fix login bug"
python cli.py worktree create 102 --description "Add API endpoint"
python cli.py worktree create 103 --description "Update docs"

# Run tasks in parallel
python cli.py parallel run \
  --issues 101 102 103 \
  --command python -c "print('Working on issue')"

# Clean up when done
python cli.py worktree clean --all

Examples

See example_parallel_issues.py for comprehensive examples:

1. Basic parallel execution
2. Using IssueParallelizer
3. Task dependencies
4. Python script execution
5. Worktree management
6. Conflict detection

Run examples:

python example_parallel_issues.py

Task Dependencies

Execute tasks with dependencies:

tasks = [
    ParallelTask(
        task_id="step1",
        issue_number="201",
        task_type="command",
        payload=["echo", "Step 1"],
        dependencies=[]
    ),
    ParallelTask(
        task_id="step2",
        issue_number="201",
        task_type="command",
        payload=["echo", "Step 2"],
        dependencies=["step1"]  # Wait for step1
    )
]

agent = ParallelAgent()
results = agent.run_parallel(tasks)

Conflict Detection

The system automatically detects when multiple worktrees modify the same files:

from git_tools import ConflictDetector, WorktreeManager

wm = WorktreeManager()
detector = ConflictDetector(wm)

# Check for overlapping changes
overlap = detector.check_overlap("101", "102")
if overlap:
    print(f"Both issues modify: {overlap}")

Auto-Commit

Enable automatic commits on successful task completion:

task = ParallelTask(
    task_id="auto-commit-test",
    issue_number="101",
    task_type="command",
    payload=["make", "test"],
    auto_commit=True  # Commit if tests pass
)

Directory Structure

repo/
├── .git/               # Main git repository
├── .worktrees/         # Worktree directory
│   ├── issue-101/      # Worktree for issue 101
│   ├── issue-102/      # Worktree for issue 102
│   └── issue-103/      # Worktree for issue 103
└── src/                # Source code

Requirements

• Python 3.7+
• Git 2.5+ (for worktree support)

License

MIT