Epic and milestone implementation

Purpose: Standard for managing multi-milestone features that span V1 → V1.1 → V2. Defines how to organize specs, track epics in Linear, and promote out-of-scope items across milestones.

Quick reference:

• Epic — Linear Project grouping issues across milestones (V1, V1.1, V2)
• Specs — Live in docs/specs/{epic-slug}/ with overview.md + milestone-prefixed artifacts (v1-brief.md)
• Tech specs — For milestone-aware features must include "Future Milestone Impact" section
• After V1 ships — Triage deferred items → promote to V1.1/V2 or kill
• Each milestone — Runs the full SDLC pipeline independently

Overview

Real features often span multiple milestones. The initial release (V1) ships core functionality, then subsequent milestones (V1.1, V2) add refinements, extensions, or deferred scope. This standard defines how to organize specs, track epics, and promote out-of-scope items across milestones.

When to use

Use the epic/milestone pattern when:

1. Feature has natural milestones — V1 is a working MVP, V1.1 adds polish, V2 adds extensions
2. Scope was explicitly split — During planning, items were deferred to "future work"
3. Out-of-scope items accumulated — Multiple out-of-scope items suggest a follow-up milestone
4. Feature is complex — Estimated at >2 weeks of work; break into shippable increments

Do NOT use for:

• Simple bug fixes — Single issue, single fix
• Small features — Ship complete in one milestone
• Unrelated issues — Happen to touch the same code

Linear Projects as epic containers

Use Linear Projects to group related issues across milestones. No custom entity needed.

Setup

1. Create a Linear Project — Name it after the feature (e.g., "Notification Center")

   • Description: Link to docs/specs/{epic-slug}/overview.md

2. Add all issues to the Project — V1, V1.1, V2 issues all in the same Project

   • Use issue labels or milestones to distinguish: milestone:v1, milestone:v1.1, milestone:v2

3. Track progress via Project view — Linear shows completion percentage, open issues, blockers

   • Use Project updates for stakeholder communication

Example

Project: Notification Center
├── PROJ-42 [milestone:v1] Core notification display
├── PROJ-43 [milestone:v1] Push notification integration
├── PROJ-44 [milestone:v1] Notification preferences page
├── PROJ-50 [milestone:v1.1] Notification history
├── PROJ-51 [milestone:v1.1] Custom notification sounds
└── PROJ-60 [milestone:v2] Notification grouping

Milestone-aware spec file convention

Directory structure

Multi-milestone features use a directory instead of a single file:

docs/specs/{epic-slug}/
  overview.md          # Multi-milestone roadmap (always present)
  v1-brief.md          # V1 brief
  v1-prototype.md      # V1 prototype (if UI work)
  v1-tech.md           # V1 tech spec
  v1.1-brief.md        # V1.1 brief (when V1.1 starts)
  v1.1-tech.md         # V1.1 tech spec
  v2-brief.md          # V2 brief (when V2 starts)
  ...

The overview.md file

Every epic directory MUST have an overview.md that provides the multi-milestone roadmap:

# Epic: {Feature Name}

**Linear Project:** {project-link}
**Created:** {date}
**Status:** V1 In Process / V1 Shipped / V1.1 In Process / etc.

## Vision

[2-3 sentences describing the complete feature when all milestones are done]

## Milestone Roadmap

### V1 — {Theme} (Target: {date or sprint})
- [Goal 1]
- [Goal 2]
- [Goal 3]

**Issues:** PROJ-42, PROJ-43, PROJ-44

### V1.1 — {Theme} (Target: {date or sprint})
- [Goal 1]
- [Goal 2]

**Issues:** PROJ-50, PROJ-51

### V2 — {Theme} (Target: TBD)
- [Goal 1]
- [Goal 2]

**Issues:** Not yet created

## Deferred Items

Items explicitly deferred during planning that haven't been assigned to a milestone yet:

- [ ] {Item 1} — Reason for deferral
- [ ] {Item 2} — Reason for deferral

## Milestone History

| Milestone | Status | Shipped | Notes |
|-----------|--------|---------|-------|
| V1    | Complete | 2026-02-20 | Core functionality |
| V1.1  | In Process | — | Polish and history |
| V2    | Not Started | — | — |

Milestone spec files

Each milestone runs through the full SDLC pipeline and produces its own set of spec files:

• v1-brief.md — Same format as single-milestone brief
• v1-prototype.md — Same format as single-milestone prototype
• v1-tech.md — Same format as single-milestone tech spec, PLUS Future Milestone Impact section

