Issues

Issues are the unit of work. Every task, bug or improvement lives as an issue with a unique identifier, a status and an assignee, which can be a person or an agent.

What it is

An issue holds everything needed to take a piece of work from start to finish:

• Identifier like DRAPPS-123: not free text: it’s the team key (DRAPPS) plus a number that increments per team. It’s stable and lets you reference the issue from branches, PRs or comments.
• Title and description (markdown).
• Priority and estimate, in story points, not hours (they feed velocity and the burndown). For hours there’s time tracking.
• Workflow status (see Workflow states).
• Assignee, creator and project (every issue lives in a project; see Projects).
• Optional cycle and milestone, for planning.
• Dates: start, target and due (deadline).
• Custom fields defined for the workspace: client, amount, delivery date… See Custom fields.
• Time spent, if you have the time tracking module: timer, entries and total.

Checklist

The description takes task lists: each item is ticked and unticked directly, in reading mode too (no need to enter the editor), and the issue shows the “checked off” progress. It’s the cheap way to break a task down without creating sub-issues.

Videos

In the description and in comments, a line that is only a video link shows the player right below it: YouTube (watch, youtu.be, shorts), Vimeo, and .mp4 or .webm files over https. Type / and pick Insert video…, or paste the link on its own line. Any other link, or one with text on the same line, stays a plain link. What is stored is the URL on its line, so an agent reading the issue over MCP sees the link, not HTML.

Collapsible blocks

To tuck away content not everyone needs (a long log, notes, an analysis), type / and pick Collapsible block, or use the button in the formatting bar. It has a title and a body below it, which can hold lists, code, tables or more collapsible blocks.

• While editing it is always open and you write it like any other text: Enter in the title moves to the body, and Backspace in an empty one removes it.
• While reading it starts folded: it opens and closes when you click its title or its arrow. The state isn’t saved; after a reload it is folded again.
• What is stored is standard markdown: <details><summary>Title</summary> … </details>. An agent reading the task over MCP sees that text, and GitHub folds it the same way.

It works in the description of tasks and projects, in project docs and in comments.

Foldable sections by heading

