Skip to main content
In PM, an epic is any discrete chunk of work — a feature, a bug fix, a spike, a decision. Every epic lives in exactly one lane, which tells PM (and you) what workflow it follows and where its stories live. The lane also determines what mechanical gates apply: which review steps are required, how stories are tracked, and whether the reconcile gate needs to run before resuming.

​
The five lanes

openspec

Spec-driven work following the proposal → design → tasks → Gate 1 → apply → Gate 2 → archive workflow. Stories live in openspec/changes/<id>/tasks.md checkboxes. Two gate reviews are mechanically required before archiving.

superpowers

Execution-focused work driven by a Superpowers plan (brainstorming, TDD, subagent-driven development). Stories live in the plan file referenced by the epic’s planPath field — PM tracks when and in what order; Superpowers drives how well.

claude-code

Freeform Claude Code work with no external spec tool required. Stories live inline in .conductor/state.json under the epic’s stories[] array. Each story has a title and a done boolean.

decision

Architectural or process decisions. No stories, no task list — just a durable record that the decision was made, what was decided, and when. The epic is the artifact.

external

Work tracked in an external system (Jira ticket, GitHub issue, Linear card). PM records the externalId and externalUrl; the external system owns the stories. PM mirrors status transitions via its tracker integration.
Stories (checkboxes, phases, plan steps) always live in the best available external source — PM never copies them into state.json except for claude-code-lane epics using inline stories[]. Keeping the source of truth in OpenSpec or Superpowers is intentional: it prevents duplication and keeps PM’s state file lean.

​
Epic lifecycle

Every epic moves through a defined set of statuses. The normal progression is linear, but epics can be paused and unpaused by the detour stack.

​
Priority

PM uses four priority levels plus an unset sentinel: Epics can be related to each other via typed links. Links are directional and recorded on both ends. The may-invalidate link is the most important in the system. When the detour is archived and /pm:resume runs, the reconcile gate re-validates the paused proposal against what the detour actually shipped. The verdict is written back durably onto this link as {verdict, amendments, reconciledAt}.

​
Hierarchy

Epics can be nested under a single parent, forming a tree. Use --parent <id> on /pm:epic add (or add-many --from <json> for bulk creation) to nest an epic. When a parent epic has children:
  • PROJECT.md indents children under their parent and shows a rolled-up X/Y children archived count in the briefing.
  • NEXT UP preserves global priority order — grouping is render-only.
  • A parent epic with all children autonomous can be dispatched as an unattended multi-agent batch via plan-hierarchy --parent <id>, where each child runs in its own git worktree and converges back sequentially.
Hierarchy validation is enforced by the engine: a parent must exist, self-loops are rejected, and cycles are rejected. remove-epic is blocked by default if an epic still has children — pass --cascade to remove the parent and all descendants together.