ticks

package
v0.19.0 Latest Latest
Warning

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

 Go to latest Published: Jul 2, 2026 License: MIT Imports: 7 Imported by: 0

Documentation

Overview

Package ticks wraps the tk CLI for interacting with the Ticks issue tracker. It provides operations for epics, tasks, and dependency graph queries.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type Client 

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

Client provides direct access to the Ticks issue tracker via the tick.Store. This avoids the overhead of exec'ing the tk CLI for each operation.

func NewClient 

func NewClient(tickDir string) *Client

NewClient creates a new Client using the given tick directory. tickDir should be the .tick directory (e.g., "/path/to/project/.tick").

func (*Client) AddAgentNote 

func (c *Client) AddAgentNote(issueID, message string) error

AddAgentNote adds a note from the agent (default author). This is the standard way for agents to leave progress notes.

func (*Client) AddHumanNote 

func (c *Client) AddHumanNote(issueID, message string) error

AddHumanNote adds a note from a human. Use this for feedback, answers, and other human-provided content.

func (*Client) AddNote 

func (c *Client) AddNote(issueID, message string, extraArgs ...string) error

AddNote adds a note to an epic or task. extraArgs can include "--from", "human" to mark the note as from a human.

func (*Client) Approve 

func (c *Client) Approve(taskID string) error

Approve sets verdict=approved on a task.

func (*Client) ClearAwaiting 

func (c *Client) ClearAwaiting(taskID string) error

ClearAwaiting clears the awaiting field of a task.

func (*Client) CloseEpic 

func (c *Client) CloseEpic(epicID, reason string) error

CloseEpic closes an epic with the given reason.

func (*Client) CloseTask 

func (c *Client) CloseTask(taskID, reason string) error

CloseTask closes a task with the given reason.

func (*Client) CompleteTask 

func (c *Client) CompleteTask(taskID string, summary string) error

CompleteTask handles task completion, respecting the requires field.

func (*Client) GetAgentNotes 

func (c *Client) GetAgentNotes(issueID string) ([]Note, error)

GetAgentNotes returns only notes from agents. Use this to read progress notes from previous agent iterations.

func (*Client) GetEpic 

func (c *Client) GetEpic(epicID string) (*Epic, error)

GetEpic returns details for a specific epic.

func (*Client) GetHumanNotes 

func (c *Client) GetHumanNotes(issueID string) ([]Note, error)

GetHumanNotes returns only notes from humans. Use this to read feedback and answers from human reviewers.

func (*Client) GetNotes 

func (c *Client) GetNotes(issueID string) ([]string, error)

GetNotes returns the notes for an epic or task as newline-separated strings.

func (*Client) GetNotesByAuthor 

func (c *Client) GetNotesByAuthor(issueID string, author string) ([]Note, error)

GetNotesByAuthor returns notes filtered by author.

func (*Client) GetStructuredNotes 

func (c *Client) GetStructuredNotes(issueID string) ([]Note, error)

GetStructuredNotes returns notes as structured Note objects with author metadata. Parses the legacy "notes" string format, detecting [human] prefix for human notes.

func (*Client) GetTask 

func (c *Client) GetTask(taskID string) (*Task, error)

GetTask returns details for a specific task.

func (*Client) HasOpenTasks 

func (c *Client) HasOpenTasks(epicID string) (bool, error)

HasOpenTasks returns true if the epic has any non-closed tasks.

func (*Client) ListAllTasks 

func (c *Client) ListAllTasks() ([]Task, error)

ListAllTasks returns all tasks regardless of parent epic.

func (*Client) ListAwaitingTasks 

func (c *Client) ListAwaitingTasks(epicID string, awaitingTypes ...string) ([]Task, error)

ListAwaitingTasks returns all tasks awaiting human attention under the given epic.

func (*Client) ListReadyEpics 

func (c *Client) ListReadyEpics() ([]Epic, error)

ListReadyEpics returns all open epics (for picker display).

func (*Client) ListTasks 

func (c *Client) ListTasks(epicID string) ([]Task, error)

