feat: add value-based milestone planning capability

Add capability for organizing backlog into shippable business capabilities
using value-based milestones (not time-based phases).

Components:
- milestone-planning skill: Value-based framework, vertical slice test, one active milestone
- create-milestones skill: Orchestrator (Haiku) for analyzing and grouping issues
- milestone-planner agent: Groups issues into capabilities autonomously (Haiku)

Core Principles:
- Milestone = shippable business capability (not phase)
- One active milestone at a time (preserves focus)
- 5-25 issues per milestone (right-sized)
- Value labels: value/high, value/medium, value/low
- Risk labels: risk/high (optional)
- Vertical slice test (can be demoed independently)
- No dates (capability-based, not time-based)

Workflow: /create-milestones reads existing Gitea issues → analyzes capability
boundaries → groups into milestones → creates in Gitea → assigns issues →
applies labels → user manually activates ONE milestone

Co-Authored-By: Claude Code <noreply@anthropic.com>
This commit is contained in:
2026-01-12 17:11:59 +01:00
parent 41105ac114
commit 0c242ebf97
3 changed files with 746 additions and 0 deletions

View File

@@ -0,0 +1,192 @@
---
name: milestone-planning
description: >
Value-based milestone planning: milestones as shippable capabilities, not phases.
One active milestone, vertical slices, value/risk labels. Use when planning
milestones or organizing backlog by capability.
user-invocable: false
---
# Milestone Planning
Value-driven milestone framework: milestones represent shippable business capabilities, not time-based phases.
## Core Principle
**If you don't deliver by date, milestones must represent value slices, not time.**
**Milestone = A shippable business capability**
Not a phase. Not "MVP". Not "Auth".
## What Makes a Good Milestone
Each milestone should answer one business question:
**"What new capability exists for the user once this is done?"**
### Good Examples
✓ Customer can register and authenticate
✓ Order can be placed and paid
✓ Admin can manage products
✓ Audit trail exists for all state changes
### Bad Examples
✗ MVP (what capability?)
✗ Backend (technical layer, not user value)
✗ Auth improvements (vague, no completion criteria)
✗ Phase 1 (time-based, not value-based)
**Test:** If it can't be demoed independently, it's too vague.
## Mapping DDD Issues to Milestones
**DDD building blocks → issues**
- Aggregates
- Commands
- Events
- Read models
- Policies
**End-to-end capability → milestone**
- Spans multiple aggregates
- Commands + invariants + events
- Read models for visibility
- Maybe UI/API glue
**Value is cross-cutting by nature.**
A milestone usually includes:
- Multiple aggregates working together
- Commands that achieve user goal
- Events connecting aggregates
- Read models for user feedback
- UI/API to trigger capability
## One Active Milestone at a Time
**Rule:** Exactly one open milestone = current value focus
**Why:**
- Preserves focus
- Avoids parallel half-value
- Forces completion
- Makes priority explicit
**Practice:**
- Everything else stays unassigned
- When done → close it → pick next highest-value milestone
- Multiple open milestones = accidental roadmap
## Priority Without Dates
Since Gitea milestones have no ordering, use labels:
**Minimal label set:**
- `value/high` - Highest business value
- `value/medium` - Moderate business value
- `value/low` - Nice to have
- `risk/high` - Technical risk or uncertainty
**Issues have:**
- Always: value label
- Sometimes: risk label
**You now have:**
- **Milestone** → what capability
- **Label** → why now
## Sizing Guidelines
A value milestone should:
- Be completable in days to a few weeks
- Deliver observable user value
- Contain 5-25 issues
**If it keeps growing:**
- You discovered multiple capabilities
- Split into separate milestones
## Vertical Slice Test
Before creating a milestone, verify:
**Can this be demoed independently?**
Test questions:
- Can a user interact with this capability end-to-end?
- Does it produce observable results?
- Is it useful on its own (not just foundation)?
- Can we ship this and get feedback?
If NO to any → not a value slice yet.
## Label Strategy
**Value labels (always):**
- Reflect business priority
- Based on user impact, revenue, strategic alignment
- Applied to every issue in milestone
**Risk labels (optional):**
- Flag technical uncertainty
- Flag new patterns/technologies
- Flag complex integrations
- Helps sequence work (derisk early)
## Anti-Patterns
**"We just deliver highest value first"**
Only works if:
- Value is explicit (labels)
- Scope is bounded (milestones)
- Work is finishable (vertical slices)
Without milestones, "value-first" quietly becomes "interesting-first".
**Multiple open milestones:**
- Splits focus
- Encourages context switching
- Hides incomplete work
- Prevents shipping
**Technical milestones:**
- "Backend" is not a capability
- "API layer" is not demoable
- "Database migration" might be necessary but not a milestone
**Phase-based milestones:**
- "MVP" → what can user do?
- "Phase 1" → what capability?
- "Q1 goals" → what ships?
## When NOT to Use Milestones
**Don't use milestones when:**
- Single capability with <5 issues (just label it)
- Exploratory work (use spike label instead)
- Refactoring without user-visible change (use technical debt label)
- Everything ships together (waterfall project)
**Milestones enforce discipline around value slices.**
## Workflow Summary
1. **Issues exist** (from DDD analysis or backlog)
2. **Group by capability** (milestone-planner agent)
3. **One milestone open** (current value slice)
4. **Label for priority** (value/risk)
5. **No dates** (capability-based, not time-based)
6. **Close ruthlessly** (finish before starting next)
## Tips
- Start with 3-5 milestones defined, 1 active
- Keep unassigned issues in backlog
- Move issues between milestones if capability boundaries change
- Split milestones that grow beyond 25 issues
- Close milestone when capability is demoable
- Review value/risk labels regularly
- Active milestone = team's current focus