MCP Standards

# Project Board Sync - GitHub Projects Integration ## Overview Synchronize AI swarms with GitHub Projects for visual task management, progress tracking, and team coordination. ## Core Features ### 1. Board Initialization ```bash # Connect swarm to GitHub Project using gh CLI # Get project details PROJECT_ID=$(gh project list --owner @me --format json | \ jq -r '.projects[] | select(.title == "Development Board") | .id') # Initialize swarm with project npx ruv-swarm github board-init \ --project-id "$PROJECT_ID" \ --sync-mode "bidirectional" \ --create-views "swarm-status,agent-workload,priority" # Create project fields for swarm tracking gh project field-create $PROJECT_ID --owner @me \ --name "Swarm Status" \ --data-type "SINGLE_SELECT" \ --single-select-options "pending,in_progress,completed" ``` ### 2. Task Synchronization ```bash # Sync swarm tasks with project cards npx ruv-swarm github board-sync \ --map-status '{ "todo": "To Do", "in_progress": "In Progress", "review": "Review", "done": "Done" }' \ --auto-move-cards \ --update-metadata ``` ### 3. Real-time Updates ```bash # Enable real-time board updates npx ruv-swarm github board-realtime \ --webhook-endpoint "https://api.example.com/github-sync" \ --update-frequency "immediate" \ --batch-updates false ``` ## Configuration ### Board Mapping Configuration ```yaml # .github/board-sync.yml version: 1 project: name: "AI Development Board" number: 1 mapping: # Map swarm task status to board columns status: pending: "Backlog" assigned: "Ready" in_progress: "In Progress" review: "Review" completed: "Done" blocked: "Blocked" # Map agent types to labels agents: coder: "🔧 Development" tester: "🧪 Testing" analyst: "📊 Analysis" designer: "🎨 Design" architect: "🏗️ Architecture" # Map priority to project fields priority: critical: "🔴 Critical" high: "🟡 High" medium: "🟢 Medium" low: "⚪ Low" # Custom fields fields: - name: "Agent Count" type: number source: task.agents.length - name: "Complexity" type: select source: task.complexity - name: "ETA" type: date source: task.estimatedCompletion ``` ### View Configuration ```javascript // Custom board views { "views": [ { "name": "Swarm Overview", "type": "board", "groupBy": "status", "filters": ["is:open"], "sort": "priority:desc" }, { "name": "Agent Workload", "type": "table", "groupBy": "assignedAgent", "columns": ["title", "status", "priority", "eta"], "sort": "eta:asc" }, { "name": "Sprint Progress", "type": "roadmap", "dateField": "eta", "groupBy": "milestone" } ] } ``` ## Automation Features ### 1. Auto-Assignment ```bash # Automatically assign cards to agents npx ruv-swarm github board-auto-assign \ --strategy "load-balanced" \ --consider "expertise,workload,availability" \ --update-cards ``` ### 2. Progress Tracking ```bash # Track and visualize progress npx ruv-swarm github board-progress \ --show "burndown,velocity,cycle-time" \ --time-period "sprint" \ --export-metrics ``` ### 3. Smart Card Movement ```bash # Intelligent card state transitions npx ruv-swarm github board-smart-move \ --rules '{ "auto-progress": "when:all-subtasks-done", "auto-review": "when:tests-pass", "auto-done": "when:pr-merged" }' ``` ## Board Commands ### Create Cards from Issues ```bash # Convert issues to project cards using gh CLI # List issues with label ISSUES=$(gh issue list --label "enhancement" --json number,title,body) # Add issues to project echo "$ISSUES" | jq -r '.[].number' | while read -r issue; do gh project item-add $PROJECT_ID --owner @me --url "https://github.com/$GITHUB_REPOSITORY/issues/$issue" done # Process with swarm npx ruv-swarm github board-import-issues \ --issues "$ISSUES" \ --add-to-column "Backlog" \ --parse-checklist \ --assign-agents ``` ### Bulk Operations ```bash # Bulk card operations npx ruv-swarm github board-bulk \ --filter "status:blocked" \ --action "add-label:needs-attention" \ --notify-assignees ``` ### Card Templates ```bash # Create cards from templates npx ruv-swarm github board-template \ --template "feature-development" \ --variables '{ "feature": "User Authentication", "priority": "high", "agents": ["architect", "coder", "tester"] }' \ --create-subtasks ``` ## Advanced Synchronization ### 1. Multi-Board Sync ```bash # Sync across multiple boards npx ruv-swarm github multi-board-sync \ --boards "Development,QA,Release" \ --sync-rules '{ "Development->QA": "when:ready-for-test", "QA->Release": "when:tests-pass" }' ``` ### 2. Cross-Organization Sync ```bash # Sync boards across organizations npx ruv-swarm github cross-org-sync \ --source "org1/Project-A" \ --target "org2/Project-B" \ --field-mapping "custom" \ --conflict-resolution "source-wins" ``` ### 3. External Tool Integration ```bash # Sync with external tools npx ruv-swarm github board-integrate \ --tool "jira" \ --mapping "bidirectional" \ --sync-frequency "5m" \ --transform-rules "custom" ``` ## Visualization & Reporting ### Board Analytics ```bash # Generate board analytics using gh CLI data # Fetch project data PROJECT_DATA=$(gh project item-list $PROJECT_ID --owner @me --format json) # Get issue metrics ISSUE_METRICS=$(echo "$PROJECT_DATA" | jq -r '.items[] | select(.content.type == "Issue")' | \ while read -r item; do ISSUE_NUM=$(echo "$item" | jq -r '.content.number') gh issue view $ISSUE_NUM --json createdAt,closedAt,labels,assignees done) # Generate analytics with swarm npx ruv-swarm github board-analytics \ --project-data "$PROJECT_DATA" \ --issue-metrics "$ISSUE_METRICS" \ --metrics "throughput,cycle-time,wip" \ --group-by "agent,priority,type" \ --time-range "30d" \ --export "dashboard" ``` ### Custom Dashboards ```javascript // Dashboard configuration { "dashboard": { "widgets": [ { "type": "chart", "title": "Task Completion Rate", "data": "completed-per-day", "visualization": "line" }, { "type": "gauge", "title": "Sprint Progress", "data": "sprint-completion", "target": 100 }, { "type": "heatmap", "title": "Agent Activity", "data": "agent-tasks-per-day" } ] } } ``` ### Reports ```bash # Generate reports npx ruv-swarm github board-report \ --type "sprint-summary" \ --format "markdown" \ --include "velocity,burndown,blockers" \ --distribute "slack,email" ``` ## Workflow Integration ### Sprint Management ```bash # Manage sprints with swarms npx ruv-swarm github sprint-manage \ --sprint "Sprint 23" \ --auto-populate \ --capacity-planning \ --track-velocity ``` ### Milestone Tracking ```bash # Track milestone progress npx ruv-swarm github milestone-track \ --milestone "v2.0 Release" \ --update-board \ --show-dependencies \ --predict-completion ``` ### Release Planning ```bash # Plan releases using board data npx ruv-swarm github release-plan-board \ --analyze-velocity \ --estimate-completion \ --identify-risks \ --optimize-scope ``` ## Team Collaboration ### Work Distribution ```bash # Distribute work among team npx ruv-swarm github board-distribute \ --strategy "skills-based" \ --balance-workload \ --respect-preferences \ --notify-assignments ``` ### Standup Automation ```bash # Generate standup reports npx ruv-swarm github standup-report \ --team "frontend" \ --include "yesterday,today,blockers" \ --format "slack" \ --schedule "daily-9am" ``` ### Review Coordination ```bash # Coordinate reviews via board npx ruv-swarm github review-coordinate \ --board "Code Review" \ --assign-reviewers \ --track-feedback \ --ensure-coverage ``` ## Best Practices ### 1. Board Organization - Clear column definitions - Consistent labeling system - Regular board grooming - Automation rules ### 2. Data Integrity - Bidirectional sync validation - Conflict resolution strategies - Audit trails - Regular backups ### 3. Team Adoption - Training materials - Clear workflows - Regular reviews - Feedback loops ## Troubleshooting ### Sync Issues ```bash # Diagnose sync problems npx ruv-swarm github board-diagnose \ --check "permissions,webhooks,rate-limits" \ --test-sync \ --show-conflicts ``` ### Performance ```bash # Optimize board performance npx ruv-swarm github board-optimize \ --analyze-size \ --archive-completed \ --index-fields \ --cache-views ``` ### Data Recovery ```bash # Recover board data npx ruv-swarm github board-recover \ --backup-id "2024-01-15" \ --restore-cards \ --preserve-current \ --merge-conflicts ``` ## Examples ### Agile Development Board ```bash # Setup agile board npx ruv-swarm github agile-board \ --methodology "scrum" \ --sprint-length "2w" \ --ceremonies "planning,review,retro" \ --metrics "velocity,burndown" ``` ### Kanban Flow Board ```bash # Setup kanban board npx ruv-swarm github kanban-board \ --wip-limits '{ "In Progress": 5, "Review": 3 }' \ --cycle-time-tracking \ --continuous-flow ``` ### Research Project Board ```bash # Setup research board npx ruv-swarm github research-board \ --phases "ideation,research,experiment,analysis,publish" \ --track-citations \ --collaborate-external ``` ## Metrics & KPIs ### Performance Metrics ```bash # Track board performance npx ruv-swarm github board-kpis \ --metrics '[ "average-cycle-time", "throughput-per-sprint", "blocked-time-percentage", "first-time-pass-rate" ]' \ --dashboard-url ``` ### Team Metrics ```bash # Track team performance npx ruv-swarm github team-metrics \ --board "Development" \ --per-member \ --include "velocity,quality,collaboration" \ --anonymous-option ``` See also: [swarm-issue.md](./swarm-issue.md), [multi-repo-swarm.md](./multi-repo-swarm.md)