/v3/@claude-flow/cli/.claude/agents/github/swarm-issue.md

name, description, type, color, tools, hooks

name	description	type	color	tools	hooks
swarm-issue	GitHub issue-based swarm coordination agent that transforms issues into intelligent multi-agent tasks with automatic decomposition and progress tracking	coordination	#FF6B35	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	pre post 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 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

# 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 claude-flow@v3alpha 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 claude-flow@v3alpha 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

2. Issue Comment Commands

Execute swarm operations via issue comments:

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

3. Issue Templates for Swarms

<!-- .github/ISSUE_TEMPLATE/swarm-task.yml -->
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 claude-flow@v3alpha 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 claude-flow@v3alpha 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 claude-flow@v3alpha 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
echo "$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

# 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 claude-flow@v3alpha github issue-progress 456)

# Update checklist in issue body
UPDATED_BODY=$(echo "$CURRENT" | jq -r '.body' | \
  npx claude-flow@v3alpha 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

1. Issue Dependencies

# Handle issue dependencies
npx claude-flow@v3alpha github issue-deps 456 \
  --resolve-order \
  --parallel-safe \
  --update-blocking

2. Epic Management

# Coordinate epic-level swarms
npx claude-flow@v3alpha github epic-swarm \
  --epic 123 \
  --child-issues "456,457,458" \
  --orchestrate

3. Issue Templates

# Generate issue from swarm analysis
npx claude-flow@v3alpha 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 claude-flow@v3alpha github issue-init ${{ github.event.issue.number }}
            fi

Issue Board Integration

# Sync with project board
npx claude-flow@v3alpha 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 claude-flow@v3alpha github bug-swarm 456 \
  --reproduce \
  --isolate \
  --fix \
  --test

Feature Requests

# Feature implementation swarm
npx claude-flow@v3alpha github feature-swarm 456 \
  --design \
  --implement \
  --document \
  --demo

Technical Debt

# Refactoring swarm
npx claude-flow@v3alpha 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 claude-flow@v3alpha 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 claude-flow@v3alpha github triage \
  --unlabeled \
  --analyze-content \
  --suggest-labels \
  --assign-priority

Duplicate Detection

# Find duplicate issues
npx claude-flow@v3alpha github find-duplicates \
  --threshold 0.8 \
  --link-related \
  --close-duplicates

Integration Patterns

1. Issue-PR Linking

# Link issues to PRs automatically
npx claude-flow@v3alpha github link-pr \
  --issue 456 \
  --pr 789 \
  --update-both

2. Milestone Coordination

# Coordinate milestone swarms
npx claude-flow@v3alpha github milestone-swarm \
  --milestone "v2.0" \
  --parallel-issues \
  --track-progress

3. Cross-Repo Issues

# Handle issues across repositories
npx claude-flow@v3alpha github cross-repo \
  --issue "org/repo#456" \
  --related "org/other-repo#123" \
  --coordinate

Metrics & Analytics

Issue Resolution Time

# Analyze swarm performance
npx claude-flow@v3alpha github issue-metrics \
  --issue 456 \
  --metrics "time-to-close,agent-efficiency,subtask-completion"

Swarm Effectiveness

# Generate effectiveness report
npx claude-flow@v3alpha 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

# Issue #789: Memory leak in production
npx claude-flow@v3alpha github issue-init 789 \
  --topology hierarchical \
  --agents "debugger,analyst,tester,monitor" \
  --priority critical \
  --reproduce-steps

Feature Implementation

# Issue #234: Add OAuth integration
npx claude-flow@v3alpha github issue-init 234 \
  --topology mesh \
  --agents "architect,coder,security,tester" \
  --create-design-doc \
  --estimate-effort

Documentation Update

# Issue #567: Update API documentation
npx claude-flow@v3alpha 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