Manage GitHub projects with AI swarm coordination: intelligent issue management, automated
project-board synchronization, and sprint planning. This file holds the core workflow; the
exhaustive command catalog and issue templates live in references/ and load only when needed.
When to use
Triaging or organizing issues, wiring a project board to a swarm, decomposing an issue into subtasks, planning or tracking a sprint, or coordinating a release/roadmap on GitHub.
Prerequisites
gh(GitHub CLI) installed and authenticated.ruv-swarmorclaude-flowavailable (npx ruv-swarm ...).- Permission to edit issues and projects in the target repo/org.
Quick start
# Create a swarm-ready issue
gh issue create \
--title "Feature: Advanced Authentication" \
--body "Implement OAuth2 with social login..." \
--label "enhancement,swarm-ready"
# Initialize a swarm for it
npx claude-flow@alpha hooks pre-task --description "Feature implementation"
# Wire a project board to the swarm (bidirectional)
PROJECT_ID=$(gh project list --owner @me --format json | jq -r '.projects[0].id')
npx ruv-swarm github board-init --project-id "$PROJECT_ID" --sync-mode "bidirectional"
Core workflow
1. Issue management & triage
Spin up a small coordination swarm, create a well-structured issue, then orchestrate tracking:
mcp__claude-flow__swarm_init { topology: "star", maxAgents: 3 }
mcp__claude-flow__agent_spawn { type: "coordinator", name: "Issue Coordinator" }
mcp__github__create_issue {
owner: "org", repo: "repository",
title: "Integration Review: Complete system integration",
body: "## Objectives\n- [ ] Verify dependencies\n- [ ] Ensure API integration\n- [ ] Validate data systems",
labels: ["integration", "review", "enhancement"]
}
mcp__claude-flow__task_orchestrate { task: "Monitor and coordinate issue progress", strategy: "adaptive", priority: "medium" }
Auto-triage unlabeled issues and decompose large ones into subtask checklists — see
references/command-reference.md for triage rules,
issue→swarm conversion, decomposition, automated progress comments, and stale-issue handling.
2. Project board automation
Connect a swarm to a GitHub Project and let it move cards as work progresses:
npx ruv-swarm github board-sync --auto-move-cards --update-metadata
npx ruv-swarm github board-auto-assign --strategy "load-balanced" --update-cards
Status mapping, custom fields, smart card transitions, bulk operations, and the
.github/board-sync.yml config are in references/command-reference.md.
3. Sprint planning & analytics
npx ruv-swarm github sprint-manage --sprint "Sprint 23" --auto-populate --track-velocity
npx ruv-swarm github milestone-track --milestone "v2.0 Release" --predict-completion
Agile/kanban board setup, board analytics, KPI tracking, and reporting commands are in the command reference.
4. Advanced coordination
Multi-board and cross-org sync, issue dependencies, epic orchestration, cross-repo coordination,
and team-collaboration automation (work distribution, standups, review coordination) are all
catalogued in references/command-reference.md.
Issue templates
Ready-to-use templates for integration tasks, bug reports, feature requests, and swarm tasks:
references/issue-templates.md.
Best practices
- Swarm coordination: initialize a swarm for complex issues; assign specialized agents by issue type; post regular automated progress updates.
- Board organization: consistent column/label naming across repos; regular grooming; well-defined automation rules.
- Data integrity: validate bidirectional sync; define conflict-resolution strategy; keep audit trails and backups of project data.
- Labeling: consistent, priority-based labeling; map agent types to labels; integrate milestones for coordination.
Security & permissions
Validate user permissions before executing issue commands; rate-limit to prevent abuse; log all swarm operations; respect private-repo settings; secure webhook endpoints for real-time updates.
Integrates with
github-release-management— coordinate release issues and milestones.github-multi-repo— multi-repository issue coordination.