Update vision-management skill for manifesto vs vision distinction

Restructured skill to clearly distinguish:
- Manifesto: Organization-level (architecture repo)
- Vision: Product-level (product repos)

Key additions:
- Architecture table showing all three levels with commands
- Manifesto section with structure, when to update, creation steps
- Vision section clarified as product-level extending manifesto
- Relationship diagram showing inheritance model
- Example of persona inheritance (org → product)
- Continuous improvement loop including retro → encoding flow
- Quick reference table for common questions

Closes #43

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

commands/create-issue.md

@@ -28,13 +28,16 @@ If title provided:
 1. Create an issue with that title
 2. Ask for description
 3. Assign to appropriate milestone (see above)
+4. Ask if this issue depends on any existing issues
+5. If dependencies exist, link them: `tea issues deps add <new-issue> <blocker>`
 
 ## Batch Mode
 
 If $1 is "batch":
 1. Ask user for the plan/direction
 2. Fetch available milestones
-3. Generate list of issues with titles, descriptions, and milestone assignments
+3. Generate list of issues with titles, descriptions, milestone assignments, and dependencies
 4. Show for approval
-5. Create each issue with milestone
+5. Create each issue with milestone (in dependency order)
-6. Display all created issue numbers
+6. Link dependencies between created issues: `tea issues deps add <issue> <blocker>`
+7. Display all created issue numbers with dependency graph

commands/groom.md

@@ -11,23 +11,27 @@ argument-hint: [issue-number]
 
 ## If issue number provided ($1):
 
-1. **Fetch the issue** details
+1. **Fetch the issue** details with `tea issues <number> --comments`
-2. **Evaluate** against grooming checklist
+2. **Check dependencies** with `tea issues deps list <number>`
-3. **Suggest improvements** for:
+3. **Evaluate** against grooming checklist
+4. **Suggest improvements** for:
    - Title clarity
    - Description completeness
    - Acceptance criteria quality
    - Scope definition
-4. **Ask user** if they want to apply changes
+   - Missing or incorrect dependencies
-5. **Update issue** if approved
+5. **Ask user** if they want to apply changes
+6. **Update issue** if approved
+7. **Link/unlink dependencies** if needed: `tea issues deps add/remove <issue> <dep>`
 
 ## If no argument (groom all):
 
 1. **List open issues**
-2. **Review each** against grooming checklist
+2. **Review each** against grooming checklist (including dependencies)
 3. **Categorize**:
-   - Ready: Well-defined, can start work
+   - Ready: Well-defined, dependencies linked, can start work
-   - Needs work: Missing info or unclear
+   - Blocked: Has unresolved dependencies
+   - Needs work: Missing info, unclear, or missing dependency links
    - Stale: No longer relevant
-4. **Present summary** table
+4. **Present summary** table with dependency status
-5. **Offer to improve** issues that need work
+5. **Offer to improve** issues that need work (including linking dependencies)

commands/manifesto.md

@@ -0,0 +1,71 @@
+---
+description: View and manage the organization manifesto. Shows identity, personas, beliefs, and principles.
+---
+
+# Organization Manifesto
+
+@~/.claude/skills/vision-management/SKILL.md
+
+The manifesto defines the organization-level vision: who we are, who we serve, what we believe, and how we work. It is distinct from product-level vision (see `/vision`).
+
+## Process
+
+1. **Check for manifesto**: Look for `manifesto.md` in the current repo root.
+
+2. **If no manifesto exists**:
+   - Ask if the user wants to create one
+   - Guide through defining:
+     1. **Who We Are**: Organization identity
+     2. **Who We Serve**: 2-4 specific personas with context and constraints
+     3. **What They're Trying to Achieve**: Jobs to be done in their voice
+     4. **What We Believe**: Core beliefs including stance on AI-augmented development
+     5. **Guiding Principles**: Decision-making rules
+     6. **Non-Goals**: What we explicitly don't do
+   - Create `manifesto.md`
+
+3. **If manifesto exists**:
+   - Display formatted summary of the manifesto
+
+## Output Format
+
+When displaying an existing manifesto:
+
+```
+## Who We Are
+
+[Identity summary from manifesto]
+
+## Who We Serve
+
+- **[Persona 1]**: [Brief description]
+- **[Persona 2]**: [Brief description]
+- **[Persona 3]**: [Brief description]
+
+## What They're Trying to Achieve
+
+- "[Job to be done 1]"
+- "[Job to be done 2]"
+- "[Job to be done 3]"
+
+## What We Believe
+
+[Summary of key beliefs - especially AI-augmented development stance]
+
+## Guiding Principles
+
+1. [Principle 1]
+2. [Principle 2]
+3. [Principle 3]
+
+## Non-Goals
+
+- [Non-goal 1]
+- [Non-goal 2]
+```
+
+## Guidelines
+
+- The manifesto is the **organization-level** document - it applies across all products
+- Update rarely - this is foundational identity, not tactical direction
+- Product repos reference the manifesto but have their own `vision.md`
+- Use `/vision` for product-level vision management

