GitHub Swarm PR Skill

Overview

This skill enables creation and management of AI swarms directly from GitHub Pull Requests, providing multi-agent code review, automated validation, and intelligent merge coordination. It transforms PRs into coordinated swarm workflows.

Key Capabilities:

• PR-based swarm creation with automatic agent assignment
• Multi-agent code review and validation
• PR comment commands for swarm control
• Automated PR lifecycle management
• Intelligent merge coordination with consensus

Quick Start

# Get PR details for swarm initialization
gh pr view 123 --json title,body,labels,files,reviews

# Get PR diff for analysis
gh pr diff 123

# Check PR status
gh pr checks 123

# Review PR with swarm-generated feedback
gh pr review 123 --comment --body "## Swarm Analysis
- Code quality: PASS
- Test coverage: 85%
- Security: No issues found"

When to Use

• Complex PRs: Large changes requiring multi-perspective review
• Security Reviews: PRs touching sensitive code paths
• Architecture Changes: Structural modifications needing architect review
• Performance-Critical: Changes to performance-sensitive code
• Cross-Team PRs: Changes affecting multiple team domains

Usage Examples

1. PR-Based Swarm Creation

# Get comprehensive PR data
PR_DATA=$(gh pr view 123 --json title,body,labels,files,additions,deletions,reviews)
PR_DIFF=$(gh pr diff 123)

# Analyze PR complexity for swarm topology
ADDITIONS=$(echo "$PR_DATA" | jq '.additions')
DELETIONS=$(echo "$PR_DATA" | jq '.deletions')
TOTAL_CHANGES=$((ADDITIONS + DELETIONS))

# Determine topology based on size
if [ $TOTAL_CHANGES -gt 500 ]; then
  TOPOLOGY="hierarchical"
  MAX_AGENTS=8
elif [ $TOTAL_CHANGES -gt 100 ]; then
  TOPOLOGY="mesh"
  MAX_AGENTS=5
else
  TOPOLOGY="ring"
  MAX_AGENTS=3
fi

echo "PR #123: $TOTAL_CHANGES changes, using $TOPOLOGY topology with $MAX_AGENTS agents"

2. Multi-Agent PR Review

# Get changed files by type
FILES=$(gh pr view 123 --json files --jq '.files[].path')

# Categorize files for agent assignment
JS_FILES=$(echo "$FILES" | grep -E '\.(js|ts|tsx)$' || true)
PY_FILES=$(echo "$FILES" | grep -E '\.py$' || true)
TEST_FILES=$(echo "$FILES" | grep -E '(test|spec)\.' || true)
CONFIG_FILES=$(echo "$FILES" | grep -E '\.(json|yaml|yml)$' || true)

# Generate comprehensive review
REVIEW_BODY="## Multi-Agent PR Review

### Code Review
$([ -n "$JS_FILES" ] && echo "**JavaScript/TypeScript**: Files reviewed")
$([ -n "$PY_FILES" ] && echo "**Python**: Files reviewed")

### Test Coverage
$([ -n "$TEST_FILES" ] && echo "Test files detected and validated" || echo "No test files found")

### Configuration Changes
$([ -n "$CONFIG_FILES" ] && echo "Configuration changes reviewed" || echo "No config changes")

### Summary
- Total files: $(echo "$FILES" | wc -l)
- Recommendation: Approve with minor suggestions

---
Generated by Swarm PR Agent"

gh pr review 123 --comment --body "$REVIEW_BODY"

3. PR Comment Commands

Use these commands in PR comments to control swarms:

<!-- Initialize swarm -->
/swarm init mesh 6

<!-- Spawn specific agents -->
/swarm spawn coder "Implement the authentication logic"
/swarm spawn tester "Write comprehensive tests"
/swarm spawn security "Review for vulnerabilities"

<!-- Check swarm status -->
/swarm status

<!-- Get analysis -->
/swarm analyze

<!-- Complete swarm work -->
/swarm complete

4. Automated PR Validation

