when-managing-multiple-repos-use-github-multi-repo

What this skill does

# GitHub Multi-Repository Management Skill

## Overview

Orchestrate complex operations across multiple related GitHub repositories with intelligent agent coordination. This skill enables consistent architecture enforcement, synchronized dependency updates, cross-repo refactoring, and coordinated releases for microservices, multi-package ecosystems, and distributed system architectures.

## When to Use This Skill

Activate this skill when managing microservices architectures spanning multiple repositories, coordinating changes across frontend/backend/infrastructure repos, migrating from monorepo to multi-repo structure, propagating breaking changes across dependent repositories, maintaining consistent coding standards across teams, synchronizing releases for multi-package systems, or enforcing architectural patterns across an organization.

Use for both small-scale coordination (2-5 repos) and large-scale orchestration (10+ repositories), one-time migrations or ongoing maintenance, and establishing governance for multi-repo ecosystems.

## Agent Coordination Architecture

### Swarm Topology

Initialize a **hierarchical topology** with a coordinator agent managing specialized worker agents. Hierarchical structure enables centralized decision-making for consistency while delegating specialized tasks to expert agents.

```bash
# Initialize hierarchical swarm for multi-repo coordination
npx claude-flow@alpha swarm init --topology hierarchical --max-agents 8 --strategy adaptive
```

### Specialized Agent Roles

**Hierarchical Coordinator** (`hierarchical-coordinator`): Top-level orchestrator that maintains global view of all repositories, makes architectural decisions, coordinates cross-repo operations, and ensures consistency. Acts as the single source of truth for multi-repo strategy.

**Repository Architect** (`repo-architect`): Analyzes repository structures, defines architectural patterns, creates dependency graphs, identifies coupling issues, and designs migration strategies. Maintains the architectural vision across repositories.

**Code Analyzer** (`code-analyzer`): Scans codebases for patterns, dependencies, and inconsistencies. Identifies code duplication across repos, tracks API contracts, and validates architectural compliance.

**CI/CD Engineer** (`cicd-engineer`): Manages build pipelines, deployment workflows, and release orchestration. Coordinates continuous integration across repositories and handles versioning strategies.

**Worker Agents** (spawned dynamically): Execute repository-specific tasks such as refactoring, testing, documentation updates, and dependency bumps. Scaled based on number of target repositories.

## Multi-Repository Workflows (SOP)

### Workflow 1: Cross-Repository Change Propagation

Propagate breaking changes, API updates, or architectural patterns across multiple repositories.

**Phase 1: Impact Analysis**

**Step 1.1: Initialize Hierarchical Coordination**

```bash
# Set up hierarchical swarm
mcp__claude-flow__swarm_init topology=hierarchical maxAgents=8 strategy=adaptive

# Spawn coordinator and specialists
mcp__claude-flow__agent_spawn type=coordinator name=hierarchical-coordinator
mcp__claude-flow__agent_spawn type=analyst name=repo-architect
mcp__claude-flow__agent_spawn type=analyst name=code-analyzer
mcp__claude-flow__agent_spawn type=coder name=cicd-engineer
```

**Step 1.2: Analyze Repository Dependencies**

Use `scripts/repo-graph.sh` to build dependency graph:

```bash
# Generate dependency graph across all repositories
bash scripts/repo-graph.sh build-graph \
  --repos "repo1,repo2,repo3" \
  --output "references/dependency-graph.dot"
```

Visualize the dependency graph to identify impact scope:

```bash
# Render graph visualization
dot -Tpng references/dependency-graph.dot -o dependency-graph.png
```

**Step 1.3: Identify Affected Repositories**

Launch coordinator to analyze impact:

```plaintext
Task("Hierarchical Coordinator", "
  Analyze the impact of <CHANGE_DESCRIPTION> across all repositories:

  1. Review dependency graph at references/dependency-graph.dot
  2. Identify direct dependents (repositories importing affected code)
  3. Identify transitive dependents (downstream consumers)
  4. Categorize changes by risk level (breaking/compatible/enhancement)
  5. Create propagation strategy with sequencing

  Store impact analysis in memory: multi-repo/impact-analysis
  Use scripts/repo-graph.sh for dependency traversal
  Run hooks: npx claude-flow@alpha hooks pre-task --description 'impact analysis'
", "hierarchical-coordinator")
```

**Phase 2: Parallel Repository Updates**

Execute coordinated updates across all affected repositories.

**Step 2.1: Spawn Worker Agents per Repository**

For each affected repository, spawn a dedicated worker agent:

```plaintext
Task("Worker: Repository 1", "
  Apply changes to repository <REPO_1>:

  1. Clone repository: bash scripts/multi-repo.sh clone <REPO_1>
  2. Create feature branch: change-propagation-<DATE>
  3. Apply code changes based on coordinator strategy
  4. Update tests to reflect new API contracts
  5. Validate build passes: npm test / cargo test
  6. Commit changes with standardized message
  7. Push branch and create draft PR

  Store results in memory: multi-repo/updates/<REPO_1>
  Run hooks for coordination
", "coder")

Task("Worker: Repository 2", "
  Apply changes to repository <REPO_2>:
  [Same steps as above, tailored to REPO_2]

  Store results in memory: multi-repo/updates/<REPO_2>
", "coder")

# Spawn additional workers for each repository
# All workers execute in parallel
```

**Step 2.2: Coordinate Test Execution**

After all workers complete, test repositories together:

```plaintext
Task("CI/CD Engineer", "
  Validate changes across all repositories:

  1. Set up integration test environment
  2. Build all modified repositories in dependency order
  3. Run integration tests with new versions
  4. Check for breaking changes in API contracts
  5. Validate performance hasn't degraded

  Use scripts/integration-test.sh for orchestration
  Store test results in memory: multi-repo/test-results
", "cicd-engineer")
```

**Phase 3: Synchronized Release**

Coordinate pull request creation and merging across repositories.

**Step 3.1: Create Pull Requests**

Generate PRs for all repositories simultaneously:

```bash
# Create PRs across all repos
bash scripts/multi-repo.sh create-prs \
  --repos "repo1,repo2,repo3" \
  --title "Propagate: <CHANGE_DESCRIPTION>" \
  --body-template "references/pr-template.md" \
  --labels "multi-repo-sync,automated"
```

**Step 3.2: Coordinate Review and Merge**

Track PR status and coordinate merging in dependency order:

```plaintext
Task("Hierarchical Coordinator", "
  Coordinate PR review and merge process:

  1. Monitor PR status using scripts/multi-repo.sh pr-status
  2. Ensure PRs are reviewed in dependency order
  3. Merge upstream dependencies first (libraries, shared code)
  4. Wait for CI to pass on each merge
  5. Merge downstream consumers after dependencies released
  6. Verify no build breaks in dependency chain

  Use scripts/multi-repo.sh merge-sequence for ordering
  Store merge sequence in memory: multi-repo/merge-plan
", "hierarchical-coordinator")
```

**Step 3.3: Tag and Release**

Create coordinated releases across repositories:

```bash
# Execute synchronized releases
bash scripts/multi-repo.sh synchronized-release \
  --repos "repo1,repo2,repo3" \
  --version-strategy "minor" \
  --release-notes-dir "references/release-notes"
```

### Workflow 2: Monorepo to Multi-Repo Migration

Migrate a monolithic repository into multiple focused repositories while preserving history.

**Phase 1: Architecture Planning**

**Step 1.1: Analyze Monorepo Structure**

```plaintext
Task("Repository Architect", "
  Analyze monorepo structure and design migration strategy:

  1. Map directory structure and module boundaries
  2. Identify logical separation points (services, packages, layers)
  3. Analyze imp