role

type Action struct {
	// ID is a unique identifier for this action.
	ID string `json:"id"`

	// Type categorizes the action (e.g., "task", "decision", "question").
	Type string `json:"type"`

	// Description is the action text.
	Description string `json:"description"`

	// Assignee is the person responsible (optional).
	Assignee string `json:"assignee,omitempty"`

	// DueDate is when the action should be completed (optional).
	DueDate string `json:"due_date,omitempty"`

	// Priority indicates urgency (e.g., "high", "medium", "low").
	Priority string `json:"priority,omitempty"`

	// Source indicates where this action was captured.
	Source string `json:"source,omitempty"`

	// Links are references to external systems.
	Links []ActionLink `json:"links,omitempty"`

	// Metadata contains additional action properties.
	Metadata map[string]any `json:"metadata,omitempty"`
}

type ActionLink struct {
	// System is the external platform (e.g., "jira", "aha", "github").
	System string `json:"system"`

	// Type is the link kind (e.g., "issue", "feature", "pr").
	Type string `json:"type"`

	// ID is the external identifier.
	ID string `json:"id"`

	// URL is the direct link.
	URL string `json:"url"`
}

type Artifact struct {
	// Name is the artifact identifier.
	Name string `json:"name"`

	// Type indicates the artifact kind (e.g., "document", "notes", "summary").
	Type string `json:"type"`

	// Format is the content format (e.g., "markdown", "html", "pdf").
	Format string `json:"format"`

	// Content is the artifact data (for inline content).
	Content string `json:"content,omitempty"`

	// URL is a link to the artifact (for external content).
	URL string `json:"url,omitempty"`

	// Metadata contains additional artifact properties.
	Metadata map[string]any `json:"metadata,omitempty"`
}

type ArtifactSpec struct {
	// ID is a unique identifier for this artifact type.
	ID string `json:"id"`

	// Name is a human-readable name (e.g., "Meeting Notes").
	Name string `json:"name"`

	// Description explains what this artifact contains.
	Description string `json:"description,omitempty"`

	// Type categorizes the artifact (e.g., "document", "report", "summary").
	Type string `json:"type"`

	// Format is the content format (e.g., "markdown", "html", "pdf").
	Format string `json:"format,omitempty"`

	// Required indicates if this artifact must be produced.
	Required bool `json:"required,omitempty"`

	// Trigger describes when this artifact is created.
	Trigger string `json:"trigger,omitempty"`
}

type BaseRole struct {
	RoleName           string
	RoleDescription    string
	RolePrompt         string
	RoleSkills         []string
	RoleOptionalSkills []string
	RoleWorkflows      []Workflow

	// Skills holds the initialized skills after Init is called.
	Skills map[string]skill.Skill
}

type BaseWorkflow struct {
	WorkflowName        string
	WorkflowDescription string
	WorkflowTrigger     string
	WorkflowInputSchema map[string]any
	ExecuteFunc         func(ctx context.Context, input map[string]any) (WorkflowResult, error)
}

type Behavior struct {
	// ID is a unique identifier for this behavior.
	ID string `json:"id"`

	// Name is a human-readable name (e.g., "Pre-meeting Preparation").
	Name string `json:"name"`

	// Description explains what this behavior does.
	Description string `json:"description,omitempty"`

	// Context specifies when this behavior applies.
	Context BehaviorContext `json:"context"`

	// Trigger defines what activates this behavior.
	Trigger BehaviorTrigger `json:"trigger"`

	// Actions define what the behavior does when activated.
	Actions []BehaviorAction `json:"actions"`

	// Enabled indicates if this behavior is active.
	Enabled bool `json:"enabled"`

	// Priority determines order when multiple behaviors match.
	Priority int `json:"priority,omitempty"`
}

type BehaviorAction struct {
	// ID is a unique identifier for this action.
	ID string `json:"id"`

	// Type categorizes the action (e.g., "tool_call", "message", "workflow").
	Type string `json:"type"`

	// Name describes the action (e.g., "Send meeting reminder").
	Name string `json:"name,omitempty"`

	// Tool is the tool to invoke (for tool_call type).
	Tool string `json:"tool,omitempty"`

	// Workflow is the workflow to run (for workflow type).
	Workflow string `json:"workflow,omitempty"`

	// Message is the message to send (for message type).
	Message string `json:"message,omitempty"`

	// Parameters contains action-specific configuration.
	Parameters map[string]any `json:"parameters,omitempty"`
}

type BehaviorContext string

type BehaviorProvider interface {
	// Behaviors returns the behaviors defined for this role.
	Behaviors() []Behavior
}

