roles

Documentation

Overview

Package roles provides role prompt loading and stage-based role selection helpers.

Package roles provides role prompt loading and stage-based role selection helpers.

Index

• func BuildRoleAssignmentPrompt(promptTemplate string, request RoleAssignmentRequest) (string, error)
• func EncodeRoleAssignmentRequest(request RoleAssignmentRequest) ([]byte, error)
• func LoadRoleAssignmentPrompt(root string) (string, error)
• type AuditLogger
• type LLMInvoker
• type Registry
  • func LoadRegistry(root string, warn func(string)) (Registry, error)
  • func (registry Registry) CustomGlobalPromptPath() (string, bool)
  • func (registry Registry) CustomRolePromptPath(role index.Role) (string, bool)
  • func (registry Registry) PromptFiles(role index.Role) []string
  • func (registry Registry) RolePromptPath(role index.Role) (string, bool)
  • func (registry Registry) Roles() []index.Role
• type RoleAssignmentCaps
• type RoleAssignmentRequest
  • func (request RoleAssignmentRequest) Validate() error
• type RoleAssignmentResult
  • func SelectRole(ctx context.Context, invoker LLMInvoker, promptTemplate string, ...) (RoleAssignmentResult, error)
• type RoleAssignmentTask
• type RoleDefinition
• type Stage
  • func (stage Stage) Valid() bool
• type StageRoleSelector
  • func (selector StageRoleSelector) RoleForStage(stage Stage) (index.Role, error)

Functions

func BuildRoleAssignmentPrompt

func BuildRoleAssignmentPrompt(promptTemplate string, request RoleAssignmentRequest) (string, error)

BuildRoleAssignmentPrompt combines the prompt template with the request JSON.

func EncodeRoleAssignmentRequest

func EncodeRoleAssignmentRequest(request RoleAssignmentRequest) ([]byte, error)

EncodeRoleAssignmentRequest serializes the role assignment request as JSON.

func LoadRoleAssignmentPrompt

func LoadRoleAssignmentPrompt(root string) (string, error)

LoadRoleAssignmentPrompt reads the role assignment prompt from the repo root.

Types

type AuditLogger

type AuditLogger interface {
	LogAgentOutcome(taskID string, role string, agent string, status string, exitCode int) error
}

AuditLogger records audit events for role assignment.

type LLMInvoker

type LLMInvoker interface {
	Invoke(ctx context.Context, prompt string) (string, error)
}

LLMInvoker executes a prompt and returns the raw model response.

type Registry

type Registry struct {
	// contains filtered or unexported fields
}

Registry captures available roles and prompt paths loaded from disk.

func LoadRegistry

func LoadRegistry(root string, warn func(string)) (Registry, error)

LoadRegistry loads role prompts from the repository root.

func (Registry) CustomGlobalPromptPath

func (registry Registry) CustomGlobalPromptPath() (string, bool)

CustomGlobalPromptPath returns the global prompt path when configured.

func (Registry) CustomRolePromptPath

func (registry Registry) CustomRolePromptPath(role index.Role) (string, bool)

CustomRolePromptPath returns the custom prompt path for a role when available.

func (Registry) PromptFiles

func (registry Registry) PromptFiles(role index.Role) []string

PromptFiles returns the ordered prompt files for the supplied role.

Prompt order:

1. .governator/roles/<role>.md
2. .governator/custom-prompts/_global.md
3. .governator/custom-prompts/<role>.md

func (Registry) RolePromptPath

func (registry Registry) RolePromptPath(role index.Role) (string, bool)

RolePromptPath returns the repo-relative prompt path for a role, if present.

func (Registry) Roles

func (registry Registry) Roles() []index.Role

Roles returns the available role names in stable order.

type RoleAssignmentCaps

type RoleAssignmentCaps struct {
	Global      int        `json:"global"`
	DefaultRole int        `json:"default_role"`
	Roles       roleIntMap `json:"roles"`
	InFlight    roleIntMap `json:"in_flight"`
}

RoleAssignmentCaps captures concurrency caps and in-flight counts for role selection.

type RoleAssignmentRequest

type RoleAssignmentRequest struct {
	Task           RoleAssignmentTask `json:"task"`
	Stage          Stage              `json:"stage"`
	AvailableRoles []index.Role       `json:"available_roles"`
	Caps           RoleAssignmentCaps `json:"caps"`
}

RoleAssignmentRequest represents the JSON input sent to the role assignment LLM.

func (RoleAssignmentRequest) Validate

func (request RoleAssignmentRequest) Validate() error

Validate ensures the role assignment request meets the contract requirements.

type RoleAssignmentResult

type RoleAssignmentResult struct {
	Role        index.Role
	Rationale   string
	RawResponse string
	Fallback    bool
}

RoleAssignmentResult captures the selected role and LLM rationale.

func SelectRole

func SelectRole(
	ctx context.Context,
	invoker LLMInvoker,
	promptTemplate string,
	request RoleAssignmentRequest,
	warn func(string),
	auditor AuditLogger,
) (RoleAssignmentResult, error)

SelectRole invokes the role assignment LLM to choose a role at dispatch time.

type RoleAssignmentTask

type RoleAssignmentTask struct {
	ID      string `json:"id"`
	Title   string `json:"title,omitempty"`
	Path    string `json:"path"`
	Content string `json:"content"`
}

RoleAssignmentTask captures the task metadata needed for role selection.

type RoleDefinition

type RoleDefinition struct {
	Name       index.Role
	PromptPath string
}

RoleDefinition describes a role and its primary prompt path.

type Stage

type Stage string

Stage labels the worker lifecycle stage used for runtime role selection.

const (
	// StageWork selects the role for implementation work.
	StageWork Stage = "work"
	// StageTest selects the role for test execution.
	StageTest Stage = "test"
	// StageReview selects the role for review execution.
	StageReview Stage = "review"
	// StageResolve selects the role for conflict resolution.
	StageResolve Stage = "resolve"
)

func (Stage) Valid

func (stage Stage) Valid() bool

Valid reports whether the stage is a supported role assignment stage.

type StageRoleSelector

type StageRoleSelector struct {
	Default   index.Role
	Overrides map[Stage]index.Role
}

StageRoleSelector maps lifecycle stages to roles, falling back to a default role.

func (StageRoleSelector) RoleForStage

func (selector StageRoleSelector) RoleForStage(stage Stage) (index.Role, error)

RoleForStage selects the role to use for the supplied stage.