Roles
Role templates — schema, guardrails, handoffs, and examples.
Role Templates
Role templates define system instructions, guardrails, capabilities, and handoffs as versioned objects (YAML/JSON).
Schema (v1)
export type Tier = 'local' | 'heavy'
export interface RoleCapability { name: string; requires?: { gpu?: boolean; longContext?: boolean; network?: boolean }; tools?: string[] }
export interface RoleGuardrails { outputSchemas?: string[]; safetyNotes?: string[]; budgets?: { maxTokens?: number; maxUsd?: number; maxWallMs?: number } }
export interface EscalationPolicy { triggers: string[]; escalateTo?: { roleKey?: string; tier?: Tier }; maxRetries?: number }
export interface HandoffRule { when: string; toRoleKey: string; contract?: string }
export interface RoleTemplateV1 { kind: 'role/v1'; key: string; version: string; displayName: string; description: string; system: string; defaultTier: Tier; capabilities: RoleCapability[]; guardrails?: RoleGuardrails; escalation?: EscalationPolicy; handoffs?: HandoffRule[]; acl?: { allowTeams?: string[]; denyTeams?: string[] }; providerHints?: { provider?: 'openai' | 'gemini' | 'deepseek'; model?: string } }Example Roles
kind: role/v1
key: pm.growth
version: 1.0.0
displayName: Growth PM
description: Plans growth experiments, defines metrics, writes specs.
system: |
You are a Growth PM. Produce concise specs and metrics.
defaultTier: local
capabilities:
- name: plan experiments
tools: [analytics.query, doc.writer]Role Flow
graph TD
A[pm.growth] --> B[eng.code-review]
A --> C[ops.browser]
C --> D[sec.reviewer]