type BehaviorTrigger struct {
	// Type is the trigger category (e.g., "event", "schedule", "condition").
	Type string `json:"type"`

	// Event is the specific event name (for event triggers).
	Event string `json:"event,omitempty"`

	// Schedule is a cron expression (for schedule triggers).
	Schedule string `json:"schedule,omitempty"`

	// Condition is a CEL expression (for condition triggers).
	Condition string `json:"condition,omitempty"`

	// Parameters contains trigger-specific configuration.
	Parameters map[string]any `json:"parameters,omitempty"`
}

type DelegationBudget struct {
	// MaxConcurrent is the maximum simultaneous delegated tasks.
	MaxConcurrent int `json:"max_concurrent,omitempty"`

	// MaxDaily is the maximum delegations per day.
	MaxDaily int `json:"max_daily,omitempty"`

	// MaxTokens is the maximum tokens consumed by delegated tasks.
	MaxTokens int64 `json:"max_tokens,omitempty"`

	// MaxCost is the maximum cost for delegated tasks.
	MaxCost float64 `json:"max_cost,omitempty"`

	// Currency for cost limits (e.g., "USD").
	Currency string `json:"currency,omitempty"`
}

type DelegationConfig struct {
	// Enabled indicates if delegation is allowed for this role.
	Enabled bool `json:"enabled"`

	// Rules define when and how to delegate.
	Rules []DelegationRule `json:"rules"`

	// Budget limits delegation resources.
	Budget *DelegationBudget `json:"budget,omitempty"`

	// DefaultTimeout is the default timeout for delegated tasks.
	DefaultTimeout string `json:"default_timeout,omitempty"`

	// RetryPolicy defines how to handle failed delegations.
	RetryPolicy *DelegationRetryPolicy `json:"retry_policy,omitempty"`
}

type DelegationProvider interface {
	// DelegationRules returns the delegation rules for this role.
	DelegationRules() []DelegationRule
}

type DelegationResult struct {
	// RuleID is the rule that triggered this delegation.
	RuleID string `json:"rule_id"`

	// TargetRole is the role that received the task.
	TargetRole string `json:"target_role"`

	// TaskID is a unique identifier for the delegated task.
	TaskID string `json:"task_id"`

	// Status is the delegation outcome (e.g., "completed", "failed", "timeout").
	Status DelegationStatus `json:"status"`

	// Output contains the result data from the delegated task.
	Output map[string]any `json:"output,omitempty"`

	// Error contains error details if the delegation failed.
	Error string `json:"error,omitempty"`

	// Duration is how long the delegation took.
	Duration string `json:"duration,omitempty"`

	// TokensUsed is the number of tokens consumed.
	TokensUsed int64 `json:"tokens_used,omitempty"`
}

type DelegationRetryPolicy struct {
	// MaxRetries is the maximum number of retry attempts.
	MaxRetries int `json:"max_retries,omitempty"`

	// InitialDelay is the delay before the first retry.
	InitialDelay string `json:"initial_delay,omitempty"`

	// MaxDelay is the maximum delay between retries.
	MaxDelay string `json:"max_delay,omitempty"`

	// Multiplier increases delay between retries.
	Multiplier float64 `json:"multiplier,omitempty"`
}

type DelegationRule struct {
	// ID is a unique identifier for this rule.
	ID string `json:"id"`

	// Name is a human-readable name (e.g., "Security Review Delegation").
	Name string `json:"name"`

	// Description explains when this rule applies.
	Description string `json:"description,omitempty"`

	// TaskPatterns are glob patterns matching task types to delegate.
	TaskPatterns []string `json:"task_patterns"`

	// TargetRoles are roles that can receive delegated work.
	TargetRoles []string `json:"target_roles"`

	// Autonomous indicates if delegation can happen without user approval.
	Autonomous bool `json:"autonomous"`

	// Priority determines rule precedence when multiple rules match.
	Priority int `json:"priority,omitempty"`

	// Condition is an optional CEL expression for conditional delegation.
	Condition string `json:"condition,omitempty"`

	// Timeout overrides the default timeout for this rule.
	Timeout string `json:"timeout,omitempty"`
}

type DelegationStatus string

type EnforcementMode string

type MemoryPolicy struct {
	// Enabled indicates if memory is enabled for this role.
	Enabled bool `json:"enabled"`

	// Scope defines memory visibility (e.g., "session", "user", "global").
	Scope string `json:"scope,omitempty"`

	// RetentionDays is how long memories are kept (0 = forever).
	RetentionDays int `json:"retention_days,omitempty"`

	// Categories lists types of information to remember.
	Categories []string `json:"categories,omitempty"`
}

