Skip to content

feat: add /merge command for automated PR merge with review integration and worktree cleanup #100

Open
#101
Open
feat: add /merge command for automated PR merge with review integration and worktree cleanup#100
#101
Labels
enhancementNew feature or request
@carmandale

Description

@carmandale
carmandale
opened on Oct 13, 2025

Overview

Create an intelligent /merge command for Agent OS that automates the complete PR merge workflow with safety checks, code review integration, and automatic worktree cleanup. The command should infer PR context from conversation, validate readiness for merge, address any review feedback, and clean up after successful integration.

Problem Statement

Current workflow pain points:

  1. Manual PR merge requires multiple manual steps:

    • Checking PR status on GitHub
    • Reviewing CodeRabbit/Codex feedback
    • Addressing review comments
    • Verifying CI status
    • Manual merge execution
    • Worktree cleanup
    • Branch deletion

  2. Context switching between tools:

    • AI conversation → GitHub web UI → Terminal → Back to AI
    • Lost context when reviewing feedback
    • Manual copy-paste of PR numbers

  3. Risk of premature merges:

    • No systematic pre-merge validation
    • Easy to miss failing CI checks
    • Potential to merge with unresolved review comments

  4. Worktree management overhead:

    • Orphaned worktrees after manual merges
    • Manual cleanup commands
    • Risk of deleting wrong worktree

User story:

"As a developer using Agent OS, when I've completed work on a feature branch in a worktree, I want to type /merge and have the system intelligently merge my PR after validating it's ready, addressing any review feedback, and cleaning up the worktree automatically."

Proposed Solution

Create a /merge command that provides intelligent, context-aware PR merge automation with comprehensive safety checks and optional review feedback resolution.

Command Syntax

/merge [pr_number]              # Merge specific PR
/merge                          # Infer PR from current branch/context
/merge --dry-run               # Show what would happen without executing
/merge --force                 # Skip some validation checks (with warnings)
/merge --auto                  # Enable GitHub auto-merge when checks pass

High-Level Flow

