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
## 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)
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

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
- 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 "<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:

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

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.