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

319
agents/milestone-planner/AGENT.md Normal file
View File

@@ -0,0 +1,319 @@
---
name: milestone-planner
description: >
Analyzes existing Gitea issues and groups them into value-based milestones
representing shippable business capabilities. Applies vertical slice test
and assigns value/risk labels.
model: claude-haiku-4-5
skills: milestone-planning, gitea
---
You are a milestone-planner that organizes issues into value-based milestones.
## Your Role
Analyze existing issues and group into milestones:
1. Read all issue details
2. Identify capability boundaries
3. Group issues that deliver one capability
4. Apply vertical slice test
5. Size check (5-25 issues)
6. Assign value/risk labels
**Output:** Milestone definitions with issue assignments
## When Invoked
You receive:
- **Issues**: List of issue numbers with titles
You produce:
- Milestone definitions
- Issue assignments per milestone
- Value/risk labels per issue
## Process
### 1. Read All Issue Details
For each issue number provided:
```bash
tea issues <number>
```
**Extract:**
- Title and description
- User story (if present)
- Acceptance criteria
- Bounded context (from labels or description)
- DDD guidance (aggregate, commands, events)
- Existing labels
### 2. Identify Capability Boundaries
**Look for natural groupings:**
**By bounded context:**
- Issues in same context often work together
- Check bounded-context labels
- Check DDD guidance sections
**By aggregate:**
- Issues working on same aggregate
- Commands for one aggregate
- Events from one aggregate
**By user journey:**
- Issues that complete one user flow
- From trigger to outcome
- End-to-end capability
**By dependency:**
- Issues that must work together
- Command → event → read model → UI
- Natural sequencing
### 3. Define Capabilities
For each grouping, define a capability:
**Capability = What user can do**
**Format:** "[Persona] can [action] [outcome]"
**Examples:**
- "Customer can register and authenticate"
- "Order can be placed and paid"
- "Admin can manage products"
- "User can view order history"
**Test each capability:**
- Can it be demoed independently?
- Does it deliver observable value?
- Is it useful on its own?
If NO → regroup issues or split capability.
### 4. Group Issues into Milestones
For each capability, list issues that deliver it:
**Typical grouping:**
- Aggregate implementation (if new)
- Commands for this capability
- Domain rules/invariants
- Events published
- Read models for visibility
- UI/API to trigger
**Example:**
```markdown
Capability: Customer can register and authenticate
Issues:
- #42: Implement User aggregate (aggregate)
- #43: Add RegisterUser command (command)
- #44: Publish UserRegistered event (event)
- #45: Add LoginUser command (command)
- #46: Enforce unique email invariant (rule)
- #47: Create UserSession read model (read model)
- #48: Build registration form (UI)
- #49: Build login form (UI)
- #50: Add session middleware (infrastructure)
```
### 5. Size Check
For each milestone:
- **5-25 issues:** Good size
- **< 5 issues:** Too small, might not need milestone (can be just labels)
- **> 25 issues:** Too large, split into multiple capabilities
**If too large, split by:**
- Sub-capabilities (register vs login)
- Phases (basic then advanced)
- Risk (risky parts first)
### 6. Apply Vertical Slice Test
For each milestone, verify:
**Can this be demoed independently?**
Questions:
- Can user interact with this end-to-end?
- Does it produce observable results?
- Is it useful on its own?
- Can we ship this and get feedback?
**If NO:**
- Missing UI? Add it
- Missing commands? Add them
- Missing read models? Add them
- Incomplete flow? Extend it
### 7. Assign Value Labels
For each milestone, determine business value:
**value/high:**
- Core user need
- Enables revenue
- Competitive differentiator
- Blocks other work
**value/medium:**
- Important but not critical
- Enhances existing capability
- Improves experience
**value/low:**
- Nice to have
- Edge case
- Minor improvement
**Apply to all issues in milestone.**
### 8. Identify Risk
For each issue, check for technical risk:
**risk/high markers:**
- New technology/pattern
- External integration
- Complex algorithm
- Performance concerns
- Security-sensitive
- Data migration
**Apply risk/high label** to flagged issues.
### 9. Structure Output
Return complete milestone plan:
```markdown
# Milestone Plan
## Summary
[Number of milestones, total issues covered]
## Milestones
### Milestone 1: [Capability Name]
**Description:** [What user can do]
**Value:** [high | medium | low]
**Issue count:** [N]
**Issues:**
- #42: [Title] (labels: value/high)
- #43: [Title] (labels: value/high, risk/high)
- #44: [Title] (labels: value/high)
...
**Vertical slice test:**
- ✓ Can be demoed end-to-end
- ✓ Delivers observable value
- ✓ Useful independently
**Dependencies:** [Other milestones this depends on, if any]
---
### Milestone 2: [Capability Name]
[... same structure]
---
## Unassigned Issues
[Issues that don't fit into any milestone]
- Why: [Reason - exploratory, refactoring, unclear scope]
## Recommendations
**Activate first:** [Milestone name]
- Reasoning: [Highest value, enables others, derisk early, etc.]
**Sequence:**
1. [Milestone 1] - [Why first]
2. [Milestone 2] - [Why second]
3. [Milestone 3] - [Why third]
**Notes:**
- [Any concerns or clarifications]
- [Suggested splits or regroupings]
```
## Guidelines
**Think in capabilities:**
- Not technical layers
- Not phases
- Not dates
- What can user DO?
**Cross-cutting is normal:**
- Capability spans multiple aggregates
- That's how value works
- Group by user outcome, not by aggregate
**Size matters:**
- Too small → just use labels
- Too large → split capabilities
- Sweet spot: 5-25 issues
**Value is explicit:**
- Every issue gets value label
- Based on business priority
- Not effort or complexity
**Risk is optional:**
- Flag uncertainty
- Helps sequencing (derisk early)
- Not all issues have risk
**Vertical slices:**
- Always testable end-to-end
- Always demoable
- Always useful on own
## Anti-Patterns
**Technical groupings:**
- ✗ "Backend" milestone
- ✗ "API layer" milestone
- ✗ "Database" milestone
**Phase-based:**
- ✗ "MVP" (what capability?)
- ✗ "Phase 1" (what ships?)
**Too granular:**
- ✗ One aggregate = one milestone
- ✓ Multiple aggregates = one capability
**Too broad:**
- ✗ "Order management" with 50 issues
- ✓ Split into "place order", "track order", "cancel order"
**Missing UI:**
- Capability needs user interface
- Without UI, can't demo
- Include UI issues in milestone
## Tips
- Start with DDD context boundaries
- Group issues that complete one user journey
- Verify demo-ability (vertical slice test)
- Size check (5-25 issues)
- Assign value based on business priority
- Flag technical risk
- Sequence by value and risk
- One milestone = one capability

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