commands/plan-issues.md

@@ -10,39 +10,41 @@ argument-hint: <feature-description>
 @~/.claude/skills/issue-writing/SKILL.md
 @~/.claude/skills/vision-management/SKILL.md
 
-1. **Check vision context**: If `vision.md` exists, read it to understand current goals and focus
+1. **Check vision context**: If `vision.md` exists, read it to understand personas, jobs to be done, and goals
-2. **Understand the feature**: Analyze what "$1" involves
+2. **Identify persona**: Which persona does "$1" serve?
-3. **Explore the codebase** if needed to understand context
+3. **Identify job**: Which job to be done does this enable?
-4. **Break down** into discrete, actionable issues:
+4. **Understand the feature**: Analyze what "$1" involves
+5. **Explore the codebase** if needed to understand context
+6. **Break down** into discrete, actionable issues:
    - Each issue should be independently completable
    - Clear dependencies between issues
    - Appropriate scope (not too big, not too small)
 
-5. **Present the plan** (include vision alignment if vision exists):
+7. **Present the plan** (include vision alignment if vision exists):
    ```
    ## Proposed Issues for: $1
 
-   Vision Alignment: Supports [Goal N: description]
+   For: [Persona name]
+   Job: "[Job to be done this enables]"
+   Supports: [Milestone/Goal name]
 
    1. [Title] - Brief description
       Dependencies: none
-      Supports: Goal N
 
    2. [Title] - Brief description
       Dependencies: #1
-      Supports: Goal N
 
    3. [Title] - Brief description
       Dependencies: #1, #2
-      Supports: Goal N
    ```
 
-   If the feature doesn't align with any vision goal, note this and ask if:
+   If the feature doesn't align with any persona/job/goal, note this and ask if:
-   - The vision should be updated to include this as a goal
+   - A new persona or job should be added to the vision
+   - A new milestone should be created
    - This should be added as a non-goal
    - Proceed anyway (with justification)
 
-6. **Ask for approval** before creating issues
+8. **Ask for approval** before creating issues
-7. **Create issues** in order
+9. **Create issues** in dependency order (blockers first)
-8. **Update dependencies** with actual issue numbers after creation
+10. **Link dependencies** using `tea issues deps add <issue> <blocker>` for each dependency
-9. **Present summary** with links to created issues
+11. **Present summary** with links to created issues and dependency graph

commands/retro.md

@@ -1,13 +1,22 @@
 ---
-description: Run a retrospective on completed work. Captures learnings, creates improvement issues, and updates product vision.
+description: Run a retrospective on completed work. Captures insights as issues for later encoding into skills/commands/agents.
 argument-hint: [task-description]
 ---
 
 # Retrospective
 
-Capture learnings from completed AI-assisted work to improve the workflow and refine the product vision.
+Capture insights from completed work as issues on the architecture repo. Issues are later encoded into learnings and skills/commands/agents.
 
 @~/.claude/skills/vision-management/SKILL.md
+@~/.claude/skills/gitea/SKILL.md
+
+## Flow
+
+```
+Retro (any repo) → Issue (architecture repo) → Encode: learning file + skill/command/agent
+```
+
+The retro creates the issue. Encoding happens when the issue is worked on.
 
 ## Process
 
@@ -18,75 +27,90 @@ Capture learnings from completed AI-assisted work to improve the workflow and re
    - What worked well?
    - Any specific improvement ideas?
 
-3. **Analyze and categorize**: Group learnings into:
+3. **Identify insights**: For each insight, determine:
-   - **Prompt improvements**: Better instructions for commands/skills
+   - **What was learned**: The specific insight
-   - **Missing capabilities**: New commands or skills needed
+   - **Where to encode it**: Which skill, command, or agent should change?
-   - **Tool issues**: Problems with tea CLI, git, or other tools
+   - **Governance impact**: What does this mean for how we work?
-   - **Context gaps**: Missing documentation or skills
 
