epic

package
v0.1.2 Latest Latest
Warning

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

 Go to latest Published: Mar 3, 2026 License: MIT Imports: 9 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func EpicIDValidator added in v0.1.2 

func EpicIDValidator(identifier string, nameAndTitle ...string) *valgo.ValidatorString[string]

EpicIDValidator returns a valgo Validator that checks whether the given string is a valid EpicID.

func NewTaskIDString 

func NewTaskIDString() string

NewTaskIDString generates a new unique task ID string.

func Now 

func Now() time.Time

Now is a helper for generating timestamps.

Types

type Epic 

type Epic struct {
	ID              EpicID         `json:"id"`
	RepoID          string         `json:"repo_id"`
	Title           string         `json:"title"`
	Description     string         `json:"description"`
	Status          Status         `json:"status"`
	ProposedTasks   []ProposedTask `json:"proposed_tasks"`
	TaskIDs         []string       `json:"task_ids"`
	PlanningPrompt  string         `json:"planning_prompt,omitempty"`
	SessionLog      []string       `json:"session_log"`
	NotReady        bool           `json:"not_ready"`
	Model           string         `json:"model,omitempty"`
	ClaimedAt       *time.Time     `json:"claimed_at,omitempty"`
	LastHeartbeatAt *time.Time     `json:"last_heartbeat_at,omitempty"`
	Feedback        *string        `json:"feedback,omitempty"`
	FeedbackType    *string        `json:"feedback_type,omitempty"`
	CreatedAt       time.Time      `json:"created_at"`
	UpdatedAt       time.Time      `json:"updated_at"`
}

Epic represents a large deliverable that contains multiple related tasks.

func NewEpic 

func NewEpic(repoID, title, description string) *Epic

NewEpic creates a new Epic in planning status, queued for a worker to claim.

type EpicID 

type EpicID struct {
	typeid.TypeID[epicPrefix]
}

EpicID is the unique identifier for an Epic.

func MustParseEpicID 

func MustParseEpicID(s string) EpicID

MustParseEpicID parses a string into an EpicID, panicking on failure.

func NewEpicID 

func NewEpicID() EpicID

NewEpicID generates a new unique EpicID.

func ParseEpicID 

func ParseEpicID(s string) (EpicID, error)

ParseEpicID parses a string into an EpicID.

type ErrTagEpicConflict 

type ErrTagEpicConflict struct{ errtag.Conflict }

ErrTagEpicConflict indicates an epic conflict (e.g. duplicate ID).

func (ErrTagEpicConflict) Msg 

func (ErrTagEpicConflict) Msg() string

func (ErrTagEpicConflict) Unwrap 

func (e ErrTagEpicConflict) Unwrap() error

type ErrTagEpicNotFound 

type ErrTagEpicNotFound struct{ errtag.NotFound }

ErrTagEpicNotFound indicates an epic was not found.

func (ErrTagEpicNotFound) Msg 

func (ErrTagEpicNotFound) Msg() string

func (ErrTagEpicNotFound) Unwrap 

func (e ErrTagEpicNotFound) Unwrap() error

type FeedbackType 

type FeedbackType string

FeedbackType classifies user feedback sent to the planning agent. 

const (
	FeedbackMessage   FeedbackType = "message"   // User sent a feedback message
	FeedbackConfirmed FeedbackType = "confirmed" // User confirmed the epic
	FeedbackClosed    FeedbackType = "closed"    // User closed the epic
)

type PlanningEpicForMetrics 

type PlanningEpicForMetrics struct {
	ID        string
	Title     string
	RepoID    string
	Model     string
	ClaimedAt *time.Time
}

PlanningEpicForMetrics is a minimal struct for epic planning metrics.

type ProposedTask 

type ProposedTask struct {
	TempID             string   `json:"temp_id"`
	Title              string   `json:"title"`
	Description        string   `json:"description"`
	DependsOnTempIDs   []string `json:"depends_on_temp_ids,omitempty"`
	AcceptanceCriteria []string `json:"acceptance_criteria,omitempty"`
}

ProposedTask represents a task proposed by the planning agent during an epic planning session. These are not yet created in the task system.

type Repository 

