{"_id":"@aigentic/claims","_rev":"2-329ce1513bf14cb6a00d2eba324f3e0f","name":"@aigentic/claims","dist-tags":{"alpha":"3.0.0-alpha.8","latest":"3.0.0-alpha.8"},"versions":{"3.0.0-alpha.8":{"name":"@aigentic/claims","version":"3.0.0-alpha.8","keywords":["claude-flow","claims","issue-tracking","work-coordination","multi-agent","swarm","mcp"],"author":{"name":"Claude Flow Team"},"license":"MIT","_id":"@aigentic/claims@3.0.0-alpha.8","maintainers":[{"name":"aigentic","email":"engineering@aigentic.net"}],"homepage":"https://github.com/ruvnet/claude-flow#readme","bugs":{"url":"https://github.com/ruvnet/claude-flow/issues"},"dist":{"shasum":"4a012085053d2112d967150a8bb3c146a8ef656a","tarball":"https://registry.npmjs.org/@aigentic/claims/-/claims-3.0.0-alpha.8.tgz","fileCount":24,"integrity":"sha512-JYg1kEQiY5frr873PEIcTWL+KRnIgYX1xX5XRtfMGfVrORZy6Pe+X85/ybFk8drvaG2LAaSGkSd3kkJxXPGExA==","signatures":[{"sig":"MEYCIQCZgwHckxTMspDax2E9UokFFZp9m4AvBFK/+80BuQA3YwIhALjzDJBN6hBexkJPMGGxq+fF8XF3RZ+uu7mh0OsshheJ","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":312177},"main":"dist/index.js","type":"module","types":"dist/index.d.ts","engines":{"node":">=18.0.0"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js","require":"./dist/index.js"},"./api":{"types":"./dist/api/index.d.ts","import":"./dist/api/index.js","require":"./dist/api/index.js"},"./api/mcp-tools":{"types":"./dist/api/mcp-tools.d.ts","import":"./dist/api/mcp-tools.js","require":"./dist/api/mcp-tools.js"}},"gitHead":"e2cb6210ce8d478b39cad81872a4aef78a05ceb4","scripts":{"dev":"tsc --watch","lint":"eslint src --ext .ts","test":"vitest run","build":"tsc","clean":"rimraf dist","typecheck":"tsc --noEmit","test:watch":"vitest","test:coverage":"vitest run --coverage"},"_npmUser":{"name":"aigentic","email":"engineering@aigentic.net"},"repository":{"url":"git+https://github.com/ruvnet/claude-flow.git","type":"git","directory":"v3/@claude-flow/claims"},"_npmVersion":"11.12.0","description":"Issue claiming and work coordination module for Claude Flow V3","directories":{},"_nodeVersion":"22.22.1","dependencies":{"@aigentic/zod":"^3.22.4"},"publishConfig":{"tag":"v3alpha","access":"public"},"_hasShrinkwrap":false,"devDependencies":{"@aigentic/node":"^20.10.0","@aigentic/tsup":"^8.0.1","@aigentic/rimraf":"^5.0.5","@aigentic/vitest":"^4.0.16","@aigentic/typescript":"^5.3.0"},"peerDependencies":{"@aigentic/shared":"^3.0.0-alpha.1"},"peerDependenciesMeta":{"@claude-flow/shared":{"optional":true}},"_npmOperationalInternal":{"tmp":"tmp/claims_3.0.0-alpha.8_1779324021987_0.5182593008203289","host":"s3://npm-registry-packages-npm-production"}}},"time":{"created":"2026-05-21T00:40:21.813Z","modified":"2026-09-13T15:30:26.886Z","3.0.0-alpha.8":"2026-05-21T00:40:22.160Z"},"bugs":{"url":"https://github.com/ruvnet/claude-flow/issues"},"author":{"name":"Claude Flow Team"},"license":"MIT","homepage":"https://github.com/ruvnet/claude-flow#readme","keywords":["claude-flow","claims","issue-tracking","work-coordination","multi-agent","swarm","mcp"],"repository":{"url":"git+https://github.com/ruvnet/claude-flow.git","type":"git","directory":"v3/@claude-flow/claims"},"description":"Issue claiming and work coordination module for Claude Flow V3","maintainers":[{"email":"engineering@aigentic.net","name":"aiggy"}],"readme":"# @claude-flow/claims\n\n[![npm version](https://img.shields.io/npm/v/@claude-flow/claims.svg)](https://www.npmjs.com/package/@claude-flow/claims)\n[![npm downloads](https://img.shields.io/npm/dm/@claude-flow/claims.svg)](https://www.npmjs.com/package/@claude-flow/claims)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n\n**Issue claiming and work coordination for human-agent collaboration.**\n\n## What is this?\n\nThis package provides a complete system for coordinating work between humans and AI agents:\n\n- **Issue Claiming** - Claim issues to work on, preventing conflicts\n- **Handoffs** - Transfer work between humans and agents seamlessly\n- **Work Stealing** - Automatically reassign stalled work\n- **Load Balancing** - Distribute work evenly across agents\n\n## Installation\n\n```bash\nnpm install @claude-flow/claims\n```\n\nOr install via Claude Flow CLI:\n\n```bash\nnpx claude-flow plugins install @claude-flow/claims\n```\n\n---\n\n## Quick Start\n\n### Claim an Issue\n\n```typescript\nimport { ClaimsService } from '@claude-flow/claims';\n\nconst claims = new ClaimsService();\n\n// Human claims an issue\nawait claims.claim({\n  issueId: 'ISSUE-123',\n  claimant: 'human:alice',\n  context: 'Working on the authentication fix'\n});\n\n// Agent claims an issue\nawait claims.claim({\n  issueId: 'ISSUE-456',\n  claimant: 'agent:coder-1:coder',\n  context: 'Implementing new feature'\n});\n```\n\n### Release a Claim\n\n```typescript\nawait claims.release({\n  issueId: 'ISSUE-123',\n  claimant: 'human:alice',\n  reason: 'Completed the work'\n});\n```\n\n### Handoff Between Human and Agent\n\n```typescript\n// Human hands off to agent\nawait claims.handoff({\n  issueId: 'ISSUE-123',\n  from: 'human:alice',\n  to: 'agent:coder-1:coder',\n  reason: 'Need AI to continue implementation',\n  progress: 40\n});\n\n// Agent accepts handoff\nawait claims.acceptHandoff({\n  issueId: 'ISSUE-123',\n  claimant: 'agent:coder-1:coder'\n});\n```\n\n### Update Claim Status\n\n```typescript\nawait claims.updateStatus({\n  issueId: 'ISSUE-123',\n  status: 'review-requested',\n  progress: 80,\n  note: 'Ready for code review'\n});\n```\n\n---\n\n## MCP Tools (17 Tools)\n\n### Core Claiming (7 tools)\n\n| Tool | Description |\n|------|-------------|\n| `claims_claim` | Claim an issue for work |\n| `claims_release` | Release a claimed issue |\n| `claims_handoff` | Request handoff to another claimant |\n| `claims_accept-handoff` | Accept a pending handoff |\n| `claims_status` | Update claim status |\n| `claims_list` | List claims by criteria |\n| `claims_board` | Visual board view of all claims |\n\n### Work Stealing (4 tools)\n\n| Tool | Description |\n|------|-------------|\n| `claims_mark-stealable` | Mark issue as available for stealing |\n| `claims_steal` | Steal a stealable issue |\n| `claims_stealable` | List all stealable issues |\n| `claims_contest-steal` | Contest a steal attempt |\n\n### Load Balancing (3 tools)\n\n| Tool | Description |\n|------|-------------|\n| `claims_load` | Get agent load information |\n| `claims_rebalance` | Suggest or apply load rebalancing |\n| `claims_swarm-overview` | Overview of swarm workload |\n\n### Additional (3 tools)\n\n| Tool | Description |\n|------|-------------|\n| `claims_history` | Get claim history for an issue |\n| `claims_metrics` | Get claiming metrics |\n| `claims_config` | Get/set claims configuration |\n\n---\n\n## Claim Statuses\n\n| Status | Description |\n|--------|-------------|\n| `active` | Currently being worked on |\n| `paused` | Temporarily paused |\n| `blocked` | Blocked by external dependency |\n| `review-requested` | Ready for review |\n| `handoff-pending` | Handoff requested, awaiting acceptance |\n| `stealable` | Available for other agents to take |\n| `completed` | Work finished |\n\n---\n\n## Work Stealing\n\nWhen work stalls, issues can be marked as stealable:\n\n```typescript\n// Mark issue as stealable\nawait claims.markStealable({\n  issueId: 'ISSUE-123',\n  reason: 'overloaded',\n  preferredTypes: ['coder', 'reviewer'],\n  context: 'Need someone to continue the implementation'\n});\n\n// Another agent steals the issue\nawait claims.steal({\n  issueId: 'ISSUE-123',\n  stealer: 'agent:coder-2:coder'\n});\n```\n\n### Steal Reasons\n\n- `timeout` - Work has been idle too long\n- `overloaded` - Current owner has too much work\n- `blocked` - Work is blocked and owner can't proceed\n- `voluntary` - Owner voluntarily releasing\n- `rebalancing` - System rebalancing workload\n- `abandoned` - Owner is no longer available\n\n---\n\n## Load Balancing\n\nAutomatically distribute work across agents:\n\n```typescript\n// Get current agent loads\nconst loads = await claims.getAgentLoads();\n\n// Preview rebalancing suggestions\nconst suggestions = await claims.rebalance({ dryRun: true });\n\n// Apply rebalancing\nawait claims.rebalance({\n  dryRun: false,\n  targetUtilization: 0.7\n});\n```\n\n---\n\n## Event Sourcing\n\nAll claim operations are event-sourced (ADR-007):\n\n```typescript\n// Events emitted\n- ClaimCreated\n- ClaimReleased\n- ClaimStatusUpdated\n- HandoffRequested\n- HandoffAccepted\n- HandoffRejected\n- ClaimMarkedStealable\n- ClaimStolen\n- ClaimContested\n```\n\n---\n\n## CLI Commands\n\n```bash\n# Claim an issue\nnpx claude-flow claims claim --issue ISSUE-123 --claimant \"human:alice\"\n\n# Release a claim\nnpx claude-flow claims release --issue ISSUE-123\n\n# View claims board\nnpx claude-flow claims board\n\n# List stealable issues\nnpx claude-flow claims stealable\n\n# Rebalance workload\nnpx claude-flow claims rebalance --dry-run\n```\n\n---\n\n## Configuration\n\n```yaml\n# claude-flow.config.yaml\nclaims:\n  autoExpiration:\n    enabled: true\n    idleTimeout: 3600000  # 1 hour\n    checkInterval: 300000  # 5 minutes\n  workStealing:\n    enabled: true\n    contestWindow: 30000  # 30 seconds\n  loadBalancing:\n    targetUtilization: 0.7\n    maxIssuesPerAgent: 5\n```\n\n---\n\n## License\n\nMIT\n","readmeFilename":"README.md"}