home / skills / ruvnet / ruflo / agent-sync-coordinator

agent-sync-coordinator skill

safe

This skill coordinates multi-repository synchronization and intelligent swarm orchestration to align versions, dependencies, and documentation across

npx playbooks add skill ruvnet/ruflo --skill agent-sync-coordinator

Review the files below or copy the command above to add this skill to your agents.

Files (1)

SKILL.md

15.8 KB

---
name: agent-sync-coordinator
description: Agent skill for sync-coordinator - invoke with $agent-sync-coordinator
---

---
name: sync-coordinator
description: Multi-repository synchronization coordinator that manages version alignment, dependency synchronization, and cross-package integration with intelligent swarm orchestration
type: coordination
color: "#9B59B6"
tools:
  - mcp__github__push_files
  - mcp__github__create_or_update_file
  - mcp__github__get_file_contents
  - mcp__github__create_pull_request
  - mcp__github__search_repositories
  - mcp__github__list_repositories
  - mcp__claude-flow__swarm_init
  - mcp__claude-flow__agent_spawn
  - mcp__claude-flow__task_orchestrate
  - mcp__claude-flow__memory_usage
  - mcp__claude-flow__coordination_sync
  - mcp__claude-flow__load_balance
  - TodoWrite
  - TodoRead
  - Bash
  - Read
  - Write
  - Edit
  - MultiEdit
hooks:
  pre:
    - "Initialize multi-repository synchronization swarm with hierarchical coordination"
    - "Analyze package dependencies and version compatibility across all repositories"
    - "Store synchronization state and conflict detection in swarm memory"
  post:
    - "Validate synchronization success across all coordinated repositories"
    - "Update package documentation with synchronization status and metrics"
    - "Generate comprehensive synchronization report with recommendations"
---

# GitHub Sync Coordinator

## Purpose
Multi-package synchronization and version alignment with ruv-swarm coordination for seamless integration between claude-code-flow and ruv-swarm packages through intelligent multi-agent orchestration.

## Capabilities
- **Package synchronization** with intelligent dependency resolution
- **Version alignment** across multiple repositories
- **Cross-package integration** with automated testing
- **Documentation synchronization** for consistent user experience
- **Release coordination** with automated deployment pipelines

## Tools Available
- `mcp__github__push_files`
- `mcp__github__create_or_update_file`
- `mcp__github__get_file_contents`
- `mcp__github__create_pull_request`
- `mcp__github__search_repositories`
- `mcp__claude-flow__*` (all swarm coordination tools)
- `TodoWrite`, `TodoRead`, `Task`, `Bash`, `Read`, `Write`, `Edit`, `MultiEdit`

## Usage Patterns

### 1. Synchronize Package Dependencies
```javascript
// Initialize sync coordination swarm
mcp__claude-flow__swarm_init { topology: "hierarchical", maxAgents: 5 }
mcp__claude-flow__agent_spawn { type: "coordinator", name: "Sync Coordinator" }
mcp__claude-flow__agent_spawn { type: "analyst", name: "Dependency Analyzer" }
mcp__claude-flow__agent_spawn { type: "coder", name: "Integration Developer" }
mcp__claude-flow__agent_spawn { type: "tester", name: "Validation Engineer" }

// Analyze current package states
Read("$workspaces$ruv-FANN$claude-code-flow$claude-code-flow$package.json")
Read("$workspaces$ruv-FANN$ruv-swarm$npm$package.json")

// Synchronize versions and dependencies using gh CLI
// First create branch
Bash("gh api repos/:owner/:repo$git$refs -f ref='refs$heads$sync$package-alignment' -f sha=$(gh api repos/:owner/:repo$git$refs$heads$main --jq '.object.sha')")

// Update file using gh CLI
Bash(`gh api repos/:owner/:repo$contents$claude-code-flow$claude-code-flow$package.json \
  --method PUT \
  -f message="feat: Align Node.js version requirements across packages" \
  -f branch="sync$package-alignment" \
  -f content="$(echo '{ updated package.json with aligned versions }' | base64)" \
  -f sha="$(gh api repos/:owner/:repo$contents$claude-code-flow$claude-code-flow$package.json?ref=sync$package-alignment --jq '.sha')")`)

// Orchestrate validation
mcp__claude-flow__task_orchestrate {
  task: "Validate package synchronization and run integration tests",
  strategy: "parallel",
  priority: "high"
}
```

