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

Update vision-management skill for manifesto vs vision distinction

Browse Source 
Restructured skill to clearly distinguish:
- Manifesto: Organization-level (architecture repo)
- Vision: Product-level (product repos)

Key additions:
- Architecture table showing all three levels with commands
- Manifesto section with structure, when to update, creation steps
- Vision section clarified as product-level extending manifesto
- Relationship diagram showing inheritance model
- Example of persona inheritance (org → product)
- Continuous improvement loop including retro → encoding flow
- Quick reference table for common questions

Closes #43

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

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit was merged in pull request #51.
This commit is contained in:
Hugo Nijhuis
2026-01-07 20:43:34 +01:00
parent fac88cfcc7
commit dc7b554ee6
1 changed files with 164 additions and 134 deletions
Download Patch File Download Diff File Expand all files Collapse all files

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

@@ -1,123 +1,175 @@
---
name: vision-management
description: Create, maintain, and evolve a product vision. Use when initializing a vision, updating goals, aligning work with vision, or connecting learnings to vision refinement.
description: Create, maintain, and evolve organization manifesto and product visions. Use when working with manifesto.md, vision.md, milestones, or aligning work with organizational direction.
---
# Vision Management
How to create, maintain, and evolve a product vision for continuous improvement.
How to create, maintain, and evolve organizational direction at two levels: manifesto (organization) and vision (product).
## Architecture
The vision system has two layers:
| Level | Document | Purpose | Command | Location |
|-------|----------|---------|---------|----------|
| **Organization** | `manifesto.md` | Identity, shared personas, beliefs, principles | `/manifesto` | Architecture repo |
| **Product** | `vision.md` | Product-specific personas, jobs, solution | `/vision` | Product repos |
| **Goals** | Gitea milestones | Measurable progress toward vision | `/vision goals` | Per repo |
| Layer | Purpose | Location |
|-------|---------|----------|
| **vision.md** | North star philosophy (why, principles, non-goals) | File in repo root |
| **Milestones** | Goals with progress tracking | Gitea milestones |
Product vision inherits from and extends the organization manifesto.
- **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
## Manifesto (Organization Level)
The vision.md file should contain the stable "why" and "who" - not progress tracking:
The manifesto defines who we are as an organization. It lives in the architecture repo and applies across all products.
### Manifesto Structure
```markdown
# Manifesto
## Who We Are
Organization identity - what makes us unique.
## Who We Serve
Shared personas across all products.
- **Persona Name**: Description, context, constraints
## What They're Trying to Achieve
Jobs to be done at the organization level.
- "Help me [outcome] without [pain]"
## What We Believe
Core beliefs that guide how we work.
### [Belief Category]
- Belief point
- Belief point
## Guiding Principles
Decision-making rules that apply everywhere.
1. **Principle**: Explanation
## Non-Goals
What the organization explicitly does NOT do.
- **Non-goal**: Why
```
### When to Update Manifesto
- **Rarely** - this is foundational identity
- When core beliefs change
- When adding/removing personas served
- When adding non-goals based on learnings
### Creating a Manifesto
1. Define organization identity (Who We Are)
2. Identify shared personas (2-4 max)
3. Articulate organization-level jobs to be done
4. Document core beliefs (especially about AI/development)
5. Establish guiding principles
6. Define non-goals
---
## Vision (Product Level)
The vision defines what a specific product does. It lives in each product repo and extends the manifesto.
### Vision Structure
```markdown
# Vision
## Who We Serve (Personas)
The people we're building for and what characterizes them.
## Who This Product Serves
Product-specific personas (may extend org personas).
- **Persona Name**: Product-specific context
- **Persona Name**: Brief description of who they are, their context, constraints
## What They're Trying to Achieve (Jobs to Be Done)
The outcomes our personas are trying to accomplish - in their words.
- "Help me [achieve outcome] without [pain point]"
- "Help me [do thing] so I can [benefit]"
## What They're Trying to Achieve
Product-specific jobs to be done.
- "Help me [outcome] without [pain]"
## The Problem
Current pain points that prevent our personas from achieving their jobs.
Pain points this product addresses.
## The Solution
How this product addresses the jobs to be done.
How this product solves those problems.
## Guiding Principles
Core beliefs that guide decisions.
## Product Principles
Product-specific principles (beyond org principles).
## Non-Goals
What we're explicitly NOT doing (and why).
What this product explicitly does NOT do.
```
Do NOT include goals, progress, or focus in vision.md - that's what milestones are for.
### When to Update Vision
## Defining Personas
- When product direction shifts
- When adding/changing personas served by this product
- When discovering new non-goals
- After major learnings from retros
Good personas are:
- **Specific**: Not "developers" but "solo developers shipping MVPs"
- **Characterized**: Include constraints, context, priorities
- **Limited**: 2-4 personas max, or you're building for everyone (no one)
### Creating a Product Vision
| Bad | Good |
|-----|------|
| "Users" | "Solo developer shipping side projects on evenings/weekends" |
| "Developers" | "Small team lead coordinating 2-5 engineers" |
| "Companies" | "Early-stage startup with no dedicated DevOps" |
1. Reference the organization manifesto
2. Define product-specific personas (can extend org personas)
3. Identify product-specific jobs to be done
4. Articulate the problem this product solves
5. Define the solution approach
6. Set product-specific principles (if any)
7. Document product non-goals
8. Create initial milestones
## Defining Jobs to Be Done
---
Jobs should be:
- **Outcome-focused**: What they want to achieve, not what they do
- **In their voice**: How they'd describe it, not technical jargon
- **Pain-aware**: Include what's hard about it today
## Relationship: Manifesto → Vision
Format: "Help me [outcome] without [pain]" or "Help me [action] so I can [benefit]"
```
Manifesto (org) Vision (product)
├── Shared Personas → Product Personas (more specific)
├── Org Jobs → Product Jobs (subset/extension)
├── Beliefs → (inherited, not duplicated)
├── Principles → Product Principles (additional)
└── Non-Goals → Product Non-Goals (additional)
```
| Bad | Good |
|-----|------|
| "Git integration" | "Help me commit and push without remembering git commands" |
| "Issue tracking" | "Help me know what to work on next without checking 5 tools" |
| "Code review" | "Help me catch bugs before they ship without slowing down" |
### Inheritance Model
## Creating a Vision
- **Personas**: Product personas can be more specific versions of org personas
- **Jobs**: Product jobs should trace back to org-level jobs
- **Beliefs**: Inherited from manifesto, not duplicated in vision
- **Principles**: Product can add specific principles; org principles apply automatically
- **Non-Goals**: Product adds its own; org non-goals apply automatically
When no vision exists:
### Example
1. **Define personas**: Who are we building for? (2-4 specific personas)
2. **Identify jobs to be done**: What are they trying to achieve?
3. **Articulate the problem**: What pain points prevent them from achieving their jobs?
4. **Define the solution**: How does the product address these jobs?
5. **Set guiding principles**: What beliefs guide decisions?
6. **Document non-goals**: What are you explicitly NOT doing?
7. **Create initial milestones**: 3-5 measurable goals tied to personas/jobs
**Manifesto** (organization):
```markdown
## Who We Serve
- **Solo Developer**: Individual shipping side projects, time-constrained
```
### Good Goals (Milestones)
**Vision** (product - e.g., CLI tool):
```markdown
## Who This Product Serves
- **Solo Developer (CLI user)**: Uses terminal daily, prefers keyboard over GUI
```
The product persona extends the org persona with product-specific context.
---
## Milestones (Goals)
Milestones are product-level goals that track progress toward the vision.
### Good Milestones
- Specific and measurable
- Tied to a persona and job to be done
- Outcome-focused (not activity-focused)
- Have clear success criteria in the description
- Include success criteria in description
| Bad | Good |
|-----|------|
| "Improve performance" | "Page load under 2 seconds" |
| "Better UX" | "User can complete checkout in under 60 seconds" |
| "More features" | "Support 3 export formats (CSV, JSON, PDF)" |
### Tying Milestones to Personas
Each milestone should clearly serve a persona's job to be done:
```
Milestone: "Automate routine git workflows"
For: Solo developer
Job: "Help me commit and push without remembering git commands"
Success: /commit, /pr commands handle 80% of git workflows
```
Include persona context in milestone descriptions:
```bash
tea milestones create --title "Automate routine git workflows" \
--description "For: Solo developer
@@ -125,35 +177,14 @@ Job: Ship without context switching to git commands
Success: /commit and /pr commands handle 80% of workflows"
```
## Managing Goals with Milestones
### Milestone-to-Vision Alignment
```bash
# List milestones with progress
tea milestones
tea milestones -f title,items_open,items_closed,state
Every milestone should trace to:
- A persona (from vision or manifesto)
- A job to be done (from vision)
- A measurable outcome
# Create a new goal
tea milestones create --title "Automate repetitive workflows" \
--description "Success: 80% of routine tasks handled by slash commands"
# View issues in a milestone
tea milestones issues "Automate repetitive workflows"
# 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
@@ -161,50 +192,49 @@ When creating or reviewing issues:
1. **Check persona alignment**: Which persona does this serve?
2. **Check job alignment**: Which job to be done does this enable?
3. **Check goal alignment**: Does this issue support a milestone?
3. **Check milestone alignment**: Does this issue support a goal?
4. **Assign to milestone**: Link the issue to the relevant goal
5. **Prioritize by focus**: Issues in priority milestones get worked first
6. **Flag misalignment**: Issues without clear persona/milestone need justification
Every issue should trace back to: "This helps [persona] achieve [job] by [outcome]."
### Identifying Gaps
Compare vision to current work:
- **Underserved personas**: Which personas have few milestones/issues?
- **Unaddressed jobs**: Which jobs to be done have no work toward them?
- **Empty milestones**: Which milestones have no issues?
- **Stalled milestones**: Which milestones have no recent progress?
- **Orphan issues**: Are there issues without a milestone?
- **Orphan issues**: Issues without a milestone need justification
## Connecting Retros to Vision
After a retrospective:
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 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 → Milestones → Issues → Work → Retro → (Vision/Milestones updated)
Manifesto → Vision → Milestones → Issues → Work → Retro → (updates)
↓
Architecture repo issues
↓
Encoded into learnings +
skills/commands/agents
```
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
1. **Manifesto** defines organizational identity (very stable)
2. **Vision** defines product direction (stable)
3. **Milestones** define measurable goals (evolve)
4. **Issues** are work items toward goals
5. **Work** implements the issues
6. **Retros** create issues on architecture repo
7. **Encoding** turns insights into learnings and system improvements
The vision is stable. The milestones evolve as you learn and achieve goals.
---
## Quick Reference
| Question | Answer |
|----------|--------|
| Where do shared personas live? | `manifesto.md` in architecture repo |
| Where do product personas live? | `vision.md` in product repo |
| Where do beliefs live? | `manifesto.md` only (inherited) |
| Where do goals live? | Gitea milestones (per repo) |
| What command for org vision? | `/manifesto` |
| What command for product vision? | `/vision` |
| What repo for learnings? | Architecture repo |