🎫 Claims & Work Coordination

The Claims system manages who is working on what — whether human or agent. It prevents conflicts, enables handoffs, and balances work across your team.

Why Use Claims?

Problem	Solution
Two agents working on the same file	Claims prevent duplicate work
Agent stuck on a task	Mark as stealable, another agent takes over
Need to hand off work	Structured handoff with context
Unbalanced workload	Automatic rebalancing across agents

How Claims Work

┌─────────────────────────────────────────────────────────────────────┐
│                        CLAIMS LIFECYCLE                             │
├─────────────────────────────────────────────────────────────────────┤
│                                                                     │
│  ┌─────────┐    ┌──────────┐    ┌──────────┐    ┌─────────────┐   │
│  │ UNCLAIMED│───▶│ CLAIMED  │───▶│ STEALABLE│───▶│ HANDED OFF  │   │
│  │         │    │          │    │          │    │             │   │
│  │ Open for│    │ Agent or │    │ Stuck or │    │ New owner   │   │
│  │ claiming│    │ human    │    │ abandoned│    │ continues   │   │
│  └─────────┘    └──────────┘    └──────────┘    └─────────────┘   │
│       │              │                │               │            │
│       └──────────────┴────────────────┴───────────────┘            │
│                           COMPLETED                                 │
└─────────────────────────────────────────────────────────────────────┘

Claims Commands

Command	What It Does	Example
issues list	See all issues and their status	npx ruflo@latest issues list
issues claim	Claim an issue for yourself/agent	npx ruflo@latest issues claim #123 --as coder-1
issues release	Release your claim	npx ruflo@latest issues release #123
issues handoff	Hand off to another worker	npx ruflo@latest issues handoff #123 --to reviewer
issues status	Update progress on claimed work	npx ruflo@latest issues status #123 --progress 75
issues stealable	List abandoned/stuck issues	npx ruflo@latest issues stealable
issues steal	Take over stealable issue	npx ruflo@latest issues steal #123
issues load	View agent workloads	npx ruflo@latest issues load
issues rebalance	Redistribute work evenly	npx ruflo@latest issues rebalance --dry-run
issues board	Visual board view	npx ruflo@latest issues board

Visual Board View

bash
npx ruflo@latest issues board

┌──────────────────────────────────────────────────────────────────────┐
│                        CLAIMS BOARD                                  │
├───────────────┬───────────────┬───────────────┬─────────────────────┤
│   UNCLAIMED   │    ACTIVE     │   STEALABLE   │     COMPLETED       │
├───────────────┼───────────────┼───────────────┼─────────────────────┤
│ #127 Add auth │ #123 Fix bug  │ #120 Refactor │ #119 Update docs    │
│ #128 Tests    │   (coder-1)   │   (stale 2h)  │ #118 Security fix   │
│               │ #124 API work │               │ #117 Performance    │
│               │   (reviewer)  │               │                     │
└───────────────┴───────────────┴───────────────┴─────────────────────┘

Handoff Workflow

When you need to pass work to someone else:

bash
# 1. Request handoff with context
npx ruflo@latest issues handoff #123 \
  --to security-architect \
  --reason "Needs security review" \
  --progress 80

# 2. Target accepts handoff
npx ruflo@latest issues accept #123 --as security-architect

# 3. Work continues with full context

Load Balancing

bash
# View current load
npx ruflo@latest issues load

# Output:
# Agent          | Claims | Load  | Status
# ---------------+--------+-------+--------
# coder-1        | 3      | 85%   | 🔴 Overloaded
# coder-2        | 1      | 25%   | 🟢 Available
# reviewer       | 2      | 50%   | 🟡 Normal
# security-arch  | 0      | 0%    | 🟢 Available

# Auto-rebalance
npx ruflo@latest issues rebalance

MCP Tools

Tool	Description
claims_claim	Claim an issue
claims_release	Release a claim
claims_handoff	Request handoff
claims_accept-handoff	Accept handoff
claims_status	Update status
claims_list	List claims
claims_stealable	List stealable
claims_steal	Steal issue
claims_load	Get load info
claims_board	Visual board
claims_rebalance	Rebalance work