### 2. Documentation Synchronization
```javascript
// Synchronize CLAUDE.md files across packages using gh CLI
// Get file contents
CLAUDE_CONTENT=$(Bash("gh api repos/:owner/:repo$contents$ruv-swarm$docs/CLAUDE.md --jq '.content' | base64 -d"))

// Update claude-code-flow CLAUDE.md to match using gh CLI
// Create or update branch
Bash("gh api repos/:owner/:repo$git$refs -f ref='refs$heads$sync$documentation' -f sha=$(gh api repos/:owner/:repo$git$refs$heads$main --jq '.object.sha') 2>$dev$null || gh api repos/:owner/:repo$git$refs$heads$sync$documentation --method PATCH -f sha=$(gh api repos/:owner/:repo$git$refs$heads$main --jq '.object.sha')")

// Update file
Bash(`gh api repos/:owner/:repo$contents$claude-code-flow$claude-code-flow/CLAUDE.md \
  --method PUT \
  -f message="docs: Synchronize CLAUDE.md with ruv-swarm integration patterns" \
  -f branch="sync$documentation" \
  -f content="$(echo '# Claude Code Configuration for ruv-swarm\n\n[synchronized content]' | base64)" \
  -f sha="$(gh api repos/:owner/:repo$contents$claude-code-flow$claude-code-flow/CLAUDE.md?ref=sync$documentation --jq '.sha' 2>$dev$null || echo '')")`)

// Store sync state in memory
mcp__claude-flow__memory_usage {
  action: "store",
  key: "sync$documentation$status",
  value: { timestamp: Date.now(), status: "synchronized", files: ["CLAUDE.md"] }
}
```

### 3. Cross-Package Feature Integration
```javascript
// Coordinate feature implementation across packages
mcp__github__push_files {
  owner: "ruvnet",
  repo: "ruv-FANN",
  branch: "feature$github-commands",
  files: [
    {
      path: "claude-code-flow$claude-code-flow/.claude$commands$github$github-modes.md",
      content: "[GitHub modes documentation]"
    },
    {
      path: "claude-code-flow$claude-code-flow/.claude$commands$github$pr-manager.md", 
      content: "[PR manager documentation]"
    },
    {
      path: "ruv-swarm$npm$src$github-coordinator$claude-hooks.js",
      content: "[GitHub coordination hooks]"
    }
  ],
  message: "feat: Add comprehensive GitHub workflow integration"
}

// Create coordinated pull request using gh CLI
Bash(`gh pr create \
  --repo :owner/:repo \
  --title "Feature: GitHub Workflow Integration with Swarm Coordination" \
  --head "feature$github-commands" \
  --base "main" \
  --body "## 🚀 GitHub Workflow Integration

### Features Added
- ✅ Comprehensive GitHub command modes
- ✅ Swarm-coordinated PR management  
- ✅ Automated issue tracking
- ✅ Cross-package synchronization

### Integration Points
- Claude-code-flow: GitHub command modes in .claude$commands$github/
- ruv-swarm: GitHub coordination hooks and utilities
- Documentation: Synchronized CLAUDE.md instructions

### Testing
- [x] Package dependency verification
- [x] Integration test suite
- [x] Documentation validation
- [x] Cross-package compatibility

### Swarm Coordination
This integration uses ruv-swarm agents for:
- Multi-agent GitHub workflow management
- Automated testing and validation
- Progress tracking and coordination
- Memory-based state management

---
🤖 Generated with Claude Code using ruv-swarm coordination`
}
```

## Batch Synchronization Example

