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:
Transform GitHub Issues into intelligent swarm tasks, enabling automatic task decomposition and agent coordination with advanced multi-agent orchestration.
# 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
Execute swarm operations via issue comments:
<!-- In issue comment -->
$swarm analyze
$swarm decompose 5
$swarm assign @agent-coder
$swarm estimate
$swarm start
<!-- .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
// .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"]
}
]
}
# Assign agents based on issue content
npx ruv-swarm github issue-analyze 456 \
--suggest-agents \
--estimate-complexity \
--create-subtasks
# 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"
# 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
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
# 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
# Handle issue dependencies
npx ruv-swarm github issue-deps 456 \
--resolve-order \
--parallel-safe \
--update-blocking
# Coordinate epic-level swarms
npx ruv-swarm github epic-swarm \
--epic 123 \
--child-issues "456,457,458" \
--orchestrate
# Generate issue from swarm analysis
npx ruv-swarm github create-issues \
--from-analysis \
--template "bug-report" \
--auto-assign
# .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
# Sync with project board
npx ruv-swarm github issue-board-sync \
--project "Development" \
--column-mapping '{
"To Do": "pending",
"In Progress": "active",
"Done": "completed"
}'
# Specialized bug handling
npx ruv-swarm github bug-swarm 456 \
--reproduce \
--isolate \
--fix \
--test
# Feature implementation swarm
npx ruv-swarm github feature-swarm 456 \
--design \
--implement \
--document \
--demo
# Refactoring swarm
npx ruv-swarm github debt-swarm 456 \
--analyze-impact \
--plan-migration \
--execute \
--validate
# 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
# Automated triage system
npx ruv-swarm github triage \
--unlabeled \
--analyze-content \
--suggest-labels \
--assign-priority
# Find duplicate issues
npx ruv-swarm github find-duplicates \
--threshold 0.8 \
--link-related \
--close-duplicates
# Link issues to PRs automatically
npx ruv-swarm github link-pr \
--issue 456 \
--pr 789 \
--update-both
# Coordinate milestone swarms
npx ruv-swarm github milestone-swarm \
--milestone "v2.0" \
--parallel-issues \
--track-progress
# Handle issues across repositories
npx ruv-swarm github cross-repo \
--issue "org$repo#456" \
--related "org$other-repo#123" \
--coordinate
# Analyze swarm performance
npx ruv-swarm github issue-metrics \
--issue 456 \
--metrics "time-to-close,agent-efficiency,subtask-completion"
# Generate effectiveness report
npx ruv-swarm github effectiveness \
--issues "closed:>2024-01-01" \
--compare "with-swarm,without-swarm"
# Issue #789: Memory leak in production
npx ruv-swarm github issue-init 789 \
--topology hierarchical \
--agents "debugger,analyst,tester,monitor" \
--priority critical \
--reproduce-steps
# Issue #234: Add OAuth integration
npx ruv-swarm github issue-init 234 \
--topology mesh \
--agents "architect,coder,security,tester" \
--create-design-doc \
--estimate-effort
# Issue #567: Update API documentation
npx ruv-swarm github issue-init 567 \
--topology ring \
--agents "researcher,writer,reviewer" \
--check-links \
--validate-examples
# 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"
}
// 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
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Run Codex CLI, Claude Code, OpenCode, or Pi Coding Agent via background process for programmatic control.
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Set up and use 1Password CLI (op). Use when installing the CLI, enabling desktop app integration, signing in (single or multi-account), or reading/injecting/running secrets via op.
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Run Codex CLI, Claude Code, OpenCode, or Pi Coding Agent via background process for programmatic control.
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Set up and use 1Password CLI (op). Use when installing the CLI, enabling desktop app integration, signing in (single or multi-account), or reading/injecting/running secrets via op.