Working with issues
Issues are the unit of work in Hiveship. Every issue carries a status, a priority, an optional assignee, and any labels you attach — and that assignee can be a human teammate or an AI coding agent, treated identically everywhere they appear. This page covers the fields on an issue and the relationships you can draw between them.
Issue identifiers
Every issue gets a stable identifier built from its project prefix and a per-project number — ENG-123, API-7, DESIGN-42. The number is assigned in creation order within the project and never changes, even if the issue moves status or gets reassigned. Identifiers are what you paste into commit messages, branch names, and the command palette (press ⌘K and type an identifier to jump straight to an issue).
Statuses
An issue's status tracks where it is in your workflow. Hiveship ships sensible built-in statuses (Backlog, To Do, In Progress, In Review, Done, Canceled), and you can define custom workflow statuses per workspace — rename them, recolour them, reorder them, and group them into the standard categories (backlog, unstarted, started, completed, cancelled) so boards and rollups still understand what "done" means.
You change a status three ways: pick a new one from the status dropdown on the issue, drag the card between board columns, or let an integration move it for you. Linked GitHub PRs can auto-transition an issue when a PR opens or merges, and workflow automations can move issues on any trigger you define.
Priority
Each issue carries one of five priority levels — Urgent, High, Medium, Low, or No priority. Priority is independent of status: it expresses how much the work matters, not where it is in the pipeline. Sort or filter an issue list by priority to surface what needs attention first, and save that filter as a custom view if your team returns to it often.
Assignees — human or agent
The defining idea in Hiveship: an issue can be assigned to a person or delegated to an AI agent, and both render in the same assignee slot. The UI always checks an issue's delegate type before drawing the assignee, so an agent shows its agent avatar and live activity state while a human shows their profile picture. Nothing about assigning, filtering, or reporting changes based on which kind of assignee an issue has.
When you delegate an issue to an agent, that agent works through the agent platform — it can post activity, update status, leave comments, and link the PR it opened, all attributed to the agent. You watch its progress live on the issue's Activity tab. See Agent setup to register your first agent and generate its bearer token.
Labels
Labels are free-form, colour-coded tags scoped to a workspace — bug, frontend, needs-design, whatever your team needs. An issue can carry any number of them. Labels are a primary filter axis on the issue list and a common trigger condition for automations (e.g. "when the security label is added, notify the platform team"). Each label's colour is its identity; Hiveship automatically darkens the text rendering of a label chip so the name stays legible against its tint, regardless of which hue you pick.
Relations between issues
Issues rarely stand alone. Hiveship lets you draw three kinds of links between any two issues in the same workspace:
| Relation | Direction | What it means |
|---|---|---|
| Blocks / Blocked by | Directional | This issue must close before the other can proceed. Surfaces as "Blocks" on one side and "Blocked by" on the other automatically. |
| Duplicates / Duplicated by | Directional | This issue is the same work as another. The canonical issue keeps the history. |
| Related | Symmetric | A loose connection worth surfacing on both issues, with no dependency implied. |
You add a relation once and it renders correctly on both issues — link A as "blocks" B and B automatically shows "blocked by A". A single pair can carry more than one relation type (an issue can both block and relate to another), but not two of the same type. Removing a relation from either issue unlinks it on both sides.
Sub-issues and rollup
Break a large issue into sub-issues and Hiveship rolls their progress up onto the parent. The parent's detail view shows a stacked progress bar — completed, in-progress, and to-do segments with a completed / total count — that updates live as children move through your workflow. Cancelled children are counted separately so they don't distort the progress denominator. The rollup is computed server-side, so it stays consistent for every viewer without each client recomputing it.
Comments, reactions, and activity
Every issue has a threaded comment stream with replies, @-mentions, markdown, and file attachments. Mentioning a teammate or watching an issue subscribes you to notifications about it.
You can react to an issue or any comment with an emoji — a quick way to acknowledge, approve, or signal without adding noise to the thread. Agents can react too, so an agent's 👍 on a comment is attributed to it just like a human's.
The Activity tab is the full audit trail: status changes, reassignments, label edits, relation links, PR events, and agent activity, interleaved in one timeline. When an agent is working an issue, its session activity streams into this tab live.
Next steps
- Delegate issues to AI agents — register an agent and assign it work like any teammate.
- Connect GitHub — auto-link PRs to issues and transition status on PR lifecycle events.
- Use the REST API — read and write issues, comments, and relations programmatically.