flowmade-one/architecture
3
0
Fork 0
Code Issues 15 Pull Requests 1 Actions Packages Projects Releases Wiki Activity

feat: add value-based milestone planning capability

Browse Source 
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:
Hugo Nijhuis
2026-01-12 17:11:59 +01:00
parent 41105ac114
commit 0c242ebf97
3 changed files with 746 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

235
skills/create-milestones/SKILL.md Normal file
View File

@@ -0,0 +1,235 @@
---
name: create-milestones
description: >
Analyze existing Gitea issues and group into value-based milestones. Creates
milestones, assigns issues, applies value/risk labels. Use when organizing
backlog by capability, or when user says /create-milestones.
model: claude-haiku-4-5
argument-hint:
user-invocable: true
---
# Create Milestones
@~/.claude/skills/milestone-planning/SKILL.md
@~/.claude/skills/gitea/SKILL.md
Analyze existing issues and organize into value-based milestones (shippable capabilities).
## Process
### 1. Fetch Existing Issues
```bash
tea issues --state open -o json
```
Get all open issues from current repository.
Verify issues exist. If none:
```
No open issues found. Create issues first using /vision-to-backlog or /ddd-breakdown.
```
### 2. Analyze Issues
Read issue details for each:
```bash
tea issues <number>
```
**Look for:**
- Issue titles and descriptions
- Bounded context labels (if present)
- Capability labels (if present)
- User stories
- Acceptance criteria
- DDD guidance (aggregates, commands, events)
### 3. Spawn Milestone Planner
Use Task tool to spawn `milestone-planner` agent:
```
Analyze these issues and group into value-based milestones.
Issues: [list of issue numbers with titles]
For each issue, you have access to:
- Full issue description
- Labels
- DDD context
Group issues into milestones that represent shippable business capabilities.
Follow milestone-planning skill principles:
- Milestone = capability user can demo
- 5-25 issues per milestone
- Cross-cutting (commands + events + reads + UI)
- Vertical slice test
Output:
- Milestone definitions
- Issue assignments
- Value/risk labels per issue
Follow milestone-planner agent instructions.
```
Agent returns grouped milestones.
### 4. Review Grouped Milestones
Present agent output to user:
```
## Proposed Milestones
### Milestone: Customer can register and authenticate
**Description:** User registration, login, and session management
**Issues:** 8
**Value:** high
**Issues:**
- #42: Implement User aggregate
- #43: Add RegisterUser command
- #44: Publish UserRegistered event
- #45: Add LoginUser command
- #46: Create UserSession read model
- #47: Build registration form
- #48: Build login form
- #49: Add session middleware
### Milestone: Order can be placed and paid
**Description:** Complete order placement with payment processing
**Issues:** 12
**Value:** high
**Issues:**
- #50: Implement Order aggregate
- #51: Add PlaceOrder command
...
[... more milestones]
```
**Ask user:**
- Approve these milestones?
- Modify any groupings?
- Change value/risk labels?
### 5. Ensure Labels Exist
Before creating milestones, ensure labels exist in Gitea:
**Check for labels:**
```bash
tea labels list
```
**Create missing labels:**
```bash
# Value labels
tea labels create "value/high" --color "#d73a4a" --description "Highest business value"
tea labels create "value/medium" --color "#fbca04" --description "Moderate business value"
tea labels create "value/low" --color "#0075ca" --description "Nice to have"
# Risk label
tea labels create "risk/high" --color "#e99695" --description "Technical risk or uncertainty"
```
### 6. Create Milestones in Gitea
For each approved milestone:
```bash
tea milestones create \
--title "<milestone title>" \
--description "<milestone description>"
```
Capture milestone ID/title for issue assignment.
### 7. Assign Issues to Milestones
For each issue in each milestone:
```bash
tea issues edit <issue-number> --milestone "<milestone-title>"
```
### 8. Apply Value/Risk Labels
For each issue:
```bash
tea issues edit <issue-number> --labels "<existing-labels>,<value-label>"
# If has risk
tea issues edit <issue-number> --labels "<existing-labels>,<value-label>,risk/high"
```
**Preserve existing labels** (bounded-context, capability, etc.)
### 9. Report Results
Show created milestones with links:
```
## Milestones Created
### Customer can register and authenticate (8 issues)
- Value: high
- Issues: #42, #43, #44, #45, #46, #47, #48, #49
- Link: [view milestone](https://git.flowmade.one/owner/repo/milestone/1)
### Order can be placed and paid (12 issues)
- Value: high
- Issues: #50-#61
- Link: [view milestone](https://git.flowmade.one/owner/repo/milestone/2)
[... more milestones]
## Next Steps
1. **Review milestones** in Gitea
2. **Activate ONE milestone** (the current value focus)
3. **Close milestone** when capability is demoable
4. **Pick next milestone** to activate
Remember: Only one open/active milestone at a time!
```
## Guidelines
**Value slices:**
- Each milestone is a shippable capability
- Can be demoed independently
- User sees observable value
**One active milestone:**
- User manually activates ONE
- This workflow doesn't activate automatically
- Forces focus and completion
**Label strategy:**
- Every issue gets value label
- High-risk issues get risk/high label
- Preserves existing labels (context, capability)
**Sizing:**
- 5-25 issues per milestone
- If larger, agent should split
- If smaller, might not need milestone
**No dates:**
- Milestones are capability-based
- Not time-based
- Ship when done, not by deadline
## Tips
- Run after creating issues from /vision-to-backlog
- Re-run if backlog grows and needs reorganization
- Agent groups by capability boundaries (aggregates, contexts)
- Review groupings - agent might miss domain nuance
- Adjust value/risk labels based on business context
- Keep one milestone open at all times

192
skills/milestone-planning/SKILL.md Normal file
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