cleveragents-core/.opencode/agents/git-commit-helper.md

description, mode, hidden, temperature, model, color, permission

description	mode	hidden	temperature	model	color	permission
Safe git commit operations subagent with comprehensive validation and rollback capabilities. Provides standardized commit operations with proper validation, conflict resolution, and author attribution.	subagent	true	0.1	openai/gpt-5-codex	#10B981	bash forgejo * *api/v1/orgs/*/labels* *api/v1/repos/*/labels* *https://git.cleverthis.com/api/v1/repos/cleveragents/cleveragents-core/labels* allow deny deny deny * forgejo_create_label forgejo_create_org_label forgejo_create_repo_label forgejo_add_issue_labels allow deny deny deny deny

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

{
  "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

{
  "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

# 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

# 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

# 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

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

# 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

# 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

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

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

# 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

# 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

# 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

# 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

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

Conventional Commit

# 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

# 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

# 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-*

# 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