Agent Swarm Issue

by ruvnet6051f6702b61No license74K starsListed Oct 8, 2026Updated Oct 8, 2026Repository updated today

Agent skill for swarm-issue - invoke with $agent-swarm-issue

AI-generated overview

Coordinates multi-agent swarms around GitHub issues, decomposing issues into tasks and tracking progress.

What it does
This skill turns GitHub issues into multi-agent swarm tasks. It describes workflows for analyzing issue content, decomposing issues into subtasks, assigning agents, updating issue checklists and labels, and posting progress comments. It also covers triage, duplicate detection, stale-issue handling, milestone and cross-repo coordination, and swarm metrics reporting.
When to use it
Use it when you want to organize work around GitHub issues with multiple coordinated agents, for example to break a large issue into subtasks, assign specialized agents, or track resolution progress on the issue itself. It also fits triage, duplicate detection, and stale-issue cleanup workflows.
Requirements
Requires GitHub access (gh CLI or GitHub MCP tools) and the ruv-swarm / claude-flow tooling referenced in the commands, including swarm initialization, agent spawning, task orchestration, and memory tools. It ships no scripts; it is instructions only.

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

1. Issue-to-Swarm Conversion

bash
# Create swarm from issue using gh CLI# Get issue detailsISSUE_DATA=$(gh issue view 456 --json title,body,labels,assignees,comments)
# Create swarm from issuenpx ruv-swarm github issue-to-swarm 456 \  --issue-data "$ISSUE_DATA" \  --auto-decompose \  --assign-agents
# Batch process multiple issuesISSUES=$(gh issue list --label "swarm-ready" --json number,title,body,labels)npx ruv-swarm github issues-batch \  --issues "$ISSUES" \  --parallel
# Update issues with swarm statusecho "$ISSUES" | jq -r '.[].number' | while read -r num; do  gh issue edit $num --add-label "swarm-processing"done

2. Issue Comment Commands

Execute swarm operations via issue comments:

markdown
<!-- In issue comment -->$swarm analyze$swarm decompose 5$swarm assign @agent-coder$swarm estimate$swarm start

3. Issue Templates for Swarms

markdown
<!-- .github/ISSUE_TEMPLATE$swarm-task.yml -->name: Swarm Taskdescription: Create a task for AI swarm processingbody:  - 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

javascript
// .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

bash
# Assign agents based on issue contentnpx ruv-swarm github issue-analyze 456 \  --suggest-agents \  --estimate-complexity \  --create-subtasks

Issue Swarm Commands

Initialize from Issue

bash
# Create swarm with full issue context using gh CLI# Get complete issue dataISSUE=$(gh issue view 456 --json title,body,labels,assignees,comments,projectItems)
# Get referenced issues and PRsREFERENCES=$(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 swarmnpx ruv-swarm github issue-init 456 \  --issue-data "$ISSUE" \  --references "$REFERENCES" \  --load-comments \  --analyze-references \  --auto-topology
# Add swarm initialization commentgh issue comment 456 --body "🐝 Swarm initialized for this issue"

Task Decomposition

bash
# Break down issue into subtasks with gh CLI# Get issue bodyISSUE_BODY=$(gh issue view 456 --json body --jq '.body')
# Decompose into subtasksSUBTASKS=$(npx ruv-swarm github issue-decompose 456 \  --body "$ISSUE_BODY" \  --max-subtasks 10 \  --assign-priorities)
# Update issue with checklistCHECKLIST=$(echo "$SUBTASKS" | jq -r '.tasks[] | "- [ ] " + .description')UPDATED_BODY="$ISSUE_BODY
## Subtasks$CHECKLIST"
gh issue edit 456 --body "$UPDATED_BODY"
# Create linked issues for major subtasksecho "$SUBTASKS" | jq -r '.tasks[] | select(.priority == "high")' | while read -r task; do  TITLE=$(echo "$task" | jq -r '.title')  BODY=$(echo "$task" | jq -r '.description')    gh issue create \    --title "$TITLE" \    --body "$BODY
Parent issue: #456" \    --label "subtask"done

Progress Tracking

bash
# Update issue with swarm progress using gh CLI# Get current issue stateCURRENT=$(gh issue view 456 --json body,labels)
# Get swarm progressPROGRESS=$(npx ruv-swarm github issue-progress 456)
# Update checklist in issue bodyUPDATED_BODY=$(echo "$CURRENT" | jq -r '.body' | \  npx ruv-swarm github update-checklist --progress "$PROGRESS")
# Edit issue with updated bodygh issue edit 456 --body "$UPDATED_BODY"
# Post progress summary as commentSUMMARY=$(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 progressif [[ $(echo "$PROGRESS" | jq -r '.completion') -eq 100 ]]; then  gh issue edit 456 --add-label "ready-for-review" --remove-label "in-progress"fi