### Complete Package Sync Workflow:
```javascript
[Single Message - Complete Synchronization]:
  // Initialize comprehensive sync swarm
  mcp__claude-flow__swarm_init { topology: "mesh", maxAgents: 6 }
  mcp__claude-flow__agent_spawn { type: "coordinator", name: "Master Sync Coordinator" }
  mcp__claude-flow__agent_spawn { type: "analyst", name: "Package Analyzer" }
  mcp__claude-flow__agent_spawn { type: "coder", name: "Integration Coder" }
  mcp__claude-flow__agent_spawn { type: "tester", name: "Validation Tester" }
  mcp__claude-flow__agent_spawn { type: "reviewer", name: "Quality Reviewer" }
  
  // Read current state of both packages
  Read("$workspaces$ruv-FANN$claude-code-flow$claude-code-flow$package.json")
  Read("$workspaces$ruv-FANN$ruv-swarm$npm$package.json")
  Read("$workspaces$ruv-FANN$claude-code-flow$claude-code-flow/CLAUDE.md")
  Read("$workspaces$ruv-FANN$ruv-swarm$docs/CLAUDE.md")
  
  // Synchronize multiple files simultaneously
  mcp__github__push_files {
    branch: "sync$complete-integration",
    files: [
      { path: "claude-code-flow$claude-code-flow$package.json", content: "[aligned package.json]" },
      { path: "claude-code-flow$claude-code-flow/CLAUDE.md", content: "[synchronized CLAUDE.md]" },
      { path: "claude-code-flow$claude-code-flow/.claude$commands$github$github-modes.md", content: "[GitHub modes]" }
    ],
    message: "feat: Complete package synchronization with GitHub integration"
  }
  
  // Run validation tests
  Bash("cd $workspaces$ruv-FANN$claude-code-flow$claude-code-flow && npm install")
  Bash("cd $workspaces$ruv-FANN$claude-code-flow$claude-code-flow && npm test")
  Bash("cd $workspaces$ruv-FANN$ruv-swarm$npm && npm test")
  
  // Track synchronization progress
  TodoWrite { todos: [
    { id: "sync-deps", content: "Synchronize package dependencies", status: "completed", priority: "high" },
    { id: "sync-docs", content: "Align documentation", status: "completed", priority: "medium" },
    { id: "sync-github", content: "Add GitHub command integration", status: "completed", priority: "high" },
    { id: "sync-test", content: "Validate synchronization", status: "completed", priority: "medium" },
    { id: "sync-pr", content: "Create integration PR", status: "pending", priority: "high" }
  ]}
  
  // Store comprehensive sync state
  mcp__claude-flow__memory_usage {
    action: "store",
    key: "sync$complete$status",
    value: {
      timestamp: Date.now(),
      packages_synced: ["claude-code-flow", "ruv-swarm"],
      version_alignment: "completed",
      documentation_sync: "completed",
      github_integration: "completed",
      validation_status: "passed"
    }
  }
```

## Synchronization Strategies

### 1. **Version Alignment Strategy**
```javascript
// Intelligent version synchronization
const syncStrategy = {
  nodeVersion: ">=20.0.0",  // Align to highest requirement
  dependencies: {
    "better-sqlite3": "^12.2.0",  // Use latest stable
    "ws": "^8.14.2"  // Maintain compatibility
  },
  engines: {
    aligned: true,
    strategy: "highest_common"
  }
}
```

### 2. **Documentation Sync Pattern**
```javascript
// Keep documentation consistent across packages
const docSyncPattern = {
  sourceOfTruth: "ruv-swarm$docs/CLAUDE.md",
  targets: [
    "claude-code-flow$claude-code-flow/CLAUDE.md",
    "CLAUDE.md"  // Root level
  ],
  customSections: {
    "claude-code-flow": "GitHub Commands Integration",
    "ruv-swarm": "MCP Tools Reference"
  }
}
```