type MetricDefinition struct {
	// ID is a unique identifier for this metric.
	ID string `json:"id"`

	// Name is a human-readable name (e.g., "Action Capture Rate").
	Name string `json:"name"`

	// Description explains what this metric measures.
	Description string `json:"description,omitempty"`

	// Type specifies how this metric is measured.
	Type MetricType `json:"type"`

	// Unit is the measurement unit (e.g., "percent", "seconds", "count").
	Unit string `json:"unit,omitempty"`

	// Target defines success thresholds.
	Target *MetricTarget `json:"target,omitempty"`

	// Labels are additional dimensions for this metric.
	Labels []string `json:"labels,omitempty"`

	// Buckets are histogram bucket boundaries (for histogram type).
	Buckets []float64 `json:"buckets,omitempty"`
}

type MetricTarget struct {
	// Value is the target value to achieve.
	Value float64 `json:"value"`

	// Operator specifies how to compare (e.g., ">=", "<=", "==").
	Operator string `json:"operator,omitempty"`

	// WarningThreshold triggers a warning when crossed.
	WarningThreshold float64 `json:"warning_threshold,omitempty"`

	// CriticalThreshold triggers an alert when crossed.
	CriticalThreshold float64 `json:"critical_threshold,omitempty"`

	// Period is the time window for evaluation (e.g., "1h", "24h", "7d").
	Period string `json:"period,omitempty"`
}

type MetricType string

type MetricsProvider interface {
	// Metrics returns the metric definitions for this role.
	Metrics() []MetricDefinition
}

type PersonaSpec struct {
	// Tone describes the communication style (e.g., "professional", "friendly").
	Tone string `json:"tone,omitempty"`

	// Language is the preferred language code (e.g., "en", "es").
	Language string `json:"language,omitempty"`

	// Formality indicates the level of formality (e.g., "formal", "casual").
	Formality string `json:"formality,omitempty"`

	// Voice describes first/third person usage (e.g., "first", "third").
	Voice string `json:"voice,omitempty"`

	// Traits lists personality characteristics.
	Traits []string `json:"traits,omitempty"`
}

type Policy struct {
	// ID is a unique identifier for this policy.
	ID string `json:"id"`

	// Name is a human-readable name (e.g., "No external API calls").
	Name string `json:"name"`

	// Description explains the policy's purpose.
	Description string `json:"description,omitempty"`

	// Type categorizes what this policy controls.
	Type PolicyType `json:"type"`

	// Rules define the specific restrictions or allowances.
	Rules []PolicyRule `json:"rules"`

	// Enforcement specifies how violations are handled.
	Enforcement PolicyEnforcement `json:"enforcement"`

	// Enabled indicates if this policy is active.
	Enabled bool `json:"enabled"`

	// Priority determines order when multiple policies apply.
	Priority int `json:"priority,omitempty"`
}

type PolicyAction string

type PolicyEnforcement struct {
	// Mode is how to handle violations (e.g., "block", "warn", "audit").
	Mode EnforcementMode `json:"mode"`

	// Message is shown when the policy is triggered.
	Message string `json:"message,omitempty"`

	// Escalation specifies who to notify on violations.
	Escalation string `json:"escalation,omitempty"`
}

type PolicyProvider interface {
	// Policies returns the policies defined for this role.
	Policies() []Policy
}

type PolicyRule struct {
	// ID is a unique identifier for this rule.
	ID string `json:"id"`

	// Action specifies allow or deny.
	Action PolicyAction `json:"action"`

	// Target specifies what this rule applies to.
	Target PolicyTarget `json:"target"`

	// Condition is an optional CEL expression for conditional rules.
	Condition string `json:"condition,omitempty"`

	// Reason explains why this rule exists.
	Reason string `json:"reason,omitempty"`
}

type PolicyTarget struct {
	// Type specifies the target category (e.g., "tool", "data", "operation").
	Type string `json:"type"`

	// Pattern is a glob pattern matching target names.
	Pattern string `json:"pattern"`

	// Attributes contains additional matching criteria.
	Attributes map[string]any `json:"attributes,omitempty"`
}

type PolicyType string

type Responsibility struct {
	// ID is a unique identifier for this responsibility.
	ID string `json:"id"`

	// Name is a short description (e.g., "Prepare meeting agenda").
	Name string `json:"name"`

	// Description provides details about what this responsibility entails.
	Description string `json:"description,omitempty"`

	// Phase indicates when this responsibility applies (e.g., "pre-meeting").
	Phase string `json:"phase,omitempty"`

	// Priority indicates relative importance (e.g., "high", "medium", "low").
	Priority string `json:"priority,omitempty"`
}