When you read a description or a document, every heading (#, ##, ###…) has an arrow in front that folds its section: everything below it up to the next heading of the same level or higher. A ## folds up to the next ## or #, with its ### inside.

• It starts fully expanded, and the state isn’t saved.
• While editing there are no arrows and everything shows, including what you left folded.
• It only changes the view: the markdown doesn’t change, so agents and exports see the whole document.
• It doesn’t apply to comments, which are short.

Sub-issues and relations

• Sub-issues: an issue can hang off another (parent/child) to break big work into pieces.
• Blocking relations: an issue can block or be blocked by another, so execution order is explicit.

Labels

Labels classify tasks: “bug”, “client”, “for the demo”… Each one has a name and a color, and a task can carry several.

Creating and managing labels

There’s no separate screen: labels are created and edited from the task itself. In the issue, in the Labels block, + Label opens the picker:

• Check or uncheck the ones you want on the task.
• New label creates one with the name you type and a color (there are eight presets, and any hex color works).
• Hovering a label shows the pencil, to rename it or change its color, and the trash can.

Creating and editing labels is for workspace members, and deleting them is for admins. A guest with write access to a project applies and removes existing labels on its tasks, but can’t create or delete any.

The labels you create belong to the workspace: they work on tasks in all its projects. The ones an import brings in stay in the target team and are only offered on its tasks.

Deleting a label removes it from every task that has it, and it can’t be undone. Automations, SLA rules and saved filters that used it aren’t fixed automatically: check them afterwards.

Adding and removing them

• In the issue: with the picker above. The × on each label removes it.
• In the list: every row has its own picker (a label icon if the task has none yet). You can check several in a row without it closing. Here you apply existing labels; to create a new one, go to the issue.
• On the board: cards show up to two labels and a “+N” with the rest. To change them, open the task.
• With a template: the task starts with the template’s labels.

Anyone who can edit a project’s tasks can add and remove labels on them. A read-only guest sees them but can’t change them. For now you can’t label several tasks at once from the multi-select.

Filtering and grouping

• The Label filter, in the list and on the board, shows tasks that have any of the chosen labels, combined with the other filters.
• Group by label makes one group per label: a task with two labels shows up in both, and tasks with none go under No label. While grouped this way, manual ordering (dragging rows) isn’t available.

In automations and SLA rules

• An automation can have “the task has a label” as a condition, and add or remove a label as an action.
• An SLA rule can apply only to tasks with certain labels.
• Adding or removing a label isn’t an event: on its own it doesn’t trigger automations or outgoing webhooks.

From an agent

Through the MCP, an agent reads, creates, edits and deletes labels, with the same permissions its user has in the app.

• list_labels returns the workspace’s labels: id, name, color and how many visible tasks carry each one.
• save_label creates a label (no id: name required, color optional, in hex) or renames it and changes its color (with id). If one with that name already exists, ignoring case, it isn’t duplicated: you get the existing one back. It requires being a workspace member.
• delete_label deletes it, and only an admin can. Without confirm: true it deletes nothing: it answers with what would be affected (tasks, templates, automations, SLA rules and views that use it). With replaceWith and another label’s id, tasks and templates get that one instead of losing it. Automations, SLA rules and views aren’t changed: the answer says which ones are left pointing at the deleted label.
• save_issue sets them when creating the task, with labelIds. When updating it, use addLabelIds and removeLabelIds, which add and remove without touching the rest; labelIds on an update is ignored.
• An id that doesn’t exist in the workspace is dropped without an error, so take the ids from list_labels.

An API key scoped to a project can’t create or delete labels, since they belong to the whole workspace.

Not to be confused with project labels

Hilbana has another kind of label, project labels, which don’t go on tasks: they group projects in the sidebar. The workspace owner manages them in Settings → Project labels, each project carries at most one, and you assign them by right-clicking the project in the sidebar or from the project page. Deleting one doesn’t delete its projects: they’re just left without a label.

You can also manage them through the MCP:

• list_project_labels returns the project labels: id, name, color, position and how many visible projects carry each one. A guest only sees the ones on their projects.
• save_project_label creates one (no id: name required, color optional, in hex) or renames it and changes its color (with id). If one with that name already exists, ignoring case, it isn’t duplicated: you get the existing one back. Workspace owner only, and within your plan’s cap.
• delete_project_label deletes it, also owner only. Without confirm: true it deletes nothing: it answers with the projects that carry it. With confirm: true it deletes it and those projects are left without a label.
• save_project puts a label on a project with projectLabelId, and null removes it. list_projects returns each project’s label.

An API key scoped to a project can’t create or delete them.

The Free plan allows 3 project labels, and paid plans have no cap (see Billing & plans). Task labels have no cap on any plan.

States and flow

Status isn’t fixed text: it’s a workflow state defined per team, classified by category (backlog, in progress, done, canceled…). The app records transitions with timestamps (when it started, when it completed, when it was canceled) and uses the completion one to close metrics like velocity and cycle time (see Insights).

Agent context

What makes Hilbana’s issues different is that they’re built so an agent can pick them up and execute them without rediscovering context every time:

• Agent context (agentContext): markdown notes with the relevant files, the verify command, the definition of done and any useful pointers. Both the UI and the MCP read and write it.
• Definition of Ready (DoR): two structured, machine-verifiable fields, definition of done (acceptance criteria) and verify command (e.g. pnpm build or the tests), that let the system decide whether an issue is ready for an agent.
• Claim / release: when an agent starts working an issue, it claims it (marked as “in progress by an agent”, with who and since when). It’s a soft lock so two agents don’t collide; when done, it releases it. Not to be confused with the assignee: the claim means “I’m touching this right now”.

Commenting from the list

In the issue list, a task’s comment counter opens its thread in a side panel, without leaving the list or losing your filters: read it, reply, and close the task right there. The panel resizes by dragging its edge (double-click restores the default width) and remembers it.

How to use it

1. Create the issue with a clear title and its description.
2. Fill in its Definition of Ready (definition of done + verify command) if you want an agent to be able to pick it up.
3. Assign it to a person or an agent, and place it in its project (and cycle, if any).
4. Move it through states as it progresses; the app records the transitions.

See also Workflow states, Cycles and Agents.