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:

let registry = CapabilityRegistry::with_built_ins();

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

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:

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:

# 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:

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:

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.