Epics
Ce contenu n’est pas encore disponible dans votre langue.
What this is
Section titled “What this is”Epics are a grouping layer between project and issue:
company → project → epic → issue → subissuelabels (per-company curated set, M:N with issues — niches live here)PR #73 (2026-05-29) added the DB layer, CRUD routes, similarity search, and the
first operator surfaces. The feat/epics-ux-and-recluster follow-up (2026-05-30)
re-clustered the existing ~2,931 issues into a curated business taxonomy,
created niche labels, and integrated epics directly into the Issues
workflow (board-by-epic default, list group-by-epic, a rich per-epic page, and
an epic chip on issue detail).
The 15-epic business taxonomy
Section titled “The 15-epic business taxonomy”Issues are grouped by what the business does, not by mechanical title
prefixes. The taxonomy (my_setup/scripts/backfill-epics/taxonomy.mjs) is an ordered,
first-match, title-first rule set:
| Layer | Epics |
|---|---|
| Business value streams | Customer Acquisition & Outbound · Social Media & Content · SaaS Product Delivery · Vertical Expansion & Research · Revenue & Finance Ops · Trust, Compliance & Legal |
| Platform & engineering | Infrastructure & DevOps · Website & Domains · Agent Coordination & Scheduling · Platform Milestones & Demos |
| Operations | Operational Issues (~990 watchdog noise) · Quality & Review · Board Actions · Daily Agency Digest · Uncategorized (catch-all) |
The original 25 mechanical clusters were renamed/remapped in place (never
deleted — the issues.epic_id FK is ON DELETE SET NULL). Niches
(niche:renovation / niche:immobilier / niche:expert-comptable) are
labels, applied on top of epics, so a ticket carries a business activity
(epic) and a vertical (label) independently.
Key invariants
Section titled “Key invariants”- Multi-tenant. Every epic query filters by
companyId(catalog EP-1). - Cross-project safety. An issue’s epic must belong to the issue’s project
(
assertEpicMatchesProject); bulk-move enforces the same (EP-2). - One
useEpicsper UI (EP-3); operator admin epic writes requireinstance_admin, agent writes require C-level / exactmanager-*(EP-4/EP-5). - Every issue is grouped. Issue create defaults
epic_idto the company’s “Uncategorized” epic when none is given. - Delete never deletes issues. Deleting an epic reassigns its issues to “Uncategorized” (row-by-row, DB-12-safe) — a cascade option was rejected as a mass-delete footgun.
- Soft enforcement only. The
mandatory-epic-projectpost-issue hook staysenabled: false; agents are nudged via theirepic-rulesAGENTS.md block.
Where to read further
Section titled “Where to read further”This page is the architecture index. The deep-dive owns the detail:
| Concern | Doc |
|---|---|
| Full narrative — schema, creation flow, write authority, dashboards, the recluster taxonomy, niche labels, the Issues-integrated UX, delete behavior, troubleshooting | my_setup/docs/aimetier-explained/epics-and-labels.html |
| Edge-case catalog (EP-1…EP-7) the fleet deep-reviewer checks against | setup/fleet/profiles/aimetier/edge-cases.md (Epics section) |
Key paths
Section titled “Key paths”| Concern | Path |
|---|---|
| DB migrations | packages/db/src/migrations/0135_epics.sql + 0136_epics_constraints.sql |
| Service · routes | server/src/services/epics/{index,similarity}.ts · server/src/routes/epics.ts |
| Uncategorized-on-create | server/src/services/issues.ts (resolveUncategorizedEpic) |
| Recluster + niches | my_setup/scripts/backfill-epics/{taxonomy,niche-labels,index}.mjs |
| Operator UI | ui/src/pages/{Epics,EpicPage}.tsx · ui/src/components/board/{EpicSwimlaneBoard,EpicProgressPanel,EpicBurndown,SprintEpicMatrix}.tsx · ui/src/lib/api/epics.ts |
| Shared constant | UNCATEGORIZED_EPIC_NAME in @aimetier/shared |