Skip to main content

Epic lifecycle & health

Epics are the one place in the work plane where a stored status is allowed — because an epic's stage is a decision, not a measurement. The doctrine that governs everything else is unchanged: derive what the world can tell you; store what only a human can tell you. Task rungs, milestone states, progress and evidence remain derived on every read; the epic's stage and its asserted health are speech acts, attributed and logged.

This page said "initiative" until the Work Spaces release. The machine is byte-for-byte the same — it simply runs on its right subject now. The initiative retired to a Space: a key namespace (prefix, title, advisory owner team) where epics are filed. A Space carries no status, no health, and no dates; an epic carries exactly what a Linear Project does, which is what makes the plane's hierarchy line up one-to-one with your PM tool's.

The five-state machine​

An epic moves through a closed machine with six named transitions:

planning ── start ──▶ active ⇄ paused
                        │
                        ├─ complete ─▶ completed ── reopen ─▶ active
                        └─ cancel ──▶ canceled ── restore ─▶ planning
  • Illegal moves teach. An out-of-order transition answers 409 with allowedTransitions — the API tells you the legal next states rather than making you guess.
  • Terminal moves are signatures. Complete, cancel, reopen and restore are human-only — an agent or automation actor gets a typed human_only refusal, enforced in the model and again at the API. The console renders these moves with an explicit confirmation for the same reason.
  • Pausing has teeth. A paused (or canceled) epic closes the dispatch gate for its member tasks; a human can override, attributed.
  • Transitions are idempotent via clientToken: a retried request replays the original answer instead of double-writing.

The console renders the stage pill as the transition control — clicking it shows exactly the legal moves for the current stage.

A state-bearing write against a retired initiative subject answers a typed 422 verdict — subject_retired, carrying the epic route and the Space's candidate epics — so an agent holding an old playbook can correct itself without a human.

Health is the headline of an update​

There is no health dropdown. Health is asserted by posting an update — one honest paragraph plus a headline (on_track / at_risk / off_track), stamped with the author's name. The epic's health IS the latest update's headline; editing history is preserved.

  • Staleness derives at read. An active epic whose latest update is older than the staleness window renders · stale beside the chip — old good news is not fresh bad news, so the color never changes; the age does.
  • No update yet renders honestly — the console says "no update yet" instead of inventing a green dot.

Signals nudge, humans assert​

The derived-health formula still runs — demoted to a signal. When the fold sees trouble (an idle milestone, a drifted approval), it renders a nudge — "the fold suggests at risk — post an update?" — with its named evidence, and pre-fills the update composer. It never overwrites the asserted headline, and it stays quiet while it agrees with a fresh one.

Yours: addressed attention​

GET /work/yours is the personal queue: every reason the plane can derive that something waits on a person — a drifted approval (the signer), an open review (the requested reviewer), an idle milestone (the epic's assignee), a design in review — resolved to a person, a sentence, and the one gesture that clears it. An item that cannot name its person or its action is not emitted: unaddressed attention is noise by definition. When an epic names no assignee, the item re-addresses through its Space's advisory owner team — shown to each member "with your team", cleared for everyone by the first action.

Yours is the only attention renderer in the product — the console's band on the Work home, orun work yours in the CLI, and the work_yours MCP tool all read the same queue, and every chip carries its source badge. The read long-polls (after + waitSeconds) so agents and dashboards can wait for the next decision instead of polling.

Archival is a view concern​

Archiving hides an epic from the default Work home; it is not a status and moves nothing in the machine. Completed and canceled epics shelve themselves after a window; unarchive restores visibility. The console's Archived facet is the shelf, with the one gesture back.