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

# 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 repo |
| **Product** | `vision.md` | Product-specific personas, jobs, solution | `/vision` | Product repos |
| **Goals** | Gitea milestones | Measurable progress toward vision | `/vision goals` | Per repo |

Product vision inherits from and extends the organization manifesto.

---

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

## Who This Product Serves
Product-specific personas (may extend org personas).
- **Persona Name**: Product-specific context

## What They're Trying to Achieve
Product-specific jobs to be done.
- "Help me [outcome] without [pain]"

## The Problem
Pain points this product addresses.

## The Solution
How this product solves those problems.

## Product Principles
Product-specific principles (beyond org principles).

## Non-Goals
What this product explicitly does NOT do.
```

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

---

## Relationship: Manifesto → Vision

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

### Inheritance Model

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

### Example

**Manifesto** (organization):
```markdown
## Who We Serve
- **Solo Developer**: Individual shipping side projects, time-constrained
```

**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)
- 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 or manifesto)
- A job to be done (from vision)
- 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 (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 |
| 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 |