core

package
v0.5.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Jan 18, 2026 License: MIT Imports: 10 Imported by: 0

Documentation

Overview

Package core provides canonical types for multi-agent team orchestration.

Index

Constants

View Source
const DefaultDirMode fs.FileMode = 0700

DefaultDirMode is the default permission for generated directories.

View Source
const DefaultFileMode fs.FileMode = 0600

DefaultFileMode is the default permission for generated files.

Variables

View Source
var DefaultRegistry = NewRegistry()

DefaultRegistry is the global adapter registry.

Functions

func AdapterNames

func AdapterNames() []string

AdapterNames returns adapter names from the default registry.

func Register

func Register(adapter Adapter)

Register adds an adapter to the default registry.

func WriteTeamFile

func WriteTeamFile(team *Team, path string) error

WriteTeamFile writes a Team to a file in YAML format.

func WriteTeamJSON

func WriteTeamJSON(team *Team, path string) error

WriteTeamJSON writes a Team to a file in JSON format.

Types

type Adapter

type Adapter interface {
	// Name returns the adapter identifier (e.g., "agentspec", "crewai").
	Name() string

	// FileExtension returns the file extension for team files.
	FileExtension() string

	// Parse converts tool-specific bytes to canonical Team.
	Parse(data []byte) (*Team, error)

	// Marshal converts canonical Team to tool-specific bytes.
	Marshal(team *Team) ([]byte, error)

	// ReadFile reads from path and returns canonical Team.
	ReadFile(path string) (*Team, error)

	// WriteFile writes canonical Team to path.
	WriteFile(team *Team, path string) error
}

Adapter converts between canonical Team definitions and tool-specific formats.

func GetAdapter

func GetAdapter(name string) (Adapter, bool)

GetAdapter returns an adapter from the default registry.

type AdapterError

type AdapterError struct {
	Name string
}

AdapterError represents an error with an adapter.

func (*AdapterError) Error

func (e *AdapterError) Error() string

type MarshalError

type MarshalError struct {
	Format string
	Err    error
}

MarshalError represents an error during marshaling.

func (*MarshalError) Error

func (e *MarshalError) Error() string

func (*MarshalError) Unwrap

func (e *MarshalError) Unwrap() error

type OrchestrationConfig

type OrchestrationConfig struct {
	// Version is the target release version (e.g., "v1.2.0").
	Version string

	// AgentSpecsPath is the path to agent spec files (e.g., "validation/specs").
	AgentSpecsPath string

	// IncludeTasks limits generation to specific tasks (empty = all tasks).
	IncludeTasks []string
}

OrchestrationConfig holds configuration for generating orchestration instructions.

type ParseError

type ParseError struct {
	Format string
	Path   string
	Err    error
}

ParseError represents an error during parsing.

func (*ParseError) Error

func (e *ParseError) Error() string

func (*ParseError) Unwrap

func (e *ParseError) Unwrap() error

type Process

type Process string

Process defines how tasks are executed within a team.

const (
	// ProcessSequential executes tasks one after another in order.
	ProcessSequential Process = "sequential"

	// ProcessParallel executes independent tasks concurrently.
	ProcessParallel Process = "parallel"

	// ProcessHierarchical uses a manager agent to delegate to specialists.
	ProcessHierarchical Process = "hierarchical"
)

func (Process) IsValid

func (p Process) IsValid() bool

IsValid checks if the process type is valid.

func (Process) String

func (p Process) String() string

String returns the string representation of the process.

type ReadError

type ReadError struct {
	Path string
	Err  error
}

ReadError represents an error during file reading.

func (*ReadError) Error

func (e *ReadError) Error() string

func (*ReadError) Unwrap

func (e *ReadError) Unwrap() error

type Registry

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

Registry manages adapter registration and lookup.

func NewRegistry

func NewRegistry() *Registry

NewRegistry creates a new adapter registry.

func (*Registry) AdapterNames

func (r *Registry) AdapterNames() []string

AdapterNames returns all registered adapter names sorted alphabetically.

func (*Registry) GetAdapter

func (r *Registry) GetAdapter(name string) (Adapter, bool)

GetAdapter returns an adapter by name.

func (*Registry) Register

func (r *Registry) Register(adapter Adapter)

Register adds an adapter to the registry.

type Status

type Status string

Status represents the result of a subtask or task.

const (
	// StatusGo indicates the check passed.
	StatusGo Status = "GO"

	// StatusNoGo indicates the check failed (blocking).
	StatusNoGo Status = "NO-GO"

	// StatusWarn indicates the check failed but is non-blocking.
	StatusWarn Status = "WARN"

	// StatusSkip indicates the check was skipped.
	StatusSkip Status = "SKIP"

	// StatusPending indicates the check has not run yet.
	StatusPending Status = "PENDING"

	// StatusRunning indicates the check is currently executing.
	StatusRunning Status = "RUNNING"
)

func ComputeTaskStatus

func ComputeTaskStatus(subtasks []SubtaskResult) Status

ComputeTaskStatus computes the overall status from subtask results.

func ComputeTeamStatus

func ComputeTeamStatus(tasks []TaskResult) Status

