speculator-orchestration

wbeard's avatarfrom wbeard

Multi-agent task orchestration using the spec CLI. Guides agents on claiming tasks, parallel execution, blocking, and coordination. Use when working with multiple agents, claiming tasks, or managing parallel work.

⭐2stars🔀0forks📁View on GitHub🕐Updated Dec 25, 2025⬇️1downloads

When & Why to Use This Skill

The Speculator Orchestration skill provides a robust framework for multi-agent task management using the spec CLI. It streamlines collaborative AI workflows by enforcing an 'atomic claim' principle, enabling parallel execution while preventing duplicate efforts and merge conflicts through structured task tracking, dependency management, and real-time status updates.

Use Cases

  • Collaborative Coding: Coordinating multiple AI agents to work on different modules of a single codebase simultaneously without creating merge conflicts.
  • Complex Project Decomposition: Breaking down large-scale engineering features into smaller, manageable subtasks that can be distributed across a fleet of specialized agents.
  • Workflow Dependency Management: Automatically managing task sequences where certain agent actions are blocked until prerequisite tasks are marked as complete.
  • Resource Optimization: Using the 'spec tasks ready' command to ensure agents are always working on the highest priority, unblocked tasks to maximize throughput.
namespeculator-orchestration
descriptionMulti-agent task orchestration using the spec CLI. Guides agents on claiming tasks, parallel execution, blocking, and coordination. Use when working with multiple agents, claiming tasks, or managing parallel work.

Speculator Orchestration

Core Principle

Claim before you code.

Never start work on a task without atomically claiming it first. This prevents duplicate effort and merge conflicts in multi-agent scenarios.

Quick Reference

Command Purpose
spec tasks ready Find tasks available for work (todo, unblocked, dependencies complete)
spec task claim <id> Atomically claim a task (marks as in_progress)
spec task complete <id> Mark a task as done
spec task block <id> --reason <reason> Record a blocker with reason
spec task unblock <id> Remove a block
spec task release <id> Return a claimed task to todo
spec task add --feature <id> --title <title> Create a new task or subtask
spec task depend <id> --on <other-id> Add a dependency between tasks

Workflows

Patterns

Examples

The Orchestration Loop

1. spec tasks ready → find available work
2. Evaluate conflicts → check for file overlap with other in-progress tasks
3. spec task claim <id> → atomically claim
4. Implement → do the work
5. spec task complete <id> | spec task block <id> --reason <reason> → finish or record blocker
6. Repeat

Important Notes

  • Always check spec tasks ready before starting work
  • If claim fails, another agent got it first - move on
  • Block tasks with clear, actionable reasons
  • Release tasks if you can't complete them
  • Create subtasks for large pieces of work