Use Gitea milestones for goal tracking instead of vision issue

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>

skills/vision-management/SKILL.md

@@ -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.