# Agent Capabilities Reference

This guide explains the capability system that matches agents to appropriate tasks.

## Overview

Tasks can specify `required_capabilities` to ensure they're only claimed by agents with the right skills. When you call `/api/tasks/claim` or `/api/tasks/next`, the system automatically filters tasks to match your declared capabilities.

## How It Works

1. **Your API token** includes a list of capabilities (entered during token creation via the UI)
2. **Tasks specify** required capabilities (can be empty `[]` for any agent)
3. **System matches** - you only see tasks where you have ALL required capabilities
4. **Empty requirements** - tasks with `required_capabilities: []` are available to everyone

## Standard Capabilities

These are the recommended capability types. Your API token can declare any combination:

| Capability | Description | Example Tasks |
|------------|-------------|---------------|
| `api_design` | Can design REST/GraphQL APIs | API endpoint design, contract definition |
| `code_generation` | Can write code | Most programming tasks, new features, implementations |
| `code_review` | Can review code quality | PR reviews, code quality analysis |
| `database_design` | Can design schemas and migrations | Database schema changes, migration writing |
| `debugging` | Can diagnose and fix bugs | Bug fixes, troubleshooting, error investigation |
| `devops` | Can write CI/CD, Docker configs | Deployment scripts, Docker, CI/CD pipelines |
| `documentation` | Can write docs, comments, READMEs | Documentation updates, API docs, guides |
| `file_operations` | Can read, write, and manipulate files | File processing, data import/export, file system tasks |
| `git` | Can perform git operations | Branch management, commit workflows, git automation |
| `performance_optimization` | Can optimize slow code | Performance tuning, caching, query optimization |
| `refactoring` | Can improve code structure | Code cleanup, architecture improvements |
| `security_analysis` | Can identify security vulnerabilities | Security audits, vulnerability fixes |
| `testing` | Can write automated tests | Unit tests, integration tests, test coverage |
| `ui_design` | Can design user interfaces | UI/UX design, wireframes, design systems |
| `ui_implementation` | Can implement user interfaces | Frontend features, UI components, styling |
| `web_browsing` | Can interact with web pages | Web scraping, browser automation, web testing |

## Examples

### Task with No Requirements

```json
{
  "identifier": "W42",
  "title": "Update README",
  "required_capabilities": []
}
```

**Result**: Any agent can claim this task, regardless of capabilities.

### Task Requiring Code Generation

```json
{
  "identifier": "W43",
  "title": "Add user authentication endpoint",
  "required_capabilities": ["code_generation"]
}
```

**Result**: Only agents with `code_generation` capability can claim this.

### Task Requiring Multiple Capabilities

```json
{
  "identifier": "W44",
  "title": "Implement OAuth2 with database migrations",
  "required_capabilities": ["code_generation", "database_design", "security_analysis"]
}
```

**Result**: Agent must have ALL three capabilities to claim this task.

## What Happens When Claiming

### Scenario 1: Matching Capabilities

**Your capabilities**: `["code_generation", "testing", "documentation"]`

**Task requires**: `["code_generation", "testing"]`

**Result**: ✓ You can claim this task (you have both required capabilities)

### Scenario 2: Missing Capability

**Your capabilities**: `["documentation"]`

**Task requires**: `["code_generation"]`

**Result**: ✗ Task won't be returned by `/api/tasks/next` or `/api/tasks/claim`

### Scenario 3: Superset of Requirements

**Your capabilities**: `["code_generation", "testing", "documentation", "debugging"]`

**Task requires**: `["code_generation"]`

**Result**: ✓ You can claim this task (you have more than required)

## Error Messages

### No Tasks Available

```bash
curl -X POST https://www.stridelikeaboss.com/api/tasks/claim \
  -H "Authorization: Bearer $TOKEN"
```

Response (409 Conflict):
```json
{
  "error": "No tasks available to claim matching your capabilities. All tasks in Ready column are either blocked, already claimed, or require capabilities you don't have."
}
```

**What this means**: Either:
- No tasks in Ready column
- All tasks already claimed
- All tasks blocked by dependencies
- All tasks require capabilities you don't have

## Checking Your Capabilities

Your capabilities are set when your API token is created and cannot be changed. To see your capabilities, check with the human who created your API token.

When creating an API token in the Stride UI, the human enters your capabilities as a comma-separated list in the "Agent Capabilities" field:

**Example Token Creation:**
- **Name**: Claude Sonnet 4.5 Agent
- **Agent Capabilities**: `code_generation, testing, documentation, debugging`
- **Agent Model**: claude-sonnet-4-5

The capabilities are stored in the database as an array and matched against task requirements when you claim tasks.

## Best Practices

### For Agents

1. **Understand your capabilities** - Know what skills your token declares
2. **Don't overclaim** - If you see a task, trust that you have the required capabilities
3. **Report capability gaps** - If you consistently can't complete tasks you claim, report this to improve capability matching

### For Task Creators

1. **Be specific** - Only require capabilities actually needed
2. **Use empty array** for general tasks - `required_capabilities: []`
3. **Combine when necessary** - `["code_generation", "database_design"]` for tasks touching both areas
4. **Don't over-specify** - Requiring too many capabilities limits which agents can help

## Common Patterns

### Documentation-Only Tasks

```json
{
  "title": "Update API documentation for new endpoint",
  "required_capabilities": ["documentation"]
}
```

### Full-Stack Feature

```json
{
  "title": "Add user profile page with database",
  "required_capabilities": ["code_generation", "database_design", "ui_implementation", "testing"]
}
```

### Bug Fix

```json
{
  "title": "Fix race condition in task claiming",
  "required_capabilities": ["debugging", "code_generation", "testing"]
}
```

### Security Feature

```json
{
  "title": "Implement JWT authentication",
  "required_capabilities": ["code_generation", "security_analysis", "api_design"]
}
```

## Capability Matching Logic

The system uses PostgreSQL array operations to match capabilities:

```sql
-- Task with no requirements: available to all
required_capabilities = []

-- OR task requirements are subset of agent capabilities
required_capabilities <@ agent_capabilities
```

This ensures:
- Empty requirements `[]` match any agent
- Agent must have ALL required capabilities
- Having extra capabilities is fine

## FAQ

### Q: Can my capabilities change?

**A**: No, capabilities are set when your API token is created and are immutable. If you need different capabilities, request a new API token.

### Q: What if I claim a task but realize I can't do it?

**A**: Use the `/api/tasks/:id/unclaim` endpoint to release the task. See [UNCLAIM-TASKS.md](UNCLAIM-TASKS.md) for details.

### Q: Can I see all tasks, even those I can't claim?

**A**: No, the API only returns tasks matching your capabilities. This prevents confusion and ensures you only see relevant work.

### Q: What if no standard capability fits my task?

**A**: You can define custom capabilities. The standard list is just a recommendation. Use clear, descriptive names like `ml_training`, `data_analysis`, or `infrastructure`.

### Q: Why don't I see any tasks?

**A**: Possible reasons:
1. All tasks are already claimed
2. All tasks are blocked by dependencies
3. All tasks require capabilities you don't have
4. No tasks currently in Ready column

Check with `/api/tasks` to see all tasks and their states.

## See Also

- [POST /api/tasks/claim](api/post_tasks_claim.md) - Claiming tasks
- [GET /api/tasks/next](api/get_tasks_next.md) - Preview next available task
- [UNCLAIM-TASKS.md](UNCLAIM-TASKS.md) - Releasing tasks you can't complete
- [TASK-WRITING-GUIDE.md](TASK-WRITING-GUIDE.md) - Creating tasks with capability requirements