type Repository interface {
	CreateEpic(ctx context.Context, epic *Epic) error
	ReadEpic(ctx context.Context, id EpicID) (*Epic, error)
	ListEpics(ctx context.Context) ([]*Epic, error)
	ListEpicsByRepo(ctx context.Context, repoID string) ([]*Epic, error)
	UpdateEpic(ctx context.Context, epic *Epic) error
	UpdateEpicStatus(ctx context.Context, id EpicID, status Status) error
	UpdateProposedTasks(ctx context.Context, id EpicID, tasks []ProposedTask) error
	SetTaskIDs(ctx context.Context, id EpicID, taskIDs []string) error
	AppendSessionLog(ctx context.Context, id EpicID, lines []string) error
	DeleteEpic(ctx context.Context, id EpicID) error

	// Worker support
	ListPlanningEpics(ctx context.Context) ([]*Epic, error)
	ClaimEpic(ctx context.Context, id EpicID) (bool, error)
	EpicHeartbeat(ctx context.Context, id EpicID) error
	SetEpicFeedback(ctx context.Context, id EpicID, feedback, feedbackType string) error
	ClearEpicFeedback(ctx context.Context, id EpicID) error
	ReleaseEpicClaim(ctx context.Context, id EpicID) error
	ListStaleEpics(ctx context.Context, threshold time.Time) ([]*Epic, error)

	// ListActiveEpics returns all epics in active status.
	ListActiveEpics(ctx context.Context) ([]*Epic, error)
	// RemoveTaskID removes a task ID from an epic's task_ids array.
	RemoveTaskID(ctx context.Context, id EpicID, taskID string) error
}

Repository is the interface for performing CRUD operations on Epics.

type Status 

type Status string

Status represents the lifecycle state of an Epic. 

const (
	StatusDraft     Status = "draft"     // Agent proposed tasks, user reviewing
	StatusPlanning  Status = "planning"  // Queued or claimed by worker, agent planning
	StatusReady     Status = "ready"     // Planning complete, tasks confirmed but not started
	StatusActive    Status = "active"    // Tasks are being picked up by agents
	StatusCompleted Status = "completed" // All tasks finished
	StatusClosed    Status = "closed"    // Manually closed
)

type Store 

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

Store wraps a Repository and adds application-level concerns for epics.

func NewStore 

func NewStore(repo Repository, taskCreator TaskCreator, logger log.Logger) *Store

NewStore creates a new Store backed by the given Repository.

func (*Store) AppendSessionLog 

func (s *Store) AppendSessionLog(ctx context.Context, id EpicID, lines []string) error

AppendSessionLog appends messages to the planning session log.

func (*Store) CheckActiveEpicsCompletion 

func (s *Store) CheckActiveEpicsCompletion(ctx context.Context) (int, error)

CheckActiveEpicsCompletion checks all active epics for completion. This is intended to be called from a background loop.

func (*Store) CheckAndCompleteEpic 

func (s *Store) CheckAndCompleteEpic(ctx context.Context, id EpicID) error

CheckAndCompleteEpic checks whether all tasks in an active epic have reached a terminal state (merged or closed). If so, the epic is transitioned to completed. Tasks in failed status prevent completion — the epic stays active.

func (*Store) ClaimPendingEpic 

func (s *Store) ClaimPendingEpic(ctx context.Context) (*Epic, error)

ClaimPendingEpic finds an unclaimed planning epic and claims it atomically.

func (*Store) CloseEpic 

func (s *Store) CloseEpic(ctx context.Context, id EpicID) error

CloseEpic closes an epic.

func (*Store) CompletePlanning added in v0.1.2 

func (s *Store) CompletePlanning(ctx context.Context, id EpicID, tasks []ProposedTask) error

CompletePlanning is called by the agent when it finishes proposing tasks. It updates the proposed tasks, transitions to draft status, releases the claim, and clears any pending feedback (it has been consumed by this planning run).

func (*Store) ConfirmEpic 

func (s *Store) ConfirmEpic(ctx context.Context, id EpicID, notReady bool) error

ConfirmEpic creates real tasks from proposed tasks and activates the epic.

func (*Store) CreateEpic 

func (s *Store) CreateEpic(ctx context.Context, epic *Epic) error

CreateEpic creates a new epic in planning status and notifies pending.

func (*Store) DeleteEpic 

func (s *Store) DeleteEpic(ctx context.Context, id EpicID) error

DeleteEpic deletes an epic. Callers are responsible for deleting child tasks before calling this method to avoid FK violations.

func (*Store) EpicHeartbeat 

func (s *Store) EpicHeartbeat(ctx context.Context, id EpicID) error

EpicHeartbeat updates the heartbeat timestamp for a claimed epic.

func (*Store) FailPlanning added in v0.1.2 

func (s *Store) FailPlanning(ctx context.Context, id EpicID) error

FailPlanning is called by the agent when planning fails. It releases the claim and transitions back to draft (if there are existing proposed tasks) or stays in planning (so it can be retried).

func (*Store) ListEpics 

func (s *Store) ListEpics(ctx context.Context) ([]*Epic, error)

