From 28242d44cc01088500b1b461e5eea59a90710a7e Mon Sep 17 00:00:00 2001 From: Hugo Nijhuis Date: Thu, 1 Jan 2026 22:22:06 +0100 Subject: [PATCH] Use Gitea milestones for goal tracking instead of vision issue MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 --- commands/create-issue.md | 31 +++++- commands/retro.md | 19 +++- commands/vision.md | 90 ++++++++-------- skills/vision-management/SKILL.md | 165 ++++++++++++++---------------- 4 files changed, 167 insertions(+), 138 deletions(-) diff --git a/commands/create-issue.md b/commands/create-issue.md index 41103ed..01a3082 100644 --- a/commands/create-issue.md +++ b/commands/create-issue.md @@ -7,13 +7,34 @@ argument-hint: [title] or "batch" @~/.claude/skills/gitea/SKILL.md +## Milestone Assignment + +Before creating issues, fetch available milestones: + +```bash +tea milestones -f title,description +``` + +For each issue, automatically assign to the most relevant milestone by matching: +- Issue content/problem area → Milestone title and description +- If no clear match, ask the user which milestone (goal) the issue supports +- If no milestones exist, skip milestone assignment + +Include `--milestone ""` in the create command when a milestone is assigned. + ## Single Issue (default) -If title provided, create an issue with that title and ask for description. + +If title provided: +1. Create an issue with that title +2. Ask for description +3. Assign to appropriate milestone (see above) ## Batch Mode + If $1 is "batch": 1. Ask user for the plan/direction -2. Generate list of issues with titles and descriptions -3. Show for approval -4. Create each issue -5. Display all created issue numbers +2. Fetch available milestones +3. Generate list of issues with titles, descriptions, and milestone assignments +4. Show for approval +5. Create each issue with milestone +6. Display all created issue numbers diff --git a/commands/retro.md b/commands/retro.md index 12708eb..e4fb89c 100644 --- a/commands/retro.md +++ b/commands/retro.md @@ -35,12 +35,27 @@ Capture learnings from completed AI-assisted work to improve the workflow and re - Ask for approval - Update the vision file and sync to Gitea -5. **Generate improvement issues**: For each actionable improvement, create an issue in the AI repo using: +5. **Generate improvement issues**: For each actionable improvement: + - Determine the appropriate milestone (see Milestone Categorization below) + - Create an issue in the AI repo with the milestone assigned: ```bash -tea issues create -r flowmade-one/ai --title "" --description "<body>" +tea issues create -r flowmade-one/ai --title "<title>" --description "<body>" --milestone "<milestone>" ``` +## Milestone Assignment + +Before creating issues, fetch available milestones: + +```bash +tea milestones -f title,description +``` + +For each issue, automatically assign to the most relevant milestone by matching: +- Issue content/problem area → Milestone title and description +- If no clear match, ask the user which milestone (goal) the issue supports +- If no milestones exist, skip milestone assignment + ## Issue Format Use this structure for retrospective issues: diff --git a/commands/vision.md b/commands/vision.md index 992d1b5..93a16d4 100644 --- a/commands/vision.md +++ b/commands/vision.md @@ -1,6 +1,6 @@ --- -description: View, create, or update the product vision. Manages vision.md and syncs to Gitea. -argument-hint: [update|goals|focus] +description: View the product vision and goal progress. Manages vision.md and Gitea milestones. +argument-hint: [goals] --- # Product Vision @@ -8,65 +8,71 @@ argument-hint: [update|goals|focus] @~/.claude/skills/vision-management/SKILL.md @~/.claude/skills/gitea/SKILL.md +## Architecture + +The vision system has two layers: + +| Layer | Purpose | Location | +|-------|---------|----------| +| **vision.md** | North star philosophy (why, principles, non-goals) | File in repo root | +| **Milestones** | Goals with progress tracking | Gitea milestones | + +Issues are assigned to milestones. Progress is visible through milestone completion. + ## Process 1. **Check for existing vision**: Look for `vision.md` in the current repo root. 2. **If no vision exists**: - Ask the user if they want to create one - - Guide them through: - - Purpose: Why does this product exist? - - Goals: 3-5 measurable outcomes with success metrics - - Current focus: Which 1-2 goals are priorities now? - - Non-goals: What are you explicitly NOT doing? - - Create `vision.md` with the vision document structure - - Create a Gitea issue labeled `vision` with the same content + - Guide them through the philosophy: purpose, principles, non-goals + - Create `vision.md` (do NOT include goals/progress - that's milestones) + - Ask about initial goals and create them as Gitea milestones 3. **If vision exists**: - - Display the current vision - - Check if $1 specifies an action: - - `update`: General update to the vision - - `goals`: Add, modify, or complete goals - - `focus`: Change the current focus area - - If no action specified, ask what the user wants to do: - - View only (done) - - Update goals - - Change focus - - Update progress - - Add non-goals - - Make the requested changes - - Update `vision.md` - - Sync changes to the Gitea vision issue + - Display the vision philosophy from `vision.md` + - Show current milestones and their progress: `tea milestones` + - Check if `$1` specifies an action: + - `goals`: Manage milestones (add, close, view progress) + - If no action specified, just display the current state -4. **Sync to Gitea**: - - Find existing issue with `vision` label: `tea issues -l vision` - - If exists: Update the issue description - - If not: Create new issue with `vision` label +4. **Managing Goals (milestones)**: + ```bash + # List milestones with progress + tea milestones + + # Create a new goal + tea milestones create --title "<goal>" --description "<success criteria>" + + # View issues in a milestone + tea milestones issues <milestone-name> + + # Close a completed goal + tea milestones close <milestone-name> + ``` ## Output Format -When displaying the vision, show it clearly: - ``` -## Current Vision +## Vision -**Purpose**: [purpose] +[Summary of vision.md purpose/principles] -**Goals**: -1. [Goal] - [Metric] [Progress indicator] -2. [Goal] - [Metric] [Progress indicator] +## Goals (Milestones) -**Current Focus**: [focus area] +| Goal | Progress | Due | +|------|----------|-----| +| [title] | 3/5 issues | [date] | -**Non-Goals**: [list] +## Current Focus -**Last Updated**: [date] +[Open milestones with nearest due dates or most activity] ``` ## Guidelines -- Keep goals specific and measurable -- Limit to 3-5 active goals -- Current focus should be 1-2 goals max -- Update "Last Updated" on every change -- Always sync to Gitea after changes +- vision.md is the stable "why" document - update rarely +- Milestones are the actionable goals - create/close as needed +- Assign issues to milestones to track progress +- Use milestone descriptions for success criteria +- Due dates on milestones are optional but help prioritization diff --git a/skills/vision-management/SKILL.md b/skills/vision-management/SKILL.md index 92c6d4f..3eb503f 100644 --- a/skills/vision-management/SKILL.md +++ b/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.