Milestone planning

Purpose: How to scope delivery milestones that produce usable software at every increment. Covers the horizontal slice rule, milestone sequencing, and the definition of done for milestones.

Quick reference:

• Milestone — A delivery checkpoint where a user can do something real (not a layer or phase)
• Horizontal Slice Rule — Every milestone includes DB + API + UI + nav + tests
• Sequence — Walking Skeleton → Core CRUD → Supporting entities → Integrations → Ops → Polish
• Done when — All issues Done, E2E verified in deployed env, CLAUDE.md updated if architecture changed

What is a milestone

A milestone is a delivery checkpoint where usable software exists. It is NOT:

• An architectural layer — "build the API"
• A project phase — "design phase", "integration phase"
• A time period — "sprint 3"

A milestone IS a set of work that, when complete, lets a user do something real.

The Horizontal Slice Rule

Every milestone must include all layers needed to make its features work end-to-end:

• Database — Schema + seed data for the feature
• API — Endpoints that serve the feature
• UI — Pages/components that consume the API
• Navigation — Any user-reachable page introduced by this milestone is reachable via navigation (no orphan routes)
• Tests — Verification that the feature works

If a milestone only touches one layer, it's too thin. Expand it. If a milestone touches all features at one layer, it's too wide. Narrow it.

The Navigation requirement is enforced at the issue level. See also: Definition of Done criteria (standards/core/linear-lifecycle.md § Definition of Done Criteria).

Milestone scoping checklist

When defining a milestone, answer these questions:

1. User action — What can a user DO after this milestone that they couldn't before?
2. Persistence — Does the action persist (saved to DB, not just toast)?
3. End-to-end — Does data flow from UI → API → DB → API → UI?
4. Navigation — Is every user-reachable page introduced by this milestone reachable via navigation (no orphan routes)?
   • See § The Horizontal Slice Rule above and standards/core/linear-lifecycle.md § Definition of Done Criteria
5. Standalone value — If this milestone shipped and nothing else did, would it be useful?
6. Demonstrable — Can you show this working in a 2-minute demo?

If any answer is "no", the milestone isn't a horizontal slice yet.

Milestone sequencing

Order milestones by dependency and value:

1. Walking Skeleton (always first) — Auth + one real page with real data
2. Core CRUD — The primary entity the user manages
3. Supporting entities — Secondary entities that depend on the core
4. Integrations — External service connections
5. Operations — Monitoring, reconciliation, admin tools
6. Polish — Cleanup, optimization, deferred items

Milestone definition of done

A milestone is complete when:

• All issues in the milestone are Done
• Feature works end-to-end — In a deployed environment
• Verification passes at all 3 levels — Static, runtime, deployed
• CLAUDE.md is updated — If architecture changed

Linear organization

Use Linear Milestones (or labels like milestone:M1) to group issues:

• One milestone per horizontal slice
• Issues within a milestone may have dependencies — Use Linear's blocking
• Milestones have a clear name — Describing the user-facing capability, not the technical work

Example: "Members Management" not "Wire Members API to UI"

Relationship to epics/phases

Milestones are cross-cutting delivery checkpoints. Epics are feature-scoped groupings. A milestone may include work from multiple epics. An epic may span multiple milestones.

Concept	Scope	Example
Epic	One feature, all milestones	"Member Management" (V1 → V1.1 → V2)
Milestone	One delivery checkpoint	"M2: Tenant & Auth working E2E" or "Members V1"
Issue	One unit of work	"Create useMembers() React Query hook"

Related standards

• standards/reference/engineering-principles.md — Decision framework and anti-patterns
• standards/core/sdlc.md — Development lifecycle with milestone completion process
• standards/core/epic-milestones.md — Epic and milestone implementation

---

Milestone Planning Standard — March 2026