agents

Documentation

Overview

Package agents provides embedded AGENTS.md templates for bd init and setup.

Index

• Constants
• Variables
• func CodexSectionBody() string
• func CurrentHash(profile Profile) string
• func CurrentHashWithOpts(profile Profile, opts RenderOpts) string
• func EmbeddedBeadsSection() string
• func EmbeddedDefault() string
• func RenderSection(profile Profile) string
• func RenderSectionWithOpts(profile Profile, opts RenderOpts) string
• func ReplaceSection(content string, profile Profile) (string, bool, error)
• func ReplaceSectionWithOpts(content string, profile Profile, opts RenderOpts) (string, bool, error)
• type Profile
• type RenderOpts
  • func DefaultRenderOpts() RenderOpts
• type SectionMeta
  • func ParseMarker(line string) *SectionMeta

Constants

const MarkerVersion = 1

MarkerVersion is the current format version for BEGIN BEADS INTEGRATION markers. Bump this when the marker format itself changes (not when template content changes).

Variables

var (
	// ErrNoSection is returned by ReplaceSection when no BEGIN marker exists.
	ErrNoSection = errors.New("no beads section markers found")
	// ErrMalformedMarkers is returned when markers exist but are invalid
	// (e.g., END before BEGIN, or BEGIN without END).
	ErrMalformedMarkers = errors.New("malformed beads section markers")
)

Functions

func CodexSectionBody

func CodexSectionBody() string

CodexSectionBody returns the setup-managed Codex guidance body without Codex-specific markers.

func CurrentHash

func CurrentHash(profile Profile) string

CurrentHash returns the hash of the current template body for a profile. Callers can compare this against a parsed marker's hash to detect staleness. Assumes a Dolt remote is configured (backward-compatible).

func CurrentHashWithOpts

func CurrentHashWithOpts(profile Profile, opts RenderOpts) string

CurrentHashWithOpts returns the hash for a profile with the given render opts.

func EmbeddedBeadsSection

func EmbeddedBeadsSection() string

EmbeddedBeadsSection returns the beads integration section with markers. The returned string is trimmed to match the existing agentsBeadsSection behavior (no trailing newline after the end marker).

func EmbeddedDefault

func EmbeddedDefault() string

EmbeddedDefault returns the full AGENTS.md template content.

func RenderSection

func RenderSection(profile Profile) string

RenderSection returns the beads integration section for the given profile, wrapped in markers that include version, profile, and hash metadata for freshness detection. Assumes a Dolt remote is configured (backward-compatible). Use RenderSectionWithOpts to control conditional content.

func RenderSectionWithOpts

func RenderSectionWithOpts(profile Profile, opts RenderOpts) string

RenderSectionWithOpts renders the beads integration section with conditional content controlled by opts. When opts.HasRemote is false, "bd dolt push" is omitted from session-completion instructions.

func ReplaceSection

func ReplaceSection(content string, profile Profile) (string, bool, error)

ReplaceSection replaces an existing beads integration section in content with a freshly rendered section for the given profile. Returns the (possibly unchanged) content, whether it was modified, and any error. Assumes a Dolt remote is configured (backward-compatible). Use ReplaceSectionWithOpts to control conditional content.

Errors:

• ErrNoSection: no BEGIN marker found (caller should append instead)
• ErrMalformedMarkers: BEGIN exists but END is missing or appears before BEGIN

func ReplaceSectionWithOpts

func ReplaceSectionWithOpts(content string, profile Profile, opts RenderOpts) (string, bool, error)

ReplaceSectionWithOpts replaces an existing beads integration section in content with a freshly rendered section for the given profile and opts.

Types

type Profile

type Profile string

Profile identifies which template variant to render.

const (
	// ProfileFull is the command-heavy profile for hookless agents (Codex, Factory, Mux, etc.).
	ProfileFull Profile = "full"
	// ProfileMinimal is the pointer-only profile for hook-enabled agents (Claude, Gemini).
	ProfileMinimal Profile = "minimal"
)

type RenderOpts

type RenderOpts struct {
	// HasRemote indicates whether a Dolt remote is configured.
	// When false, "bd dolt push" is omitted from session-completion instructions.
	HasRemote bool
}

RenderOpts controls conditional content in rendered templates.

func DefaultRenderOpts

func DefaultRenderOpts() RenderOpts

DefaultRenderOpts returns opts that assume a remote is configured, preserving backward-compatible behavior for callers that don't pass opts.

type SectionMeta

type SectionMeta struct {
	Version int
	Profile Profile
	Hash    string
}

SectionMeta holds metadata parsed from a BEGIN BEADS INTEGRATION marker.

func ParseMarker

func ParseMarker(line string) *SectionMeta

ParseMarker parses a BEGIN BEADS INTEGRATION marker line and returns its metadata. Returns nil if the line is not a valid begin marker. Supports both legacy (no metadata) and new (profile + hash) formats.