ListTasks returns all tasks under the given parent epic.

func (*Client) ListTickTasks added in v0.12.0 

func (c *Client) ListTickTasks(epicID string) ([]*tick.Tick, error)

ListTickTasks returns raw tick.Tick pointers for all tasks under the given epic. This is used by wave.Compute which needs the full tick.Tick struct for dependency analysis (BlockedBy, Status, Awaiting, Priority, etc).

func (*Client) NextAwaitingTask 

func (c *Client) NextAwaitingTask(epicID string, awaitingTypes ...string) (*Task, error)

NextAwaitingTask returns the next task awaiting human attention.

func (*Client) NextReadyEpic 

func (c *Client) NextReadyEpic() (*Epic, error)

NextReadyEpic returns the next ready (unblocked) epic.

func (*Client) NextTask 

func (c *Client) NextTask(epicID string) (*Task, error)

NextTask returns the next open, unblocked task for the given epic that is ready for agent work. Returns nil if no tasks are available.

func (*Client) NextTaskWithOptions 

func (c *Client) NextTaskWithOptions(opts ...NextTaskOption) (*Task, error)

NextTaskWithOptions returns the next open, unblocked task ready for agent work. Uses functional options to configure behavior.

func (*Client) ProcessVerdict 

func (c *Client) ProcessVerdict(taskID string) (VerdictResult, error)

ProcessVerdict reads a task, processes its verdict, and saves the result.

func (*Client) Reject 

func (c *Client) Reject(taskID string, feedback string) error

Reject sets verdict=rejected on a task with optional feedback.

func (*Client) ReopenTask 

func (c *Client) ReopenTask(taskID string) error

ReopenTask reopens a closed task.

func (*Client) SetAwaiting 

func (c *Client) SetAwaiting(taskID string, awaiting string, note string) error

SetAwaiting updates the awaiting field of a task.

func (*Client) SetStatus 

func (c *Client) SetStatus(issueID, status string) error

SetStatus updates the status of an issue.

func (*Client) SetVerdict 

func (c *Client) SetVerdict(taskID string, verdict string, feedback string) error

SetVerdict sets the verdict on a task and optionally adds feedback as a note.

type Epic 

type Epic struct {
	ID          string    `json:"id"`
	Title       string    `json:"title"`
	Description string    `json:"description"`
	Notes       string    `json:"notes,omitempty"`
	Status      string    `json:"status"`
	Priority    int       `json:"priority"`
	Type        string    `json:"type"`
	Owner       string    `json:"owner"`
	Children    []string  `json:"children,omitempty"`
	CreatedBy   string    `json:"created_by"`
	CreatedAt   time.Time `json:"created_at"`
	UpdatedAt   time.Time `json:"updated_at"`
	ClosedAt    time.Time `json:"closed_at,omitempty"`
}

Epic represents an epic containing multiple tasks.

func (*Epic) IsClosed 

func (e *Epic) IsClosed() bool

IsClosed returns true if the epic status is "closed".

func (*Epic) IsOpen 

func (e *Epic) IsOpen() bool

IsOpen returns true if the epic status is "open".

type NextTaskOption 

type NextTaskOption func(*NextTaskOptions)

NextTaskOption is a functional option for configuring NextTask.

func OrphanedOnly 

func OrphanedOnly() NextTaskOption

OrphanedOnly filters to tasks whose parent epic is closed.

func StandaloneOnly 

func StandaloneOnly() NextTaskOption

StandaloneOnly filters to tasks without a parent epic.

func WithEpic 

func WithEpic(epicID string) NextTaskOption

WithEpic sets the epic ID to search within.

type NextTaskOptions 

type NextTaskOptions struct {
	// EpicID filters to tasks under a specific epic. Empty means search all tasks.
	EpicID string
	// StandaloneOnly when true, only returns tasks without a parent epic.
	StandaloneOnly bool
	// OrphanedOnly when true, only returns tasks whose parent epic is closed.
	OrphanedOnly bool
}

NextTaskOptions configures the behavior of NextTask.

type Note 