# Run comprehensive PR validation
validate_pr() {
  local PR_NUM=$1

  # Get PR details
  PR=$(gh pr view $PR_NUM --json state,mergeable,reviews,statusCheckRollup)

  # Check merge status
  MERGEABLE=$(echo "$PR" | jq -r '.mergeable')

  # Check CI status
  CI_STATUS=$(echo "$PR" | jq -r '.statusCheckRollup[0].conclusion // "pending"')

  # Check review status
  APPROVALS=$(echo "$PR" | jq '[.reviews[] | select(.state == "APPROVED")] | length')

  # Validation report
  cat << EOF
## PR #$PR_NUM Validation Report

### Merge Status
- Mergeable: $MERGEABLE
- CI Status: $CI_STATUS
- Approvals: $APPROVALS

### Recommendations
$([ "$MERGEABLE" == "MERGEABLE" ] && echo "- Ready for merge" || echo "- Resolve conflicts first")
$([ "$CI_STATUS" == "SUCCESS" ] && echo "- CI passing" || echo "- Wait for CI to complete")
$([ $APPROVALS -ge 2 ] && echo "- Sufficient approvals" || echo "- Need more reviews")
EOF
}

validate_pr 123

5. Intelligent Merge Coordination

# Check if PR is ready to merge
check_merge_readiness() {
  local PR_NUM=$1

  # Get all checks
  CHECKS=$(gh pr checks $PR_NUM --json name,state,conclusion)

  # Count passed/failed/pending
  PASSED=$(echo "$CHECKS" | jq '[.[] | select(.conclusion == "success")] | length')
  FAILED=$(echo "$CHECKS" | jq '[.[] | select(.conclusion == "failure")] | length')
  PENDING=$(echo "$CHECKS" | jq '[.[] | select(.state == "pending")] | length')

  if [ $FAILED -gt 0 ]; then
    echo "Cannot merge: $FAILED checks failed"
    return 1
  elif [ $PENDING -gt 0 ]; then
    echo "Waiting: $PENDING checks still running"
    return 2
  else
    echo "Ready to merge: All $PASSED checks passed"
    return 0
  fi
}

# Merge with appropriate strategy
merge_pr() {
  local PR_NUM=$1

  # Get PR size
  SIZE=$(gh pr view $PR_NUM --json additions,deletions --jq '.additions + .deletions')

  # Choose merge strategy
  if [ $SIZE -lt 50 ]; then
    gh pr merge $PR_NUM --squash --delete-branch
  elif [ $SIZE -lt 200 ]; then
    gh pr merge $PR_NUM --merge --delete-branch
  else
    # Large PR - rebase to maintain history
    gh pr merge $PR_NUM --rebase --delete-branch
  fi
}

check_merge_readiness 123 && merge_pr 123

PR Label Integration

Automatic Agent Assignment

{
  "label-mapping": {
    "bug": ["debugger", "tester"],
    "feature": ["architect", "coder", "tester"],
    "refactor": ["analyst", "coder"],
    "docs": ["researcher", "writer"],
    "performance": ["analyst", "optimizer"],
    "security": ["security", "reviewer"]
  }
}

Label-Based Topology Selection

# Determine topology from PR labels
get_topology() {
  local PR_NUM=$1
  LABELS=$(gh pr view $PR_NUM --json labels --jq '.labels[].name')

  if echo "$LABELS" | grep -q "critical"; then
    echo "hierarchical"  # Most structured for critical changes
  elif echo "$LABELS" | grep -q "feature"; then
    echo "mesh"  # Collaborative for features
  else
    echo "ring"  # Simple for routine changes
  fi
}

MCP Tool Integration

Multi-Agent PR Coordination

// Initialize PR-specific swarm
mcp__claude-flow__swarm_init { topology: "mesh", maxAgents: 8 }
mcp__claude-flow__agent_spawn { type: "coordinator", name: "PR Coordinator" }
mcp__claude-flow__agent_spawn { type: "reviewer", name: "Code Reviewer" }
mcp__claude-flow__agent_spawn { type: "tester", name: "Test Engineer" }
mcp__claude-flow__agent_spawn { type: "analyst", name: "Impact Analyzer" }
mcp__claude-flow__agent_spawn { type: "optimizer", name: "Performance Optimizer" }

