Issues

Issues are the work-tracking primitive in ProxifAI. They link to branches, pull requests, sprints, initiatives, and workflows — and they can be assigned to either a human or an AI agent. The schema lives in internal/core/models/models.go (look for type Issue struct).

Anatomy of an issue

assigneeId and assigneeAgentId are independent — an issue can have both a human owner and an agent that’s actively working on it, or just one, or neither.

Status

Six statuses, defined as IssueStatus in models.go:

Status transitions emit issue.status_changed platform events that trigger rules can react to.

Priority

Type

The type field is purely descriptive — it doesn’t change behavior. Use it to filter views and to enable type-specific UI affordances (e.g. story-point columns on storys).

Creating issues

pfai task create \
  --title "Auth: redirect loop on 401" \
  --type bug --priority high \
  --team backend --assignee alice \
  --label "auth,production"

Assigning to an agent

assigneeAgentId makes an issue actionable by a workflow:

pfai task dispatch BACK-42 --agent claude-code --branch main

This sets assigneeAgentId, creates an AgentExecution, and dispatches the agent in per_execution mode against the issue’s repo. The agent inherits the issue’s context (description, comments, linked PRs) via the pfai_<execID> token and reports progress back through pfai exec status / pfai exec log.

When the agent opens a PR with Closes #<number> in its body, the PR gets linked back automatically and merging it transitions the issue to done.

Sub-issues

Set parentId to nest issues under another. The full chain is browsable in the UI as a tree, and the parent’s progress bar reflects sub-issue completion. There’s no enforced depth limit — epic → story → task → subtask is the convention but technically arbitrary.

pfai task create --parent BACK-100 --title "Wire OIDC callback handler"

Activity timeline

Every change to an issue appends an Activity row. Twelve activity types are recorded (models.go):

issue_created · status_changed · priority_changed · assignee_changed
title_changed · description_changed · labels_changed
comment_added · comment_deleted · time_logged
agent_dispatched · workflow_assigned

Comments are a separate concern from activity — they’re stored in Comment and rendered inline with activity entries in the UI. Both support @-mentions; mentioning @<agent-name> triggers the comment_trigger and dispatches that agent.

Custom fields

Per-team CustomFieldDefinition rows let you add fields to every issue in the team. Four storage types are supported, plus a select-style mode:

Each definition has position, isRequired, and defaultValue. Manage with pfai custom-field or the Team Settings → Custom Fields UI.

Filtering and views

The issue list query supports filtering on every column above. The web UI exposes the most common filters as one-click chips; the API accepts the same as URL params:

pfai task ls --status open,in_progress --priority high,urgent --assignee @me
pfai task ls --label bug --updated-after "7 days ago" -o json

Saved combinations live in the View table per team — see Teams & Views for visibility scopes.

Time tracking

Per-issue TimeEntry rows record duration + optional note + author. Totals roll up to sprint and project dashboards. Log time via the issue detail page’s Log time button or:

pfai time log BACK-42 --duration 1h30m --note "Reviewed redirect handler"

Traceability to code

When a linked PR with Closes #42 merges, the issue transitions to done. The transition emits issue.status_changed so other automation can pile on (e.g. ping the customer who reported the bug).

REST endpoints

See also