swarm-board

Interact with the swarm task board. Use when you need to query existing tasks, check backlog status, create new tasks, or understand the current project state.

⭐5stars🔀1forks📁View on GitHub🕐Updated Jan 11, 2026

When & Why to Use This Skill

The swarm-board skill provides a robust interface for interacting with task management systems, enabling AI agents and users to query, create, and track work items in real-time. By facilitating deep visibility into project states, backlogs, and task lifecycles, it ensures streamlined coordination and prevents redundant efforts in complex workflows.

Use Cases

  • Project State Awareness: Query the current backlog and work-in-progress to understand project status before initiating new actions.
  • Structured Task Creation: Generate new tasks using Gherkin format to provide clear, actionable requirements and acceptance criteria for team members or agents.
  • Deduplication and Efficiency: Search existing tasks and completed work to prevent the creation of duplicate items and optimize resource allocation.
  • Performance Monitoring: Access real-time statistics on task distribution (Backlog, InProgress, Done) to identify bottlenecks and manage agent workloads effectively.
nameswarm-board
descriptionInteract with the swarm task board. Use when you need to query existing tasks, check backlog status, create new tasks, or understand the current project state.

Swarm Task Board

This skill enables you to interact with the swarm task management system to query tasks, understand project state, and create new work items.

Quick Reference

Action Command
List all tasks curl $MANAGER_URL/api/v1/tasks
List by status curl "$MANAGER_URL/api/v1/tasks?status=Backlog"
Get task details curl $MANAGER_URL/api/v1/tasks/{id}
Create task curl -X POST $MANAGER_URL/api/v1/tasks -d '{...}'
Get stats curl $MANAGER_URL/api/v1/stats

Note: MANAGER_URL is typically http://manager:8080 inside containers.

Querying Tasks

List All Tasks

curl -s "$MANAGER_URL/api/v1/tasks" | jq

Response:

[
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "title": "Add user authentication",
    "description": "Feature: User Authentication\n  As a user...",
    "status": "Backlog",
    "priority": "High",
    "source": "user",
    "created_at": "2024-01-15T10:30:00Z"
  }
]

Filter by Status

Valid statuses: Backlog, InProgress, Review, Done, NeedsWork

# Get backlog items
curl -s "$MANAGER_URL/api/v1/tasks?status=Backlog" | jq

# Get completed tasks
curl -s "$MANAGER_URL/api/v1/tasks?status=Done" | jq

# Get tasks in review
curl -s "$MANAGER_URL/api/v1/tasks?status=Review" | jq

Get Single Task

Supports full UUID or partial ID prefix:

curl -s "$MANAGER_URL/api/v1/tasks/550e8400" | jq

Get Statistics

curl -s "$MANAGER_URL/api/v1/stats" | jq

Response:

{
  "total_tasks": 15,
  "backlog": 5,
  "in_progress": 2,
  "review": 1,
  "done": 7,
  "needs_work": 0,
  "active_agents": 3
}

Creating Tasks

Create a New Task

curl -X POST "$MANAGER_URL/api/v1/tasks" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Add password reset functionality",
    "description": "Feature: Password Reset\n  As a user\n  I want to reset my password\n  So that I can regain access to my account\n\n  Scenario: Request password reset\n    Given I am on the login page\n    When I click \"Forgot Password\"\n    And I enter my email address\n    Then I should receive a reset email\n\nTechnical Notes:\n- Use existing email service\n- Token expires in 1 hour\n\nAcceptance Criteria:\n- [ ] Reset email sent within 30 seconds\n- [ ] Token is single-use\n- [ ] Old password invalidated after reset",
    "priority": "Medium"
  }'

Task Fields

Field Required Values
title Yes Short descriptive title
description Yes Gherkin format preferred
priority No High, Medium (default), Low

Gherkin Format

Tasks should use Gherkin format for clarity:

Feature: [Feature name]
  As a [user role]
  I want [goal]
  So that [benefit]

  Scenario: [Primary scenario]
    Given [precondition]
    When [action]
    Then [expected outcome]

Technical Notes:
- [Implementation detail 1]
- [Implementation detail 2]

Acceptance Criteria:
- [ ] [Criterion 1]
- [ ] [Criterion 2]

Building Context

Before creating new tasks, gather context:

1. Check Current Backlog

# See what's already planned
curl -s "$MANAGER_URL/api/v1/tasks?status=Backlog" | jq '.[].title'

2. Review Completed Work

# See what's been done recently
curl -s "$MANAGER_URL/api/v1/tasks?status=Done" | jq '.[-5:] | .[].title'

3. Check Work In Progress

# See what workers are doing
curl -s "$MANAGER_URL/api/v1/tasks?status=InProgress" | jq '.[].title'

4. Get Overall Stats

curl -s "$MANAGER_URL/api/v1/stats" | jq

Avoiding Duplicates

Before creating a task, check if similar work exists:

  1. Check backlog for similar titles
  2. Check completed tasks - don't recreate finished work
  3. Check in-progress tasks - don't duplicate active work

Example deduplication check:

# Search for tasks mentioning "authentication"
curl -s "$MANAGER_URL/api/v1/tasks" | jq '[.[] | select(.title | ascii_downcase | contains("auth"))]'

Task Lifecycle

Backlog → InProgress (claimed by worker)
InProgress → Review (PR created)
Review → Done (approved & merged)
Review → NeedsWork (changes requested)
NeedsWork → InProgress (worker addresses feedback)

Priority Guidelines

Priority Use When
High Core functionality gaps, security issues, blocking bugs
Medium Feature enhancements, performance improvements
Low Technical debt, documentation, nice-to-have features

Best Practices

  1. Keep tasks focused - 1-4 hours of work each
  2. Use Gherkin format - Clear acceptance criteria
  3. Check for duplicates - Query backlog before creating
  4. Set appropriate priority - Don't make everything High
  5. Include technical notes - Help workers understand context