tracker

Documentation

Overview

Package tracker defines the pluggable task tracking interface. Implementations can read stories from files (BMAD, TODO.md), external services (GitHub Issues, Linear), or custom scripts.

Index

• func SortByPriority(stories []Story)
• type CommandConfig
• type CommandTracker
  • func NewCommandTracker(workDir string, config CommandConfig) *CommandTracker
  • func (ct *CommandTracker) ListAll() ([]Story, error)
  • func (ct *CommandTracker) ListPending() ([]Story, error)
  • func (ct *CommandTracker) MarkComplete(storyID string) error
  • func (ct *CommandTracker) MarkInProgress(storyID string) error
  • func (ct *CommandTracker) NextStory() (*Story, error)
  • func (ct *CommandTracker) RevertToReady(storyID string) error
• type FileTracker
  • func NewFileTracker(dir, filename string) *FileTracker
  • func (ft *FileTracker) ListAll() ([]Story, error)
  • func (ft *FileTracker) ListPending() ([]Story, error)
  • func (ft *FileTracker) MarkComplete(storyID string) error
  • func (ft *FileTracker) MarkInProgress(storyID string) error
  • func (ft *FileTracker) NextStory() (*Story, error)
  • func (ft *FileTracker) RevertToReady(storyID string) error
• type FlatFileTracker
  • func NewFlatFileTracker(dir, filename string) *FlatFileTracker
  • func (ft *FlatFileTracker) ListAll() ([]Story, error)
  • func (ft *FlatFileTracker) ListPending() ([]Story, error)
  • func (ft *FlatFileTracker) MarkComplete(storyID string) error
  • func (ft *FlatFileTracker) MarkInProgress(storyID string) error
  • func (ft *FlatFileTracker) NextStory() (*Story, error)
  • func (ft *FlatFileTracker) RevertToReady(storyID string) error
• type Registry
  • func NewRegistry() *Registry
  • func (r *Registry) Available() []string
  • func (r *Registry) Get(name string) (TaskTracker, error)
  • func (r *Registry) Register(name string, factory TrackerFactory)
• type Story
  • func (s Story) IsActionable() bool
• type StoryStatus
• type TaskTracker
  • func AutoDetect(dir, filename string) TaskTracker
• type TrackerFactory

Functions

func SortByPriority

func SortByPriority(stories []Story)

SortByPriority sorts stories with in-progress first, then ready-for-dev.

Types

type CommandConfig

type CommandConfig struct {
	Next     string // Command that outputs a single Story JSON (or empty for none).
	Complete string // Command to mark story done. Receives story ID as arg.
	Progress string // Command to mark story in-progress. Receives story ID as arg.
	Pending  string // Command that outputs JSON array of pending Story objects.
	All      string // Command that outputs JSON array of all Story objects.
	Timeout  int    // Command timeout in seconds (default: 30).
}

CommandConfig defines user-provided commands for each tracker operation. Users configure these in .ralph-engine/config.yaml under tracker.commands.

Example config:

tracker:
  type: "command"
  commands:
    next:     "./scripts/next-story.sh"
    complete: "./scripts/mark-complete.sh {{.ID}}"
    progress: "./scripts/mark-progress.sh {{.ID}}"
    pending:  "./scripts/list-pending.sh"
    all:      "./scripts/list-all.sh"

Each command SHALL output JSON in the Story format. The engine passes story ID as the first argument where {{.ID}} appears.

type CommandTracker

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

CommandTracker delegates all operations to user-defined commands. This enables integration with ANY task system — Jira, Notion, custom DB, etc.

func NewCommandTracker

func NewCommandTracker(workDir string, config CommandConfig) *CommandTracker

NewCommandTracker creates a tracker that calls external commands.

func (*CommandTracker) ListAll

func (ct *CommandTracker) ListAll() ([]Story, error)

ListAll calls the "all" command and parses the output as a Story array.

func (*CommandTracker) ListPending

func (ct *CommandTracker) ListPending() ([]Story, error)

ListPending calls the "pending" command and parses the output as a Story array.

func (*CommandTracker) MarkComplete

func (ct *CommandTracker) MarkComplete(storyID string) error

MarkComplete calls the "complete" command with the story ID.

func (*CommandTracker) MarkInProgress

func (ct *CommandTracker) MarkInProgress(storyID string) error

MarkInProgress calls the "progress" command with the story ID.

func (*CommandTracker) NextStory

func (ct *CommandTracker) NextStory() (*Story, error)

NextStory calls the "next" command and parses the output as a Story.

func (*CommandTracker) RevertToReady

func (ct *CommandTracker) RevertToReady(storyID string) error

RevertToReady calls the "revert" command, or falls back to the "progress" command with ready-for-dev hint.

type FileTracker

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

FileTracker reads stories from a YAML file (sprint-status.yaml). It supports BMAD v6 format and generic sprint tracking.

func NewFileTracker

func NewFileTracker(dir, filename string) *FileTracker

NewFileTracker creates a tracker that reads from a YAML file.

func (*FileTracker) ListAll

func (ft *FileTracker) ListAll() ([]Story, error)

ListAll returns all stories from the sprint status file.