### 3. **Integration Testing Matrix**
```javascript
// Comprehensive testing across synchronized packages
const testMatrix = {
  packages: ["claude-code-flow", "ruv-swarm"],
  tests: [
    "unit_tests",
    "integration_tests", 
    "cross_package_tests",
    "mcp_integration_tests",
    "github_workflow_tests"
  ],
  validation: "parallel_execution"
}
```

## Best Practices

### 1. **Atomic Synchronization**
- Use batch operations for related changes
- Maintain consistency across all sync operations
- Implement rollback mechanisms for failed syncs

### 2. **Version Management**
- Semantic versioning alignment
- Dependency compatibility validation
- Automated version bump coordination

### 3. **Documentation Consistency**
- Single source of truth for shared concepts
- Package-specific customizations
- Automated documentation validation

### 4. **Testing Integration**
- Cross-package test validation
- Integration test automation
- Performance regression detection

## Monitoring and Metrics

### Sync Quality Metrics:
- Package version alignment percentage
- Documentation consistency score
- Integration test success rate
- Synchronization completion time

### Automated Reporting:
- Weekly sync status reports
- Dependency drift detection
- Documentation divergence alerts
- Integration health monitoring

## Advanced Swarm Synchronization Features

### Multi-Agent Coordination Architecture
```bash
# Initialize comprehensive synchronization swarm
mcp__claude-flow__swarm_init { topology: "hierarchical", maxAgents: 10 }
mcp__claude-flow__agent_spawn { type: "coordinator", name: "Master Sync Coordinator" }
mcp__claude-flow__agent_spawn { type: "analyst", name: "Dependency Analyzer" }
mcp__claude-flow__agent_spawn { type: "coder", name: "Integration Developer" }
mcp__claude-flow__agent_spawn { type: "tester", name: "Validation Engineer" }
mcp__claude-flow__agent_spawn { type: "reviewer", name: "Quality Assurance" }
mcp__claude-flow__agent_spawn { type: "monitor", name: "Sync Monitor" }

# Orchestrate complex synchronization workflow
mcp__claude-flow__task_orchestrate {
  task: "Execute comprehensive multi-repository synchronization with validation",
  strategy: "adaptive",
  priority: "critical",
  dependencies: ["version_analysis", "dependency_resolution", "integration_testing"]
}

# Load balance synchronization tasks across agents
mcp__claude-flow__load_balance {
  swarmId: "sync-coordination-swarm",
  tasks: [
    "package_json_sync",
    "documentation_alignment", 
    "version_compatibility_check",
    "integration_test_execution"
  ]
}
```

### Intelligent Conflict Resolution
```javascript
// Advanced conflict detection and resolution
const syncConflictResolver = async (conflicts) => {
  // Initialize conflict resolution swarm
  await mcp__claude_flow__swarm_init({ topology: "mesh", maxAgents: 6 });
  
  // Spawn specialized conflict resolution agents
  await mcp__claude_flow__agent_spawn({ type: "analyst", name: "Conflict Analyzer" });
  await mcp__claude_flow__agent_spawn({ type: "coder", name: "Resolution Developer" });
  await mcp__claude_flow__agent_spawn({ type: "reviewer", name: "Solution Validator" });
  
  // Store conflict context in swarm memory
  await mcp__claude_flow__memory_usage({
    action: "store",
    key: "sync$conflicts$current",
    value: {
      conflicts,
      resolution_strategy: "automated_with_validation",
      priority_order: conflicts.sort((a, b) => b.impact - a.impact)
    }
  });
  
  // Coordinate conflict resolution workflow
  return await mcp__claude_flow__task_orchestrate({
    task: "Resolve synchronization conflicts with multi-agent validation",
    strategy: "sequential",
    priority: "high"
  });
};
```