-4. **Connect to vision** (if `vision.md` exists in the target repo):
+4. **Create issue on architecture repo**: Always create issues on `flowmade-one/ai`:
-   - Did this work make progress on any vision goals?
-   - Did learnings reveal new priorities that should become goals?
-   - Did we discover something that should be a non-goal?
-   - Should the current focus shift based on what we learned?
-
-   If any vision updates are needed:
-   - Present suggested changes to `vision.md`
-   - Ask for approval
-   - Update the vision file and sync to Gitea
-
-5. **Generate improvement issues**: For each actionable improvement:
-   - Determine the appropriate milestone (see Milestone Categorization below)
-   - Create an issue in the AI repo with the milestone assigned:
 
    ```bash
-tea issues create -r flowmade-one/ai --title "<title>" --description "<body>" --milestone "<milestone>"
+   tea issues create -r flowmade-one/ai \
+     --title "[Learning] <brief description>" \
+     --description "## Context
+   [Task that triggered this insight]
+
+   ## Insight
+   [The specific learning - be concrete and actionable]
+
+   ## Suggested Encoding
+   - [ ] \`skills/xxx/SKILL.md\` - [what to add/change]
+   - [ ] \`commands/xxx.md\` - [what to add/change]
+   - [ ] \`agents/xxx/agent.md\` - [what to add/change]
+
+   ## Governance
+   [What this means for how we work going forward]"
    ```
 
-## Milestone Assignment
+5. **Connect to vision**: Check if insight affects vision:
+   - **Architecture repo**: Does this affect `manifesto.md`? (beliefs, principles, non-goals)
+   - **Product repo**: Does this affect `vision.md`? (product direction, goals)
 
-Before creating issues, fetch available milestones:
+   If vision updates are needed, present suggested changes and ask for approval.
 
-```bash
+## When the Issue is Worked On
-tea milestones -f title,description
-```
 
-For each issue, automatically assign to the most relevant milestone by matching:
+When encoding a learning issue, the implementer should:
-- Issue content/problem area → Milestone title and description
-- If no clear match, ask the user which milestone (goal) the issue supports
-- If no milestones exist, skip milestone assignment
 
-## Issue Format
+1. **Create learning file**: `learnings/YYYY-MM-DD-short-title.md`
-
-Use this structure for retrospective issues:
 
    ```markdown
-## Context
+   # [Learning Title]
-What task triggered this learning (brief).
 
-## Problem / Observation
+   **Date**: YYYY-MM-DD
-What was the friction point or insight.
+   **Context**: [Task that triggered this learning]
+   **Issue**: #XX
 
-## Suggested Improvement
+   ## Learning
-Concrete, actionable change to make.
 
-## Affected Files
+   [The specific insight]
-- commands/xxx.md
+
-- skills/xxx/SKILL.md
+   ## Encoded In
+
+   - `skills/xxx/SKILL.md` - [what was added/changed]
+   - `commands/xxx.md` - [what was added/changed]
+
+   ## Governance
+
+   [What this means for how we work]
    ```
 
+2. **Update skill/command/agent** with the encoded knowledge
+
+3. **Close the issue** with reference to the learning file and changes made
+
+## Encoding Destinations
+
+| Insight Type | Encode In |
+|--------------|-----------|
+| How to use a tool | `skills/[tool]/SKILL.md` |
+| Workflow improvement | `commands/[command].md` |
+| Subtask behavior | `agents/[agent]/agent.md` |
+| Organization belief | `manifesto.md` |
+| Product direction | `vision.md` (in product repo) |
+
 ## Labels
 
-Add appropriate labels:
+Add appropriate labels to issues:
-- `retrospective` - Always add this
+- `learning` - Always add this
 - `prompt-improvement` - For command/skill text changes
-- `new-feature` - For new commands/skills
+- `new-feature` - For new commands/skills/agents
 - `bug` - For things that are broken
 
 ## Guidelines
 