func (*FileTracker) ListPending

func (ft *FileTracker) ListPending() ([]Story, error)

ListPending returns all actionable stories sorted by priority.

func (*FileTracker) MarkComplete

func (ft *FileTracker) MarkComplete(storyID string) error

MarkComplete transitions a story to done status and writes back.

func (*FileTracker) MarkInProgress

func (ft *FileTracker) MarkInProgress(storyID string) error

MarkInProgress transitions a story to in-progress status and writes back.

func (*FileTracker) NextStory

func (ft *FileTracker) NextStory() (*Story, error)

NextStory returns the highest-priority actionable story. In-progress stories are returned first (resume interrupted work), then ready-for-dev stories in file order.

func (*FileTracker) RevertToReady

func (ft *FileTracker) RevertToReady(storyID string) error

RevertToReady transitions a story back to ready-for-dev (e.g., after quality gate failure).

type FlatFileTracker

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

FlatFileTracker reads stories from a flat key-value YAML file. Supports the BMAD v6 sprint-status.yaml format:

development_status:
  epic-1: done
  1-1-resolve-critical-issues: done
  1-2-unified-permission-system: ready-for-dev

func NewFlatFileTracker

func NewFlatFileTracker(dir, filename string) *FlatFileTracker

NewFlatFileTracker creates a tracker for flat YAML sprint status files.

func (*FlatFileTracker) ListAll

func (ft *FlatFileTracker) ListAll() ([]Story, error)

ListAll returns all stories from the flat status file.

func (*FlatFileTracker) ListPending

func (ft *FlatFileTracker) ListPending() ([]Story, error)

ListPending returns all actionable stories sorted by priority.

func (*FlatFileTracker) MarkComplete

func (ft *FlatFileTracker) MarkComplete(storyID string) error

MarkComplete transitions a story to done status.

func (*FlatFileTracker) MarkInProgress

func (ft *FlatFileTracker) MarkInProgress(storyID string) error

MarkInProgress transitions a story to in-progress status.

func (*FlatFileTracker) NextStory

func (ft *FlatFileTracker) NextStory() (*Story, error)

NextStory returns the highest-priority actionable story.

func (*FlatFileTracker) RevertToReady

func (ft *FlatFileTracker) RevertToReady(storyID string) error

RevertToReady transitions a story back to ready-for-dev.

type Registry

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

Registry holds registered tracker implementations.

func NewRegistry

func NewRegistry() *Registry

NewRegistry creates an empty tracker registry.

func (*Registry) Available

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

Available returns the names of all registered trackers.

func (*Registry) Get

func (r *Registry) Get(name string) (TaskTracker, error)

Get creates a tracker instance by name.

func (*Registry) Register

func (r *Registry) Register(name string, factory TrackerFactory)

Register adds a tracker factory to the registry.

type Story

type Story struct {
	ID        string      `json:"id" yaml:"id"`
	Title     string      `json:"title" yaml:"title"`
	Status    StoryStatus `json:"status" yaml:"status"`
	EpicID    string      `json:"epic_id" yaml:"epic_id"`
	EpicTitle string      `json:"epic_title" yaml:"epic_title"`
	FilePath  string      `json:"file_path,omitempty" yaml:"file_path,omitempty"`
	Tags      []string    `json:"tags,omitempty" yaml:"tags,omitempty"`
	DependsOn []string    `json:"depends_on,omitempty" yaml:"depends_on,omitempty"`
}

Story represents a unit of work the engine can execute.

func (Story) IsActionable

func (s Story) IsActionable() bool

IsActionable returns true if the story can be worked on.

type StoryStatus

type StoryStatus string

StoryStatus represents the lifecycle state of a story.

const (
	StatusBacklog     StoryStatus = "backlog"
	StatusReadyForDev StoryStatus = "ready-for-dev"
	StatusInProgress  StoryStatus = "in-progress"
	StatusReview      StoryStatus = "review"
	StatusDone        StoryStatus = "done"
	StatusBlocked     StoryStatus = "blocked"
)

type TaskTracker

type TaskTracker interface {
	// NextStory returns the highest-priority actionable story, or nil if none.
	NextStory() (*Story, error)
	// MarkComplete transitions a story to done status.
	MarkComplete(storyID string) error
	// MarkInProgress transitions a story to in-progress status.
	MarkInProgress(storyID string) error
	// ListPending returns all actionable stories sorted by priority.
	ListPending() ([]Story, error)
	// ListAll returns all stories regardless of status.
	ListAll() ([]Story, error)
	// RevertToReady transitions a story back to ready-for-dev (e.g., after quality gate failure).
	RevertToReady(storyID string) error
}

TaskTracker is the interface that all tracker implementations must satisfy. The engine uses this to discover, pick, and update story progress.

func AutoDetect

func AutoDetect(dir, filename string) TaskTracker

AutoDetect creates the right tracker based on the file format. Returns a FlatFileTracker if the file contains "development_status:", otherwise returns a FileTracker (structured YAML with epics array).

type TrackerFactory

type TrackerFactory func() TaskTracker //nolint:revive // Used as tracker.TrackerFactory for clarity across packages

TrackerFactory creates a new TaskTracker instance.