// Store PR context in swarm memory
mcp__claude-flow__memory_usage {
  action: "store",
  key: "pr/123/context",
  value: {
    pr_number: 123,
    files_changed: ["src/auth.js", "tests/auth.test.js"],
    complexity_score: 7.5,
    risk_assessment: "medium",
    agents_assigned: ["reviewer", "tester", "security"]
  }
}

// Orchestrate comprehensive PR review
mcp__claude-flow__task_orchestrate {
  task: "Execute multi-agent PR review and validation",
  strategy: "parallel",
  priority: "high",
  dependencies: ["diff_analysis", "test_validation", "security_review"]
}

Swarm-Coordinated Merge

// Coordinate merge decision with swarm
mcp__claude-flow__coordination_sync { swarmId: "pr-review-swarm" }

// Analyze merge readiness
mcp__claude-flow__task_orchestrate {
  task: "Evaluate PR merge readiness with comprehensive validation",
  strategy: "sequential",
  priority: "critical"
}

// Store merge decision
mcp__claude-flow__memory_usage {
  action: "store",
  key: "pr/123/merge_decision",
  value: {
    ready_to_merge: true,
    all_checks_passed: true,
    agent_consensus: "approved",
    merge_strategy: "squash"
  }
}

GitHub Actions Integration

# .github/workflows/swarm-pr.yml
name: Swarm PR Handler
on:
  pull_request:
    types: [opened, labeled, synchronize]
  issue_comment:
    types: [created]

jobs:
  swarm-review:
    if: contains(github.event.pull_request.labels.*.name, 'swarm-review')
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Analyze PR
        id: analyze
        run: |
          CHANGES=$(git diff --stat HEAD~1 | tail -1)
          echo "changes=$CHANGES" >> $GITHUB_OUTPUT

      - name: Post Swarm Analysis
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: |
          gh pr comment ${{ github.event.pull_request.number }} \
            --body "## Swarm Analysis

          Changes: ${{ steps.analyze.outputs.changes }}

          Swarm agents have been assigned to review this PR."

  handle-commands:
    if: github.event_name == 'issue_comment' && startsWith(github.event.comment.body, '/swarm')
    runs-on: ubuntu-latest
    steps:
      - name: Process Swarm Command
        run: |
          COMMAND="${{ github.event.comment.body }}"
          echo "Processing: $COMMAND"
          # Handle swarm commands

Best Practices

1. PR Templates for Swarm

<!-- .github/pull_request_template.md -->
## Summary
[Brief description of changes]

## Swarm Configuration
- **Topology**: [mesh/hierarchical/ring/star]
- **Max Agents**: [number]
- **Priority**: [critical/high/medium/low]

## Tasks for Swarm
- [ ] Code review
- [ ] Test validation
- [ ] Security scan
- [ ] Performance check

## Checklist
- [ ] Tests added/updated
- [ ] Documentation updated
- [ ] No breaking changes

2. Status Checks

# Require swarm completion before merge
required_status_checks:
  contexts:
    - "swarm/review-complete"
    - "swarm/tests-validated"
    - "swarm/security-approved"

3. Review Quality

• Run security scan on all PRs touching auth code
• Require architect review for structural changes
• Auto-assign reviewers based on CODEOWNERS
• Use swarm consensus for merge decisions

Metrics and Reporting

# Generate PR swarm report
generate_report() {
  local PR_NUM=$1

  gh pr view $PR_NUM --json \
    title,additions,deletions,reviews,comments,createdAt,updatedAt | \
  jq '{
    title: .title,
    size: (.additions + .deletions),
    reviews: (.reviews | length),
    comments: (.comments | length),
    age_hours: ((now - (.createdAt | fromdateiso8601)) / 3600 | floor)
  }'
}

generate_report 123

Related Skills

• github-swarm-issue - Issue-based swarm coordination
• github-workflow - CI/CD automation
• github-sync - Repository synchronization
• github-modes - GitHub integration modes

---

Version History

• 1.0.0 (2026-01-02): Initial skill conversion from swarm-pr agent