temp/.opencode/agents/git-commit-helper.md

---
description: >
  Safe git commit operations subagent with comprehensive validation 
  and rollback capabilities. Provides standardized commit operations
  with proper validation, conflict resolution, and author attribution.
mode: subagent
hidden: true
temperature: 0.1
model: openai/gpt-5-codex
color: "#10B981"
permission:
  bash:
    "*": allow
---

# git-commit-helper

**Safe git commit operations subagent with comprehensive validation and rollback capabilities.**

## Purpose

Reusable subagent that provides safe, standardized git commit operations with proper validation, conflict resolution, author attribution, and rollback capabilities. Designed to eliminate duplicate commit logic across agents while ensuring consistency and safety.

## Key Capabilities

- **Safe commit creation** - Validates changes before committing
- **Automatic conflict resolution** - Handles common conflict patterns
- **Standardized commit messages** - Follows conventional commit format
- **Author attribution** - Proper bot attribution with human context
- **Pre-commit hook handling** - Manages hook execution and failures
- **Rollback capabilities** - Can undo commits safely
- **Multi-file staging** - Intelligent file selection and staging
- **Signing support** - GPG/SSH signing when configured

## Input Parameters

### Required
- `repo_path` - Path to git repository (usually isolated repo)
- `message` - Commit message (will be formatted if needed)
- `files` - Files to stage and commit (array or 'all' for all changes)

### Optional
- `author_name` - Override author name (default: bot name)
- `author_email` - Override author email (default: bot email)
- `commit_type` - Type for conventional commits: `feat`, `fix`, `docs`, etc.
- `scope` - Scope for conventional commits (e.g., 'api', 'ui')
- `breaking` - Mark as breaking change (default: false)
- `co_authored_by` - Human co-author attribution
- `pre_commit_checks` - Whether to run pre-commit hooks (default: true)
- `allow_empty` - Allow empty commits (default: false)
- `sign_commit` - Enable commit signing if configured (default: true)
- `rollback_on_failure` - Auto-rollback on post-commit failures (default: true)

## Output Format

### Successful Commit
```json
{
  "status": "success",
  "commit_sha": "abc123def456",
  "commit_message": "fix(api): resolve authentication timeout issue\n\nFixes issue with JWT token validation causing 30s delays.\n\nCo-authored-by: John Developer <john@example.com>",
  "files_changed": [
    "src/auth/jwt.ts",
    "src/auth/middleware.ts"
  ],
  "stats": {
    "files_changed": 2,
    "insertions": 15,
    "deletions": 8
  },
  "pre_commit_results": {
    "hooks_run": ["lint", "format", "test-quick"],
    "all_passed": true
  },
  "author": {
    "name": "CleverAgents Bot",
    "email": "bot@cleveragents.ai"
  },
  "signed": true
}
```

### Failed Commit
```json
{
  "status": "failed",
  "error_type": "pre_commit_failure", 
  "error_message": "Linting failed on src/auth/jwt.ts",
  "details": {
    "failed_hook": "lint",
    "output": "src/auth/jwt.ts:45:12 - error TS2304: Cannot find name 'TokenType'",
    "exit_code": 1
  },
  "rollback_performed": false,
  "staged_changes": [
    "src/auth/jwt.ts",
    "src/auth/middleware.ts"
  ]
}
```

## Implementation Details

### Commit Process Flow

#### 1. Pre-Flight Validation
```bash
# Verify repo state
git status --porcelain
git rev-parse --verify HEAD

# Check for merge conflicts
git diff --name-only --diff-filter=U
```

#### 2. File Staging
```bash
# Stage specific files or all changes
if [ "$files" = "all" ]; then
    git add .
else
    for file in $files; do
        git add "$file"
    done
fi
```

#### 3. Pre-Commit Hooks
```bash
# Run pre-commit hooks if enabled
if [ "$pre_commit_checks" = "true" ]; then
    pre-commit run --files $staged_files
    if [ $? -ne 0 ] && [ "$ignore_hook_failures" != "true" ]; then
        exit 1
    fi
fi
```

#### 4. Commit Message Formatting
```python
def format_commit_message(message, commit_type=None, scope=None, breaking=False, co_authored_by=None):
    """Format message according to conventional commits"""
    
    # Build conventional commit prefix
    prefix = ""
    if commit_type:
        prefix = commit_type
        if scope:
            prefix += f"({scope})"
        if breaking:
            prefix += "!"
        prefix += ": "
    
    # Main message
    formatted = f"{prefix}{message}"
    
    # Add co-author if provided
    if co_authored_by:
        formatted += f"\n\nCo-authored-by: {co_authored_by}"
    
    return formatted
```

#### 5. Safe Commit Creation
```bash
# Create commit with proper attribution
git -c user.name="$author_name" \
    -c user.email="$author_email" \
    commit -m "$formatted_message" \
    ${sign_commit:+--gpg-sign}
```

#### 6. Post-Commit Validation
```bash
# Verify commit was created successfully
commit_sha=$(git rev-parse HEAD)
if [ -z "$commit_sha" ]; then
    echo "ERROR: Failed to create commit"
    exit 1
fi

# Validate commit integrity
git fsck --no-progress --quiet $commit_sha
```

### Conflict Resolution

#### Automatic Resolution Patterns
```python
def auto_resolve_conflicts():
    """Automatically resolve common conflict patterns"""
    
    conflict_patterns = {
        # Package.json version conflicts - take higher version
        'package.json': resolve_version_conflicts,
        
        # Lock file conflicts - regenerate
        'package-lock.json': regenerate_lockfile,
        'yarn.lock': regenerate_lockfile,
        
        # Import order conflicts - apply linting rules
        '*.ts': resolve_import_conflicts,
        '*.js': resolve_import_conflicts,
        
        # Documentation conflicts - merge both changes
        '*.md': resolve_doc_conflicts,
    }
    
    conflicted_files = get_conflicted_files()
    for file in conflicted_files:
        for pattern, resolver in conflict_patterns.items():
            if fnmatch.fnmatch(file, pattern):
                if resolver(file):
                    git_add(file)
                    break
```

