Vapora/docs/features/capability-packages.md

# Pre-built Capability Packages

The `vapora-capabilities` crate provides a registry of pre-configured agent capabilities. Each capability is a self-contained bundle that defines everything an agent needs to operate: its system prompt, model preferences, task types, MCP tool bindings, scheduling priority, and inference temperature.

## Overview

A capability package encapsulates:

- `system_prompt` — the instruction context injected as `Role::System` into every LLM call
- `preferred_provider` and `preferred_model` — resolved at runtime through `LLMRouter`
- `task_types` — the set of task labels this capability handles (used by the swarm coordinator for assignment)
- `mcp_tools` — tool names exposed to the agent via the MCP gateway
- `priority` — integer weight (0–100) for swarm scheduling decisions
- `temperature` — controls output determinism; lower values for review/analysis, higher for generative tasks

The value proposition is operational simplicity: call `CapabilityRegistry::with_built_ins()`, pass the resulting definitions to `AgentExecutor`, and the agents are ready. No manual system prompt authoring, no per-agent LLM config wiring.

## Built-in Capabilities

| ID | Role | Purpose |
|----|------|---------|
| `code-reviewer` | `code_reviewer` | Security and correctness-focused code review. Uses Claude Opus 4.6 at temperature 0.1. MCP tools: `file_read`, `file_list`, `git_diff`, `code_search` |
| `doc-generator` | `documenter` | Generates technical documentation from source code. Uses Claude Sonnet 4.6 at temperature 0.3. MCP tools: `file_read`, `file_list`, `code_search`, `file_write` |
| `pr-monitor` | `monitor` | PR health monitoring and merge readiness assessment. Uses Claude Sonnet 4.6 at temperature 0.1. MCP tools: `git_diff`, `git_log`, `git_status`, `file_list`, `file_read` |

## Runtime Flow

At agent server startup:

```rust
let registry = CapabilityRegistry::with_built_ins();
```

This populates the registry with all built-in `CapabilityPackage` instances. When an agent is activated:

```rust
let definition: AgentDefinition = registry.activate("code-reviewer")?;
```

`activate()` resolves the capability into an `AgentDefinition` with `system_prompt` fully populated. `AgentExecutor` receives this definition and prepends the prompt as `Role::System` on every invocation before forwarding the request to the LLM:

```rust
let response = router
    .complete_with_budget(role, model, messages_with_system, budget_ctx)
    .await?;
```

`LLMRouter::complete_with_budget()` applies the capability's `preferred_provider`, `preferred_model`, and token budget. If the budget is exhausted, the router falls back through the configured fallback chain transparently.

## TOML Customization

Capabilities can be overridden or extended via a TOML file without modifying built-ins:

```toml
# Override built-in: use Sonnet instead of Opus for code-reviewer
[[override]]
id = "code-reviewer"
preferred_model = "claude-sonnet-4-6"
max_tokens = 16384

# Add a custom capability
[[custom]]
id = "db-optimizer"
display_name = "Database Optimizer"
description = "Analyzes and optimizes SQL queries and schema"
agent_role = "db_optimizer"
task_types = ["db_optimization", "query_review"]
system_prompt = "You are a database performance expert..."
mcp_tools = ["file_read", "code_search"]
preferred_provider = "claude"
preferred_model = "claude-sonnet-4-6"
max_tokens = 4096
temperature = 0.2
priority = 70
parallelizable = true
```

Load and apply with:

```rust
use vapora_capabilities::{CapabilityRegistry, CapabilityLoader};

let registry = CapabilityRegistry::with_built_ins();
CapabilityLoader::load_and_apply("config/capabilities.toml", &registry)?;
```

`load_and_apply` merges `[[override]]` entries into existing built-ins (only specified fields are replaced) and inserts `[[custom]]` entries as new packages. The registry is append-only after construction; overrides operate by replacement of the matching entry.

## Architecture

`vapora-capabilities` sits at the base of the dependency graph to avoid circular imports:

```text
vapora-shared
    └── vapora-capabilities   (depends on vapora-shared for AgentDefinition)
            └── vapora-agents (depends on vapora-capabilities for registry access)
```

`vapora-capabilities` imports only `vapora-shared` types (`AgentDefinition`, `AgentRole`, `LLMProvider`). It has no dependency on `vapora-agents`. This means capability definitions can be constructed, tested, and loaded independently of the agent runtime.

## Environment Variables

These configure the LLM router used by all executors that receive a capability definition:

| Variable | Purpose |
|----------|---------|
| `LLM_ROUTER_CONFIG` | Path to the router configuration TOML file |
| `ANTHROPIC_API_KEY` | API key for Claude models (Opus, Sonnet) |
| `OPENAI_API_KEY` | API key for OpenAI models (GPT-4, etc.) |
| `OLLAMA_URL` | Base URL for a local Ollama instance |
| `OLLAMA_MODEL` | Default model name to use when routing to Ollama |

The router config at `LLM_ROUTER_CONFIG` defines routing rules, fallback chains, and per-role budget limits. Capability packages specify a `preferred_provider` and `preferred_model`, but the router enforces budget constraints and can override the preference if a fallback is triggered.