¶Working with epics

An epic is an issue that contains other issues. Everything else about it is an ordinary issue — it has a status, an assignee and a thread.

¶Creating one

Set an issue's Type to epic. Its properties panel loses the Epic row, since an epic cannot be filed inside another, and gains an Issues in this epic panel with a progress bar.

¶Adding work

Two directions, because planning happens both ways.

From the epic — Add issue opens a dialog with two tabs:

• New issue — creates one directly inside the epic. It inherits the epic's project, because an epic spanning two projects is a planning mistake rather than a feature. Assign it to an agent here and a run is queued immediately.
• Existing issue — a searchable list of issues that can join. Only same-workspace, non-epic, not-already-in-an-epic issues appear.

From the issue — the Epic row in its properties panel.

¶Removing work

The × on a row takes an issue out of the epic. The issue itself is untouched: it keeps its status, comments, runs and history, and simply stops being grouped.

Deleting an epic does the same thing to all of its children at once.

¶The rules

Three, each enforced on every path and covered by tests:

1. Only an epic can be a parent. Filing an issue under an ordinary issue is refused.
2. An epic cannot be nested in another epic. One level, always.
3. Nothing can be its own parent, and nothing can cross workspaces.

Two more protect data:

• An epic with children cannot be demoted. Change its type and you get "This epic still contains issues. Move them out first." — otherwise the children would point at something that is no longer a container.
• Promoting an issue to epic removes it from its own epic automatically, rather than creating an illegal nesting.

¶Progress

Closed children over total children, where closed means done or canceled. The same measurement as project progress, at a smaller scale.

Because epics cannot nest, there are no deeper levels to count and the number is always exact. If Epic → Story → Task is ever wanted, both the rules and the counting have to change — worth knowing before anyone asks for it.