architecture/skills/vision-management/SKILL.md

name, description

name	description
vision-management	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

# 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

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

## Who We Serve
- **Solo Developer**: Individual shipping side projects, time-constrained

Vision (product - e.g., CLI tool):

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

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