architecture/skills/vision-management/SKILL.md

---
name: vision-management
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.
user-invocable: 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

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

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):
```markdown
## Who We Serve
- **Agencies & Consultancies**: Teams building solutions for clients
```

**Vision** (product - architecture tooling):
```markdown
## 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

```bash
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) |