architecture/commands/vision.md

---
description: View the product vision and goal progress. Manages vision.md and Gitea milestones.
argument-hint: [goals]
---

# Product Vision

@~/.claude/skills/vision-management/SKILL.md
@~/.claude/skills/gitea/SKILL.md

This command manages **product-level** vision. For organization-level vision, use `/manifesto`.

## Architecture

| Level | Document | Purpose | Command |
|-------|----------|---------|---------|
| **Organization** | `manifesto.md` | Who we are, shared personas, beliefs | `/manifesto` |
| **Product** | `vision.md` | Product-specific personas, jobs, solution | `/vision` |
| **Goals** | Gitea milestones | Measurable progress toward vision | `/vision goals` |

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

## Manifesto Location

The manifesto lives in the sibling `architecture` repo:

```
org/
├── architecture/
│   └── manifesto.md    ← organization manifesto
├── product-a/
│   └── vision.md       ← extends ../architecture/manifesto.md
└── product-b/
    └── vision.md
```

Look for manifesto in this order:
1. `./manifesto.md` (if this IS the architecture repo)
2. `../architecture/manifesto.md` (sibling repo)

## Process

1. **Load organization context**: Find and read `manifesto.md` using the location rules above
   - Extract personas (Who We Serve)
   - Extract jobs to be done (What They're Trying to Achieve)
   - Extract guiding principles
   - Extract non-goals
   - If not found, warn and continue without inheritance context

2. **Check for product vision**: Look for `vision.md` in the current repo root

3. **If no vision exists**:
   - Show the organization manifesto summary
   - Ask if the user wants to create a product vision
   - Guide them through defining (with inheritance):

     **Who This Product Serves**
     - Show manifesto personas first
     - Ask: "Which personas does this product serve? How does it extend or specialize them?"
     - Product personas should reference org personas with product-specific context

     **What They're Trying to Achieve**
     - Show manifesto jobs first
     - Ask: "What product-specific jobs does this enable? How do they trace back to org jobs?"
     - Use a table format showing the connection

     **The Problem**
     - What pain points does this product solve?

     **The Solution**
     - How does this product address those jobs?

     **Product Principles**
     - Show manifesto principles first
     - Ask: "Any product-specific principles? These should extend, not duplicate."
     - Each principle should note what org principle it extends

     **Product Non-Goals**
     - Show manifesto non-goals first
     - Ask: "Any product-specific non-goals?"
     - Org non-goals apply automatically

   - Create `vision.md` with proper inheritance markers
   - Ask about initial goals, create as Gitea milestones

4. **If vision exists**:
   - Display organization context summary
   - Display the product vision from `vision.md`
   - Validate inheritance (warn if vision duplicates rather than extends)
   - Show current milestones and their progress: `tea milestones`
   - Check if `$1` specifies an action:
     - `goals`: Manage milestones (add, close, view progress)
   - If no action specified, just display the current state

5. **Managing Goals (milestones)**:
   ```bash
   # List milestones with progress
   tea milestones

   # Create a new goal
   tea milestones create --title "<goal>" --description "For: <persona>
Job: <job to be done>
Success: <criteria>"

   # View issues in a milestone
   tea milestones issues <milestone-name>

   # Close a completed goal
   tea milestones close <milestone-name>
   ```

## Vision Structure Template

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

## Output Format

```
## Organization Context

From manifesto.md:
- **Personas**: [list from manifesto]
- **Core beliefs**: [key beliefs]
- **Principles**: [list]

## Product: [Name]

### Who This Product Serves

- **[Persona 1]**: [Product-specific description]
  ↳ Extends: [Org persona]

### What They're Trying to Achieve

| Product Job | → Org Job |
|-------------|-----------|
| [job] | [org job it enables] |

### Vision Summary

[Problem/solution from vision.md]

### Goals (Milestones)

| Goal | For | Progress | Due |
|------|-----|----------|-----|
| [title] | [Persona] | 3/5 issues | [date] |
```

## Inheritance Rules

- **Personas**: Product personas extend org personas with product-specific context
- **Jobs**: Product jobs trace back to org-level jobs (show the connection)
- **Beliefs**: Inherited from manifesto, never duplicated in vision
- **Principles**: Product adds specific principles that extend org principles
- **Non-Goals**: Product adds its own; org non-goals apply automatically

## Guidelines

- Product vision builds on organization manifesto - extend, don't duplicate
- Every product persona should reference which org persona it extends
- Every product job should show which org job it enables
- Product principles should note which org principle they extend
- Use `/manifesto` for organization-level identity and beliefs
- Use `/vision` for product-specific direction and goals