Developer

Epic Template & Definition of Done

Every Linear issue with the Epic type uses the description template and Definition of Done checklist on this page. The template keeps epics scoped, verifiable, and linked to their Codex reference; the DoD keeps completion criteria uniform so “Done” means the same thing across the project.

When to use

Apply this template when:

Creating a new Epic in Linear (paste the structure below into the description, fill in sections)
Refining an existing Epic that pre-dates the template (the “Apply template to all epics” task does this mechanically for the 0.3.0 epic set)
Reviewing an epic before moving it from Backlog to Todo — if sections are missing or the DoD is customized, fix it before work starts

Epics are the unit of work that ships a user-visible capability end-to-end. Smaller issues (Task, Feature, Improvement, Bug, Spike, Documentation) use their own templates and are typically children of an Epic.

Epic description template

Paste this block into a new Epic’s description and replace the angle-bracket placeholders. All sections are required; do not delete headings even if a section is empty (write “None” instead).

## Summary

<One paragraph. What capability does this epic ship and for whom. Avoid implementation detail —
that belongs in the Codex reference.>

## Codex reference

<Link to the authoritative Codex page(s) that specify this capability. If the Codex doesn't yet
cover it, this epic must include a Documentation child issue that lands the page before or
alongside the code.>

## In scope

- <Bullet list of what this epic delivers>
- <Be specific — "X works end-to-end from UI through API to database" beats "X is implemented">

## Out of scope

- <Bullets calling out work that a reader might reasonably assume is included but isn't>
- <List the follow-on epic or issue ID for each deferred item — no loose "later" promises>

## Acceptance Criteria

1. <Numbered list. Each AC is independently verifiable and phrased as an observable outcome.>
2. <At least one AC must be an integration test exercising the path between contexts this epic
   touches (non-negotiable — isolated unit tests do not satisfy this requirement).>
3. <Continue numbering…>

## Definition of Done

<Paste the DoD block from the next section verbatim. Do not customize per-epic — if an item
doesn't apply (e.g. no TS changes), leave it checked-off-as-N/A in the PR description rather than
deleting it from the AC list.>

## Depends on

- SPEC-XXX — <short reason this epic can't start until that one lands>
- <Or "None" if this epic has no blockers>

## Blocks

- SPEC-YYY — <short reason the downstream epic needs this one>
- <Or "None" if nothing depends on this epic>

Definition of Done

This block is verbatim for every epic. Copy it into the Epic description under the “Definition of Done” heading without modification. Uniformity is the point — if an item doesn’t apply to a particular epic, mark it N/A in the PR, don’t remove the line.

- [ ] ruff check passes (zero errors, zero warnings)
- [ ] ruff format check passes
- [ ] ty check passes (zero diagnostics; strict-max: `rules.all = "error"`)
- [ ] biome check passes (for epics touching TS)
- [ ] tsc --noEmit passes (for epics touching TS)
- [ ] Architecture validator passes with zero violations
- [ ] Unit tests pass; coverage meets layer threshold (domain ≥90%, application ≥80%, infra ≥60%)
- [ ] Integration test exercises the path between contexts (non-negotiable)
- [ ] Codex updated to reflect implemented behavior
- [ ] Migration tested via full DB reset
- [ ] For epics adding APIs: API/UI parity verified (every UI action reachable via API)

Why each item is in the DoD

ruff check / format — Lint and format pass for every epic. Zero tolerance for warnings, including pre-existing ones in files you touched.
ty check — Strict typing (rules.all = "error") is the project baseline; epics do not relax it. Per ADR-051, ty is the primary checker and ruff ANN enforces missing-annotation hygiene; mypy is informational-transitional.
biome / tsc — Frontend epics must clear the TS toolchain; mark N/A only if the epic touches no TS files.
Architecture validator — Layer boundaries (tools/quality/validate_architecture.py) are enforced in CI. Violations block merge.
Coverage thresholds — Per-layer targets are a floor, not a ceiling. Domain logic is pure and cheap to test; infrastructure is harder and the threshold reflects that.
Integration test — The non-negotiable. An epic that ships only unit tests has not demonstrated the capability works end-to-end. The integration test must exercise the path between contexts the epic introduces or modifies.
Codex updated — Codex is the authoritative specification. Code changes without a Codex update leave the spec stale; this item catches that.
Migration tested via full DB reset — Running bash tools/db/db.sh reset must produce a working database. If the migration relies on existing data, call it out explicitly — but by default, pre-deployment the project assumes a resettable database.
API/UI parity — For epics adding APIs: every UI action must be reachable via the API (Spectral is API-first; UI is one consumer).

Using the template in Linear

The Linear team-level Epic template (Team settings → Templates) prefills the structure above plus the Epic label. When you create a new issue and select the Epic template, the description arrives pre-populated; fill in the placeholders and wire up Depends on / Blocks relations via the Linear relation UI (not just as text in the description — text is for human readers, relations drive the dependency graph).

If you notice the Linear template drifting from this page, re-sync from this page rather than editing Linear and back-porting. This Codex page is the source of truth.

Your First Feature — vertical-slice walkthrough an Epic typically follows
Testing — layer-by-layer test strategy the coverage thresholds map to
Architecture — the layer boundaries the architecture validator enforces

Previous
CI Secrets Next
Testing