ComputeTeamStatus computes the overall status from task results.

func (Status) Emoji

func (s Status) Emoji() string

Emoji returns the emoji representation of the status.

func (Status) IsBlocking

func (s Status) IsBlocking() bool

IsBlocking returns true if this status should block the workflow.

func (Status) IsPassing

func (s Status) IsPassing() bool

IsPassing returns true if this status indicates success.

func (Status) String

func (s Status) String() string

String returns the string representation of the status.

type Subtask

type Subtask struct {
	// Name is the subtask identifier (e.g., "build", "tests", "lint").
	Name string `json:"name" yaml:"name"`

	// Description explains what this subtask validates or does.
	Description string `json:"description,omitempty" yaml:"description,omitempty"`

	// Command is the CLI command to execute (e.g., "go build ./...").
	Command string `json:"command,omitempty" yaml:"command,omitempty"`

	// Pattern is a regex pattern to search for (presence indicates failure).
	Pattern string `json:"pattern,omitempty" yaml:"pattern,omitempty"`

	// File is a specific file that must exist.
	File string `json:"file,omitempty" yaml:"file,omitempty"`

	// Files is a glob pattern for files to check (used with Pattern).
	Files string `json:"files,omitempty" yaml:"files,omitempty"`

	// Required indicates if failure blocks the workflow (NO-GO vs WARN).
	Required bool `json:"required" yaml:"required"`

	// ExpectedOutput describes what successful execution looks like.
	ExpectedOutput string `json:"expected_output,omitempty" yaml:"expected_output,omitempty"`

	// Timeout in seconds for command execution.
	Timeout int `json:"timeout,omitempty" yaml:"timeout,omitempty"`
}

Subtask represents an individual check or action within a task.

func NewSubtask

func NewSubtask(name string) *Subtask

NewSubtask creates a new Subtask with the given name.

func (*Subtask) IsCommandBased

func (s *Subtask) IsCommandBased() bool

IsCommandBased returns true if this subtask executes a command.

func (*Subtask) IsFileBased

func (s *Subtask) IsFileBased() bool

IsFileBased returns true if this subtask checks for file existence.

func (*Subtask) IsPatternBased

func (s *Subtask) IsPatternBased() bool

IsPatternBased returns true if this subtask searches for a pattern.

func (*Subtask) Optional

func (s *Subtask) Optional() *Subtask

Optional marks the subtask as optional (WARN instead of NO-GO on failure).

func (*Subtask) Type

func (s *Subtask) Type() string

Type returns the subtask type based on its configuration.

func (*Subtask) WithCommand

func (s *Subtask) WithCommand(cmd string) *Subtask

WithCommand sets the command and returns the subtask for chaining.

func (*Subtask) WithFile

func (s *Subtask) WithFile(file string) *Subtask

WithFile sets the file and returns the subtask for chaining.

func (*Subtask) WithFiles

func (s *Subtask) WithFiles(files string) *Subtask

WithFiles sets the files glob and returns the subtask for chaining.

func (*Subtask) WithPattern

func (s *Subtask) WithPattern(pattern string) *Subtask

WithPattern sets the pattern and returns the subtask for chaining.

type SubtaskResult

type SubtaskResult struct {
	Name    string `json:"name"`
	Status  Status `json:"status"`
	Message string `json:"message,omitempty"`
	Output  string `json:"output,omitempty"`
}

SubtaskResult holds the result of a subtask execution.

type Task

type Task struct {
	// Name is the task identifier (e.g., "qa-validation", "docs-validation").
	Name string `json:"name" yaml:"name"`

	// Description explains what this task accomplishes.
	Description string `json:"description,omitempty" yaml:"description,omitempty"`

	// Agent is the name of the agent assigned to this task.
	Agent string `json:"agent" yaml:"agent"`

	// DependsOn lists task names that must complete before this task.
	DependsOn []string `json:"depends_on,omitempty" yaml:"depends_on,omitempty"`

	// Subtasks are the individual checks or actions within this task.
	Subtasks []Subtask `json:"subtasks,omitempty" yaml:"subtasks,omitempty"`

	// Inputs are data or context passed to the task.
	Inputs []string `json:"inputs,omitempty" yaml:"inputs,omitempty"`

	// Outputs are data or artifacts produced by the task.
	Outputs []string `json:"outputs,omitempty" yaml:"outputs,omitempty"`
}

Task represents a unit of work assigned to an agent within a team.

func NewTask

func NewTask(name, agent string) *Task

NewTask creates a new Task with the given name and agent.

func (*Task) AddDependency

func (t *Task) AddDependency(taskName string) *Task

AddDependency adds a task dependency.

func (*Task) AddSubtask

func (t *Task) AddSubtask(subtask Subtask) *Task

AddSubtask adds a subtask to the task.

func (*Task) AddSubtasks

func (t *Task) AddSubtasks(subtasks ...Subtask) *Task

AddSubtasks adds multiple subtasks to the task.

func (*Task) HasDependencies

func (t *Task) HasDependencies() bool

HasDependencies returns true if this task depends on other tasks.

func (*Task) HasSubtasks

func (t *Task) HasSubtasks() bool

