spec

Documentation

Overview

Package spec parses everflow spec documents — markdown files with YAML frontmatter. A spec is one Run's worth of work: the frontmatter carries the structured config (provider, project, runner, base branch, status); the markdown body is what the planner reads each iteration to decide the next increment.

See ADR-0024 for the rationale (spec = Run; sweep + spec modes coexist).

Index

• Variables
• type Spec
  • func Parse(path string) (*Spec, error)
  • func ParseBytes(data []byte) (*Spec, error)
  • func (s *Spec) IsReady() bool
  • func (s *Spec) Validate() error

Variables

var ErrNoFrontmatter = errors.New("spec: missing YAML frontmatter")

ErrNoFrontmatter is returned when a spec file doesn't start with the "---" delimiter. Frontmatter is required — the planner needs the structured config to drive a Run.

Types

type Spec

type Spec struct {
	// Required:
	Goal     string `yaml:"goal"`
	Provider string `yaml:"provider"` // "gitlab" | "github"
	Project  string `yaml:"project"`  // "owner/repo" or path-with-namespace
	Runner   string `yaml:"runner"`   // "claude" | "qwen" | ... — see runner.Registry

	// Optional:
	Model       string `yaml:"model"` // e.g. "claude-haiku-4-5" — passed to the runner via runner.Request.Model; empty means the runner's default
	BaseRepo    string `yaml:"base_repo"`
	BaseBranch  string `yaml:"base_branch"`
	Concurrency int    `yaml:"concurrency"`
	Status      string `yaml:"status"`    // "draft" | "ready" | "in_progress" | "compressed"; everflow only acts on "ready"
	DraftMRs    bool   `yaml:"draft_mrs"` // opens MRs as Draft / WIP — spike safety net

	// Populated by the parser:
	Body string `yaml:"-"` // markdown body after the frontmatter
	Path string `yaml:"-"` // filesystem path Parse loaded from (empty for ParseBytes)
}

Spec is the parsed shape of a spec file. Frontmatter fields are exported for unmarshalling; Body and Path are populated by Parse/ParseBytes.

func Parse

func Parse(path string) (*Spec, error)

Parse reads a spec from disk.

func ParseBytes

func ParseBytes(data []byte) (*Spec, error)

ParseBytes parses an in-memory spec. Useful for tests + future watch- directory ingestion that has the content already.

func (*Spec) IsReady

func (s *Spec) IsReady() bool

IsReady is true when the spec's `status:` is "ready" (or empty — treated as ready since the field is optional). Future spec-ingestion will use this to decide which specs to Trigger.

func (*Spec) Validate

func (s *Spec) Validate() error

Validate checks that the required fields are present. Returns a single error joining any missing ones so the user can fix all at once.