engine

Documentation

Overview

Package engine implements the core autonomous execution loop. It orchestrates Claude sessions, enforces quality gates between iterations, monitors resources, and persists progress for resume capability.

prompt.go contains the system prompt template that is injected into each Claude session via --append-system-prompt. It provides the AI agent with context about the current sprint state, quality requirements, research tools, and the engine's expectations for the session.

Index

• Constants
• func BuildPrompt(ctx PromptContext) string
• type Engine
  • func New(opts EngineOpts) (*Engine, error)
  • func (e *Engine) ExitInfo() ExitReason
  • func (e *Engine) Preflight(ctx context.Context) []PreflightResult
  • func (e *Engine) Run(ctx context.Context, tk tracker.TaskTracker, onEvent EventHandler) RunResult
  • func (e *Engine) Status() EngineStatus
• type EngineEvent
• type EngineOpts
• type EngineStatus
• type EventHandler
• type ExitReason
• type PreflightResult
• type PromptContext
• type RunResult

Constants

const DefaultCooldown = 10 * time.Second

DefaultCooldown is the pause between Claude sessions.

Functions

func BuildPrompt

func BuildPrompt(ctx PromptContext) string

BuildPrompt generates the system prompt for an autonomous agent session. Structure: Identity → Context → Story → Research → Workflow → Quality → Persistence → Exit. Minimal boilerplate. Dynamic sections injected only when configured. The prompt is agent-agnostic — works with any CLI-based AI agent.

Types

type Engine

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

Engine is the core autonomous execution loop.

func New

func New(opts EngineOpts) (*Engine, error)

New creates an Engine with validated configuration.

func (*Engine) ExitInfo

func (e *Engine) ExitInfo() ExitReason

ExitInfo returns the reason the engine stopped (thread-safe).

func (*Engine) Preflight

func (e *Engine) Preflight(ctx context.Context) []PreflightResult

Preflight runs pre-execution checks and returns results. Each check is independent — all are run even if some fail.

func (*Engine) Run

func (e *Engine) Run(ctx context.Context, tk tracker.TaskTracker, onEvent EventHandler) RunResult

Run executes the autonomous loop: pick story → call agent → check gates → repeat. Supports dry-run, max-iterations, and single-story modes for testing.

func (*Engine) Status

func (e *Engine) Status() EngineStatus

Status returns the current engine status (thread-safe).

type EngineEvent

type EngineEvent struct {
	Type    string
	Message string
	Data    map[string]interface{}
}

EngineEvent describes something that happened during the loop.

type EngineOpts

type EngineOpts struct {
	ProjectDir        string
	StateDir          string
	Binary            string // "claude" or "claudebox"
	Model             string // Agent model (e.g., "opus", "sonnet")
	MaxTurns          int    // Max agent turns per session (0 = unlimited)
	AllowedTools      string // Comma-separated allowed tools
	DisallowedTools   string // Comma-separated denied tools (takes precedence)
	SkipPermissions   bool   // --dangerously-skip-permissions
	MaxFailures       int    // Circuit breaker threshold
	CooldownSeconds   int    // Seconds between sessions
	CooldownMinutes   int    // Circuit breaker cooldown
	StoriesPerSession int    // Target stories per Claude session
	Debug             bool   // Enable verbose debug logging to file
	LogMaxFiles       int    // Max log files to keep (default: 10)
	LogMaxSizeMB      int64  // Max log file size in MB (default: 50)
	DryRun            bool   // Show what would happen without calling agent
	MaxIterations     int    // Stop after N iterations (0 = infinite)
	SingleStory       string // Run only this story ID, then stop
	MaxGateRetries    int    // Max quality gate fix attempts (0 = unlimited)
	// Config sections passed through from config.yaml for prompt building.
	WorkflowType         string                 // "bmad-v6", "basic", "tdd-strict"
	WorkflowCommands     map[string]string      // Phase → agent command mapping
	WorkflowInstructions string                 // Free-form workflow instructions for prompt
	QualityGate          string                 // "full", "standard", "minimal"
	Paths                *config.PathsConfig    // Project artifact paths
	Prompt               *config.PromptConfig   // Custom prompt sections
	Research             *config.ResearchConfig // Research tools config
	Hooks                *hooks.HooksConfig     // Lifecycle hooks (nil = no hooks)
}

EngineOpts configures a new Engine instance.

type EngineStatus

type EngineStatus string //nolint:revive // Used as engine.EngineStatus for clarity across packages

EngineStatus represents the current state of the engine.

const (
	StatusIdle    EngineStatus = "idle"
	StatusRunning EngineStatus = "running"
	StatusPaused  EngineStatus = "paused"
	StatusStopped EngineStatus = "stopped"
	StatusBlocked EngineStatus = "blocked"
)

type EventHandler

type EventHandler func(event EngineEvent)

EventHandler receives engine events for display (dashboard, logs).

type ExitReason

type ExitReason string

ExitReason indicates why the engine stopped.

const (
	ExitAllComplete      ExitReason = "all_complete"
	ExitCircuitBreaker   ExitReason = "circuit_breaker"
	ExitUsageLimit       ExitReason = "usage_limit"
	ExitUserInterrupt    ExitReason = "user_interrupt"
	ExitResourceCritical ExitReason = "resource_critical"
	ExitBlocked          ExitReason = "blocked"
)

type PreflightResult

type PreflightResult struct {
	Name    string
	OK      bool
	Message string
}

PreflightResult holds the outcome of a single preflight check.

type PromptContext

type PromptContext struct {
	StoryID              string
	StoryTitle           string
	EpicID               string
	EpicTitle            string
	SessionNumber        int
	StoriesDone          int
	StoriesTotal         int
	WorkflowType         string            // "bmad-v6", "basic", "tdd-strict"
	WorkflowCommands     map[string]string // Phase → agent command mapping from config
	WorkflowInstructions string            // Free-form workflow instructions
	QualityGate          string            // "full", "standard", "minimal"
	SSHAvailable         bool
	Findings             int
	// StoryContent is the full story file content (read from paths.stories).
	StoryContent string
	// PromptMD is the content of .ralph-engine/prompt.md.
	PromptMD string
	// Sections holds custom prompt sections from config (files + inline content).
	Sections []config.PromptSection
	// ProjectDir is needed to resolve file paths in prompt sections.
	ProjectDir string
	// Research holds configured research tools for prompt injection.
	Research *config.ResearchConfig
}

PromptContext holds the dynamic values injected into the session prompt.

type RunResult

type RunResult struct {
	ExitReason      ExitReason
	SessionsRun     int
	StoriesComplete int
	TotalCostUSD    float64
	Error           error
}

RunResult holds the outcome of an engine run.