-- Be specific and actionable - vague issues won't get fixed
+- **Always create issues on architecture repo** - regardless of which repo the retro runs in
-- One issue per improvement (don't bundle unrelated things)
+- **Be specific**: Vague insights can't be encoded
-- Reference specific commands/skills when relevant
+- **One issue per insight**: Don't bundle unrelated things
-- Keep issues small and focused
+- **Encoding happens later**: Retro captures the issue, encoding is separate work
-- Skip creating issues for one-off edge cases that won't recur
+- **Skip one-offs**: Don't capture insights for edge cases that won't recur

commands/vision.md

@@ -8,41 +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 |
+Product vision inherits from and extends the organization manifesto.
-|-------|---------|----------|
-| **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.
 
 ## 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**:
+2. **Check for product vision**: Look for `vision.md` in the current repo root
-   - Ask the user if they want to create one
-   - Guide them through the philosophy: purpose, principles, non-goals
-   - Create `vision.md` (do NOT include goals/progress - that's milestones)
-   - Ask about initial goals and create them as Gitea milestones
 
-3. **If vision exists**:
+3. **If no vision exists**:
-   - Display the vision philosophy from `vision.md`
+   - Reference the organization manifesto if it exists
+   - Ask if the user wants to create a product vision
+   - Guide them through defining:
+     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
+
+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 "<goal>" --description "<success criteria>"
+   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>
@@ -54,25 +67,44 @@ Issues are assigned to milestones. Progress is visible through milestone complet
 ## Output Format
 
 ```
-## Vision
+## Organization Context
 
-[Summary of vision.md purpose/principles]
+See manifesto for shared personas, beliefs, and principles.
+[Link or note about manifesto.md location]
 
-## Goals (Milestones)
+## Product: [Name]
 
-| Goal | Progress | Due |
+### Who This Product Serves
-|------|----------|-----|
-| [title] | 3/5 issues | [date] |
 
-## Current Focus
+- **[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)
+
+| Goal | For | Progress | Due |
+|------|-----|----------|-----|
+| [title] | [Persona] | 3/5 issues | [date] |
+
+### Current Focus
 
 [Open milestones with nearest due dates or most activity]
 ```
 
 ## Guidelines
 
-- vision.md is the stable "why" document - update rarely
+- Product vision builds on organization manifesto - don't duplicate, extend
-- Milestones are the actionable goals - create/close as needed
+- Product personas can be more specific versions of org personas
-- Assign issues to milestones to track progress
+- Product jobs should trace back to org-level jobs to be done
-- Use milestone descriptions for success criteria
+- Milestones are product-specific goals toward the vision
-- Due dates on milestones are optional but help prioritization
+- 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

learnings/README.md

@@ -0,0 +1,88 @@
+# Learnings
+
+This folder captures learnings from retrospectives and day-to-day work. Learnings serve three purposes:
+
+1. **Historical record**: What we learned and when
+2. **Governance reference**: Why we work the way we do
+3. **Encoding source**: Input that gets encoded into skills, commands, and agents
+
+## The Learning Flow
+
+```
+Experience → Learning captured → Encoded into system → Knowledge is actionable
+                   ↓
+            Stays here for:
+            - Historical reference
+            - Governance validation
+            - Periodic review
+```
+
+Learnings are **not** the final destination. They are inputs that get encoded into commands, skills, and agents where Claude can actually use them. But we keep the learning file as a record of *why* we encoded what we did.
+
+## Writing a Learning
+
+Create a new file: `YYYY-MM-DD-short-title.md`
+
+Use this template:
+
+```markdown
+# [Title]
+
+**Date**: YYYY-MM-DD
+**Context**: What triggered this learning (task, incident, observation)
+
+## Learning
+
+The insight we gained. Be specific and actionable.
+
+## Encoded In
+
+Where this learning has been (or will be) encoded:
+
+- `skills/xxx/SKILL.md` - What was added/changed
+- `commands/xxx.md` - What was added/changed
+- `agents/xxx/agent.md` - What was added/changed
+
+If not yet encoded, note: "Pending: Issue #XX"
+
+## Governance
+
+What this learning means for how we work going forward. This is the "why" that justifies the encoding.
+```
+
+## Encoding Process
+
+1. **Capture the learning** in this folder
+2. **Create an issue** to encode it into the appropriate location
+3. **Update the skill/command/agent** with the encoded knowledge
+4. **Update the learning file** with the "Encoded In" references
+
+The goal: Claude should be able to *use* the learning, not just *read* about it.
+
+## What Gets Encoded Where
+
+| Learning Type | Encode In |
+|---------------|-----------|
+| How to use a tool | `skills/` |
+| Workflow improvement | `commands/` |
+| Subtask behavior | `agents/` |
+| Organization belief | `manifesto.md` |
+| Product direction | `vision.md` (in product repo) |
+
+## Periodic Review
+
+Periodically review learnings to:
+
+- Verify encoded locations still reflect the learning
+- Check if governance is still being followed
+- Identify patterns across multiple learnings
+- Archive or update outdated learnings
+
+## Naming Convention
+
+Files follow the pattern: `YYYY-MM-DD-short-kebab-title.md`
+
+Examples:
+- `2024-01-15-always-use-comments-flag.md`
+- `2024-01-20-verify-before-cleanup.md`
+- `2024-02-01-small-prs-merge-faster.md`

manifesto.md

@@ -0,0 +1,78 @@
+# Manifesto
+
+## Who We Are
+
+We are a small, focused team of AI-native builders. We believe the future of software development is human-AI collaboration, and we're building the tools and practices to make that real.
+
+We move fast with intention. We value quality over quantity. We encode our knowledge into systems that amplify what we can accomplish.
+
+## Who We Serve
+
+### Solo Developer
+The individual shipping side projects, MVPs, or freelance work. Time is their scarcest resource. They context-switch between coding, design, ops, and everything else. They need to move fast without sacrificing quality, and they can't afford to remember every command or best practice.
+
+### Small Team (2-5 people)
+The startup or small product team that needs to punch above their weight. They don't have dedicated specialists for every function. They need consistency across contributors and visibility into what's happening without heavyweight process.
+
+### Agency / Consultancy
+Building for clients under deadlines. They need speed, consistency, and the ability to apply learnings across projects. Every efficiency gain multiplies across engagements.
+
+## What They're Trying to Achieve
+
+- "Help me ship without getting bogged down in repetitive tasks"
+- "Help me maintain quality without slowing down"
+- "Help me know what to work on next without checking multiple tools"
+- "Help me apply best practices without memorizing them"
+- "Help me onboard to codebases faster"
+- "Help me stay in flow instead of context-switching"
+
+## What We Believe
+
+### AI-Augmented Development
+
+We believe AI fundamentally changes how software is built:
+
+- **Developers become orchestrators.** The role shifts from writing every line to directing, reviewing, and refining. The human provides judgment, context, and intent. AI handles execution and recall.
+
+- **Repetitive tasks should be automated.** If you do something more than twice, encode it. Commits, PR creation, issue management, code review - these should flow, not interrupt.
+
+- **AI amplifies individuals.** A solo developer with good AI tooling can accomplish what used to require a team. Small teams can tackle problems that used to need departments.
+
+- **Knowledge belongs in systems, not heads.** Best practices, patterns, and learnings should be encoded where AI can apply them. Tribal knowledge is a liability.
+
+- **Iteration speed is a competitive advantage.** The faster you can go from idea to deployed code to learning, the faster you improve. AI collapses the feedback loop.
+
+### Quality Without Ceremony
+
+- Ship small, ship often
+- Automate verification, not just generation
+- Good defaults beat extensive configuration
+- Working software over comprehensive documentation
+
+### Sustainable Pace
+
+- Tools should reduce cognitive load, not add to it
+- Automation should free humans for judgment calls
+- The goal is flow, not burnout
+
+## Guiding Principles
+
+1. **Encode, don't document.** If something is important enough to write down, it's important enough to encode into a skill, command, or agent that can act on it.
+
+2. **Small teams, big leverage.** Design for amplification. Every tool, pattern, and practice should multiply what individuals can accomplish.
+
+3. **Opinionated defaults, escape hatches available.** Make the right thing easy. Make customization possible but not required.
+
+4. **Learn in public.** Capture learnings. Update the system. Share what works.
+
+5. **Ship to learn.** Prefer shipping something imperfect and learning from reality over planning for perfection.
+
+## Non-Goals
+
+- **Building for enterprises with complex compliance needs.** We optimize for speed and small teams, not audit trails and approval workflows.
+
+- **Supporting every tool and platform.** We go deep on our chosen stack rather than shallow on everything.
+
+- **Replacing developer judgment.** AI augments human decision-making; it doesn't replace it. Critical thinking, architecture decisions, and user empathy remain human responsibilities.
+
+- **Comprehensive documentation for its own sake.** We encode knowledge into actionable systems. Docs exist to explain the "why," not to duplicate what the system already does.

skills/backlog-grooming/SKILL.md

@@ -33,10 +33,18 @@ For each issue, verify:
 - [ ] Clear boundaries (what's included/excluded)
 
 ### 5. Dependencies
-- [ ] Dependencies identified
+- [ ] Dependencies identified in description
+- [ ] Dependencies formally linked (`tea issues deps list <number>`)
 - [ ] No circular dependencies
 - [ ] Blocking issues are tracked
 
+To check/fix dependencies:
+```bash
+tea issues deps list <number>           # View current dependencies
+tea issues deps add <issue> <blocker>   # Add missing dependency
+tea issues deps remove <issue> <dep>    # Remove incorrect dependency
+```
+
 ### 6. Labels
 - [ ] Type label (bug/feature/etc)
 - [ ] Priority if applicable

skills/gitea/SKILL.md

@@ -70,6 +70,13 @@ tea issues reopen <number>
 
 # Labels
 tea issues edit <number> --labels "bug,help wanted"
+
+# Dependencies
+tea issues deps list <number>              # List blockers for an issue
+tea issues deps add <issue> <blocker>      # Add dependency (issue is blocked by blocker)
+tea issues deps add 5 3                    # Issue #5 depends on #3
+tea issues deps add 5 owner/repo#3         # Cross-repo dependency
+tea issues deps remove <issue> <blocker>   # Remove a dependency
 ```
 
 ### Pull Requests

skills/issue-writing/SKILL.md

@@ -104,7 +104,19 @@ Use labels to categorize:
 
 ## Dependencies
 
-Reference related issues:
+Identify and link dependencies when creating issues:
-- "Depends on #N" - Must complete first
+
-- "Blocks #N" - This blocks another
+1. **In the description**, document dependencies:
-- "Related to #N" - Informational link
+   ```markdown
+   ## Dependencies
+   - Depends on #12 (must complete first)
+   - Related to #15 (informational)
+   ```
+
+2. **After creating the issue**, formally link blockers using tea CLI:
+   ```bash
+   tea issues deps add <this-issue> <blocker-issue>
+   tea issues deps add 5 3    # Issue #5 is blocked by #3
+   ```
+
+This creates a formal dependency graph that tools can query.

skills/roadmap-planning/SKILL.md

@@ -80,6 +80,13 @@ In issue descriptions:
 - Depends on #13 (API setup)
 ```
 
+After creating issues, formally link dependencies:
+```bash
+tea issues deps add <issue> <blocker>
+tea issues deps add 14 12    # Issue #14 depends on #12
+tea issues deps add 14 13    # Issue #14 depends on #13
+```
+
 ## Creating Issues
 
 Use the gitea skill for issue operations.

skills/vision-management/SKILL.md

@@ -1,143 +1,240 @@
 ---
 name: vision-management
-description: Create, maintain, and evolve a product vision. Use when initializing a vision, updating goals, aligning work with vision, or connecting learnings to vision refinement.
+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 a product vision for continuous improvement.
+How to create, maintain, and evolve organizational direction at two levels: manifesto (organization) and vision (product).
 
 ## Architecture
 
-The vision system has two layers:
+| 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 |
 
-| Layer | Purpose | Location |
+Product vision inherits from and extends the organization manifesto.
-|-------|---------|----------|
-| **vision.md** | North star philosophy (why, principles, non-goals) | File in repo root |
-| **Milestones** | Goals with progress tracking | Gitea milestones |
 
-- **vision.md** is stable - updated rarely when direction changes
+---
-- **Milestones** are actionable - created/closed as goals evolve
-- **Issues** are assigned to milestones to track progress
 
-## Vision Document Structure
+## Manifesto (Organization Level)
 
-The vision.md file should contain the stable "why" - not progress tracking:
+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
-What problem does this product solve? Who benefits?
+Pain points this product addresses.
 
 ## The Solution
-How does this product solve the problem?
+How this product solves those problems.
 
-## Guiding Principles
+## Product Principles
-Core beliefs that guide decisions.
+Product-specific principles (beyond org principles).
 
 ## Non-Goals
-What we're explicitly NOT doing.
+What this product explicitly does NOT do.
 ```
 
-Do NOT include goals, progress, or focus in vision.md - that's what milestones are for.
+### When to Update Vision
 
-## Creating a Vision
+- When product direction shifts
+- When adding/changing personas served by this product
+- When discovering new non-goals
+- After major learnings from retros
 
-When no vision exists:
+### Creating a Product Vision
 
-1. **Identify the problem**: What pain point does this solve?
+1. Reference the organization manifesto
-2. **Define the solution**: How does the product address it?
+2. Define product-specific personas (can extend org personas)
-3. **Set guiding principles**: What beliefs guide decisions?
+3. Identify product-specific jobs to be done
-4. **Document non-goals**: What are you explicitly NOT doing?
+4. Articulate the problem this product solves
-5. **Create initial milestones**: 3-5 measurable goals
+5. Define the solution approach
+6. Set product-specific principles (if any)
+7. Document product non-goals
+8. Create initial milestones
 
-### Good Goals (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)
-- Have clear success criteria in the description
+- Include success criteria in description
-
-| Bad | Good |
-|-----|------|
-| "Improve performance" | "Page load under 2 seconds" |
-| "Better UX" | "User can complete checkout in under 60 seconds" |
-| "More features" | "Support 3 export formats (CSV, JSON, PDF)" |
-
-## Managing Goals with Milestones
 
 ```bash
-# List milestones with progress
+tea milestones create --title "Automate routine git workflows" \
-tea milestones
+  --description "For: Solo developer
-tea milestones -f title,items_open,items_closed,state
+Job: Ship without context switching to git commands
-
+Success: /commit and /pr commands handle 80% of workflows"
-# Create a new goal
-tea milestones create --title "Automate repetitive workflows" \
-  --description "Success: 80% of routine tasks handled by slash commands"
-
-# View issues in a milestone
-tea milestones issues "Automate repetitive workflows"
-
-# Close a completed goal
-tea milestones close "Automate repetitive workflows"
 ```
 
-### Assigning Issues to Milestones
+### Milestone-to-Vision Alignment
 
-When creating issues, assign them to the relevant milestone:
+Every milestone should trace to:
+- A persona (from vision or manifesto)
+- A job to be done (from vision)
+- A measurable outcome
 
-```bash
+---
-tea issues create --title "Add /commit command" \
-  --description "..." \
-  --milestone "Automate repetitive workflows"
-```
-
-Progress is automatically tracked through open/closed issue counts.
 
 ## Aligning Issues with Vision
 
 When creating or reviewing issues:
 
-1. **Check goal alignment**: Does this issue support a milestone?
+1. **Check persona alignment**: Which persona does this serve?
-2. **Assign to milestone**: Link the issue to the relevant goal
+2. **Check job alignment**: Which job to be done does this enable?
-3. **Prioritize by focus**: Issues in priority milestones get worked first
+3. **Check milestone alignment**: Does this issue support a goal?
-4. **Flag misalignment**: Issues without a milestone need justification
+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
 
-Compare milestones to current backlog:
+- **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
 
-- Which milestones have no issues?
+---
-- Which milestones have stalled (no recent progress)?
-- Are there issues without a milestone?
-
-## Connecting Retros to Vision
-
-After a retrospective:
-
-1. **Review learnings**: Any that affect the vision or goals?
-2. **Milestone changes**: Should any goals be added, closed, or modified?
-3. **Non-goal additions**: Did we learn something to add to vision.md?
-4. **Progress check**: Did completed work close any milestones?
-
-### Retro-to-Vision Questions
-
-- "Did this work reveal a new goal we should add as a milestone?"
-- "Did we learn something that should become a non-goal in vision.md?"
-- "Should we close or modify any milestones based on what we learned?"
-- "Are any milestones ready to close?"
 
 ## Continuous Improvement Loop
 
 ```
-Vision → Milestones → Issues → Work → Retro → (Vision/Milestones updated)
+Manifesto → Vision → Milestones → Issues → Work → Retro → (updates)
+                                                    ↓
+                                          Architecture repo issues
+                                                    ↓
+                                          Encoded into learnings +
+                                          skills/commands/agents
 ```
 
-1. **Vision** defines why and principles (stable)
+1. **Manifesto** defines organizational identity (very stable)
-2. **Milestones** define measurable goals
+2. **Vision** defines product direction (stable)
-3. **Issues** are work items toward those goals
+3. **Milestones** define measurable goals (evolve)
-4. **Work** implements the issues
+4. **Issues** are work items toward goals
-5. **Retros** capture learnings
+5. **Work** implements the issues
-6. **Updates** refine vision and create/close milestones
+6. **Retros** create issues on architecture repo
+7. **Encoding** turns insights into learnings and system improvements
 
-The vision is stable. The milestones evolve as you learn and achieve goals.
+---
+
+## 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 |