Project 33: Multi-Repository Refactoring Agent
Project 33: Multi-Repository Refactoring Agent
Build an agent that coordinates refactoring across multiple repositories - renaming interfaces, updating imports, and ensuring consistency across your entire organization’s codebase with proper dependency ordering and atomic changes.
Quick Reference
| Attribute | Value |
|---|---|
| Difficulty | Expert (Level 4) |
| Time Estimate | 1 month+ |
| Primary Language | TypeScript |
| Alternative Languages | Python, Go |
| Prerequisites | Projects 7, 10, 14, 25 (GitHub MCP, Subagents, Checkpoints, Code Review) |
| Key Topics | Dependency graphs, parallel processing, atomic changes, PR coordination, rollback strategies |
| Kiro CLI Concepts | Subagent orchestration, GitHub MCP, checkpoints, hooks, parallel execution |
| Main Book Reference | “Monorepo Development” by Ben Awad; “Pro Git” by Scott Chacon |
1. Learning Objectives
By completing this project, you will:
- Master cross-repository dependency mapping: Build dependency graphs across multiple repos and understand topological ordering
- Implement subagent orchestration patterns: Coordinate parallel agents working on different repositories with proper synchronization
- Design atomic multi-repo changes: Create change sets that can be applied or rolled back as a unit across repositories
- Build sophisticated PR coordination: Create linked pull requests with proper dependencies and merge ordering
- Implement enterprise-grade rollback: Handle failures gracefully with checkpoint-based recovery across distributed systems
2. Deep Theoretical Foundation
2.1 The Multi-Repository Challenge
Large organizations often have polyrepo architectures where code is spread across many repositories. Making consistent changes across these repos is one of software engineering’s hardest problems.
THE POLYREPO CHALLENGE
┌─────────────────────────────────────────────────────────────────────────┐
│ │
│ ORGANIZATION CODEBASE │
│ ──────────────────── │
│ │
│ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │
│ │ @org/core-types │ │ @org/user-api │ │ @org/web-client │ │
│ │ │ │ │ │ │ │
│ │ interface │ │ import { │ │ import { │ │
│ │ UserService { │──▶│ UserService │──▶│ UserService │ │
│ │ ... │ │ } from │ │ } from │ │
│ │ } │ │ '@org/core' │ │ '@org/user-api' │ │
│ └─────────────────┘ └─────────────────┘ └─────────────────┘ │
│ │ │ │ │
│ │ │ │ │
│ ┌──────┴──────┐ ┌──────┴──────┐ ┌──────┴──────┐ │
│ │ 3 files │ │ 7 files │ │ 15 files │ │
│ │ 150 LOC │ │ 2,500 LOC │ │ 8,000 LOC │ │
│ └─────────────┘ └─────────────┘ └─────────────┘ │
│ │
│ THE PROBLEM: Rename UserService → AccountService │
│ ───────────────────────────────────────────────── │
│ │
│ Manual approach: │
│ 1. Update @org/core-types (wait for CI) │
│ 2. Publish new version (wait for npm) │
│ 3. Update @org/user-api to use new version (wait for CI) │
│ 4. Publish @org/user-api (wait for npm) │
│ 5. Update @org/web-client (wait for CI) │
│ 6. Repeat for ALL dependent repos... │
│ │
│ Time: Days to weeks │
│ Risk: Inconsistent state during migration │
│ │
└─────────────────────────────────────────────────────────────────────────┘
2.2 Dependency Graph Theory
Understanding dependency graphs is fundamental to multi-repo refactoring. From “Algorithms” (Sedgewick, Ch. 4):
DEPENDENCY GRAPH FUNDAMENTALS
┌─────────────────────────────────────────────────────────────────────────┐
│ │
│ DIRECTED ACYCLIC GRAPH (DAG) │
│ ──────────────────────────── │
│ │
│ @org/core-types (no dependencies - ROOT) │
│ │ │
│ ├───────────────────────┐ │
│ │ │ │
│ ▼ ▼ │
│ @org/user-api @org/auth-service │
│ │ │ │
│ ├───────────────────────┼─────────────────┐ │
│ │ │ │ │
│ ▼ ▼ ▼ │
│ @org/web-client @org/mobile-app @org/admin-dashboard │
│ │
│ │
│ TOPOLOGICAL SORT: Processing order that respects dependencies │
│ ───────────────────────────────────────────────────────── │
│ │
│ Level 0: @org/core-types (process first) │
│ Level 1: @org/user-api, @org/auth-service │
│ Level 2: @org/web-client, @org/mobile-app, @org/admin-dashboard │
│ │
│ Key insight: Repos at the same level can be processed in PARALLEL │
│ │
├─────────────────────────────────────────────────────────────────────────┤
│ │
│ CRITICAL PATH ANALYSIS │
│ ────────────────────── │
│ │
│ The critical path is the longest path through the dependency graph. │
│ It determines the minimum time to complete the refactoring. │
│ │
│ Critical path: core-types → user-api → web-client │
│ Length: 3 levels (cannot be parallelized) │
│ │
│ Non-critical: auth-service → mobile-app (can parallel with above) │
│ │
└─────────────────────────────────────────────────────────────────────────┘
2.3 The Subagent Orchestration Pattern
For multi-repo work, a single agent is insufficient. We need coordinated subagents:
SUBAGENT ORCHESTRATION ARCHITECTURE
┌─────────────────────────────────────────────────────────────────────────┐
│ │
│ ORCHESTRATOR AGENT │
│ ───────────────── │
│ │
│ ┌─────────────────────────────────────────────────────────────────┐ │
│ │ │ │
│ │ Responsibilities: │ │
│ │ • Parse user request │ │
│ │ • Build dependency graph │ │
│ │ • Determine processing order │ │
│ │ • Spawn and coordinate subagents │ │
│ │ • Aggregate results │ │
│ │ • Handle failures and rollback │ │
│ │ │ │
│ └─────────────────────────────────────────────────────────────────┘ │
│ │ │
│ ┌──────────────────┼──────────────────┐ │
│ │ │ │ │
│ ▼ ▼ ▼ │
│ ┌───────────────┐ ┌───────────────┐ ┌───────────────┐ │
│ │ SUBAGENT 1 │ │ SUBAGENT 2 │ │ SUBAGENT 3 │ │
│ │ ─────────── │ │ ─────────── │ │ ─────────── │ │
│ │ │ │ │ │ │ │
│ │ Target: │ │ Target: │ │ Target: │ │
│ │ core-types │ │ user-api │ │ auth-service │ │
│ │ │ │ │ │ │ │
│ │ Status: │ │ Status: │ │ Status: │ │
│ │ ✓ Complete │ │ ~ Running │ │ ⏸ Waiting │ │
│ │ │ │ │ │ │ │
│ └───────────────┘ └───────────────┘ └───────────────┘ │
│ │
│ SYNCHRONIZATION BARRIER │
│ ────────────────────── │
│ │
│ Level 0 complete ────────────────────────────────────────────────▶ │
│ Level 1 agents spawned │
│ Level 1 complete ────────────────────────────────────────────────▶ │
│ Level 2 agents spawned │
│ ... │
│ │
└─────────────────────────────────────────────────────────────────────────┘
2.4 Atomic Change Sets and Two-Phase Commit
To ensure consistency, changes must be applied atomically. This pattern comes from distributed database theory:
TWO-PHASE COMMIT FOR MULTI-REPO CHANGES
┌─────────────────────────────────────────────────────────────────────────┐
│ │
│ PHASE 1: PREPARE │
│ ──────────────── │
│ │
│ Orchestrator: "Prepare to rename UserService → AccountService" │
│ │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
│ │ core-types │ │ user-api │ │ auth-service│ │ web-client │ │
│ │ │ │ │ │ │ │ │ │
│ │ Create │ │ Create │ │ Create │ │ Create │ │
│ │ branch │ │ branch │ │ branch │ │ branch │ │
│ │ ✓ │ │ ✓ │ │ ✓ │ │ ✓ │ │
│ │ │ │ │ │ │ │ │ │
│ │ Apply │ │ Apply │ │ Apply │ │ Apply │ │
│ │ changes │ │ changes │ │ changes │ │ changes │ │
│ │ ✓ │ │ ✓ │ │ ✓ │ │ ✓ │ │
│ │ │ │ │ │ │ │ │ │
│ │ Run tests │ │ Run tests │ │ Run tests │ │ Run tests │ │
│ │ ✓ │ │ ✓ │ │ ✓ │ │ ✗ FAIL │ │
│ │ │ │ │ │ │ │ │ │
│ │ VOTE: YES │ │ VOTE: YES │ │ VOTE: YES │ │ VOTE: NO │ │
│ └─────────────┘ └─────────────┘ └─────────────┘ └─────────────┘ │
│ │
│ DECISION: One "NO" vote → ABORT │
│ │
├─────────────────────────────────────────────────────────────────────────┤
│ │
│ PHASE 2A: ABORT (if any failures) │
│ ──────────────────────────────── │
│ │
│ Orchestrator: "Abort - delete all branches" │
│ │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
│ │ core-types │ │ user-api │ │ auth-service│ │ web-client │ │
│ │ │ │ │ │ │ │ │ │
│ │ Delete │ │ Delete │ │ Delete │ │ Delete │ │
│ │ branch │ │ branch │ │ branch │ │ branch │ │
│ │ ✓ Rolled │ │ ✓ Rolled │ │ ✓ Rolled │ │ ✓ Rolled │ │
│ │ back │ │ back │ │ back │ │ back │ │
│ └─────────────┘ └─────────────┘ └─────────────┘ └─────────────┘ │
│ │
├─────────────────────────────────────────────────────────────────────────┤
│ │
│ PHASE 2B: COMMIT (if all success) │
│ ───────────────────────────────── │
│ │
│ Orchestrator: "Commit - create PRs in dependency order" │
│ │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
│ │ core-types │ │ user-api │ │ auth-service│ │ web-client │ │
│ │ │ │ │ │ │ │ │ │
│ │ Create PR │ │ Create PR │ │ Create PR │ │ Create PR │ │
│ │ #101 │ │ #234 │ │ #567 │ │ #890 │ │
│ │ │ │ │ │ │ │ │ │
│ │ Deps: none │ │ Deps: #101 │ │ Deps: #101 │ │ Deps: #234 │ │
│ │ │ │ │ │ │ │ Deps: #567 │ │
│ └─────────────┘ └─────────────┘ └─────────────┘ └─────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────────┘
2.5 Handling the Diamond Dependency Problem
A common challenge in multi-repo refactoring is the diamond dependency:
THE DIAMOND DEPENDENCY PROBLEM
┌─────────────────────────────────────────────────────────────────────────┐
│ │
│ @org/core-types │
│ │ │
│ ┌─────────┴─────────┐ │
│ │ │ │
│ ▼ ▼ │
│ @org/user-api @org/auth-service │
│ │ │ │
│ └─────────┬─────────┘ │
│ │ │
│ ▼ │
│ @org/web-client │
│ (depends on BOTH) │
│ │
│ │
│ PROBLEM: @org/web-client imports from both user-api and auth-service │
│ ──────────────────────────────────────────────────────────────────── │
│ │
│ During migration: │
│ • core-types renames UserService → AccountService │
│ • user-api is updated and published │
│ • auth-service is NOT yet updated │
│ • web-client now sees CONFLICTING types! │
│ - user-api exports AccountService │
│ - auth-service still exports UserService │
│ │
│ SOLUTION: Ensure level-1 repos are updated ATOMICALLY │
│ ─────────────────────────────────────────────────────── │
│ │
│ 1. Update core-types (don't publish yet) │
│ 2. Update user-api AND auth-service in parallel │
│ 3. Wait for BOTH to pass tests │
│ 4. Merge core-types PR first │
│ 5. Publish core-types │
│ 6. Merge user-api and auth-service PRs │
│ 7. Publish both │
│ 8. Now web-client can be updated safely │
│ │
└─────────────────────────────────────────────────────────────────────────┘
2.6 GitHub MCP for PR Coordination
The GitHub MCP provides the interface for cross-repo PR management:
GITHUB MCP OPERATIONS
┌─────────────────────────────────────────────────────────────────────────┐
│ │
│ REPOSITORY ANALYSIS │
│ ─────────────────── │
│ │
│ gh repo list @org --json name,description,updatedAt │
│ gh api repos/{owner}/{repo}/contents/package.json │
│ → Parse dependencies to build graph │
│ │
├─────────────────────────────────────────────────────────────────────────┤
│ │
│ BRANCH OPERATIONS │
│ ───────────────── │
│ │
│ # Create feature branch across repos │
│ gh api repos/{owner}/{repo}/git/refs \ │
│ --method POST \ │
│ --field ref="refs/heads/refactor/rename-user-service" \ │
│ --field sha="{base_sha}" │
│ │
│ # Delete branch on rollback │
│ gh api repos/{owner}/{repo}/git/refs/heads/{branch} --method DELETE │
│ │
├─────────────────────────────────────────────────────────────────────────┤
│ │
│ PULL REQUEST OPERATIONS │
│ ─────────────────────── │
│ │
│ # Create PR with dependencies in description │
│ gh pr create \ │
│ --repo @org/user-api \ │
│ --title "refactor: Rename UserService to AccountService" \ │
│ --body "Depends on: org/core-types#101" \ │
│ --label "refactoring" \ │
│ --draft │
│ │
│ # Mark PR as ready when dependencies are merged │
│ gh pr ready 234 --repo @org/user-api │
│ │
│ # Auto-merge when checks pass │
│ gh pr merge 234 --auto --squash --repo @org/user-api │
│ │
├─────────────────────────────────────────────────────────────────────────┤
│ │
│ CI/CD COORDINATION │
│ ────────────────── │
│ │
│ # Watch for CI completion │
│ gh run watch --repo @org/user-api │
│ │
│ # Get CI status │
│ gh pr checks 234 --repo @org/user-api │
│ │
└─────────────────────────────────────────────────────────────────────────┘
3. Complete Project Specification
3.1 What You Will Build
A Kiro CLI agent that:
- Accepts a refactoring request (rename, move, update API)
- Analyzes all organization repositories for impact
- Builds dependency graph and determines processing order
- Spawns subagents to process repositories in parallel
- Creates coordinated PRs with proper dependencies
- Handles failures with atomic rollback
- Reports progress and final status
3.2 Functional Requirements
| Requirement | Description |
|---|---|
| Repository Discovery | Find all repos containing the target symbol |
| Dependency Analysis | Build cross-repo dependency graph |
| Parallel Processing | Process independent repos simultaneously |
| Change Application | Apply refactoring transformations |
| Test Validation | Run tests in each repo after changes |
| PR Creation | Create linked PRs with dependencies |
| Rollback Handling | Revert all changes on failure |
| Progress Reporting | Show real-time status of all repos |
3.3 Non-Functional Requirements
- Atomicity: All repos updated or none
- Consistency: No repo left in broken state
- Isolation: Parallel agents don’t interfere
- Durability: Checkpoints survive failures
4. Solution Architecture
4.1 System Architecture
┌──────────────────────────────────────────────────────────────────────────────┐
│ MULTI-REPO REFACTORING AGENT │
├──────────────────────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────────────────────────────────────────────────────────────────┐ │
│ │ CLI INTERFACE │ │
│ │ │ │
│ │ kiro-cli chat │ │
│ │ > "Rename UserService to AccountService across all repos" │ │
│ │ │ │
│ └────────────────────────────────────┬────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────────────────────────────────────────────────────────────┐ │
│ │ ORCHESTRATOR AGENT │ │
│ │ │ │
│ │ ┌────────────────┐ ┌────────────────┐ ┌────────────────┐ │ │
│ │ │ Repo Analyzer │ │ Graph Builder │ │ Subagent │ │ │
│ │ │ │ │ │ │ Coordinator │ │ │
│ │ │ • List repos │ │ • Parse deps │ │ │ │ │
│ │ │ • Find usages │ │ • Topo sort │ │ • Spawn agents │ │ │
│ │ │ • Count files │ │ • Level assign │ │ • Sync barrier │ │ │
│ │ └────────────────┘ └────────────────┘ │ • Aggregate │ │ │
│ │ └────────────────┘ │ │
│ │ │ │
│ └──────────────────────────────┬──────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────────────────────────────────────────────────────────────┐ │
│ │ SUBAGENT POOL │ │
│ │ │ │
│ │ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ │
│ │ │ Subagent │ │ Subagent │ │ Subagent │ │ │
│ │ │ core-types │ │ user-api │ │ auth-service │ │ │
│ │ │ │ │ │ │ │ │ │
│ │ │ Clone │ │ Clone │ │ Clone │ │ │
│ │ │ Branch │ │ Branch │ │ Branch │ │ │
│ │ │ Transform │ │ Transform │ │ Transform │ │ │
│ │ │ Test │ │ Test │ │ Test │ │ │
│ │ │ Report │ │ Report │ │ Report │ │ │
│ │ └──────────────┘ └──────────────┘ └──────────────┘ │ │
│ │ │ │
│ └──────────────────────────────┬──────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────────────────────────────────────────────────────────────┐ │
│ │ INTEGRATION LAYER │ │
│ │ │ │
│ │ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ │
│ │ │ GitHub MCP │ │ Checkpoint │ │ Test Runner │ │ │
│ │ │ │ │ Manager │ │ Hook │ │ │
│ │ │ • PR ops │ │ │ │ │ │ │
│ │ │ • Branch ops │ │ • Save state │ │ • Run tests │ │ │
│ │ │ • CI status │ │ • Restore │ │ • Report │ │ │
│ │ └──────────────┘ └──────────────┘ └──────────────┘ │ │
│ │ │ │
│ └─────────────────────────────────────────────────────────────────────────┘ │
│ │
└──────────────────────────────────────────────────────────────────────────────┘
4.2 Data Flow
REFACTORING DATA FLOW
┌─────────────────────────────────────────────────────────────────────────┐
│ │
│ USER REQUEST │
│ "Rename UserService → AccountService" │
│ │ │
│ ▼ │
│ ┌────────────────────────────────────────────────────────────────┐ │
│ │ REPOSITORY SCAN │ │
│ │ │ │
│ │ Output: ImpactAnalysis │ │
│ │ { │ │
│ │ targetSymbol: "UserService", │ │
│ │ affectedRepos: [ │ │
│ │ { name: "core-types", files: 3, usages: 5 }, │ │
│ │ { name: "user-api", files: 7, usages: 23 }, │ │
│ │ { name: "auth-service", files: 4, usages: 12 }, │ │
│ │ { name: "web-client", files: 12, usages: 45 } │ │
│ │ ] │ │
│ │ } │ │
│ └───────────────────────────────┬────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌────────────────────────────────────────────────────────────────┐ │
│ │ DEPENDENCY GRAPH │ │
│ │ │ │
│ │ Output: DependencyGraph │ │
│ │ { │ │
│ │ levels: [ │ │
│ │ ["core-types"], │ │
│ │ ["user-api", "auth-service"], │ │
│ │ ["web-client"] │ │
│ │ ], │ │
│ │ edges: [ │ │
│ │ { from: "core-types", to: "user-api" }, │ │
│ │ { from: "core-types", to: "auth-service" }, │ │
│ │ { from: "user-api", to: "web-client" }, │ │
│ │ { from: "auth-service", to: "web-client" } │ │
│ │ ] │ │
│ │ } │ │
│ └───────────────────────────────┬────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌────────────────────────────────────────────────────────────────┐ │
│ │ PARALLEL EXECUTION │ │
│ │ │ │
│ │ Level 0: │ │
│ │ ├── Subagent: core-types → Success │ │
│ │ └── ✓ Barrier: Level 0 complete │ │
│ │ │ │
│ │ Level 1: │ │
│ │ ├── Subagent: user-api → Success │ │
│ │ ├── Subagent: auth-service → Success │ │
│ │ └── ✓ Barrier: Level 1 complete │ │
│ │ │ │
│ │ Level 2: │ │
│ │ ├── Subagent: web-client → Success │ │
│ │ └── ✓ Barrier: Level 2 complete │ │
│ │ │ │
│ └───────────────────────────────┬────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌────────────────────────────────────────────────────────────────┐ │
│ │ PR CREATION │ │
│ │ │ │
│ │ Output: PRCoordination │ │
│ │ { │ │
│ │ prs: [ │ │
│ │ { repo: "core-types", number: 101, deps: [] }, │ │
│ │ { repo: "user-api", number: 234, deps: [101] }, │ │
│ │ { repo: "auth-service", number: 567, deps: [101] }, │ │
│ │ { repo: "web-client", number: 890, deps: [234, 567] } │ │
│ │ ], │ │
│ │ mergeOrder: ["core-types", "user-api", "auth-service", │ │
│ │ "web-client"] │ │
│ │ } │ │
│ └────────────────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────────┘
4.3 Key Data Structures
// Core types for multi-repo refactoring
interface RefactoringRequest {
type: 'rename' | 'move' | 'deprecate' | 'update-api';
target: {
symbol: string;
type: 'interface' | 'class' | 'function' | 'type' | 'constant';
sourceRepo: string;
};
replacement: {
symbol: string;
location?: string; // For move operations
};
}
interface ImpactAnalysis {
targetSymbol: string;
affectedRepos: RepoImpact[];
totalFiles: number;
totalUsages: number;
estimatedTime: string;
}
interface RepoImpact {
name: string;
files: string[];
usages: UsageLocation[];
dependencies: string[];
isSource: boolean; // true if this repo defines the symbol
}
interface UsageLocation {
file: string;
line: number;
column: number;
context: string; // Surrounding code
usageType: 'import' | 'type-reference' | 'value-reference';
}
interface DependencyGraph {
nodes: string[]; // Repo names
edges: DependencyEdge[];
levels: string[][]; // Repos grouped by dependency level
criticalPath: string[];
}
interface DependencyEdge {
from: string; // Repo that provides
to: string; // Repo that consumes
symbols: string[]; // Shared symbols
}
interface SubagentResult {
repo: string;
status: 'success' | 'failure' | 'skipped';
changes: FileChange[];
testResults: TestResult;
branchName: string;
commitSha: string;
error?: string;
}
interface PRCoordination {
prs: PRInfo[];
mergeOrder: string[];
autoMergeEnabled: boolean;
}
interface PRInfo {
repo: string;
number: number;
title: string;
branch: string;
dependencies: number[]; // PR numbers this depends on
status: 'draft' | 'ready' | 'merged' | 'closed';
checksStatus: 'pending' | 'passing' | 'failing';
}
interface MultiRepoCheckpoint {
id: string;
timestamp: Date;
request: RefactoringRequest;
repoStates: Map<string, RepoCheckpoint>;
phase: 'analyzing' | 'processing' | 'creating-prs' | 'complete';
}
interface RepoCheckpoint {
repo: string;
branchName: string;
baseSha: string;
headSha: string;
status: 'pending' | 'processing' | 'success' | 'failure' | 'rolled-back';
}
5. Phased Implementation Guide
Phase 1: Repository Analysis (Days 1-7)
Goals:
- Scan organization repositories
- Find symbol usages across repos
- Build initial impact analysis
Tasks:
- Implement GitHub MCP integration for repo listing
- Build symbol search using ripgrep or AST parsing
- Parse package.json for dependency mapping
- Generate impact analysis report
- Create visualization of affected repos
Milestone Checkpoint:
$ kiro-cli chat
> "Analyze impact of renaming UserService in @org"
[Analysis] Scanning organization repositories...
├── Found 12 repositories with TypeScript
├── Searching for "UserService" usages...
└── Building dependency graph...
[Impact Analysis]
┌────────────────────────────────────────────────────────────────────┐
│ Repository │ Files │ Usages │ Dependencies │
├──────────────────────┼───────┼────────┼───────────────────────────┤
│ @org/core-types │ 3 │ 5 │ None (source) │
│ @org/user-api │ 7 │ 23 │ @org/core-types │
│ @org/auth-service │ 4 │ 12 │ @org/core-types │
│ @org/web-client │ 12 │ 45 │ user-api, auth-service │
└──────────────────────┴───────┴────────┴───────────────────────────┘
Total: 4 repos, 26 files, 85 usages
Estimated time: 2-3 hours with AI assistance
Hint 1: Use gh api repos/{owner}/{repo}/contents/package.json to fetch package.json files directly from GitHub.
Phase 2: Dependency Graph (Days 8-14)
Goals:
- Build complete dependency graph
- Implement topological sorting
- Determine processing levels
Tasks:
- Parse all package.json dependencies
- Build directed graph of repo dependencies
- Implement topological sort algorithm
- Group repos by dependency level
- Identify critical path
Milestone Checkpoint:
> "Show dependency graph for refactoring"
[Dependency Graph]
Level 0 (no dependencies):
└── @org/core-types
Level 1 (depends on Level 0):
├── @org/user-api
└── @org/auth-service
Level 2 (depends on Level 1):
└── @org/web-client
Critical Path: core-types → user-api → web-client
Parallel Opportunities: user-api and auth-service can run in parallel
Hint 2: Use Kahn’s algorithm for topological sort - it naturally gives you level assignments.
Phase 3: Subagent Orchestration (Days 15-21)
Goals:
- Implement subagent spawning
- Build synchronization barriers
- Handle parallel execution
Tasks:
- Create subagent configuration for repo processing
- Implement barrier synchronization between levels
- Build result aggregation system
- Add progress reporting for parallel agents
- Implement timeout handling
Milestone Checkpoint:
> "Start refactoring UserService → AccountService"
[Orchestrator] Creating checkpoint: multi-repo-refactor-20241222
[Level 0] Processing 1 repository...
├── [Subagent: core-types] Cloning... ✓
├── [Subagent: core-types] Creating branch... ✓
├── [Subagent: core-types] Applying changes... 3 files
├── [Subagent: core-types] Running tests... ✓
└── ✓ Level 0 complete
[Level 1] Processing 2 repositories in parallel...
├── [Subagent: user-api] Applying changes... 7 files
├── [Subagent: auth-service] Applying changes... 4 files
├── [Subagent: user-api] Running tests... ✓
├── [Subagent: auth-service] Running tests... ✓
└── ✓ Level 1 complete
[Level 2] Processing 1 repository...
...
Hint 3: Use Promise.all() for parallel execution within a level, but await between levels.
Phase 4: PR Coordination (Days 22-28)
Goals:
- Create linked pull requests
- Express dependencies between PRs
- Enable auto-merge in correct order
Tasks:
- Create PRs with proper descriptions
- Add dependency links in PR descriptions
- Implement PR status monitoring
- Set up auto-merge with dependency checks
- Handle merge conflicts
Milestone Checkpoint:
> "Create pull requests for the changes"
[PR Creation]
├── Creating PR in @org/core-types...
│ ✓ PR #101: "refactor: Rename UserService to AccountService"
│
├── Creating PR in @org/user-api...
│ ✓ PR #234: "refactor: Update to AccountService"
│ └── Dependencies: org/core-types#101
│
├── Creating PR in @org/auth-service...
│ ✓ PR #567: "refactor: Update to AccountService"
│ └── Dependencies: org/core-types#101
│
└── Creating PR in @org/web-client...
✓ PR #890: "refactor: Update to AccountService"
└── Dependencies: org/user-api#234, org/auth-service#567
[Auto-merge enabled]
Merge order: #101 → #234, #567 → #890
Phase 5: Rollback and Recovery (Days 29-35)
Goals:
- Implement atomic rollback
- Handle partial failures
- Provide recovery options
Tasks:
- Build checkpoint restoration
- Implement branch deletion for rollback
- Add PR closure on failure
- Create recovery commands
- Test failure scenarios
Hint 4: Store the base SHA for each repo before changes - this is your rollback target.
6. Testing Strategy
6.1 Unit Tests
describe('DependencyGraph', () => {
it('should detect circular dependencies', () => {
const graph = new DependencyGraph();
graph.addEdge('A', 'B');
graph.addEdge('B', 'C');
graph.addEdge('C', 'A'); // Creates cycle
expect(() => graph.topologicalSort()).toThrow('Circular dependency detected');
});
it('should group repos by dependency level', () => {
const graph = new DependencyGraph();
graph.addEdge('core', 'api');
graph.addEdge('core', 'auth');
graph.addEdge('api', 'web');
graph.addEdge('auth', 'web');
const levels = graph.getLevels();
expect(levels[0]).toEqual(['core']);
expect(levels[1]).toContain('api');
expect(levels[1]).toContain('auth');
expect(levels[2]).toEqual(['web']);
});
});
6.2 Integration Tests
describe('MultiRepoRefactoring', () => {
it('should rollback all repos on single failure', async () => {
const orchestrator = new RefactoringOrchestrator();
// Mock one repo to fail tests
mockTestRunner.mockImplementation((repo) => {
if (repo === 'auth-service') {
return { passed: false, errors: ['Test failed'] };
}
return { passed: true };
});
await orchestrator.execute({
type: 'rename',
target: { symbol: 'UserService', sourceRepo: 'core-types' },
replacement: { symbol: 'AccountService' }
});
// Verify all repos rolled back
expect(mockGitHub.deleteBranch).toHaveBeenCalledWith('core-types', 'refactor/rename-user-service');
expect(mockGitHub.deleteBranch).toHaveBeenCalledWith('user-api', 'refactor/rename-user-service');
expect(mockGitHub.deleteBranch).toHaveBeenCalledWith('auth-service', 'refactor/rename-user-service');
});
});
7. Common Pitfalls and Debugging
7.1 Common Issues
| Pitfall | Symptom | Solution |
|---|---|---|
| Race conditions | Parallel agents conflict | Use level-based synchronization |
| Stale dependencies | Package versions don’t match | Verify versions before starting |
| Merge conflicts | PRs can’t auto-merge | Process in strict dependency order |
| Test flakiness | Random failures block progress | Implement retry with backoff |
| API rate limits | GitHub API errors | Add rate limiting and queuing |
7.2 Debugging Strategies
1. Enable detailed logging per subagent:
const subagent = createSubagent({
repo: 'user-api',
onProgress: (step, detail) => {
console.log(`[${repo}] ${step}: ${detail}`);
},
onError: (error) => {
console.error(`[${repo}] ERROR: ${error.message}`);
console.error(`[${repo}] Stack: ${error.stack}`);
}
});
2. Visualize dependency graph:
> "Show me the dependency graph in Mermaid format"
graph TD
core-types --> user-api
core-types --> auth-service
user-api --> web-client
auth-service --> web-client
3. Inspect checkpoint state:
> "Show checkpoint details for multi-repo-refactor-20241222"
[Checkpoint: multi-repo-refactor-20241222]
├── Phase: creating-prs
├── Repos:
│ ├── core-types: success (branch: refactor/rename-user-service)
│ ├── user-api: success (branch: refactor/rename-user-service)
│ ├── auth-service: failure (tests failed)
│ └── web-client: skipped (blocked by auth-service)
└── Action: Rollback recommended
8. Extensions and Challenges
8.1 Beginner Extensions
- Add dry-run mode that shows planned changes without applying
- Generate detailed change report with diffs
- Add notification system (Slack, email) for progress
8.2 Intermediate Extensions
- Support for monorepo structures (Lerna, Nx)
- Implement semantic versioning bump automation
- Add approval workflow before PR creation
8.3 Advanced Extensions
- Machine learning for effort estimation based on history
- Integration with code review platforms (Reviewable, Graphite)
- Support for cross-language refactoring (shared API types)
9. Real-World Connections
9.1 Industry Tools
| Tool | Pattern Used | Company |
|---|---|---|
| Sourcegraph Batch Changes | Multi-repo refactoring | Sourcegraph |
| Renovate Bot | Dependency updates | Mend |
| Dependabot | Automated PRs | GitHub |
| Atomist | Code transformation | Atomist |
9.2 Enterprise Use Cases
- API versioning: Update all consumers when API changes
- Security patches: Apply fixes across all repositories
- Framework upgrades: Migrate React/Vue/Angular versions
- Deprecation: Remove usage of deprecated APIs
10. Self-Assessment Checklist
Understanding Verification
- I can explain topological sorting and why it matters
- I understand the two-phase commit pattern for atomic changes
- I can describe the diamond dependency problem and solutions
- I know how to coordinate PRs with dependencies
- I can explain subagent orchestration patterns
Implementation Verification
- Repository analysis correctly finds all usages
- Dependency graph is built correctly
- Subagents process repos in parallel within levels
- Synchronization barriers work between levels
- PRs are created with correct dependencies
- Rollback works when any repo fails
Integration Verification
- Full refactoring works on test repositories
- PR auto-merge respects dependency order
- Recovery works from any checkpoint
- Progress is reported accurately
11. Completion Criteria
Minimum Viable Completion
- Analyzes repositories and builds dependency graph
- Processes repos in correct dependency order
- Creates PRs with dependency information
- Handles single-repo failures with rollback
Full Completion
- Parallel processing within dependency levels
- Full atomic rollback across all repos
- Auto-merge with dependency checking
- Comprehensive progress reporting
- Checkpoint-based recovery
Excellence (Going Above and Beyond)
- Monorepo support
- Cross-organization refactoring
- Machine learning for effort estimation
- Integration with code review platforms
- Visual dependency graph in dashboard
This guide was expanded from LEARN_KIRO_CLI_MASTERY.md. For the complete learning path, see the README.