HasSubtasks returns true if this task has subtasks.

func (*Task) RequiredSubtaskCount

func (t *Task) RequiredSubtaskCount() int

RequiredSubtaskCount returns the number of required subtasks.

func (*Task) SubtaskNames

func (t *Task) SubtaskNames() []string

SubtaskNames returns the names of all subtasks.

func (*Task) WithDescription

func (t *Task) WithDescription(desc string) *Task

WithDescription sets the description and returns the task for chaining.

type TaskResult

type TaskResult struct {
	Name     string          `json:"name"`
	Agent    string          `json:"agent"`
	Status   Status          `json:"status"`
	Subtasks []SubtaskResult `json:"subtasks,omitempty"`
}

TaskResult holds the result of a task execution.

type Team

type Team struct {
	// Name is the team identifier (e.g., "release-team").
	Name string `json:"name" yaml:"name"`

	// Description explains what this team accomplishes.
	Description string `json:"description,omitempty" yaml:"description,omitempty"`

	// Process defines how tasks are executed (sequential, parallel, hierarchical).
	Process Process `json:"process" yaml:"process"`

	// Manager is the orchestrating agent (required for hierarchical process).
	Manager string `json:"manager,omitempty" yaml:"manager,omitempty"`

	// Agents lists all agent names participating in this team.
	Agents []string `json:"agents,omitempty" yaml:"agents,omitempty"`

	// Tasks defines the work to be done, with agent assignments and subtasks.
	Tasks []Task `json:"tasks" yaml:"tasks"`

	// Version is the target version for release workflows.
	Version string `json:"version,omitempty" yaml:"version,omitempty"`
}

Team represents a multi-agent orchestration definition. A team coordinates multiple agents to accomplish a complex workflow.

func NewTeam

func NewTeam(name string, process Process) *Team

NewTeam creates a new Team with the given name and process type.

func ParseJSON

func ParseJSON(data []byte, path string) (*Team, error)

ParseJSON parses JSON bytes into a Team.

func ParseYAML

func ParseYAML(data []byte, path string) (*Team, error)

ParseYAML parses YAML bytes into a Team.

func ReadTeamDir

func ReadTeamDir(dir string) ([]*Team, error)

ReadTeamDir reads all team files from a directory.

func ReadTeamFile

func ReadTeamFile(path string) (*Team, error)

ReadTeamFile reads a team file (YAML or JSON) and returns the Team.

func (*Team) AddAgent

func (t *Team) AddAgent(agent string) *Team

AddAgent adds an agent to the team.

func (*Team) AddAgents

func (t *Team) AddAgents(agents ...string) *Team

AddAgents adds multiple agents to the team.

func (*Team) AddTask

func (t *Team) AddTask(task Task) *Team

AddTask adds a task to the team.

func (*Team) AgentTasks

func (t *Team) AgentTasks(agent string) []Task

AgentTasks returns all tasks assigned to a specific agent.

func (*Team) GenerateOrchestrationMD

func (t *Team) GenerateOrchestrationMD(cfg OrchestrationConfig) string

GenerateOrchestrationMD generates Claude Code orchestration instructions in Markdown.

func (*Team) GetTask

func (t *Team) GetTask(name string) *Task

GetTask returns a task by name, or nil if not found.

func (*Team) ParallelGroups

func (t *Team) ParallelGroups() ([][]Task, error)

ParallelGroups returns tasks grouped by execution wave. Tasks in the same group can run in parallel.

func (*Team) RequiredSubtaskCount

func (t *Team) RequiredSubtaskCount() int

RequiredSubtaskCount returns the total number of required subtasks.

func (*Team) TaskNames

func (t *Team) TaskNames() []string

TaskNames returns the names of all tasks.

func (*Team) TopologicalSort

func (t *Team) TopologicalSort() ([]Task, error)

TopologicalSort returns tasks in dependency order. Tasks with no dependencies come first, followed by tasks whose dependencies are satisfied.

func (*Team) TotalSubtaskCount

func (t *Team) TotalSubtaskCount() int

TotalSubtaskCount returns the total number of subtasks across all tasks.

func (*Team) Validate

func (t *Team) Validate() error

Validate checks if the team definition is valid.

func (*Team) WithDescription

func (t *Team) WithDescription(desc string) *Team

WithDescription sets the description and returns the team for chaining.

func (*Team) WithManager

func (t *Team) WithManager(manager string) *Team

WithManager sets the manager agent (for hierarchical process).

type TeamResult

type TeamResult struct {
	Name    string       `json:"name"`
	Status  Status       `json:"status"`
	Tasks   []TaskResult `json:"tasks"`
	Version string       `json:"version,omitempty"` // Target version if applicable
}

TeamResult holds the result of a team execution.

type ValidationError

type ValidationError struct {
	Field   string
	Message string
}

ValidationError represents a validation error.

func (*ValidationError) Error

func (e *ValidationError) Error() string

type WriteError

type WriteError struct {
	Path string
	Err  error
}

WriteError represents an error during file writing.

func (*WriteError) Error

func (e *WriteError) Error() string

func (*WriteError) Unwrap

func (e *WriteError) Unwrap() error

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL