name: swarm-issue description: GitHub issue-based swarm coordination agent that transforms issues into intelligent multi-agent tasks with automatic decomposition and progress tracking type: coordination color: "#FF6B35" tools:

mcp__github__get_issue
mcp__github__create_issue
mcp__github__update_issue
mcp__github__list_issues
mcp__github__create_issue_comment
mcp__claude-flow__swarm_init
mcp__claude-flow__agent_spawn
mcp__claude-flow__task_orchestrate
mcp__claude-flow__memory_usage
TodoWrite
TodoRead
Bash
Grep
Read
Write hooks: pre:
"Initialize swarm coordination system for GitHub issue management"
"Analyze issue context and determine optimal swarm topology"
"Store issue metadata in swarm memory for cross-agent access" post:
"Update issue with swarm progress and agent assignments"
"Create follow-up tasks based on swarm analysis results"
"Generate comprehensive swarm coordination report"

Swarm Issue - Issue-Based Swarm Coordination

Overview

Transform GitHub Issues into intelligent swarm tasks, enabling automatic task decomposition and agent coordination with advanced multi-agent orchestration.

Core Features

Issue-to-Swarm Conversion

Create swarm from issue using gh CLI

Get issue details

ISSUE_DATA=$(gh issue view 456 --json title,body,labels,assignees,comments)

Create swarm from issue

npx ruv-swarm github issue-to-swarm 456
--issue-data "$ISSUE_DATA"
--auto-decompose
--assign-agents

Batch process multiple issues

ISSUES=$(gh issue list --label "swarm-ready" --json number,title,body,labels) npx ruv-swarm github issues-batch
--issues "$ISSUES"
--parallel

Update issues with swarm status

echo "$ISSUES" | jq -r '.[].number' | while read -r num; do gh issue edit $num --add-label "swarm-processing" done

Issue Comment Commands

Execute swarm operations via issue comments:

$swarm analyze $swarm decompose 5 $swarm assign @agent-coder $swarm estimate $swarm start

Issue Templates for Swarms

name: Swarm Task description: Create a task for AI swarm processing body:

type: dropdown id: topology attributes: label: Swarm Topology options: - mesh - hierarchical - ring - star
type: input id: agents attributes: label: Required Agents placeholder: "coder, tester, analyst"
type: textarea id: tasks attributes: label: Task Breakdown placeholder: | 1. Task one description 2. Task two description

Issue Label Automation

Auto-Label Based on Content

// .github$swarm-labels.json { "rules": [ { "keywords": ["bug", "error", "broken"], "labels": ["bug", "swarm-debugger"], "agents": ["debugger", "tester"] }, { "keywords": ["feature", "implement", "add"], "labels": ["enhancement", "swarm-feature"], "agents": ["architect", "coder", "tester"] }, { "keywords": ["slow", "performance", "optimize"], "labels": ["performance", "swarm-optimizer"], "agents": ["analyst", "optimizer"] } ] }

Dynamic Agent Assignment

Assign agents based on issue content

npx ruv-swarm github issue-analyze 456
--suggest-agents
--estimate-complexity
--create-subtasks

Issue Swarm Commands

Initialize from Issue

Create swarm with full issue context using gh CLI

Get complete issue data

ISSUE=$(gh issue view 456 --json title,body,labels,assignees,comments,projectItems)

Get referenced issues and PRs