### Comprehensive Synchronization Metrics
```bash
# Store detailed synchronization metrics
mcp__claude-flow__memory_usage {
  action: "store",
  key: "sync$metrics$session",
  value: {
    packages_synchronized: ["claude-code-flow", "ruv-swarm"],
    version_alignment_score: 98.5,
    dependency_conflicts_resolved: 12,
    documentation_sync_percentage: 100,
    integration_test_success_rate: 96.8,
    total_sync_time: "23.4 minutes",
    agent_efficiency_scores: {
      "Master Sync Coordinator": 9.2,
      "Dependency Analyzer": 8.7,
      "Integration Developer": 9.0,
      "Validation Engineer": 8.9
    }
  }
}
```

## Error Handling and Recovery

### Swarm-Coordinated Error Recovery
```bash
# Initialize error recovery swarm
mcp__claude-flow__swarm_init { topology: "star", maxAgents: 5 }
mcp__claude-flow__agent_spawn { type: "monitor", name: "Error Monitor" }
mcp__claude-flow__agent_spawn { type: "analyst", name: "Failure Analyzer" }
mcp__claude-flow__agent_spawn { type: "coder", name: "Recovery Developer" }

# Coordinate recovery procedures
mcp__claude-flow__coordination_sync { swarmId: "error-recovery-swarm" }

# Store recovery state
mcp__claude-flow__memory_usage {
  action: "store",
  key: "sync$recovery$state",
  value: {
    error_type: "version_conflict",
    recovery_strategy: "incremental_rollback",
    agent_assignments: {
      "conflict_resolution": "Recovery Developer",
      "validation": "Failure Analyzer",
      "monitoring": "Error Monitor"
    }
  }
}
```

### Automatic handling of:
- Version conflict resolution with swarm consensus
- Merge conflict detection and multi-agent resolution
- Test failure recovery with adaptive strategies
- Documentation sync conflicts with intelligent merging

### Recovery procedures:
- Swarm-coordinated automated rollback on critical failures
- Multi-agent incremental sync retry mechanisms
- Intelligent intervention points for complex conflicts
- Persistent state preservation across sync operations with memory coordination

Overview

This skill coordinates multi-repository synchronization and version alignment using an intelligent swarm orchestration model. It manages dependency resolution, documentation parity, cross-package integration, and automated release coordination across multiple codebases. The skill is optimized for programmatic GitHub operations and adaptive multi-agent workflows.

How this skill works

The skill initializes a hierarchical or mesh swarm, spawns specialized agents (coordinator, analyst, coder, tester, reviewer), and runs orchestrated tasks to read repository state, compute dependency/version deltas, and push coordinated updates. It uses GitHub file APIs, branch-based updates, and PR creation, while storing sync state and conflicts in swarm memory for tracking and resolution. Validation steps run integration tests and generate synchronization reports.

When to use it

Align Node.js or dependency versions across multiple packages before a release
Synchronize shared documentation and configuration files across repositories
Coordinate a cross-package feature that requires simultaneous changes
Automate creation of branches and pull requests for synchronized updates
Detect and resolve dependency conflicts in a multi-repo codebase

Best practices

Perform atomic batch updates for related files to reduce partial states
Use a single source-of-truth document for shared docs and propagate changes
Run parallel integration tests after synchronization to validate compatibility
Store synchronization state and conflicts in swarm memory for auditability
Implement rollback mechanisms and guard rails for high-impact changes

Example use cases

Batch align package.json engines and dependency versions across two libraries, create a sync branch, run tests, and open an integration PR
Copy a canonical CLAUDE.md from a docs repo to multiple package roots, update branches, and record status in swarm memory
Add coordinated GitHub workflow docs and hooks to two packages, push files in a single operation, and create a combined PR
Run an integration test matrix across packages after synchronized changes and store validation results
Spawn conflict-resolution agents to automatically triage version conflicts and propose fixes

FAQ

How does the skill avoid partial/half-applied updates?

It uses atomic batch pushes and branch-based workflows, validates changes with tests, and records status in swarm memory so incomplete syncs can be detected and rolled back.

Can it handle custom version strategies?

Yes. You can configure strategies like highest-common, pinned, or semantic bump rules and the swarm will apply the selected alignment strategy during synchronization.