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

Use Gitea milestones for goal tracking instead of vision issue

Browse Source 
Refactored the vision system to separate concerns:
- vision.md remains the stable "north star" philosophy document
- Gitea milestones now track goals with automatic progress via issue counts
- Updated /vision, /retro, and /create-issue commands to auto-assign milestones

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
Hugo Nijhuis
2026-01-01 22:22:06 +01:00
parent 9e1ca55196
commit 28242d44cc
4 changed files with 167 additions and 138 deletions
Download Patch File Download Diff File Expand all files Collapse all files

165
skills/vision-management/SKILL.md
View File

@@ -7,57 +7,56 @@ description: Create, maintain, and evolve a product vision. Use when initializin
How to create, maintain, and evolve a product vision for continuous improvement.
## Vision Document Location
## Architecture
The vision lives in two places:
The vision system has two layers:
1. **`vision.md`** at repo root - Source of truth, versionable
2. **Gitea issue** labeled `vision` - Integrates with issue workflow
| Layer | Purpose | Location |
|-------|---------|----------|
| **vision.md** | North star philosophy (why, principles, non-goals) | File in repo root |
| **Milestones** | Goals with progress tracking | Gitea milestones |
Keep these in sync. The file is authoritative; the issue mirrors it.
- **vision.md** is stable - updated rarely when direction changes
- **Milestones** are actionable - created/closed as goals evolve
- **Issues** are assigned to milestones to track progress
## Vision Document Structure
The vision.md file should contain the stable "why" - not progress tracking:
```markdown
# Product Vision
# Vision
## Purpose
Why this product exists. The problem it solves.
## The Problem
What problem does this product solve? Who benefits?
## Goals
1. [Goal 1] - [Success metric]
2. [Goal 2] - [Success metric]
3. [Goal 3] - [Success metric]
## The Solution
How does this product solve the problem?
## Current Focus
What we're prioritizing now and why.
## Guiding Principles
Core beliefs that guide decisions.
## Non-Goals
What we're explicitly NOT doing.
## Progress
- [Goal 1]: [Status/progress]
- [Goal 2]: [Status/progress]
## Last Updated
[Date] - [What changed]
```
Do NOT include goals, progress, or focus in vision.md - that's what milestones are for.
## Creating a Vision
When no vision exists:
1. **Identify the purpose**: What problem does this product solve? Who benefits?
2. **Define 3-5 goals**: Concrete, measurable outcomes
3. **Set success metrics**: How will you know each goal is achieved?
4. **Choose current focus**: Which 1-2 goals are priorities right now?
5. **Document non-goals**: What are you explicitly NOT doing?
1. **Identify the problem**: What pain point does this solve?
2. **Define the solution**: How does the product address it?
3. **Set guiding principles**: What beliefs guide decisions?
4. **Document non-goals**: What are you explicitly NOT doing?
5. **Create initial milestones**: 3-5 measurable goals
### Good Goals
### Good Goals (Milestones)
- Specific and measurable
- Outcome-focused (not activity-focused)
- Have clear success criteria
- Have clear success criteria in the description
| Bad | Good |
|-----|------|
@@ -65,92 +64,80 @@ When no vision exists:
| "Better UX" | "User can complete checkout in under 60 seconds" |
| "More features" | "Support 3 export formats (CSV, JSON, PDF)" |
## Updating the Vision
## Managing Goals with Milestones
Update the vision when:
```bash
# List milestones with progress
tea milestones
tea milestones -f title,items_open,items_closed,state
- A goal is achieved (update progress, possibly add new goal)
- Learnings from retros reveal new priorities
- Strategic direction changes
- A non-goal becomes a goal (or vice versa)
# Create a new goal
tea milestones create --title "Automate repetitive workflows" \
--description "Success: 80% of routine tasks handled by slash commands"
### Update Process
# View issues in a milestone
tea milestones issues "Automate repetitive workflows"
1. Read current vision
2. Identify what needs to change
3. Draft the update
4. Present changes for approval
5. Update `vision.md`
6. Sync to Gitea issue
# Close a completed goal
tea milestones close "Automate repetitive workflows"
```
### Assigning Issues to Milestones
When creating issues, assign them to the relevant milestone:
```bash
tea issues create --title "Add /commit command" \
--description "..." \
--milestone "Automate repetitive workflows"
```
Progress is automatically tracked through open/closed issue counts.
## Aligning Issues with Vision
When creating or reviewing issues:
1. **Check goal alignment**: Does this issue support a vision goal?
2. **Tag appropriately**: Reference the goal in the issue description
3. **Prioritize by vision**: Issues supporting current focus get priority
4. **Flag misalignment**: Issues that don't align with any goal need justification
### Alignment Check Template
```markdown
## Vision Alignment
Supports: Goal 2 (Security)
Priority: High (current focus area)
```
1. **Check goal alignment**: Does this issue support a milestone?
2. **Assign to milestone**: Link the issue to the relevant goal
3. **Prioritize by focus**: Issues in priority milestones get worked first
4. **Flag misalignment**: Issues without a milestone need justification
### Identifying Gaps
Compare vision goals to current backlog:
Compare milestones to current backlog:
- Which goals have no supporting issues?
- Which goals have stalled (no recent progress)?
- Are there issues that don't align with any goal?
- Which milestones have no issues?
- Which milestones have stalled (no recent progress)?
- Are there issues without a milestone?
## Connecting Retros to Vision
After a retrospective:
1. **Review learnings**: Any that affect the vision?
2. **Goal changes**: Should any goals be added, removed, or modified?
3. **Non-goal additions**: Did we learn something we should explicitly avoid?
4. **Progress updates**: Did completed work advance any goals?
1. **Review learnings**: Any that affect the vision or goals?
2. **Milestone changes**: Should any goals be added, closed, or modified?
3. **Non-goal additions**: Did we learn something to add to vision.md?
4. **Progress check**: Did completed work close any milestones?
### Retro-to-Vision Questions
- "Did this work reveal a new priority we should add as a goal?"
- "Did we learn something that should become a non-goal?"
- "Should our current focus shift based on what we learned?"
- "Did this work make progress on any goals?"
## Vision Issue in Gitea
Create/update a Gitea issue that mirrors the vision:
```bash
# Create vision issue
tea issues create --title "Product Vision" --description "$(cat vision.md)" --labels "vision"
# Update existing vision issue
tea issues edit <issue-number> --description "$(cat vision.md)"
```
Benefits of the vision issue:
- Other issues can reference it (`Supports #N`)
- Visible in backlog alongside work items
- Provides discussion space for vision questions
- "Did this work reveal a new goal we should add as a milestone?"
- "Did we learn something that should become a non-goal in vision.md?"
- "Should we close or modify any milestones based on what we learned?"
- "Are any milestones ready to close?"
## Continuous Improvement Loop
```
Vision → Issues → Work → Retro → Vision (updated)
Vision → Milestones → Issues → Work → Retro → (Vision/Milestones updated)
```
1. **Vision** defines what success looks like
2. **Issues** are created to achieve vision goals
3. **Work** implements the issues
4. **Retros** capture learnings from the work
5. **Vision updates** incorporate learnings (loop continues)
1. **Vision** defines why and principles (stable)
2. **Milestones** define measurable goals
3. **Issues** are work items toward those goals
4. **Work** implements the issues
5. **Retros** capture learnings
6. **Updates** refine vision and create/close milestones
The vision is a living document that evolves as you learn.
The vision is stable. The milestones evolve as you learn and achieve goals.