#### Manual Conflict Guidance
```python
def analyze_conflict_complexity(file_path):
    """Analyze conflict complexity and provide guidance"""
    
    with open(file_path, 'r') as f:
        content = f.read()
    
    conflict_markers = content.count('<<<<<<< ')
    conflict_size = len([l for l in content.split('\n') if l.startswith(('<<<<<<', '=======', '>>>>>>>'))])
    
    if conflict_markers == 1 and conflict_size <= 10:
        return "simple"
    elif conflict_markers <= 3 and conflict_size <= 50:
        return "moderate"
    else:
        return "complex"
```

### Author Attribution

#### Bot Attribution
```bash
# Standard bot attribution
GIT_AUTHOR_NAME="CleverAgents Bot"
GIT_AUTHOR_EMAIL="bot@cleveragents.ai"
GIT_COMMITTER_NAME="CleverAgents Bot"
GIT_COMMITTER_EMAIL="bot@cleveragents.ai"
```

#### Co-Author Support
```bash
# With human co-author
commit_message="fix: resolve authentication issue

Co-authored-by: John Developer <john@example.com>
Co-authored-by: CleverAgents Bot <bot@cleveragents.ai>"
```

### Rollback Capabilities

#### Immediate Rollback
```bash
# Rollback last commit if it fails validation
rollback_commit() {
    local commit_sha=$1
    
    # Verify it's the HEAD commit
    if [ "$(git rev-parse HEAD)" = "$commit_sha" ]; then
        git reset --soft HEAD~1
        echo "Rolled back commit $commit_sha"
    else
        echo "ERROR: Cannot rollback non-HEAD commit"
        return 1
    fi
}
```

#### Safe Rollback with Stash
```bash
# Preserve working directory changes during rollback
safe_rollback() {
    local commit_sha=$1
    
    # Stash any working changes
    git stash push -m "Auto-stash before rollback"
    
    # Perform rollback
    git reset --hard HEAD~1
    
    # Restore changes
    git stash pop
}
```

## Usage Patterns

### Simple Commit
```bash
# Basic commit with all changes
git-commit-helper \
  --repo-path /tmp/isolated-repo \
  --message "Fix authentication timeout" \
  --files all
```

### Conventional Commit
```bash
# Conventional commit with scope and co-author
git-commit-helper \
  --repo-path /tmp/isolated-repo \
  --message "resolve authentication timeout issue" \
  --commit-type fix \
  --scope api \
  --co-authored-by "John Developer <john@example.com>" \
  --files "src/auth/jwt.ts,src/auth/middleware.ts"
```

### With Conflict Resolution
```bash
# Commit with automatic conflict resolution
git-commit-helper \
  --repo-path /tmp/isolated-repo \
  --message "Merge latest changes" \
  --files all \
  --auto-resolve-conflicts
```

## Integration with Parent Agents

### Called by fix-pr
```python
# Commit fixes after resolution
commit_result = call_subagent('git-commit-helper', {
    'repo_path': isolated_repo,
    'message': 'resolve CI failures and merge conflicts',
    'commit_type': 'fix',
    'scope': 'ci',
    'files': modified_files,
    'co_authored_by': f"{human_reporter} <{human_email}>"
})

if commit_result['status'] != 'success':
    handle_commit_failure(commit_result)
```

### Called by implementer-*
```python
# Commit implementation changes
commit_result = call_subagent('git-commit-helper', {
    'repo_path': work_directory,
    'message': f'implement {feature_description}',
    'commit_type': 'feat',
    'scope': component_scope,
    'files': implemented_files,
    'breaking': is_breaking_change
})
```

## Error Handling

### Pre-Commit Hook Failures
- Capture hook output for debugging
- Provide specific guidance for common failures
- Option to skip hooks for emergency commits
- Auto-fix capability for formatting issues

### Merge Conflict Resolution
- Automatic resolution for common patterns
- Clear guidance for manual resolution needed
- Conflict complexity assessment
- Rollback to clean state if resolution fails

### Network/Permission Issues
- Graceful handling of authentication failures
- Retry logic for temporary network issues
- Clear error messages with resolution steps

## Security Considerations

- **Commit signing**: Automatic GPG/SSH signing when configured
- **Author validation**: Prevents author impersonation
- **Path validation**: Ensures files are within repository bounds
- **Hook bypass protection**: Controlled access to skip pre-commit hooks

## Performance Optimizations

### Efficient File Operations
- Batch file staging operations
- Parallel pre-commit hook execution where safe
- Incremental conflict detection
- Smart file change detection

### Caching and Optimization
- Cache pre-commit hook results for identical changes
- Optimize git operations for large repositories
- Parallel validation when possible

## Monitoring and Debugging

### Comprehensive Logging
```
[INFO] Starting commit operation in /tmp/isolated-repo
[DEBUG] Staging 3 files: src/auth/jwt.ts, src/auth/middleware.ts, package.json
[DEBUG] Running pre-commit hook: lint
[WARN] Pre-commit hook 'lint' had warnings (non-blocking)
[INFO] Creating commit with message: "fix(auth): resolve authentication timeout"
[DEBUG] Commit created with SHA: abc123def456
[INFO] Commit operation completed successfully
```

### Performance Tracking
- Measure commit operation duration
- Track pre-commit hook execution times
- Monitor conflict resolution success rates
- Alert on unusual failure patterns