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

31
commands/create-issue.md
View File

@@ -7,13 +7,34 @@ argument-hint: [title] or "batch"
@~/.claude/skills/gitea/SKILL.md @~/.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 "<milestone>"` in the create command when a milestone is assigned.
## Single Issue (default) ## 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 ## Batch Mode
If $1 is "batch": If $1 is "batch":
1. Ask user for the plan/direction 1. Ask user for the plan/direction
2. Generate list of issues with titles and descriptions 2. Fetch available milestones
3. Show for approval 3. Generate list of issues with titles, descriptions, and milestone assignments
4. Create each issue 4. Show for approval
5. Display all created issue numbers 5. Create each issue with milestone
6. Display all created issue numbers

19
commands/retro.md
View File

@@ -35,12 +35,27 @@ Capture learnings from completed AI-assisted work to improve the workflow and re
- Ask for approval - Ask for approval
- Update the vision file and sync to Gitea - 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 ```bash
tea issues create -r flowmade-one/ai --title "<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 ## Issue Format
Use this structure for retrospective issues: Use this structure for retrospective issues:

90
commands/vision.md
View File

@@ -1,6 +1,6 @@
--- ---
description: View, create, or update the product vision. Manages vision.md and syncs to Gitea. description: View the product vision and goal progress. Manages vision.md and Gitea milestones.
argument-hint: [update|goals|focus] argument-hint: [goals]
--- ---
# Product Vision # Product Vision
@@ -8,65 +8,71 @@ argument-hint: [update|goals|focus]
@~/.claude/skills/vision-management/SKILL.md @~/.claude/skills/vision-management/SKILL.md
@~/.claude/skills/gitea/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 ## Process
1. **Check for existing vision**: Look for `vision.md` in the current repo root. 1. **Check for existing vision**: Look for `vision.md` in the current repo root.
2. **If no vision exists**: 2. **If no vision exists**:
- Ask the user if they want to create one - Ask the user if they want to create one
- Guide them through: - Guide them through the philosophy: purpose, principles, non-goals
- Purpose: Why does this product exist? - Create `vision.md` (do NOT include goals/progress - that's milestones)
- Goals: 3-5 measurable outcomes with success metrics - Ask about initial goals and create them as Gitea milestones
- 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
3. **If vision exists**: 3. **If vision exists**:
- Display the current vision - Display the vision philosophy from `vision.md`
- Check if $1 specifies an action: - Show current milestones and their progress: `tea milestones`
- `update`: General update to the vision - Check if `$1` specifies an action:
- `goals`: Add, modify, or complete goals - `goals`: Manage milestones (add, close, view progress)
- `focus`: Change the current focus area - If no action specified, just display the current state
- 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
4. **Sync to Gitea**: 4. **Managing Goals (milestones)**:
- Find existing issue with `vision` label: `tea issues -l vision` ```bash
- If exists: Update the issue description # List milestones with progress
- If not: Create new issue with `vision` label 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 ## Output Format
When displaying the vision, show it clearly:
``` ```
## Current Vision ## Vision
**Purpose**: [purpose] [Summary of vision.md purpose/principles]
**Goals**: ## Goals (Milestones)
1. [Goal] - [Metric] [Progress indicator]
2. [Goal] - [Metric] [Progress indicator]
**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 ## Guidelines
- Keep goals specific and measurable - vision.md is the stable "why" document - update rarely
- Limit to 3-5 active goals - Milestones are the actionable goals - create/close as needed
- Current focus should be 1-2 goals max - Assign issues to milestones to track progress
- Update "Last Updated" on every change - Use milestone descriptions for success criteria
- Always sync to Gitea after changes - Due dates on milestones are optional but help prioritization

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. 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 | Layer | Purpose | Location |
2. **Gitea issue** labeled `vision` - Integrates with issue workflow |-------|---------|----------|
| **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 ## Vision Document Structure
The vision.md file should contain the stable "why" - not progress tracking:
```markdown ```markdown
# Product Vision # Vision
## Purpose ## The Problem
Why this product exists. The problem it solves. What problem does this product solve? Who benefits?
## Goals ## The Solution
1. [Goal 1] - [Success metric] How does this product solve the problem?
2. [Goal 2] - [Success metric]
3. [Goal 3] - [Success metric]
## Current Focus ## Guiding Principles
What we're prioritizing now and why. Core beliefs that guide decisions.
## Non-Goals ## Non-Goals
What we're explicitly NOT doing. 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 ## Creating a Vision
When no vision exists: When no vision exists:
1. **Identify the purpose**: What problem does this product solve? Who benefits? 1. **Identify the problem**: What pain point does this solve?
2. **Define 3-5 goals**: Concrete, measurable outcomes 2. **Define the solution**: How does the product address it?
3. **Set success metrics**: How will you know each goal is achieved? 3. **Set guiding principles**: What beliefs guide decisions?
4. **Choose current focus**: Which 1-2 goals are priorities right now? 4. **Document non-goals**: What are you explicitly NOT doing?
5. **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 - Specific and measurable
- Outcome-focused (not activity-focused) - Outcome-focused (not activity-focused)
- Have clear success criteria - Have clear success criteria in the description
| Bad | Good | | Bad | Good |
|-----|------| |-----|------|
@@ -65,92 +64,80 @@ When no vision exists:
| "Better UX" | "User can complete checkout in under 60 seconds" | | "Better UX" | "User can complete checkout in under 60 seconds" |
| "More features" | "Support 3 export formats (CSV, JSON, PDF)" | | "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) # Create a new goal
- Learnings from retros reveal new priorities tea milestones create --title "Automate repetitive workflows" \
- Strategic direction changes --description "Success: 80% of routine tasks handled by slash commands"
- A non-goal becomes a goal (or vice versa)
### Update Process # View issues in a milestone
tea milestones issues "Automate repetitive workflows"
1. Read current vision # Close a completed goal
2. Identify what needs to change tea milestones close "Automate repetitive workflows"
3. Draft the update ```
4. Present changes for approval
5. Update `vision.md` ### Assigning Issues to Milestones
6. Sync to Gitea issue
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 ## Aligning Issues with Vision
When creating or reviewing issues: When creating or reviewing issues:
1. **Check goal alignment**: Does this issue support a vision goal? 1. **Check goal alignment**: Does this issue support a milestone?
2. **Tag appropriately**: Reference the goal in the issue description 2. **Assign to milestone**: Link the issue to the relevant goal
3. **Prioritize by vision**: Issues supporting current focus get priority 3. **Prioritize by focus**: Issues in priority milestones get worked first
4. **Flag misalignment**: Issues that don't align with any goal need justification 4. **Flag misalignment**: Issues without a milestone need justification
### Alignment Check Template
```markdown
## Vision Alignment
Supports: Goal 2 (Security)
Priority: High (current focus area)
```
### Identifying Gaps ### Identifying Gaps
Compare vision goals to current backlog: Compare milestones to current backlog:
- Which goals have no supporting issues? - Which milestones have no issues?
- Which goals have stalled (no recent progress)? - Which milestones have stalled (no recent progress)?
- Are there issues that don't align with any goal? - Are there issues without a milestone?
## Connecting Retros to Vision ## Connecting Retros to Vision
After a retrospective: After a retrospective:
1. **Review learnings**: Any that affect the vision? 1. **Review learnings**: Any that affect the vision or goals?
2. **Goal changes**: Should any goals be added, removed, or modified? 2. **Milestone changes**: Should any goals be added, closed, or modified?
3. **Non-goal additions**: Did we learn something we should explicitly avoid? 3. **Non-goal additions**: Did we learn something to add to vision.md?
4. **Progress updates**: Did completed work advance any goals? 4. **Progress check**: Did completed work close any milestones?
### Retro-to-Vision Questions ### Retro-to-Vision Questions
- "Did this work reveal a new priority we should add as a goal?" - "Did this work reveal a new goal we should add as a milestone?"
- "Did we learn something that should become a non-goal?" - "Did we learn something that should become a non-goal in vision.md?"
- "Should our current focus shift based on what we learned?" - "Should we close or modify any milestones based on what we learned?"
- "Did this work make progress on any goals?" - "Are any milestones ready to close?"
## 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
## Continuous Improvement Loop ## Continuous Improvement Loop
``` ```
Vision → Issues → Work → Retro → Vision (updated) Vision → Milestones → Issues → Work → Retro → (Vision/Milestones updated)
``` ```
1. **Vision** defines what success looks like 1. **Vision** defines why and principles (stable)
2. **Issues** are created to achieve vision goals 2. **Milestones** define measurable goals
3. **Work** implements the issues 3. **Issues** are work items toward those goals
4. **Retros** capture learnings from the work 4. **Work** implements the issues
5. **Vision updates** incorporate learnings (loop continues) 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.