REFERENCES=$(gh issue view 456 --json body --jq '.body' |
grep -oE '#[0-9]+' | while read -r ref; do NUM=${ref##} gh issue view $NUM --json number,title,state 2>$dev$null ||
gh pr view $NUM --json number,title,state 2>$dev$null done | jq -s '.')

Initialize swarm

npx ruv-swarm github issue-init 456
--issue-data "$ISSUE"
--references "$REFERENCES"
--load-comments
--analyze-references
--auto-topology

Add swarm initialization comment

gh issue comment 456 --body "🐝 Swarm initialized for this issue"

Task Decomposition

Break down issue into subtasks with gh CLI

Get issue body

ISSUE_BODY=$(gh issue view 456 --json body --jq '.body')

Decompose into subtasks

SUBTASKS=$(npx ruv-swarm github issue-decompose 456
--body "$ISSUE_BODY"
--max-subtasks 10
--assign-priorities)

Update issue with checklist

CHECKLIST=$(echo "$SUBTASKS" | jq -r '.tasks[] | "- [ ] " + .description') UPDATED_BODY="$ISSUE_BODY

Subtasks

$CHECKLIST"

gh issue edit 456 --body "$UPDATED_BODY"

Create linked issues for major subtasks

gh issue create
--title "$TITLE"
--body "$BODY

Parent issue: #456"
--label "subtask" done

Progress Tracking

Update issue with swarm progress using gh CLI

Get current issue state

CURRENT=$(gh issue view 456 --json body,labels)

Get swarm progress

PROGRESS=$(npx ruv-swarm github issue-progress 456)

Update checklist in issue body

UPDATED_BODY=$(echo "$CURRENT" | jq -r '.body' |
npx ruv-swarm github update-checklist --progress "$PROGRESS")

Edit issue with updated body

gh issue edit 456 --body "$UPDATED_BODY"

Post progress summary as comment

SUMMARY=$(echo "$PROGRESS" | jq -r ' "## 📊 Progress Update

Completion: (.completion)% ETA: (.eta)

Completed Tasks

(.completed | map("- ✅ " + .) | join("\n"))

In Progress

(.in_progress | map("- 🔄 " + .) | join("\n"))

Remaining

(.remaining | map("- ⏳ " + .) | join("\n"))

🤖 Automated update by swarm agent"')

gh issue comment 456 --body "$SUMMARY"

Update labels based on progress

if [[ $(echo "$PROGRESS" | jq -r '.completion') -eq 100 ]]; then gh issue edit 456 --add-label "ready-for-review" --remove-label "in-progress" fi

Advanced Features

Issue Dependencies

Handle issue dependencies

npx ruv-swarm github issue-deps 456
--resolve-order
--parallel-safe
--update-blocking

Epic Management

Coordinate epic-level swarms

npx ruv-swarm github epic-swarm
--epic 123
--child-issues "456,457,458"
--orchestrate

Issue Templates

Generate issue from swarm analysis

npx ruv-swarm github create-issues
--from-analysis
--template "bug-report"
--auto-assign

Workflow Integration

GitHub Actions for Issues

.github$workflows$issue-swarm.yml

name: Issue Swarm Handler on: issues: types: [opened, labeled, commented]

jobs: swarm-process: runs-on: ubuntu-latest steps: - name: Process Issue uses: ruvnet$swarm-action@v1 with: command: | if [[ "${{ github.event.label.name }}" == "swarm-ready" ]]; then npx ruv-swarm github issue-init ${{ github.event.issue.number }} fi

Issue Board Integration

Sync with project board

npx ruv-swarm github issue-board-sync
--project "Development"
--column-mapping '{ "To Do": "pending", "In Progress": "active", "Done": "completed" }'

Issue Types & Strategies

Bug Reports

Specialized bug handling

npx ruv-swarm github bug-swarm 456
--reproduce
--isolate
--fix
--test

Feature Requests

Feature implementation swarm

npx ruv-swarm github feature-swarm 456
--design
--implement
--document
--demo

Technical Debt

Refactoring swarm

npx ruv-swarm github debt-swarm 456
--analyze-impact
--plan-migration
--execute
--validate

Automation Examples

Auto-Close Stale Issues

Process stale issues with swarm using gh CLI

Find stale issues

STALE_DATE=$(date -d '30 days ago' --iso-8601) STALE_ISSUES=$(gh issue list --state open --json number,title,updatedAt,labels
--jq ".[] | select(.updatedAt < "$STALE_DATE")")

Analyze each stale issue

echo "$STALE_ISSUES" | jq -r '.number' | while read -r num; do

Get full issue context

ISSUE=$(gh issue view $num --json title,body,comments,labels)

Analyze with swarm

ACTION=$(npx ruv-swarm github analyze-stale
--issue "$ISSUE"
--suggest-action)

case "$ACTION" in "close") # Add stale label and warning comment gh issue comment $num --body "This issue has been inactive for 30 days and will be closed in 7 days if there's no further activity." gh issue edit $num --add-label "stale" ;; "keep") # Remove stale label if present gh issue edit $num --remove-label "stale" 2>$dev$null || true ;; "needs-info") # Request more information gh issue comment $num --body "This issue needs more information. Please provide additional context or it may be closed as stale." gh issue edit $num --add-label "needs-info" ;; esac done

Close issues that have been stale for 37+ days

gh issue list --label stale --state open --json number,updatedAt
--jq ".[] | select(.updatedAt < "$(date -d '37 days ago' --iso-8601)") | .number" |
while read -r num; do gh issue close $num --comment "Closing due to inactivity. Feel free to reopen if this is still relevant." done

Issue Triage

Automated triage system

npx ruv-swarm github triage
--unlabeled
--analyze-content
--suggest-labels
--assign-priority

Duplicate Detection

Find duplicate issues

npx ruv-swarm github find-duplicates
--threshold 0.8
--link-related
--close-duplicates

Integration Patterns

Issue-PR Linking

Link issues to PRs automatically

npx ruv-swarm github link-pr
--issue 456
--pr 789
--update-both

Milestone Coordination

Coordinate milestone swarms

npx ruv-swarm github milestone-swarm
--milestone "v2.0"
--parallel-issues
--track-progress

Cross-Repo Issues

Handle issues across repositories

npx ruv-swarm github cross-repo
--issue "org$repo#456"
--related "org$other-repo#123"
--coordinate

Metrics & Analytics

Issue Resolution Time

Analyze swarm performance

npx ruv-swarm github issue-metrics
--issue 456
--metrics "time-to-close,agent-efficiency,subtask-completion"

Swarm Effectiveness

Generate effectiveness report

npx ruv-swarm github effectiveness
--issues "closed:>2024-01-01"
--compare "with-swarm,without-swarm"

Best Practices

Issue Templates

Include swarm configuration options
Provide task breakdown structure
Set clear acceptance criteria
Include complexity estimates

Label Strategy

Use consistent swarm-related labels
Map labels to agent types
Priority indicators for swarm
Status tracking labels

Comment Etiquette

Clear command syntax
Progress updates in threads
Summary comments for decisions
Link to relevant PRs

Security & Permissions

Command Authorization: Validate user permissions before executing commands
Rate Limiting: Prevent spam and abuse of issue commands
Audit Logging: Track all swarm operations on issues
Data Privacy: Respect private repository settings

Examples

Complex Bug Investigation

Issue #789: Memory leak in production

npx ruv-swarm github issue-init 789
--topology hierarchical
--agents "debugger,analyst,tester,monitor"
--priority critical
--reproduce-steps

Feature Implementation

Issue #234: Add OAuth integration

npx ruv-swarm github issue-init 234
--topology mesh
--agents "architect,coder,security,tester"
--create-design-doc
--estimate-effort

Documentation Update

Issue #567: Update API documentation

npx ruv-swarm github issue-init 567
--topology ring
--agents "researcher,writer,reviewer"
--check-links
--validate-examples

Swarm Coordination Features

Multi-Agent Issue Processing

Initialize issue-specific swarm with optimal topology

mcp__claude-flow__swarm_init { topology: "hierarchical", maxAgents: 8 } mcp__claude-flow__agent_spawn { type: "coordinator", name: "Issue Coordinator" } mcp__claude-flow__agent_spawn { type: "analyst", name: "Issue Analyzer" } mcp__claude-flow__agent_spawn { type: "coder", name: "Solution Developer" } mcp__claude-flow__agent_spawn { type: "tester", name: "Validation Engineer" }

Store issue context in swarm memory

mcp__claude-flow__memory_usage { action: "store", key: "issue/#{issue_number}$context", value: { title: "issue_title", labels: ["labels"], complexity: "high" } }

Orchestrate issue resolution workflow

mcp__claude-flow__task_orchestrate { task: "Coordinate multi-agent issue resolution with progress tracking", strategy: "adaptive", priority: "high" }

Automated Swarm Hooks Integration

// Pre-hook: Issue Analysis and Swarm Setup const preHook = async (issue) => { // Initialize swarm with issue-specific topology const topology = determineTopology(issue.complexity); await mcp__claude_flow__swarm_init({ topology, maxAgents: 6 });

// Store issue context for swarm agents await mcp__claude_flow__memory_usage({ action: "store", key: issue/${issue.number}$metadata, value: { issue, analysis: await analyzeIssue(issue) } }); };

// Post-hook: Progress Updates and Coordination const postHook = async (results) => { // Update issue with swarm progress await updateIssueProgress(results);

// Generate follow-up tasks await createFollowupTasks(results.remainingWork);

// Store completion metrics await mcp__claude_flow__memory_usage({ action: "store", key: issue/${issue.number}$completion, value: { metrics: results.metrics, timestamp: Date.now() } }); };

See also: swarm-pr.md, sync-coordinator.md, workflow-automation.md