From c0ef16035ce3cb4f025fdf094895229c9de4f2e0 Mon Sep 17 00:00:00 2001 From: Hugo Nijhuis Date: Wed, 7 Jan 2026 20:24:28 +0100 Subject: [PATCH] Update /vision command for product-level only MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Clarifies /vision is for product-level vision, distinct from /manifesto which handles organization-level vision. Changes: - Added architecture table showing org vs product vs goals levels - Process now checks for manifesto first for org context - Output format includes Organization Context section - Guidelines clarify when to use /manifesto vs /vision - Product personas/jobs extend (not duplicate) org-level ones Closes #41 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 --- commands/vision.md | 90 ++++++++++++++++++++++++++-------------------- 1 file changed, 52 insertions(+), 38 deletions(-) diff --git a/commands/vision.md b/commands/vision.md index fe3cfb3..27c6a1d 100644 --- a/commands/vision.md +++ b/commands/vision.md @@ -8,47 +8,54 @@ argument-hint: [goals] @~/.claude/skills/vision-management/SKILL.md @~/.claude/skills/gitea/SKILL.md +This command manages **product-level** vision. For organization-level vision, use `/manifesto`. + ## Architecture -The vision system has two layers: +| 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` | -| Layer | Purpose | Location | -|-------|---------|----------| -| **vision.md** | North star philosophy (why, principles, non-goals) | File in repo root | -| **Milestones** | Goals with progress tracking | Gitea milestones | - -Issues are assigned to milestones. Progress is visible through milestone completion. +Product vision inherits from and extends the organization manifesto. ## Process -1. **Check for existing vision**: Look for `vision.md` in the current repo root. +1. **Check for organization manifesto**: Note if `manifesto.md` exists (provides org context) -2. **If no vision exists**: - - Ask the user if they want to create one +2. **Check for product vision**: Look for `vision.md` in the current repo root + +3. **If no vision exists**: + - Reference the organization manifesto if it exists + - Ask if the user wants to create a product vision - Guide them through defining: - 1. **Personas**: Who are we building for? (2-4 specific personas) - 2. **Jobs to be done**: What are they trying to achieve? - 3. **The problem**: What pain points exist today? - 4. **The solution**: How does this product address their jobs? - 5. **Guiding principles**: What beliefs guide decisions? - 6. **Non-goals**: What are we explicitly NOT doing? - - Create `vision.md` (do NOT include goals/progress - that's milestones) - - Ask about initial goals tied to personas/jobs, create as Gitea milestones + 1. **Product personas**: Who does this product serve? (may extend org personas) + 2. **Product jobs**: What specific jobs does this product address? + 3. **The problem**: What pain points does this product solve? + 4. **The solution**: How does this product address those jobs? + 5. **Product principles**: Any product-specific principles (beyond org principles)? + 6. **Product non-goals**: What is this product explicitly NOT doing? + - Create `vision.md` + - Ask about initial goals, create as Gitea milestones -3. **If vision exists**: - - Display the vision philosophy from `vision.md` +4. **If vision exists**: + - Display organization context (if manifesto exists) + - Display the product vision from `vision.md` - 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 -4. **Managing Goals (milestones)**: +5. **Managing Goals (milestones)**: ```bash # List milestones with progress tea milestones # Create a new goal - tea milestones create --title "" --description "" + tea milestones create --title "" --description "For: +Job: +Success: " # View issues in a milestone tea milestones issues @@ -60,37 +67,44 @@ Issues are assigned to milestones. Progress is visible through milestone complet ## Output Format ``` -## Who We Serve +## Organization Context -- **[Persona 1]**: [Brief description] -- **[Persona 2]**: [Brief description] +See manifesto for shared personas, beliefs, and principles. +[Link or note about manifesto.md location] -## What They're Trying to Achieve +## Product: [Name] -- "[Job to be done 1]" -- "[Job to be done 2]" +### Who This Product Serves -## Vision +- **[Persona 1]**: [Product-specific description] +- **[Persona 2]**: [Product-specific description] + +### What They're Trying to Achieve + +- "[Product-specific job 1]" +- "[Product-specific job 2]" + +### Product Vision [Summary of problem/solution from vision.md] -## Goals (Milestones) +### Goals (Milestones) | Goal | For | Progress | Due | |------|-----|----------|-----| | [title] | [Persona] | 3/5 issues | [date] | -## Current Focus +### Current Focus [Open milestones with nearest due dates or most activity] ``` ## Guidelines -- vision.md is the stable "why" and "who" document - update rarely -- Personas and jobs to be done are foundational - everything traces back to them -- Milestones are actionable goals - each should serve a specific persona's job -- Assign issues to milestones to track progress -- Use milestone descriptions for: persona, job, success criteria -- Due dates on milestones are optional but help prioritization -- If you can't tie work to a persona/job, question whether it should be done +- Product vision builds on organization manifesto - don't duplicate, extend +- Product personas can be more specific versions of org personas +- Product jobs should trace back to org-level jobs to be done +- Milestones are product-specific goals toward the vision +- Use `/manifesto` for organization-level identity and beliefs +- Use `/vision` for product-specific direction and goals +- If this is the architecture repo itself, use `/manifesto` instead