architecture/old/skills/vision-management/SKILL.md

name, model, description, user-invocable

name	model	description	user-invocable
vision-management	haiku	Create, maintain, and evolve organization manifesto and product visions. Use when working with manifesto.md, vision.md, milestones, or aligning work with organizational direction.	false

Vision Management

How to create, maintain, and evolve organizational direction at two levels: manifesto (organization) and vision (product).

Architecture

Level	Document	Purpose	Command	Location
Organization	manifesto.md	Identity, shared personas, beliefs, principles	/manifesto	../architecture/ (sibling repo)
Product	vision.md	Product-specific personas, jobs, solution	/vision	Product repo root
Goals	Gitea milestones	Measurable progress toward vision	/vision goals	Per repo

Product vision inherits from and extends the organization manifesto - it should never duplicate.

---

Manifesto (Organization Level)

The manifesto defines who we are as an organization. It lives in the architecture repo and applies across all products.

Manifesto Structure

# 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

# Vision

This product vision builds on the [organization manifesto](../architecture/manifesto.md).

## Who This Product Serves

### [Persona Name]

[Product-specific description]

*Extends: [Org persona] (from manifesto)*

## What They're Trying to Achieve

These trace back to organization-level jobs:

| Product Job | Enables Org Job |
|-------------|-----------------|
| "[Product-specific job]" | "[Org job from manifesto]" |

## The Problem

[Pain points this product addresses]

## The Solution

[How this product solves those problems]

## Product Principles

These extend the organization's guiding principles:

### [Principle Name]

[Description]

*Extends: "[Org principle]"*

## Non-Goals

These extend the organization's non-goals:

- **[Non-goal].** [Explanation]

## Architecture

This project follows organization architecture patterns (see software-architecture skill).

### Alignment
- [Which patterns we use and where]

### Intentional Divergences
| Area | Standard Pattern | What We Do Instead | Why |
|------|------------------|-------------------|-----|

When to Update Vision

• When product direction shifts
• When adding/changing personas served by this product
• When discovering new non-goals
• After major learnings from retros

Creating a Product Vision

1. Start with the manifesto - read it first
2. Define product personas that extend org personas
3. Identify product jobs that trace back to org jobs
4. Articulate the problem this product solves
5. Define the solution approach
6. Set product-specific principles (noting what they extend)
7. Document product non-goals
8. Create initial milestones

---

Inheritance Model

Manifesto (org)              Vision (product)
├── Personas            →    Product Personas (extend with specifics)
├── Jobs                →    Product Jobs (trace back to org jobs)
├── Beliefs             →    (inherited, never duplicated)
├── Principles          →    Product Principles (extend, note source)
└── Non-Goals           →    Product Non-Goals (additive)

Inheritance Rules

Component	Rule	Format
Personas	Extend with product-specific context	*Extends: [Org persona] (from manifesto)*
Jobs	Trace back to org-level jobs	Table with Product Job → Org Job columns
Beliefs	Inherited automatically	Never include in vision
Principles	Add product-specific, note what they extend	*Extends: "[Org principle]"*
Non-Goals	Additive	Org non-goals apply automatically

Example

Manifesto (organization):

## Who We Serve
- **Agencies & Consultancies**: Teams building solutions for clients

Vision (product - architecture tooling):

## Who This Product Serves

### Flowmade Developers

The team building Flowmade's platform. They need efficient, consistent AI workflows.

*Extends: Agencies & Consultancies (from manifesto) - we are our own first customer.*

The product persona extends the org persona with product-specific context and explicitly notes the connection.

---

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)
• Include success criteria in description

tea milestones create --title "Automate routine git workflows" \
  --description "For: Solo developer
Job: Ship without context switching to git commands
Success: /commit and /pr commands handle 80% of workflows"

Milestone-to-Vision Alignment

Every milestone should trace to:

• A persona (from vision, which extends manifesto)
• A job to be done (from vision, which traces to manifesto)
• A measurable outcome

---

Aligning Issues with Vision

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 milestone alignment: Does this issue support a goal?
4. Assign to milestone: Link the issue to the relevant goal

Every issue should trace back to: "This helps [persona] achieve [job] by [outcome]."

Identifying Gaps

• 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?
• Orphan issues: Issues without a milestone need justification

---

Continuous Improvement Loop

Manifesto → Vision → Milestones → Issues → Work → Retro → (updates)
                                                    ↓
                                          Architecture repo issues
                                                    ↓
                                          Encoded into learnings +
                                          skills/commands/agents

1. Manifesto defines organizational identity (very stable)
2. Vision defines product direction, extends manifesto (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

---

Quick Reference

Question	Answer
Where do shared personas live?	manifesto.md in architecture repo
Where do product personas live?	vision.md in product repo (extend org personas)
Where do beliefs live?	manifesto.md only (inherited, never duplicated)
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
How do product jobs relate to org jobs?	They trace back (show in table)
How do product principles relate?	They extend (note the source)