type Note struct {
	Content   string    `json:"content"`
	Author    string    `json:"author,omitempty"` // "agent" (default/empty) or "human"
	CreatedAt time.Time `json:"created_at,omitempty"`
}

Note represents a single note with author metadata. Notes can be from agents (default) or humans.

func (*Note) IsFromAgent 

func (n *Note) IsFromAgent() bool

IsFromAgent returns true if the note was created by an agent. Notes with empty author are considered agent notes (default).

func (*Note) IsFromHuman 

func (n *Note) IsFromHuman() bool

IsFromHuman returns true if the note was created by a human.

type Task 

type Task struct {
	ID          string   `json:"id"`
	Title       string   `json:"title"`
	Description string   `json:"description"`
	Status      string   `json:"status"`
	Priority    int      `json:"priority"`
	Type        string   `json:"type"`
	Owner       string   `json:"owner"`
	BlockedBy   []string `json:"blocked_by,omitempty"`
	Parent      string   `json:"parent,omitempty"`
	Manual      bool     `json:"manual,omitempty"`

	// Requires declares a gate that must be passed before closing.
	// Set at creation time, persists through the tick lifecycle.
	// Valid values: approval, review, content
	Requires *string `json:"requires,omitempty"`

	// Awaiting indicates the tick is waiting for human action.
	// null means agent's turn, any other value means human's turn.
	// Valid values: work, approval, input, review, content, escalation, checkpoint
	Awaiting *string `json:"awaiting,omitempty"`

	// Verdict is the human's response to an awaiting state.
	// Processed immediately when set, then cleared.
	// Valid values: approved, rejected
	Verdict *string `json:"verdict,omitempty"`

	CreatedBy string    `json:"created_by"`
	CreatedAt time.Time `json:"created_at"`
	UpdatedAt time.Time `json:"updated_at"`
	ClosedAt  time.Time `json:"closed_at,omitempty"`
}

Task represents a single task in the Ticks issue tracker.

func (*Task) ClearAwaiting 

func (t *Task) ClearAwaiting()

ClearAwaiting clears both Awaiting and Manual fields. Use this when the task is ready for agent work.

func (*Task) GetAwaitingType 

func (t *Task) GetAwaitingType() string

GetAwaitingType returns the type of human action the task is waiting for. Returns an empty string if the task is not awaiting human action. For backwards compatibility, returns "work" if Manual is true and Awaiting is not set.

func (*Task) IsAwaitingHuman 

func (t *Task) IsAwaitingHuman() bool

IsAwaitingHuman returns true if the task is waiting for human action. A task is awaiting human action when the Awaiting field is non-nil, or when Manual is true (backwards compatibility - Manual is equivalent to awaiting=work).

func (*Task) IsClosed 

func (t *Task) IsClosed() bool

IsClosed returns true if the task status is "closed".

func (*Task) IsOpen 

func (t *Task) IsOpen() bool

IsOpen returns true if the task status is "open".

func (*Task) ProcessVerdict 

func (t *Task) ProcessVerdict() VerdictResult

ProcessVerdict processes the verdict on a task according to the awaiting type. Returns a VerdictResult indicating what changes were made.

Verdict processing matrix:

  • work, approval, review, content: approved=close, rejected=agent continues
  • input, escalation: approved=agent continues, rejected=close
  • checkpoint: never closes, always back to agent

After processing:

  • Awaiting and Verdict are cleared (transient fields)
  • Requires is NOT cleared (persists through cycles)
  • Status is set to "closed" if ShouldClose is true

func (*Task) SetAwaiting 

func (t *Task) SetAwaiting(awaitingType string)

SetAwaiting sets the Awaiting field and clears the Manual field. This ensures new ticks use only the Awaiting field for human action state. Pass an empty string to clear the awaiting state (agent's turn).

type VerdictResult 

type VerdictResult struct {
	// ShouldClose indicates whether the task should be closed.
	ShouldClose bool
	// TransientCleared indicates whether transient fields were cleared.
	TransientCleared bool
}

VerdictResult represents the outcome of processing a verdict.

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.