Epics (Stage 0)

An epic is an optional Stage 0 that splits a change too large for a single feature into multiple discrete member features with declared dependencies and contracts. Most features skip it — reach for an epic only when one feature can’t cleanly hold the work.

When to use an epic

Use an epic when a change naturally breaks into several features that depend on one another and need to agree on interfaces. Each member then runs the normal pipeline on its own. See concepts for the glossary terms (epic, charter, contracts, member feature).

Creating an epic

/feature-forge:forge-0-epic <epic-name>

The epic name is kebab-case. The command runs an interview that frames the epic (goal, description), then walks you through:

1. List member features — the discrete features that make up the epic.
2. Charter — a one-paragraph charter per member describing its responsibility. A charter is not a PRD; PRD-level detail belongs in Stage 1.
3. Contracts — structured per member: exposes (what it provides to siblings) and consumes (what it needs from siblings).
4. Dependencies — declare dependsOn relationships between members.

Re-running /feature-forge:forge-0-epic <epic-name> on an existing epic enters EDIT mode, where you can add, remove, or reorder features and change dependencies or contracts.

What it produces

Under specs/<epic>/:

• epic-manifest.json — the source of truth.
• EPIC.md — a human-readable mirror.
• A subdirectory plus a .pipeline-state.json per member feature.

Running members through the pipeline

Each member feature goes through the normal pipeline, starting at:

/feature-forge:forge-1-prd <member>

See Stage 1. When a member’s PRD and tech spec are written, the relevant epic context — its charter, its contracts, and any completed direct dependencies — is injected automatically.

Dependency gate

At Stage 5, if a member has unmet direct dependencies the loop warns you and requires you to explicitly proceed (unless forced). Completing a member can unlock its dependents.

If the epic decomposition looks wrong

While writing a member’s PRD or tech spec you may realize the epic itself is off — a sibling feature is missing, a boundary between features should move, a feature should split, or a dependency edge is wrong. Rather than forcing that into the current feature’s notes, forge records it as an epic change request on the member and routes it by whether it blocks the current feature:

• Blocking — the concern must be settled before this feature continues safely. The stage exit sends you back to /feature-forge:forge-0-epic <epic> to reconcile first.
• Non-blocking — the concern is real but downstream. You finish the current feature; the request waits, and the exit just leaves a reminder.

Re-running /feature-forge:forge-0-epic <epic> (EDIT mode) reads any open requests and offers to apply each — pre-filled for add-feature and dependency changes; boundary moves and splits are guided-manual. Every change still needs your approval. Open requests are surfaced so they don’t get lost: the dashboard flags affected members with ⚠️, and /feature-forge:forge-verify <epic> epic reports them as findings.

Dashboard and verification

• /feature-forge:forge <epic> shows the epic dashboard — the members and their states.
• /feature-forge:forge-verify <epic> verifies the epic: manifest validity, member-state coherence, and contract drift.

autoVerify applies to each member’s per-stage verification (PRD through implementation), so members are auto-verified as they progress just like standalone features. Epic-level verification (forge-verify <epic> epic) is a separate, manual gate — run it after adding or reordering members, or when member contracts change.

Reference

For internals and the CLI, see the maintainer reference pages: epic overview, epic architecture, and epic CLI reference.