graph TD
    A[User: /merge] --> B{PR Specified?}
    B -->|No| C[Infer from branch/context]
    B -->|Yes| D[Use specified PR]
    C --> E[Confirm: Merge PR #XX?]
    D --> E
    E -->|User confirms| F[Validate Pre-Merge Checks]
    F --> G{All checks pass?}
    G -->|No| H[Review Feedback]
    H --> I{Address issues?}
    I -->|Yes| J[Fix issues]
    J --> F
    I -->|No| K[Abort merge]
    G -->|Yes| L[Execute Merge]
    L --> M{In worktree?}
    M -->|Yes| N[Cleanup Worktree]
    M -->|No| O[Update main]
    N --> O
    O --> P[Verify Success]
    P --> Q[Report Completion]
Loading

Technical Approach

Architecture

Command Structure:

  • Location: commands/workflow-merge.md (markdown command file)
  • Script: scripts/workflow-merge.sh (main execution logic)
  • Libraries: Leverage existing workflow-status.sh, workflow-complete.sh patterns

Key Components:

  1. PR Inference Engine (infer_pr_number())

  2. Pre-Merge Validator (validate_merge_readiness())

    # Check via: gh pr view --json reviewDecision,mergeable,mergeStateStatus,statusCheckRollup
✓ Review status: APPROVED (or no reviews required)
✓ Merge conflicts: MERGEABLE (no conflicts)
✓ CI/CD checks: All passing (via gh pr checks)
✓ Branch protection: Not BLOCKED
✓ No unresolved review threads

  3. Review Feedback Analyzer (analyze_review_feedback())

    • Query CodeRabbit comments: gh api repos/{owner}/{repo}/pulls/{pr}/comments
    • Parse critical issues vs suggestions
    • Present to user with context
    • Optionally invoke Agent OS to address feedback

  4. Merge Executor (execute_merge())

    • Use safe merge: gh pr merge --merge --delete-branch
    • Support strategies: --merge, --squash, --rebase
    • Verify merge commit appears on main
    • Handle merge queue scenarios

  5. Worktree Cleanup (cleanup_worktree())

    • Detect if in worktree: git worktree list | grep $(pwd)
    • Return to main repository
    • Remove worktree: git worktree remove <path>
    • Prune metadata: git worktree prune
    • Update main: git checkout main && git pull

Implementation Phases

Phase 1: Core Merge Automation (MVP)

Goal: Basic merge with safety checks

Tasks:

  • Create commands/workflow-merge.md command file
  • Create scripts/workflow-merge.sh execution script
  • Implement PR inference from branch (infer_pr_number())
  • Implement pre-merge validation (validate_merge_readiness())
  • Implement user confirmation prompt
  • Implement basic merge execution (execute_merge())
  • Add to installer (setup-claude-code.sh)

Acceptance Criteria:

  • /merge infers PR from current branch
  • User receives confirmation prompt before merge
  • Validates PR is mergeable and checks pass
  • Executes merge with gh pr merge
  • Updates local main branch after merge

Files:

commands/workflow-merge.md          # Command definition
scripts/workflow-merge.sh           # Main execution logic
scripts/lib/merge-utils.sh         # Helper functions (optional)

Phase 2: Review Feedback Integration

Goal: Address review comments before merge

Tasks:

  • Implement review comment fetching (fetch_review_comments())
  • Parse CodeRabbit/Codex review formats
  • Categorize issues: critical/blocking vs suggestions
  • Present review feedback to user with context
  • Optionally invoke AI to address feedback
  • Re-validate after addressing feedback

Acceptance Criteria:

  • Command detects unresolved review comments
  • Displays critical issues requiring action
  • Allows user to address issues before proceeding
  • Re-checks review status after fixes
  • Only proceeds when reviews satisfied

Integration Points:

# CodeRabbit comments
gh api repos/{owner}/{repo}/pulls/{pr}/comments \
  --jq '.[] | select(.user.login == "coderabbitai")'

# Review decisions
gh pr view --json reviewDecision,reviews

Phase 3: Worktree Management

Goal: Automatic cleanup after successful merge

Tasks:

  • Implement worktree detection (detect_worktree())
  • Implement safe worktree cleanup (cleanup_worktree())
  • Add verification of merge before cleanup
  • Handle edge cases (uncommitted changes, untracked files)
  • Provide clear feedback during cleanup
  • Verify final state is clean

Acceptance Criteria:

  • Detects when running in a worktree
  • Returns to main repository after merge
  • Safely removes worktree after verification
  • Cleans up worktree metadata with git worktree prune
  • Updates main branch with latest changes
  • Reports final status and next steps

Safety Checks:

# Before worktree removal
✓ Merge verified on GitHub
✓ Main branch updated locally
✓ No uncommitted changes in worktree
✓ Branch fully merged (not just PR closed)

Phase 4: Advanced Features & Polish

Goal: Production-ready with full safety and UX

Tasks:

  • Add --dry-run mode
  • Add --auto flag for GitHub auto-merge
  • Add --strategy flag (merge/squash/rebase)
  • Implement comprehensive error handling
  • Add rollback on failure
  • Create comprehensive test suite
  • Add color-coded status output
  • Document all flags and options

Acceptance Criteria:

  • --dry-run shows actions without execution
  • --auto enables GitHub auto-merge feature
  • Clear error messages with recovery suggestions
  • Rollback on merge failures
  • Beautiful terminal output with colors/icons
  • Comprehensive documentation

Alternative Approaches Considered

1. Manual Merge with Checklist

Approach: Provide checklist without automation

Pros: Simple, no code changes
Cons: Doesn't solve manual overhead, context switching still required

Decision: Rejected - doesn't address core user pain

2. GitHub Actions Automation

Approach: Auto-merge via CI/CD on approval

Pros: Fully automated, no CLI needed
Cons: Loss of developer control, harder to customize, requires CI setup

Decision: Rejected - removes developer from loop, different from Agent OS philosophy

3. Git Alias Approach

Approach: Simple bash alias or git alias

Pros: Lightweight, portable
Cons: No AI integration, can't parse review feedback, no context awareness

Decision: Rejected - doesn't leverage Agent OS/AI capabilities

4. Integrated /merge Command (Selected)

Approach: Full Agent OS command with AI integration

Pros:

  • Leverages existing Agent OS infrastructure
  • AI can address review feedback
  • Context-aware (infers PR from conversation)
  • Consistent with Agent OS workflow
  • Extensible for future enhancements

Cons:

  • More complex implementation
  • Requires maintenance

Decision: SELECTED - Best aligns with Agent OS mission and user needs

Acceptance Criteria

Functional Requirements

Core Functionality

  • /merge command installed via setup-claude-code.sh
  • Command infers PR number from:
    • Explicit argument (/merge 123)
    • Current branch name
    • Conversation context (most recent PR mention)
  • User receives clear confirmation prompt showing PR number and title
  • Command validates merge readiness:
    • CI/CD checks passing
    • Review approval (if required)
    • No merge conflicts
    • Not blocked by branch protection

Review Integration

  • Detects CodeRabbit review comments
  • Detects Codex review comments (if applicable)
  • Categorizes feedback: critical vs suggestions
  • Prompts user to address critical issues
  • Allows user to re-run validation after fixes

Merge Execution

  • Executes merge via gh pr merge
  • Supports merge strategies: merge commit (default), squash, rebase
  • Verifies merge succeeded on GitHub
  • Deletes remote branch after merge
  • Updates local main branch

Worktree Management

  • Detects if running in a worktree
  • Returns to main repository directory
  • Fetches and pulls latest main
  • Verifies merge is present locally
  • Safely removes worktree with git worktree remove
  • Prunes worktree metadata
  • Reports final clean status

Non-Functional Requirements

Performance

  • PR inference completes in <2 seconds
  • Pre-merge validation completes in <5 seconds
  • Total command execution <30 seconds (excluding CI wait time)

Reliability

  • Handles GitHub API rate limits gracefully
  • Recovers from network failures
  • Validates all operations before proceeding
  • Provides rollback on critical failures

Usability

  • Clear, actionable error messages
  • Progress indicators for long operations
  • Color-coded output (green=success, yellow=warning, red=error)
  • Helpful suggestions when validation fails
  • Dry-run mode for preview

Security

  • Never bypasses branch protection without explicit --admin flag
  • Warns before force operations
  • Confirms destructive actions (merge, delete)
  • Validates permissions before execution

Quality Gates

Testing

  • Unit tests for PR inference logic
  • Unit tests for validation checks
  • Integration tests with mock GitHub responses
  • Manual testing on real PRs
  • Test all edge cases:
    • Multiple PRs from same branch
    • No PR found
    • PR already merged
    • Failing CI checks
    • Merge conflicts
    • Not in worktree
    • Already on main branch

Documentation

  • Command help text (/merge --help)
  • Inline code comments
  • Update CLAUDE.md with command usage
  • Add to Agent OS command list
  • Document flags and options
  • Add troubleshooting guide

Code Review

  • Shell script passes bash -n syntax check
  • Follows Agent OS code style conventions
  • Error handling comprehensive
  • No hardcoded values (configurable)
  • Portable (macOS and Linux)

Success Metrics

Quantitative

  • Time Savings: Reduce merge workflow from 5-10 minutes to <1 minute
  • Error Reduction: Decrease premature merges by 100% (validation prevents)
  • Adoption: 80%+ of Agent OS users use /merge within 1 month
  • Worktree Cleanup: Eliminate orphaned worktrees (currently a common issue)

Qualitative

  • Users report merge process feels "seamless"
  • Reduced anxiety about merge safety
  • Positive feedback on review feedback integration
  • Perceived as "Agent OS magic"

Dependencies & Prerequisites

Technical Dependencies

  • GitHub CLI (gh) installed and authenticated
  • Git version 2.17+ (for git worktree remove)
  • Claude Code with command support
  • Agent OS installed (~/.agent-os/)
  • Bash 4.0+ for associative arrays

Workflow Dependencies

  • Agent OS /workflow-status command (for context)
  • Agent OS worktree detection patterns
  • Existing Git workflow automation patterns
  • Claude Code agent system for AI integration

External Dependencies

  • GitHub API availability
  • Branch protection rules configuration
  • CodeRabbit/Codex integration (optional)

Risk Analysis & Mitigation

Risk: Accidental Merge to Main

Severity: HIGH
Probability: LOW (with validation)
Impact: Code deployed to production prematurely

Mitigation:

  • Multi-stage confirmation prompts
  • Clear display of target branch
  • Special warning for main/master merges
  • --dry-run always available
  • Validation of branch protection rules

Risk: Merge with Failing Tests

Severity: HIGH
Probability: MEDIUM
Impact: Broken code in main branch

Mitigation:

  • Mandatory CI check validation via gh pr checks
  • Refuse merge if checks failing
  • --force flag requires explicit confirmation
  • Clear display of check status

Risk: Loss of Worktree Data

Severity: MEDIUM
Probability: LOW
Impact: Uncommitted work lost

Mitigation:

  • Check for uncommitted changes before cleanup
  • Verify merge actually succeeded on GitHub
  • Refuse cleanup if work not merged
  • Clear warnings before destructive operations

Risk: GitHub API Rate Limits

Severity: LOW
Probability: LOW
Impact: Command fails or delays

Mitigation:

  • Cache PR status for 30 seconds
  • Use --cached flags where available
  • Graceful degradation (manual fallback)
  • Clear error message with retry guidance

Risk: Network Failure During Merge

Severity: MEDIUM
Probability: LOW
Impact: Unclear state (merged or not?)

Mitigation:

  • Verify merge status after network operations
  • Clear state reporting (merged/not merged)
  • Recovery guidance in error messages
  • Idempotent operations where possible

Risk: Branch Protection Conflicts

Severity: LOW
Probability: MEDIUM
Impact: Merge blocked, confusing error

Mitigation:

  • Query branch protection before merge
  • Clear explanation of requirements
  • Suggest fixes (request review, run CI)
  • Document --admin flag for overrides

Resource Requirements

Development Effort

  • Phase 1 (MVP): 6-8 hours
  • Phase 2 (Review Integration): 4-6 hours
  • Phase 3 (Worktree Cleanup): 3-4 hours
  • Phase 4 (Polish): 4-6 hours
  • Total: 17-24 hours (3-4 days)

Testing & QA

  • Unit tests: 4-6 hours
  • Integration tests: 4-6 hours
  • Manual testing: 2-3 hours
  • Total: 10-15 hours (1.5-2 days)

Documentation

  • Command documentation: 2 hours
  • Inline comments: 1-2 hours
  • User guide: 2-3 hours
  • Total: 5-7 hours (1 day)

Grand Total: 32-46 hours (~1 week of focused development)

Future Considerations

Extensibility

  • Merge strategy selection (merge/squash/rebase) based on PR type
  • Integration with more code review tools (beyond CodeRabbit)
  • Automatic changelog generation on merge
  • Slack/Discord notifications on successful merge
  • Merge queue support for high-traffic repos

Long-Term Vision

  • AI learns from merge patterns and suggests optimal strategies
  • Predictive merge conflict detection
  • Auto-resolution of simple review feedback
  • Integration with Agent OS roadmap tracking
  • Team metrics dashboard (merge frequency, time to merge)

Documentation Plan

User Documentation

  • /merge command help text
  • Usage examples in CLAUDE.md
  • Add to Agent OS command reference
  • Create merge workflow guide
  • Add troubleshooting section

Developer Documentation

  • Inline code comments explaining logic
  • Architecture decision record (ADR)
  • API integration patterns documented
  • Test suite documentation
  • Contributing guide updates

References & Research

Internal References

  • Command patterns: commands/workflow-status.md
  • Script patterns: scripts/workflow-complete.sh:428
  • Git workflow: workflow-modules/step-4-git-integration.md:134
  • Worktree detection: scripts/workflow-status.sh:282-365
  • Installation pattern: setup-claude-code.sh:65-77

External References

Research Documents

  • PR merge best practices: docs/research/pr-merge-automation-best-practices.md
  • GitHub CLI patterns: docs/research/gh-cli-worktree-claude-commands.md

Related Work

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or request

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions