Epics
The Epics page of a project: each body of work with its reference, goal, value, measures, owner, MoSCoW priority, status, dates and colour, its lifecycle and its versions.
By the end of this page you will have written down a project's epics, know every field an epic carries and what reads it downstream, and know how an epic moves from a draft to done, how it is deleted, and where every version of it is kept.
An epic is a body of work the client recognises: "loyalty tiers", "checkout redesign", "the
supplier portal". It is the scope a release is cut from and the parent of every story, so it is
written before the stories are, in the client's words, with the goal, the value and the measures
that say when it is done. An epic takes the next number of the project's shared tracker sequence,
so its reference (CRM-12) sits in the same series as the stories that will hang under it, and
every save of it is kept as a version.
Before you begin
| You want to | You need |
|---|---|
| Open the Epics page | epic:view-any on the project, which every default role carries. A client guest sees the agreed epics only. |
| Add an epic | epic:create. Project managers and business analysts have it by default. |
| Edit, move an epic | epic:update. |
| Delete an epic | epic:delete. |
| Name an owner | The person to be a member of the team. |
The page lives under a project: open the project and choose Epics in the sidebar, badged with how many epics you may see.
Read the epics
The table lists one epic per row:
| Column | What it shows |
|---|---|
| Reference | The epic's key, painted in the epic's colour. |
| Epic | The title, with the goal beneath it. Press the title to open the detail flyout. |
| Status | Draft, in review, approved, in progress, done or cancelled, as a badge. Hidden from a guest. |
| Priority | The MoSCoW letter: M, S, C or W. |
| Owner | The person who answers for the epic, or Unassigned. |
| Due | The date agreed, when there is one. |
| Updated | How long ago the record last changed. |
| Row menu | View Epic, Edit Epic, Move to, Activity, Delete Epic. |
Sort by reference, title, status, priority, due date or updated by pressing a column heading; press it again to flip the direction. The list opens in the project's own order.
Above the table, narrow the list with the search box (words in the reference, the title or the goal), the status list and the priority list. The filters travel in the page address, so a filtered list can be shared; Clear Filters on the empty state drops them all.
Add an epic
- Press New Epic.
- Type the Title and the Goal: what the epic is called and, in one sentence, what it achieves. These two are enough; the rest can follow, and Heimdall will draft them from the brief once the brief import lands.
- Write the Summary, the scope in prose, and under Why it matters the Business Value, the Hypothesis the epic bets on and the Success Metrics that will test it.
- Pick the Owner and the Priority, set the Starts and Due dates if they are agreed, and a Colour if you want the epic to stand out on the board and the roadmap.
- Press Create Epic.
The epic takes the next number of the project (the first epic of CRM is CRM-1), starts as a
draft, appears in the table at once, writes its first version, and epic.created goes out to
every endpoint subscribed to it.
One sequence for the tracker
Epics, stories, tasks and bugs share one number series per project, so
CRM-12 is always one thing and a reference in a commit or a conversation
never needs a type. A number is never reused, even after a delete.
Open an epic
Press an epic's title, or View Epic in its row menu, to open the detail flyout: the reference, status and priority at the top, then the summary, the value, the hypothesis and the measures, the owner, the dates, and the Versions section with every save of the epic. From the flyout:
- Edit opens the editor on this epic.
- Move to changes the status in one step, offering only the moves the lifecycle allows.
- Restore this version under any earlier version puts it back; see revisions and versions.
- Activity opens the epic's history: every change, who made it and where it came from.
- Delete opens the confirmation.
A link such as /projects/<id>/epics?show=<epic id> opens the page with that epic's flyout
already open; Heimdall's View buttons use it.
Edit an epic
- Press Edit Epic in the row menu, or Edit in the flyout.
- Change what you need. The owner must be a member of the team and the due date on or after the start.
- Press Save Changes.
The save writes a new version of the epic and epic.updated goes out with the columns that
changed, each with its old and new value. An edit that changes nothing writes nothing and announces
nothing. The status does not change from the editor; it moves from the list or the flyout.
Move an epic along its lifecycle
An epic reaches In review and Approved through its approval alone: Submit for review on the approval bar puts it in review, and the approvers' verdicts move it out, to approved when the request carries and back to where it stood when it is rejected or withdrawn. Move to in the row menu or the flyout offers the other moves the lifecycle allows from where the epic stands, and is refused while a request is open:
| From | To |
|---|---|
| Draft | Cancelled |
| In review | Draft, cancelled |
| Approved | In progress, cancelled |
| In progress | Done, cancelled |
| Done | In progress |
| Cancelled | Draft |
An approval stamps when the epic was agreed and at which version, and a client guest sees the epic
from that moment on, through in progress and done, and loses it when it is cancelled. Every move
writes a version with the reason moved and epic.status_changed goes out with the status before
and after; an approval writes one with the reason approval.
Delete an epic
Delete Epic in the row menu or Delete in the flyout opens the confirmation. Deleting
removes the epic with every version it kept and its activity history; the work items under it stay
in the backlog and lose their epic, and its number is never handed out again.
epic.deleted goes out. Prefer Cancelled for an epic the client dropped: it keeps
the record and the reasoning.
All the fields
What happens next
- Every save, move and restore writes a version and an entry in the project's activity history.
epic.created,epic.updated,epic.status_changed,epic.restoredandepic.deletedgo out to the webhook endpoints subscribed to theepic.*family.- Stories, tasks, bugs and spikes hang under epics on the Backlog page, which groups and filters by epic; releases will be composed from them and the roadmap will place them by their dates, as those modules land.
Heimdall on this page
Heimdall reads epics and their versions through the same tools the MCP server offers and carries the open project as its context.
On the editor, Ask Heimdall beside each long field drafts it, improves it, shortens it, makes it testable or rewrites it as Given, When, Then; the draft waits under the field until you take it or drop it. See inline assists.
Writing epics stays with people for now; the brief import will draft them into a review queue, and Heimdall will propose improvements to the ones that lack a goal, a measure or an owner.
From the API and MCP
Epics API
List, read, add, change, move and delete epics, and read and restore their versions.
list_epics and get_epic
The MCP tools that read a project's epics as the token sees them.
Permissions
| Action | Permission |
|---|---|
| See the epics | epic:view-any, epic:view; a client guest sees the agreed epics only |
| Add an epic | epic:create |
| Edit or move an epic | epic:update |
| Delete an epic | epic:delete |
| Read or restore its versions | epic:view to read, epic:update to restore; never a client guest |
Frequently asked
Related
- Traceability — the Links panel in the flyout: what this implements, verifies, depends on or relates to, read from either side
- Comments and mentions — the Discussion panel in the flyout: questions, answers, mentions, followers
- Attachments — the Files panel in the flyout: wireframes, specifications and samples pinned on the record
- Backlog — the stories, tasks, bugs and spikes under the epics
- Revisions and versions — every save kept, any version put back
- The planning record — what hangs off epics as the modules land
- Status reference — every epic status, priority and revision reason
epic.*webhook events
How is this guide?
Last updated on
Planning
The pages where a project's scope is written down: epics, the backlog of stories, tasks, bugs and spikes with their acceptance criteria, the functional and non-functional requirements, the business rules, the use cases with their flows, the RAID log, the decisions, the links between them, the comments and the files on each, every save kept as a restorable version, and the approvals that turn a draft into an agreed version; the rest as it lands.
Backlog
The Backlog page of a project: every story, task, sub-task, bug, spike and improvement with its reference, kind, status, priority, people, estimates and the fields its kind adds, its lifecycle, its hand-over and its versions.