ListEpics returns all epics.

func (*Store) ListEpicsByRepo 

func (s *Store) ListEpicsByRepo(ctx context.Context, repoID string) ([]*Epic, error)

ListEpicsByRepo returns all epics for a given repo.

func (*Store) ListPlanningEpicsForMetrics 

func (s *Store) ListPlanningEpicsForMetrics(ctx context.Context) ([]PlanningEpicForMetrics, error)

ListPlanningEpicsForMetrics returns epics that are actively being planned by a worker agent (claimed epics in planning or draft status). This is used by the task metrics to include planning agents in the active agents count.

func (*Store) ReadEpic 

func (s *Store) ReadEpic(ctx context.Context, id EpicID) (*Epic, error)

ReadEpic reads an epic by ID.

func (*Store) ReleaseEpicClaim 

func (s *Store) ReleaseEpicClaim(ctx context.Context, id EpicID) error

ReleaseEpicClaim releases a worker's claim on an epic, making it available again.

func (*Store) RemoveTaskAndCheck 

func (s *Store) RemoveTaskAndCheck(ctx context.Context, id EpicID, taskID string) error

RemoveTaskAndCheck removes a task ID from an epic's task_ids list and checks if the epic should be marked as completed.

func (*Store) RequestChanges added in v0.1.2 

func (s *Store) RequestChanges(ctx context.Context, id EpicID, feedback string) error

RequestChanges stores user feedback on the current draft plan and transitions the epic back to planning status so a worker can pick it up for re-planning. The feedback is stored in the epic and passed to the next agent run as context.

func (*Store) SetTaskStatusReader 

func (s *Store) SetTaskStatusReader(reader TaskStatusReader)

SetTaskStatusReader sets the TaskStatusReader used for epic completion checks. This is set after construction to avoid circular dependencies.

func (*Store) StartPlanning 

func (s *Store) StartPlanning(ctx context.Context, id EpicID, prompt string) error

StartPlanning transitions an epic back to planning status and notifies pending.

func (*Store) TimeoutStaleEpics 

func (s *Store) TimeoutStaleEpics(ctx context.Context, timeout time.Duration) (int, error)

TimeoutStaleEpics releases claimed epics whose heartbeat has expired.

func (*Store) UpdateProposedTasks 

func (s *Store) UpdateProposedTasks(ctx context.Context, id EpicID, tasks []ProposedTask) error

UpdateProposedTasks updates the proposed tasks (used for manual edits by the user).

func (*Store) WaitForPending 

func (s *Store) WaitForPending() <-chan struct{}

WaitForPending returns a channel that signals when a planning epic might be available.

type TaskCreateFunc 

type TaskCreateFunc func(ctx context.Context, repoID, title, description string, dependsOn, acceptanceCriteria []string, epicID string, ready bool, model string) (string, error)

TaskCreateFunc is a function that creates a task and returns its ID.

type TaskCreator 

type TaskCreator interface {
	CreateTaskFromEpic(ctx context.Context, repoID, title, description string, dependsOn, acceptanceCriteria []string, epicID string, ready bool, model string) (string, error)
}

TaskCreator creates tasks in the task system when an epic is confirmed.

type TaskCreatorFunc 

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

TaskCreatorFunc adapts a function to the TaskCreator interface.

func NewTaskCreatorFunc 

func NewTaskCreatorFunc(fn TaskCreateFunc) *TaskCreatorFunc

NewTaskCreatorFunc creates a TaskCreator from a function.

func (*TaskCreatorFunc) CreateTaskFromEpic 

func (f *TaskCreatorFunc) CreateTaskFromEpic(ctx context.Context, repoID, title, description string, dependsOn, acceptanceCriteria []string, epicID string, ready bool, model string) (string, error)

type TaskStatusReadFunc 

type TaskStatusReadFunc func(ctx context.Context, taskID string) (string, error)

TaskStatusReadFunc is a function that reads a task status by ID.

type TaskStatusReader 

type TaskStatusReader interface {
	ReadTaskStatus(ctx context.Context, taskID string) (string, error)
}

TaskStatusReader reads task statuses for epic completion checking.

type TaskStatusReaderFunc 

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

TaskStatusReaderFunc adapts a function to the TaskStatusReader interface.

func NewTaskStatusReaderFunc 

func NewTaskStatusReaderFunc(fn TaskStatusReadFunc) *TaskStatusReaderFunc

NewTaskStatusReaderFunc creates a TaskStatusReader from a function.

func (*TaskStatusReaderFunc) ReadTaskStatus 

func (f *TaskStatusReaderFunc) ReadTaskStatus(ctx context.Context, taskID string) (string, error)

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.