Actor Profiles

The profile_json schema defines an actor's identity, capabilities, and operational boundaries.

Every actor stores its configuration in a profile_json field -- a structured JSON object that contains identity, model routing, permissions, prompt stack, dispatch rules, and more. This profile is the canonical source from which all runtime configuration files are generated.

Profile structure

The profile follows a normalized YAML frontmatter format (ADR-0056) with these top-level sections:

Identity

The identity section defines who the actor is and what it specializes in:

identity:
  display_name: "Security Architect"
  title: "Senior Security Architect"
  slug: "security-architect"
  domains:
    - security
    - infrastructure
    - compliance
  working_style: "methodical"
  communication_tone: "precise"
  output_format: "structured"

Routing

The routing section defines which AI model the actor uses via route aliases -- stable names that resolve to provider/model pairs at export time:

routing:
  route_alias: "premium-security-reasoning"
  override_policy: "project"

Route aliases decouple actor definitions from volatile provider model IDs. Instead of storing anthropic/claude-opus-4-8 directly, actors reference a route alias that is resolved from the Model Route catalog at export time. See Model Routing for details.

Runtime

The runtime section defines the actor's permission profile and operational boundaries:

runtime:
  permission_profile: "builder"
  max_concurrent_tasks: 3
  tool_restrictions:
    - "no_direct_db_access"
  recommended_skills:
    - nexus-init
    - nexus-sec-scan
    - nexus-code-review
  recommended_plugins:
    - nexus-compaction-plus
    - nexus-cost-control

See the Actor System overview for the full permission matrix.

Cost and telemetry

cost:
  cost_class: "premium"
  budget_alert_threshold: 0.8

telemetry:
  collect_token_usage: true
  collect_session_metrics: true

Avatar

Actors have visual identities via DiceBear-generated avatars or custom uploads:

avatar:
  provider: "dicebear"
  style: "bottts-neutral"
  seed: "security-architect"
  background_color: "#1a1a2e"
  custom_url: null

DiceBear avatars are pre-generated from the slug seed, converted to SVG, and cached in S3/Supabase storage. Custom SVG uploads are disabled until sanitization is implemented -- use PNG or WebP for custom avatars.

Prompt stack

The prompt stack defines the layered instruction set that shapes the actor's behavior. It follows a 7-layer hierarchy from global rules down to task-specific context:

prompt_stack:
  - layer: "global_rules"
    source: "platform"
  - layer: "project_rules"
    source: "directives"
  - layer: "actor_identity"
    source: "profile"
  - layer: "actor_methods"
    source: "profile"
  - layer: "tool_policy"
    source: "permission_profile"
  - layer: "output_contract"
    source: "profile"
  - layer: "task_context"
    source: "session"

Layers are assembled at export time and materialized into the generated AGENTS.md and runtime configuration files.

Dispatch configuration

Controls how the actor interacts with the Dispatch system:

dispatch:
  can_create_followup_tickets: true
  escalation_target: "project-lead"
  auto_acknowledge: false
  default_priority: "normal"

Vita

Personalized actors can have a vita_json field -- a backstory that adds depth to the actor's identity. This is optional and primarily used for promoted (personalized) actors:

vita:
  backstory: "15 years of experience in fintech security..."
  specializations:
    - "OWASP Top 10 auditing"
    - "SOC 2 compliance"
  certifications:
    - "CISSP"
    - "AWS Security Specialty"

The vita is included in the actor's prompt stack at the identity layer, providing the agent with contextual background that shapes its responses and decision-making style.