The milestone prefix (v1-, v1.1-, v2-) distinguishes artifacts across milestones.

Single-milestone vs multi-milestone comparison

Aspect	Single-Milestone	Multi-Milestone
Location	docs/specs/{issue-id}-brief.md	docs/specs/{epic-slug}/v1-brief.md
Overview	Not needed	Required (overview.md)
Linear grouping	Single issue	Project with multiple issues
Out-of-scope	Captured, may become separate issues	Promoted to future milestones

Out-of-scope promotion process

When V1 ships (or during V1 planning), deferred items need a home. This is a manual process.

During planning (V1)

1. Capture out-of-scope items — The plan agent returns outOfScopeItems in the brief package
2. Add to overview.md — Document each item in the "Deferred Items" section
3. Don't create issues yet — Wait until V1 ships to assess priority

After V1 ships

1. Review deferred items — Open docs/specs/{epic-slug}/overview.md
2. Triage each item:
   • Promote to V1.1 — Create Linear issue, add to Project, label milestone:v1.1
   • Promote to V2 — Create Linear issue, add to Project, label milestone:v2
   • Kill — Remove from overview.md (it's not worth doing)
   • Keep deferred — Leave in Deferred Items section
3. Update overview.md — Move promoted items from "Deferred Items" to the appropriate milestone section
4. Start V1.1 pipeline — Run full SDLC for V1.1 issues

Promotion template

When creating issues for promoted items:

Title: {Item title}
Description:
  Promoted from {epic-name} V1 deferred items.

  Original deferral reason: {reason}

  Context: {link to overview.md}

Labels: milestone:v1.1
Project: {epic project}

Future Milestone Impact (tech spec addition)

Tech specs for milestone-aware features MUST include a "Future Milestone Impact" section. This allows the Technical Critic to flag V1 decisions that would make V1.1 or V2 harder.

Section template

Add this section to the tech spec output:

## Future Milestone Impact

### Known Future Milestones
- V1.1: {brief description of what V1.1 will add}
- V2: {brief description of what V2 will add, if known}

### V1 Decisions That Affect Future Milestones

| Decision | Impact on Future Milestones | Mitigation |
|----------|---------------------------|------------|
| {decision} | {how it helps or hurts V1.1/V2} | {what we're doing about it} |

### Technical Debt Introduced

| Debt | Reason for Accepting | When to Address |
|------|---------------------|-----------------|
| {debt item} | {why we're accepting it in V1} | {V1.1 / V2 / Never} |

### Extensibility Considerations

- {How the V1 architecture accommodates known future work}
- {Extension points left open intentionally}
- {Areas that will need refactoring for V1.1/V2}

Orchestrator responsibilities

The orchestrator manages epic/milestone workflows:

Starting a new epic

1. Create Linear Project — For the epic
2. Create spec directory — At docs/specs/{epic-slug}/
3. Create overview.md — With initial milestone roadmap
4. Run V1 through full pipeline — Plan → Prototype → Tech → Issue → Implement → Verify
5. Ship V1

Starting a new milestone (V1.1, V2, etc.)

1. Promote deferred items — Review and triage (see above)
2. Create issues — For the new milestone
3. Update overview.md — With new milestone details
4. Run new milestone through full pipeline — Each milestone is a complete SDLC cycle
5. Ship the milestone

Milestone transitions

When moving from one milestone to the next:

1. Mark previous milestone as Complete — In overview.md
2. Add shipped date — To Milestone History table
3. Review what worked / what didn't — Retrospective
4. Carry forward lessons learned — Into next milestone brief

Rules

1. Epic = Linear Project — Don't invent new grouping mechanisms
2. Overview is required — Every epic directory needs overview.md
3. Milestone prefix all artifacts — v1-brief.md, not brief.md
4. Promote manually — No automation; human judgment required for triage
5. Future Milestone Impact required — Tech specs for milestone-aware features must include this section
6. Each milestone is full SDLC — Don't skip steps because "we already did V1"

Related standards

• standards/core/sdlc.md — Development lifecycle
• standards/core/milestone-planning.md — Milestone scoping and horizontal slice rule
• Planning agent — Brief creation (captures out-of-scope)
• Tech agent — Tech spec creation (Future Milestone Impact)
• CLAUDE.md — Orchestrator instructions

---

Epic and Milestone Implementation Standard v3.0 -- March 2026