type Role interface {
	// Name returns the role identifier (e.g., "meeting-pm", "code-reviewer").
	// Names should be lowercase with hyphens.
	Name() string

	// Description returns a human-readable description of the role.
	Description() string

	// Spec returns the complete role specification.
	// This includes all metadata, behaviors, policies, and metrics.
	Spec() *RoleSpec

	// SystemPrompt returns the system prompt that defines the role's persona.
	// The context can be used to incorporate dynamic information.
	SystemPrompt(ctx context.Context) (string, error)

	// RequiredSkills returns the names of skills this role needs.
	// These are validated and provided during Init.
	RequiredSkills() []string

	// Init initializes the role with its required skills.
	// Skills are provided as a map keyed by skill name.
	Init(ctx context.Context, skills map[string]skill.Skill) error

	// Close releases any resources held by the role.
	Close() error

	// Workflows returns the structured workflows this role supports.
	// Workflows are optional; roles can function with just the system prompt.
	Workflows() []Workflow
}

type RoleSpec struct {
	// ID is the unique identifier for this role (e.g., "meeting-pm").
	ID string `json:"id"`

	// Name is the human-readable name (e.g., "Meeting Program Manager").
	Name string `json:"name"`

	// Description provides a detailed explanation of the role.
	Description string `json:"description"`

	// Version is the semantic version of this role spec (e.g., "1.0.0").
	Version string `json:"version,omitempty"`

	// Purpose explains why this role exists.
	Purpose string `json:"purpose,omitempty"`

	// Goals define what success looks like for this role.
	Goals []string `json:"goals,omitempty"`

	// Responsibilities define what this role is accountable for.
	Responsibilities []Responsibility `json:"responsibilities,omitempty"`

	// Skills defines required and optional skill dependencies.
	Skills SkillRequirements `json:"skills"`

	// Policies define governance rules for the role.
	Policies []Policy `json:"policies,omitempty"`

	// Memory defines memory retention policies.
	Memory *MemoryPolicy `json:"memory,omitempty"`

	// Behaviors define context-specific actions.
	Behaviors []Behavior `json:"behaviors,omitempty"`

	// Artifacts define documents and outputs the role produces.
	Artifacts []ArtifactSpec `json:"artifacts,omitempty"`

	// Metrics define success measurements and KPIs.
	Metrics []MetricDefinition `json:"metrics,omitempty"`

	// Delegation configures sub-agent orchestration.
	Delegation *DelegationConfig `json:"delegation,omitempty"`

	// Persona defines communication style and tone.
	Persona *PersonaSpec `json:"persona,omitempty"`

	// Metadata contains arbitrary extension data.
	Metadata map[string]any `json:"metadata,omitempty"`
}

type SkillRef struct {
	// Name is the skill identifier (e.g., "meeting", "google").
	Name string `json:"name"`

	// MinVersion is the minimum required version (optional).
	MinVersion string `json:"min_version,omitempty"`

	// Purpose explains why this skill is needed.
	Purpose string `json:"purpose,omitempty"`
}

type SkillRequirements struct {
	// Required lists skills that must be provided.
	Required []SkillRef `json:"required,omitempty"`

	// Optional lists skills that enhance the role but aren't mandatory.
	Optional []SkillRef `json:"optional,omitempty"`
}

type SkillRequirer interface {
	// OptionalSkills returns skill names that enhance the role but aren't mandatory.
	OptionalSkills() []string
}

type SubRole interface {
	Role

	// Parent returns the name of the parent role.
	Parent() string

	// Overrides returns prompt overrides or extensions for this subrole.
	Overrides() SubRoleOverrides
}

type SubRoleOverrides struct {
	// SystemPromptSuffix is appended to the parent's system prompt.
	SystemPromptSuffix string

	// AdditionalSkills are skills needed beyond the parent's requirements.
	AdditionalSkills []string

	// WorkflowOverrides maps workflow names to replacement workflows.
	WorkflowOverrides map[string]Workflow
}

type Workflow interface {
	// Name returns the workflow identifier (e.g., "prepare-meeting").
	Name() string

	// Description returns a human-readable description.
	Description() string

	// Trigger describes when this workflow should be invoked.
	// Can be "manual", "on_meeting_start", "on_meeting_end", etc.
	Trigger() string

	// InputSchema returns JSON Schema for the workflow's input parameters.
	// Returns nil if no input is required.
	InputSchema() map[string]any

	// Execute runs the workflow with the given input.
	// Returns the workflow result or an error.
	Execute(ctx context.Context, input map[string]any) (WorkflowResult, error)
}

type WorkflowResult struct {
	// Success indicates whether the workflow completed successfully.
	Success bool `json:"success"`

	// Output contains workflow-specific result data.
	Output map[string]any `json:"output,omitempty"`

	// Artifacts are files or documents produced by the workflow.
	Artifacts []Artifact `json:"artifacts,omitempty"`

	// Actions are follow-up items identified by the workflow.
	Actions []Action `json:"actions,omitempty"`

	// Message is a human-readable summary of the result.
	Message string `json:"message,omitempty"`

	// Error contains error details if Success is false.
	Error string `json:"error,omitempty"`
}