Advanced Features

1. Issue Dependencies

bash
# Handle issue dependenciesnpx ruv-swarm github issue-deps 456 \  --resolve-order \  --parallel-safe \  --update-blocking

2. Epic Management

bash
# Coordinate epic-level swarmsnpx ruv-swarm github epic-swarm \  --epic 123 \  --child-issues "456,457,458" \  --orchestrate

3. Issue Templates

bash
# Generate issue from swarm analysisnpx ruv-swarm github create-issues \  --from-analysis \  --template "bug-report" \  --auto-assign

Workflow Integration

GitHub Actions for Issues

yaml
# .github$workflows$issue-swarm.ymlname: Issue Swarm Handleron:  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

bash
# Sync with project boardnpx ruv-swarm github issue-board-sync \  --project "Development" \  --column-mapping '{    "To Do": "pending",    "In Progress": "active",    "Done": "completed"  }'

Issue Types & Strategies

Bug Reports

bash
# Specialized bug handlingnpx ruv-swarm github bug-swarm 456 \  --reproduce \  --isolate \  --fix \  --test

Feature Requests

bash
# Feature implementation swarmnpx ruv-swarm github feature-swarm 456 \  --design \  --implement \  --document \  --demo

Technical Debt

bash
# Refactoring swarmnpx ruv-swarm github debt-swarm 456 \  --analyze-impact \  --plan-migration \  --execute \  --validate

Automation Examples

Auto-Close Stale Issues

bash
# Process stale issues with swarm using gh CLI# Find stale issuesSTALE_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 issueecho "$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"      ;;  esacdone
# Close issues that have been stale for 37+ daysgh 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

bash
# Automated triage systemnpx ruv-swarm github triage \  --unlabeled \  --analyze-content \  --suggest-labels \  --assign-priority

Duplicate Detection

bash
# Find duplicate issuesnpx ruv-swarm github find-duplicates \  --threshold 0.8 \  --link-related \  --close-duplicates

Integration Patterns

1. Issue-PR Linking

bash
# Link issues to PRs automaticallynpx ruv-swarm github link-pr \  --issue 456 \  --pr 789 \  --update-both

2. Milestone Coordination

bash
# Coordinate milestone swarmsnpx ruv-swarm github milestone-swarm \  --milestone "v2.0" \  --parallel-issues \  --track-progress

3. Cross-Repo Issues

bash
# Handle issues across repositoriesnpx ruv-swarm github cross-repo \  --issue "org$repo#456" \  --related "org$other-repo#123" \  --coordinate

Metrics & Analytics

Issue Resolution Time

bash
# Analyze swarm performancenpx ruv-swarm github issue-metrics \  --issue 456 \  --metrics "time-to-close,agent-efficiency,subtask-completion"

Swarm Effectiveness

bash
# Generate effectiveness reportnpx ruv-swarm github effectiveness \  --issues "closed:>2024-01-01" \  --compare "with-swarm,without-swarm"

Best Practices

1. Issue Templates

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

2. Label Strategy

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

3. Comment Etiquette

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

Security & Permissions

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

Examples

Complex Bug Investigation

bash
# Issue #789: Memory leak in productionnpx ruv-swarm github issue-init 789 \  --topology hierarchical \  --agents "debugger,analyst,tester,monitor" \  --priority critical \  --reproduce-steps

Feature Implementation

bash
# Issue #234: Add OAuth integrationnpx ruv-swarm github issue-init 234 \  --topology mesh \  --agents "architect,coder,security,tester" \  --create-design-doc \  --estimate-effort

Documentation Update

bash
# Issue #567: Update API documentationnpx ruv-swarm github issue-init 567 \  --topology ring \  --agents "researcher,writer,reviewer" \  --check-links \  --validate-examples

Swarm Coordination Features

Multi-Agent Issue Processing

bash
# Initialize issue-specific swarm with optimal topologymcp__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 memorymcp__claude-flow__memory_usage {  action: "store",  key: "issue/#{issue_number}$context",  value: { title: "issue_title", labels: ["labels"], complexity: "high" }}
# Orchestrate issue resolution workflowmcp__claude-flow__task_orchestrate {  task: "Coordinate multi-agent issue resolution with progress tracking",  strategy: "adaptive",  priority: "high"}

Automated Swarm Hooks Integration

javascript
// Pre-hook: Issue Analysis and Swarm Setupconst 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 Coordinationconst 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 [blocked], sync-coordinator.md [blocked], workflow-automation.md [blocked]

Source and attribution

Source:ruvnet/rufloin.agents/skills/agent-swarm-issueat commit6051f67

License: No license

Content belongs to its original authors. SourceWeft indexes it from a public repository.

Report or request removal