Backlog Epics, Tasks and Subtasks
- Desktop, mobile and web
- All plans
What it does
Organizes large work on the backlog board, on top of the existing linked tasks. An epic is a container of tickets: no agent works on it. It holds tasks, a task holds subtasks. The board shows how far an epic is, what blocks it and what an agent should do next. A ticket has one parent, and the tree stops at three levels.
Video (1 min 18 s): The Epics view, shown in the real app. Three epics are mixed on a board and an agent starts on one task; a click on Epics gives each epic its row, with its progress, what comes next and its tasks in their columns; a click on a name opens the epic, and Board brings the usual board back.
Where to find it
- New task form, under the title: Epic checkbox and Epic or parent field.
- A card's … menu: Blocked by…, Blocks…, Move to epic…, Parent…, Remove from epic, Convert to epic / Convert to ticket. On an epic: Waits for epic…, Then epic…, Pause / Resume, Convert to ticket.
- Board header, once the board has an epic: the Board / Epics switch.
- Above the tags: the epic filter row, once the board has an epic, with No epic. A chip filters the board; with one epic filtered, Open epic appears next to Clear.
- With one tag filtered: Turn this tag into an epic.
- Open an epic: its name and goal first, then its page: Break down, Start epic, Pause, Waits for / Then, Validation, its tickets.
- Open a task with subtasks: its page, at the top of its detail.
- The eye icon at the end of an epic's "3/5" line, or of a task's Subtasks 3/5 line (also on their page in the detail): Hide its tasks from the board / Hide its subtasks from the board, and Show… to bring them back.
How to use it
- Create an epic, or convert a ticket. An epic has no executor, model, worktree or reviewer.
- File tickets under it: Epic or parent in the form, Move to epic… on a card, New task or Add existing tickets… on the epic. A tag that already plays that role becomes an epic with Turn this tag into an epic: its tickets move in, and one that already has a parent keeps it and is listed.
- Read the board. The epic card shows closed / total, in progress, blocked and the next ready ticket, with no Start or Resume. Subtasks fold under their task as Subtasks 3/5 while they share a column; unfold to read, open or start one. A subtask elsewhere, or a search hit whose parent does not match, is its own card with
↳ #12. Tasks and subtasks carry a chip with their epic. A waiting card reads Blocked by #12 (+N), and a click opens the blocker. - Or read it by epic: the Epics view lists every epic with the state its card shows. Its first epic is unfolded, the chevron folds or unfolds the others: the tickets show in the columns where they stand, under the board's names and colours. A click on an epic's name, or Open epic, opens its page; a click on a ticket opens that ticket. Start next on a row stays inside that epic. Closed epics are grouped at the bottom, and the last line leads back to the board on the tickets outside any epic. It reads the board: to move a ticket, use the board or the ticket's detail. Epic cards stay in the board's columns.
- Set dependencies from the card menu. Invalid targets stay listed, greyed with the reason. Removing a dependency stays in Linked tasks.
- Run it: Start next (with one epic filtered it reads Start next in <epic>), or the epic page's Start next and Start epic.
- Close it. When all its tickets are closed, the card offers Close the epic. Nothing closes on its own, and closing an epic with open tickets, or with a validation that did not pass, asks first and closes nothing else.
Break down (epic page): starts an agent of the project that reads the code and proposes tasks, subtasks, dependencies and acceptance items as a draft on the epic page. Edit titles, remove, reorder, tick what waits on what, then Approve creates everything in one go; Discard leaves nothing. It uses your agent quota.
Start epic (epic page): two modes, both with Up to this many at once and One worktree per ticket when more than one runs.
- Start a few tickets, once: starts its first ready tickets now and says why the others do not start. Nothing restarts when they close.
- Run it to the end, then stop: one machine keeps starting its ready tickets as others close, closes a task once all its subtasks are, runs its validation, then stops. No other epic starts. Now or Later (a day and a time), on the machine you name. The epic page and card show Running with Stop, or Scheduled with Cancel. A note on the epic keeps the log of the run, and the project's assistant hears about a ticket that cannot start, a stall and the end: it gives you the summary. A ticket of a run is told to close itself once done, because the next one waits for that.
Pause (epic page, card menu): the epic moves to Pending and its tickets no longer leave: Start next, triggers and runs skip them, and they read Epic paused. Nothing is moved and agents at work finish their ticket. You can still start a ticket by hand. Resume brings it back.
Order of the epics (epic page, Waits for / Then, or the card menu): an epic that waits for another sits in Pending, its tickets read Epic waiting for #12, and it comes back by itself once that epic is closed. Nothing starts by itself at that moment: launch it when you want.
Validation (epic page): turn on Tests, Security or Your own check. Once its tickets are closed, each one becomes a ticket of the epic with its own agent (QA and Security for the first two). A run starts them by itself; otherwise Run the validation does. A defect found becomes a new ticket, and the check runs again after the fix: three rounds on its own, then it asks for someone. When it reads Validated, a person closes the epic, and that is what releases the next one.
Acceptance checklist (ticket detail, under the title): add, tick, reorder. The card shows 2/5. Closing a ticket with items open asks first.
Settings
backlogHiddenChildren(global, account-synced, phone included, no Settings row: the eye icon of an epic or a task with subtasks; default[], every child shown; alsosettings_set): ticket ids of the parents whose tickets are hidden from the board. The parent card stays with its progress; an epic hides its tasks and their subtasks; a search still shows what it finds, and a child stays a card when its parent is filtered out of the board.backlogBoardView(global, account-synced, phone included, no Settings row: the Board / Epics switch of the board header; defaultboard, orepics; alsosettings_set): how a board reads. A board without an epic always shows its columns.backlogEpicParallel(global, account-synced, no Settings row: the Up to this many at once field of the Start epic dialog; default 2, from 1 to 5; alsosettings_set): how many ready tickets of an epic start at once.- Per epic, on the row and on the account (no Settings row): the plan of its last run (limit, worktrees) and the steps of its validation, both on the epic page, also set by
backlog_epic_run.
Agent tools (MCP)
backlog_create({ parentId, isEpic }),backlog_update({ parentId, isEpic })(""detaches). A refused parent creates nothing.backlog_list({ parentId }): direct children. Each row carriesparentId,isEpic,children: { closed, total }.backlog_getreportshierarchy.backlog_start_next({ epicId }): stays inside the epic. Only a ready ticket starts: in TODO, not an epic, no children, no open blocker, not locked, its epic not on hold. Extra reasons:only_containers_left,epic_has_no_ready_child,epic_on_hold,all_todo_tasks_on_hold,epic_not_found.backlog_epic_run({ epicId, action }):start(withparallel,worktrees,deviceId),pause,resume,stop,validation(withsteps). To run it later,backlog_update({ schedule })on the epic.backlog_linkjoins two epics withblocked_by, andbacklog_getreportshierarchy.hold,runningandvalidation.backlog_propose_breakdown({ epicId, items }): a draft the user approves; no ticket exists before that.backlog_checklist({ taskId, add, check, uncheck }):status: "done"andbacklog_submit_for_reviewrefuse with items open, unlessacknowledgeOpenChecklist: true.- An agent started on a child receives the epic's goal and its siblings' status, one line each.
Providers
All providers. The brief block and the tools are the same for every CLI; a break-down runs on the project's executor.
Mobile
Shows the epic card, its chip, ↳ #12, subtasks folded as 3/5, Blocked by #12 and the children in the ticket detail. Creates an epic or a ticket under a parent, and Add tasks on an empty epic files the new ticket under it. A line of chips under the search filters the board by epic or No epic (swipe it), and with one epic picked Start next stays inside it. In the detail of an epic: Pause / Resume, Start epic (the run to the end, now or later, on the machine you name), Stop, Tests and Security. The phone only writes it: a desktop does the work. Editing links and the order of the epics (read-only on the phone), Start a few tickets, once, Your own check, reviewing a break-down and editing a checklist are on the desktop. The Board / Epics switch sits under the search: same view, its tickets grouped by column one under the other, and with one epic filtered Open epic sits next to the chips. The eye icon at the end of an epic's "3/5" line or a task's Subtasks 3/5 line hides or shows its tickets on the board, the same choice as on the desktop.
Limits
- One parent per ticket, three levels. A dependency links two tickets or two epics, never one of each, and never a ticket and its own parent.
- A run needs its machine on: it does not wake it up, and tickets wait if it sleeps. With Nothing starts by itself at launch, a run found on when the app starts stops and says so.
- A run moves on when a ticket closes. An agent that stops without closing its own gets a question from the project's assistant after ten minutes.
- Stop, Pause and the end of a run never stop an agent at work: Pause the project does.
- 60 items per break-down draft; 50 checklist items per ticket, 500 characters each; 5 tickets at once for Start epic.
- The all-projects view marks epics but does not fold subtasks. There are no sprints, story points or Gantt charts.
- Moving an epic to another board leaves its tickets here, detached; the dialog says how many.
Common questions
- Can I hide an epic's tasks from the board? Yes, on the desktop and the phone. Click the eye icon at the end of the epic's "3/5" line: its tasks (and their subtasks) leave every column and the epic card stays with its progress. Click it again to show them. Same on a task with subtasks, at the end of its Subtasks 3/5 line. The choice is kept per parent on your account, on every computer and on the phone. A search still finds the hidden tickets, and column counts still include them.
- Is there a video that shows it? Yes, a demo of the Epics view in the real app: the switch next to Board, one row per epic with its progress and its next task, the tasks by column, then an epic opened by its name: https://youtu.be/S2uJ8Ijafqs
- How do I see how far each epic is? Open the Backlog, then click Epics next to Board, in the header above the search field (the switch only shows once the board has an epic). Each epic has its row with its progress ("2/6", "1 in progress") and Next:, and the chevron unfolds its tasks in the columns where they stand. Video: https://youtu.be/S2uJ8Ijafqs
- Why does clicking an epic at the top of the board not open it? Those chips filter the board. With one epic filtered, Open epic appears next to Clear. In the Epics view, and on an epic's card or chip on a ticket, a click on its name opens it.
- How do I see all my epics at once, and where their tickets are? Switch the board to Epics in its header. Each epic unfolds into its tickets, column by column. The switch only shows once the board has an epic, and your choice is kept on your account.
- Can I take epics out of the columns? No. An epic stays a card of the board, where its column says if it is paused or closed. The Epics view is the way to read them apart.
- How do I group tickets into an epic? Create an epic, then Move to epic… on each ticket or Add existing tickets… on the epic. If a tag already plays that role, filter on it and click Turn this tag into an epic.
- Why can't I start an epic? It is a container: no agent works on it. Start its tasks, Start next on its page, or Start epic to launch several or run it to its end.
- Can I run just one epic tonight? Yes: Start epic, Run it to the end, then stop, Later. It stops at the end of that epic. Keep the machine on.
- Can an epic wait for another one? Yes: Waits for on its page. Its tickets do not start until the other is closed, and a loop is refused.
- Who closes an epic after its validation? A person, or the assistant if you ask it. It never closes on its own: closing it is what releases the next one.
- Why is my ticket not picked up? If it reads Epic paused or Epic waiting for #12, its epic holds it: resume the epic, or close the one it waits for. You can still start it by hand.
- Why can't I pick an agent on my epic? Nothing runs on an epic, so it has no Execution zone. Each ticket under it has its own agent: open the ticket to choose it. Start epic then uses the agent of each ticket.
- Why does Start next skip a ticket? It only hands out a ready ticket: in TODO, not an epic, without subtasks, no open blocker, not locked against agents, its epic not paused or waiting. On a team board, not in a teammate's charge.
- Why is there no card for this ticket? A subtask folds under its task while they share a column: open Subtasks 3/5 on the task. It becomes a card as soon as it moves to another column.
- Why was my link refused? One parent per ticket, three levels, no loop, no dependency between an epic and a ticket, no dependency between a ticket and its own parent. The message says which, and names the loop.
- Does closing an epic close its tickets? No. It asks first if some are open, and leaves them as they are.
- Do my existing parent links change? They are kept, and now fold as a task and its subtasks. Nothing else moves until you create an epic.