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>

CLAUDE.md

@@ -16,8 +16,8 @@ make install
 ```
 ai/
 ├── commands/       # Slash commands (/work-issue, /dashboard)
-├── skills/         # Auto-triggered capabilities
+├── skills/         # Knowledge modules (auto-triggered)
-├── agents/         # Subagents with isolated context
+├── agents/         # Focused subtask handlers (isolated context)
 ├── scripts/        # Hook scripts (pre-commit, token loading)
 ├── settings.json   # Claude Code settings
 └── Makefile        # Install/uninstall symlinks
@@ -25,6 +25,42 @@ ai/
 
 All files symlink to `~/.claude/` via `make install`.
 
+## Architecture
+
+### Skills
+Knowledge modules that teach Claude how to do something. Referenced by commands via `@~/.claude/skills/xxx/SKILL.md`.
+
+- **Purpose**: Encode best practices and tool knowledge
+- **Location**: `skills/<name>/SKILL.md`
+- **Usage**: Included in commands for context, auto-triggered by Claude Code
+
+Example: `gitea` skill teaches tea CLI usage, `issue-writing` teaches how to structure issues.
+
+### Commands
+User-facing entry points invoked with `/command-name`. Run in main conversation context.
+
+- **Purpose**: Orchestrate workflows with user interaction
+- **Location**: `commands/<name>.md`
+- **Usage**: User types `/dashboard`, `/work-issue 42`, etc.
+
+Commands reference skills for knowledge and optionally spawn agents for subtasks.
+
+### Agents
+Small, focused units that handle specific subtasks in isolated context.
+
+- **Purpose**: Complex subtasks that benefit from isolation
+- **Location**: `agents/<name>/agent.md`
+- **Usage**: Spawned via Task tool, return results to caller
+
+Good agent candidates:
+- Code review (analyze diff, report issues)
+- Content generation (write issue body, PR description)
+- Analysis tasks (categorize, prioritize, summarize)
+
+**When to use agents vs direct execution:**
+- Use agents when: task is self-contained, benefits from isolation, can run in parallel
+- Use direct execution when: task needs conversation history, requires user interaction mid-task
+
 ## Gitea Integration
 
 Uses `tea` CLI for issue/PR management:
@@ -37,7 +73,7 @@ tea logins add --name flowmade --url https://git.flowmade.one --token <your-toke
 # Create token at: https://git.flowmade.one/user/settings/applications
 ```
 
-### Available Commands
+## Available Commands
 
 | Command | Description |
 |---------|-------------|
@@ -45,8 +81,11 @@ tea logins add --name flowmade --url https://git.flowmade.one --token <your-toke
 | `/dashboard` | Show open issues and PRs |
 | `/review-pr <n>` | Review PR with diff and comments |
 | `/create-issue` | Create single or batch issues |
-| `/retro` | Capture learnings from completed work, create improvement issues |
+| `/retro` | Capture learnings, create improvement issues |
+| `/vision` | View/manage product vision and milestones |
+| `/plan-issues` | Break down features into issues |
+| `/improve` | Identify gaps between vision and backlog |
 
-## Usage
+## Vision & Goals
 
-This project is meant to be used alongside Claude Code to enhance productivity and maintain consistent workflows.
+Product vision lives in `vision.md` (philosophy) and Gitea milestones (goals with progress tracking). See `/vision` command.

VISION.md

@@ -36,14 +36,21 @@ Skills don't do anything on their own. They're building blocks.
 
 ### Agents
 
-Agents combine multiple skills into specialized personas that can work autonomously.
+Agents are small, focused units that handle specific subtasks in isolated context.
 
-The `product-manager` agent combines issue-writing, backlog-grooming, and roadmap-planning skills to handle complex PM tasks. It can explore the codebase, plan features, and create well-structured issues—all with isolated context so it doesn't pollute the main conversation.
+Unlike commands (which run in the main conversation), agents are spawned via the Task tool to do a specific job and report back. They should be:
+- **Small and focused**: One clear responsibility
+- **Isolated**: Work without needing conversation history
+- **Result-oriented**: Return a specific output (analysis, categorization, generated content)
+
+Examples:
+- `code-reviewer`: Reviews a PR diff and reports issues
+- A hypothetical `categorize-milestone`: Given an issue, determines which milestone it belongs to
 
 Agents enable:
 - **Parallel processing**: Multiple agents can work simultaneously
-- **Context preservation**: Each agent maintains its own focused context
+- **Context isolation**: Complex subtasks don't pollute the main conversation
-- **Complex workflows**: Combine skills for multi-step tasks
+- **Reusability**: Same agent can be spawned by different commands
 
 ### Commands
 
@@ -51,11 +58,12 @@ Commands are the user-facing entry points—what you actually invoke.
 
 When you run `/plan-issues add dark mode`, the command:
 1. Understands what you're asking for
-2. Invokes the right agents and skills
+2. References skills for knowledge (how to write issues, use Gitea, etc.)
-3. Guides you through the workflow with approvals
+3. Optionally spawns agents for complex subtasks
-4. Takes action (creates issues, PRs, etc.)
+4. Guides you through the workflow with approvals
+5. Takes action (creates issues, PRs, etc.)
 
-Commands make the power of skills and agents accessible through simple invocations.
+Commands run in the main conversation context, using skills for knowledge and spawning agents only when isolated processing is beneficial.
 
 ## Target Users
 

agents/code-reviewer/AGENT.md

@@ -13,7 +13,7 @@ You are a code review specialist that provides immediate, structured feedback on
 
 You will receive a PR number to review. Follow this process:
 
-1. Fetch PR diff using `tea pulls <number> -f diff`
+1. Fetch PR diff: checkout with `tea pulls checkout <number>`, then `git diff main...HEAD`
 2. Analyze the diff for issues in these categories:
    - **Code Quality**: Readability, maintainability, complexity
    - **Bugs**: Logic errors, edge cases, null checks
@@ -22,7 +22,7 @@ You will receive a PR number to review. Follow this process:
    - **Test Coverage**: Missing tests, untested edge cases
 3. Generate a structured review comment
 4. Post the review using `tea comment <number> "<review body>"`
-5. **If verdict is LGTM**: Approve with `tea pulls approve <number>`, then auto-merge with `tea pulls merge <number> --style rebase`
+5. **If verdict is LGTM**: Merge with `tea pulls merge <number> --style rebase`
 6. **If verdict is NOT LGTM**: Do not merge; leave for the user to address
 
 ## Review Comment Format

agents/product-manager/AGENT.md

@@ -1,26 +0,0 @@
----
-name: product-manager
-description: Backlog management and roadmap planning specialist. Use for batch issue operations, comprehensive backlog reviews, or feature planning that requires codebase exploration.
-# Model: sonnet handles planning and issue-writing well.
-# Tasks follow structured patterns from skills; opus not required.
-model: sonnet
-skills: gitea, issue-writing, backlog-grooming, roadmap-planning
----
-
-You are a product manager specializing in backlog management and roadmap planning.
-
-## Capabilities
-
-You can:
-- Review and improve existing issues
-- Create new well-structured issues
-- Analyze the backlog for gaps and priorities
-- Plan feature breakdowns
-- Maintain roadmap clarity
-
-## Behavior
-
-- Always fetch current issue state before making changes
-- Ask for approval before creating or modifying issues
-- Provide clear summaries of actions taken
-- Use the gitea skill for all issue/PR operations

commands/create-issue.md

@@ -5,15 +5,39 @@ argument-hint: [title] or "batch"
 
 # Create Issue(s)
 
-Use the gitea skill.
+@~/.claude/skills/gitea/SKILL.md
+
+## Milestone Assignment
+
+Before creating issues, fetch available milestones:
+
+```bash
+tea milestones -f title,description
+```
+
+For each issue, automatically assign to the most relevant milestone by matching:
+- 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
+
+Include `--milestone "<milestone>"` in the create command when a milestone is assigned.
 
 ## Single Issue (default)
-If title provided, create an issue with that title and ask for description.
+
+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. Generate list of issues with titles and descriptions
+2. Fetch available milestones
-3. Show for approval
+3. Generate list of issues with titles, descriptions, milestone assignments, and dependencies
-4. Create each issue
+4. Show for approval
-5. Display all created issue numbers
+5. Create each issue with milestone (in dependency order)
+6. Link dependencies between created issues: `tea issues deps add <issue> <blocker>`
+7. Display all created issue numbers with dependency graph

commands/dashboard.md

@@ -4,7 +4,7 @@ description: Show dashboard of open issues, PRs awaiting review, and CI status.
 
 # Repository Dashboard
 
-Use the gitea skill.
+@~/.claude/skills/gitea/SKILL.md
 
 Fetch and display:
 1. All open issues

commands/groom.md

@@ -5,27 +5,33 @@ argument-hint: [issue-number]
 
 # Groom Issues
 
-Use the gitea, backlog-grooming, and issue-writing skills.
+@~/.claude/skills/gitea/SKILL.md
+@~/.claude/skills/backlog-grooming/SKILL.md
+@~/.claude/skills/issue-writing/SKILL.md
 
 ## 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/improve.md

@@ -0,0 +1,82 @@
+---
+description: Identify improvement opportunities based on product vision. Analyzes gaps between vision goals and current backlog.
+---
+
+# Improvement Analysis
+
+@~/.claude/skills/vision-management/SKILL.md
+@~/.claude/skills/gitea/SKILL.md
+@~/.claude/skills/issue-writing/SKILL.md
+@~/.claude/skills/roadmap-planning/SKILL.md
+
+## Process
+
+1. **Read the vision**: Load `vision.md` from the repo root.
+   - If no vision exists, suggest running `/vision` first
+
+2. **Fetch current backlog**: Get all open issues from Gitea using `tea issues`
+
+3. **Analyze alignment**:
+
+   For each vision goal, check:
+   - Are there issues supporting this goal?
+   - Is there recent activity/progress?
+   - Are issues blocked or stalled?
+
+   For each open issue, check:
+   - Does it align with a vision goal?
+   - Is it supporting the current focus?
+
+4. **Identify gaps and opportunities**:
+
+   - **Unsupported goals**: Vision goals with no issues
+   - **Stalled goals**: Goals with issues but no recent progress
+   - **Orphan issues**: Issues that don't support any goal
+   - **Focus misalignment**: Issues not aligned with current focus getting priority
+   - **Missing non-goals**: Patterns suggesting things we should explicitly avoid
+
+5. **Present findings**:
+
+   ```
+   ## Vision Alignment Report
+
+   ### Goals Coverage
+   - Goal 1: [status] - N issues, [progress]
+   - Goal 2: [status] - N issues, [progress]
+
+   ### Gaps Identified
+   1. [Gap description]
+      Suggestion: [concrete action]
+
+   2. [Gap description]
+      Suggestion: [concrete action]
+
+   ### Orphan Issues
+   - #N: [title] - No goal alignment
+
+   ### Recommended Actions
+   1. [Action with rationale]
+   2. [Action with rationale]
+   ```
+
+6. **Offer to take action**:
+
+   For unsupported goals:
+   - Ask if user wants to plan issues for the gap
+   - If yes, run the `/plan-issues` workflow for that goal
+   - This breaks down the goal into concrete, actionable issues
+
+   For other findings:
+   - Re-prioritize issues based on focus
+   - Close or re-scope orphan issues
+   - Update vision with suggested changes
+
+   Always ask for approval before making changes.
+
+## Guidelines
+
+- Focus on actionable improvements, not just observations
+- Prioritize suggestions by impact on vision goals
+- Keep suggestions specific and concrete
+- One issue per improvement (don't bundle)
+- Reference specific goals when suggesting new issues

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

@@ -1,23 +1,33 @@
 ---
-description: Plan and create issues for a feature or improvement. Breaks down work into well-structured issues.
+description: Plan and create issues for a feature or improvement. Breaks down work into well-structured issues with vision alignment.
 argument-hint: <feature-description>
 ---
 
 # Plan Feature: $1
 
-Use the gitea, roadmap-planning, and issue-writing skills.
+@~/.claude/skills/gitea/SKILL.md
+@~/.claude/skills/roadmap-planning/SKILL.md
+@~/.claude/skills/issue-writing/SKILL.md
+@~/.claude/skills/vision-management/SKILL.md
 
-1. **Understand the feature**: Analyze what "$1" involves
+1. **Check vision context**: If `vision.md` exists, read it to understand personas, jobs to be done, and goals
-2. **Explore the codebase** if needed to understand context
+2. **Identify persona**: Which persona does "$1" serve?
-3. **Break down** into discrete, actionable issues:
+3. **Identify job**: Which job to be done does this enable?
+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)
 
-4. **Present the plan**:
+7. **Present the plan** (include vision alignment if vision exists):
    ```
    ## Proposed Issues for: $1
 
+   For: [Persona name]
+   Job: "[Job to be done this enables]"
+   Supports: [Milestone/Goal name]
+
    1. [Title] - Brief description
       Dependencies: none
 
@@ -28,7 +38,13 @@ Use the gitea, roadmap-planning, and issue-writing skills.
       Dependencies: #1, #2
    ```
 
-5. **Ask for approval** before creating issues
+   If the feature doesn't align with any persona/job/goal, note this and ask if:
-6. **Create issues** in order
+   - A new persona or job should be added to the vision
-7. **Update dependencies** with actual issue numbers after creation
+   - A new milestone should be created
-8. **Present summary** with links to created issues
+   - This should be added as a non-goal
+   - Proceed anyway (with justification)
+
+8. **Ask for approval** before creating issues
+9. **Create issues** in dependency order (blockers first)
+10. **Link dependencies** using `tea issues deps add <issue> <blocker>` for each dependency
+11. **Present summary** with links to created issues and dependency graph

commands/retro.md

@@ -1,11 +1,22 @@
 ---
-description: Run a retrospective on completed work. Captures learnings and creates improvement issues in the AI repo.
+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.
+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
 
@@ -16,49 +27,90 @@ Capture learnings from completed AI-assisted work to improve the workflow.
    - 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. **Generate improvement issues**: For each actionable improvement, create an issue in the AI repo using:
+4. **Create issue on architecture repo**: Always create issues on `flowmade-one/ai`:
 
-```bash
+   ```bash
-tea issues create -r flowmade-one/ai --title "<title>" --description "<body>"
+   tea issues create -r flowmade-one/ai \
-```
+     --title "[Learning] <brief description>" \
+     --description "## Context
+   [Task that triggered this insight]
 
-## Issue Format
+   ## Insight
+   [The specific learning - be concrete and actionable]
 
-Use this structure for retrospective issues:
+   ## 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]
 
-```markdown
+   ## Governance
-## Context
+   [What this means for how we work going forward]"
-What task triggered this learning (brief).
+   ```
 
-## Problem / Observation
+5. **Connect to vision**: Check if insight affects vision:
-What was the friction point or insight.
+   - **Architecture repo**: Does this affect `manifesto.md`? (beliefs, principles, non-goals)
+   - **Product repo**: Does this affect `vision.md`? (product direction, goals)
 
-## Suggested Improvement
+   If vision updates are needed, present suggested changes and ask for approval.
-Concrete, actionable change to make.
 
-## Affected Files
+## When the Issue is Worked On
-- commands/xxx.md
+
-- skills/xxx/SKILL.md
+When encoding a learning issue, the implementer should:
-```
+
+1. **Create learning file**: `learnings/YYYY-MM-DD-short-title.md`
+
+   ```markdown
+   # [Learning Title]
+
+   **Date**: YYYY-MM-DD
+   **Context**: [Task that triggered this learning]
+   **Issue**: #XX
+
+   ## Learning
+
+   [The specific insight]
+
+   ## 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/review-pr.md

@@ -5,9 +5,9 @@ argument-hint: <pr-number>
 
 # Review PR #$1
 
-Use the gitea skill.
+@~/.claude/skills/gitea/SKILL.md
 
-1. **View PR details** including description and metadata
+1. **View PR details** with `--comments` flag to see description, metadata, and discussion
 2. **Get the diff** to review the changes
 
 Review the changes and provide feedback on:
@@ -20,3 +20,19 @@ Ask the user what action to take:
 - **Merge**: Post review summary as comment, then merge with rebase style
 - **Request changes**: Leave feedback without merging
 - **Comment only**: Add a comment for discussion
+
+## Merging
+
+Always use tea CLI for merges to preserve user attribution:
+
+```bash
+tea pulls merge <number> --style rebase
+```
+
+For review comments, use `tea comment` since `tea pulls review` is interactive-only:
+
+```bash
+tea comment <number> "<review summary>"
+```
+
+> **Warning**: Never use the Gitea API with admin credentials for user-facing operations like merging. This causes the merge to be attributed to the admin account instead of the user.

commands/roadmap.md

@@ -4,7 +4,7 @@ description: View current issues as a roadmap. Shows open issues organized by st
 
 # Roadmap View
 
-Use the gitea skill.
+@~/.claude/skills/gitea/SKILL.md
 
 1. **Fetch all open issues**
 2. **Analyze dependencies** from issue descriptions

commands/vision.md

@@ -0,0 +1,110 @@
+---
+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.
+
+## Process
+
+1. **Check for organization manifesto**: Note if `manifesto.md` exists (provides org context)
+
+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. **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
+
+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>
+   ```
+
+## Output Format
+
+```
+## Organization Context
+
+See manifesto for shared personas, beliefs, and principles.
+[Link or note about manifesto.md location]
+
+## Product: [Name]
+
+### Who This Product Serves
+
+- **[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
+
+- 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

commands/work-issue.md

@@ -5,9 +5,9 @@ argument-hint: <issue-number>
 
 # Work on Issue #$1
 
-Use the gitea skill.
+@~/.claude/skills/gitea/SKILL.md
 
-1. **View the issue** to understand requirements
+1. **View the issue** with `--comments` flag to understand requirements and context
 2. **Create a branch**: `git checkout -b issue-$1-<short-kebab-title>`
 3. **Plan**: Use TodoWrite to break down the work based on acceptance criteria
 4. **Implement** the changes

docs/writing-commands.md

@@ -72,7 +72,7 @@ argument-hint: <issue-number>
 
 # Work on Issue #$1
 
-Use the gitea skill.
+@~/.claude/skills/gitea/SKILL.md
 
 1. **View the issue** to understand requirements
 2. **Create a branch**: `git checkout -b issue-$1-<short-kebab-title>`
@@ -138,7 +138,7 @@ argument-hint: [issue-number]
 
 # Groom Issues
 
-Use the gitea skill.
+@~/.claude/skills/gitea/SKILL.md
 
 ## If issue number provided ($1):
 1. **Fetch the issue** details
@@ -163,7 +163,7 @@ argument-hint: [title] or "batch"
 
 # Create Issue(s)
 
-Use the gitea skill.
+@~/.claude/skills/gitea/SKILL.md
 
 ## Single Issue (default)
 If title provided, create an issue with that title.
@@ -176,41 +176,45 @@ If $1 is "batch":
 4. Create each issue
 ```
 
-## Invoking Skills
+## Including Skills
 
-Commands reference skills by name to gain domain knowledge. When a skill is referenced, Claude reads the skill file before proceeding.
+Commands include skills using the `@` file reference syntax. This automatically injects the skill content into the command context when the command is invoked.
 
-### Explicit Reference
+### File Reference Syntax
+
+Use the `@` prefix followed by the path to the skill file:
 
 ```markdown
 # Groom Issues
 
-Use the **gitea**, **backlog-grooming**, and **issue-writing** skills.
+@~/.claude/skills/gitea/SKILL.md
+@~/.claude/skills/backlog-grooming/SKILL.md
+@~/.claude/skills/issue-writing/SKILL.md
 
 1. **Fetch the issue** details
 2. **Evaluate** against grooming checklist
 ...
 ```
 
-The phrase "Use the gitea, backlog-grooming and issue-writing skills" tells Claude to read and apply knowledge from those skill files.
+When the command runs, the content of each referenced skill file is automatically loaded into context.
 
-### Skill-Based Approach
+### Why File References?
 
-Commands should reference skills rather than embedding CLI commands directly:
+**DO NOT** use phrases like "Use the gitea skill" - skills have only ~20% auto-activation rate. File references guarantee the skill content is available.
 
-```markdown
+| Pattern | Behavior |
-1. **Fetch the issue** details
+|---------|----------|
-```
+| `@~/.claude/skills/gitea/SKILL.md` | Content automatically injected |
+| "Use the gitea skill" | Relies on auto-activation (~20% success) |
 
-This relies on the `gitea` skill to provide the CLI knowledge.
+### When to Include Skills
 
-### When to Reference Skills
+| Include explicitly | Skip skill reference |
-
+|-------------------|---------------------|
-| Reference explicitly | Reference implicitly |
+| CLI syntax is needed | Well-known commands |
-|---------------------|---------------------|
+| Core methodology required | Simple operations |
-| Core methodology is needed | Just using a tool |
+| Quality standards matter | One-off actions |
-| Quality standards matter | Simple operations |
+| Patterns should be followed | No domain knowledge needed |
-| Patterns should be followed | Well-known commands |
 
 ## Invoking Agents
 
@@ -313,7 +317,7 @@ argument-hint: <issue-number>
 
 # Work on Issue #$1
 
-Use the gitea skill.
+@~/.claude/skills/gitea/SKILL.md
 
 1. **View the issue** to understand requirements
 2. **Create a branch**: `git checkout -b issue-$1-<short-kebab-title>`
@@ -340,7 +344,7 @@ description: Show dashboard of open issues, PRs awaiting review, and CI status.
 
 # Repository Dashboard
 
-Use the gitea skill.
+@~/.claude/skills/gitea/SKILL.md
 
 Fetch and display:
 1. All open issues
@@ -365,7 +369,9 @@ argument-hint: [issue-number]
 
 # Groom Issues
 
-Use the gitea, backlog-grooming, and issue-writing skills.
+@~/.claude/skills/gitea/SKILL.md
+@~/.claude/skills/backlog-grooming/SKILL.md
+@~/.claude/skills/issue-writing/SKILL.md
 
 ## If issue number provided ($1):
 1. **Fetch the issue** details
@@ -388,7 +394,7 @@ Use the gitea, backlog-grooming, and issue-writing skills.
 **Key patterns:**
 - **Optional argument**: `[issue-number]` with brackets
 - **Mode switching**: Different behavior based on argument presence
-- **Explicit skill reference**: "Use the gitea, backlog-grooming and issue-writing skills"
+- **Skill file references**: Uses `@~/.claude/skills/` to include multiple skills
 - **Approval workflow**: "Ask user if they want to apply changes"
 - **Categorization**: Groups items for presentation
 
@@ -402,7 +408,9 @@ argument-hint: <feature-description>
 
 # Plan Feature: $1
 
-Use the gitea, roadmap-planning, and issue-writing skills.
+@~/.claude/skills/gitea/SKILL.md
+@~/.claude/skills/roadmap-planning/SKILL.md
+@~/.claude/skills/issue-writing/SKILL.md
 
 1. **Understand the feature**: Analyze what "$1" involves
 2. **Explore the codebase** if needed to understand context
@@ -422,7 +430,7 @@ Use the gitea, roadmap-planning, and issue-writing skills.
 ```
 
 **Key patterns:**
-- **Multi-skill composition**: References three skills together
+- **Multi-skill composition**: Includes three skills via `@~/.claude/skills/`
 - **Codebase exploration**: May need to understand context
 - **Structured output**: Template for presenting the plan
 - **Two-phase execution**: Plan first, then execute after approval
@@ -438,7 +446,7 @@ argument-hint: <pr-number>
 
 # Review PR #$1
 
-Use the gitea skill.
+@~/.claude/skills/gitea/SKILL.md
 
 1. **View PR details** including description and metadata
 2. **Get the diff** to review the changes
@@ -641,7 +649,7 @@ Update references:
 - [ ] Frontmatter includes argument-hint (if arguments needed)
 - [ ] Workflow steps are clear and numbered
 - [ ] Commands and tools are specified explicitly
-- [ ] Skills are referenced where methodology matters
+- [ ] Skills are included via `@~/.claude/skills/<name>/SKILL.md` file references
 - [ ] Approval points exist before significant actions
 - [ ] Edge cases are handled (no data, invalid input)
 - [ ] Output formatting is specified

docs/writing-skills.md

@@ -2,11 +2,77 @@
 
 A guide to creating reusable knowledge modules for the Claude Code AI workflow system.
 
+> **Official Documentation**: For the most up-to-date information, see https://code.claude.com/docs/en/skills
+
 ## What is a Skill?
 
-Skills are **knowledge modules**—focused documents that teach Claude how to do something well. Unlike commands (which define workflows) or agents (which execute tasks), skills are passive: they encode domain expertise, patterns, and best practices that can be referenced when needed.
+Skills are **model-invoked knowledge modules**—Claude automatically applies them when your request matches their description. Unlike commands (which require explicit `/command` invocation), skills are triggered automatically based on semantic matching.
 
-Think of skills as the "how-to guides" that inform Claude's work. A skill doesn't act on its own—it provides the knowledge that commands and agents use to complete their tasks effectively.
+## YAML Frontmatter (Required)
+
+Every `SKILL.md` file **must** start with YAML frontmatter. This is how Claude discovers and triggers skills.
+
+### Format Requirements
+
+- Must start with `---` on **line 1** (no blank lines before it)
+- Must end with `---` before the markdown content
+- Use spaces for indentation (not tabs)
+
+### Required Fields
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| `name` | **Yes** | Lowercase letters, numbers, and hyphens only (max 64 chars). Should match directory name. |
+| `description` | **Yes** | What the skill does and when to use it (max 1024 chars). **This is critical for triggering.** |
+
+### Optional Fields
+
+| Field | Description |
+|-------|-------------|
+| `allowed-tools` | **Restricts** which tools Claude can use when this skill is active. If omitted, no restrictions apply. |
+| `model` | Specific model to use when skill is active (e.g., `claude-sonnet-4-20250514`). |
+
+### Writing Effective Descriptions
+
+The `description` field determines when Claude applies the skill. A good description answers:
+
+1. **What does this skill do?** List specific capabilities.
+2. **When should Claude use it?** Include trigger terms users would mention.
+
+**Bad (too vague):**
+```yaml
+description: Helps with documents
+```
+
+**Good (specific with trigger terms):**
+```yaml
+description: View, create, and manage Gitea issues and pull requests using tea CLI. Use when working with issues, PRs, viewing issue details, creating pull requests, adding comments, merging PRs, or when the user mentions tea, gitea, issue numbers, or PR numbers.
+```
+
+### Example Frontmatter
+
+```yaml
+---
+name: gitea
+description: View, create, and manage Gitea issues and pull requests using tea CLI. Use when working with issues, PRs, viewing issue details, creating pull requests, or when the user mentions tea, gitea, or issue numbers.
+---
+
+# Gitea CLI (tea)
+
+[Rest of skill content...]
+```
+
+## Subagents and Skills
+
+Subagents **do not automatically inherit skills** from the main conversation. To give a subagent access to skills, list them in the agent's `skills` field:
+
+```yaml
+---
+name: code-reviewer
+description: Review code for quality and best practices
+skills: gitea, code-review
+---
+```
 
 ## File Structure
 
@@ -77,39 +143,29 @@ Quick-reference tables, checklists, or commands.
 
 Not every skill needs all sections—include what's relevant. Some skills are primarily patterns (like `issue-writing`), others are reference-heavy (like `gitea`).
 
-## How Skills are Loaded
+## How Skills are Discovered and Triggered
 
-Skills are loaded by **explicit reference**. When a command or agent mentions a skill by name, Claude reads the skill file to gain that knowledge.
+Skills are **model-invoked**: Claude decides which skills to use based on your request.
 
-### Referenced by Commands
+### Discovery Process
 
-Commands reference skills in their instructions:
+1. **At startup**: Claude loads only the `name` and `description` of each available skill
+2. **On request**: Claude matches your request against skill descriptions using semantic similarity
+3. **Activation**: When a match is found, Claude asks to use the skill before loading the full content
 
-```markdown
+### Subagent Access
-# Groom Issues
 
-Use the **backlog-grooming** and **issue-writing** skills to review and improve issues.
+Subagents (defined in `.claude/agents/`) must explicitly list which skills they can use:
 
-1. Fetch open issues...
+```yaml
+---
+name: product-manager
+description: Manages backlog and roadmap
+skills: gitea, issue-writing, backlog-grooming, roadmap-planning
+---
 ```
 
-When this command runs, Claude reads both referenced skills before proceeding.
+**Important**: Built-in agents and the Task tool do not have access to skills. Only custom subagents with an explicit `skills` field can use them.
-
-### Referenced by Agents
-
-Agents list their skills explicitly:
-
-```markdown
-# Product Manager Agent
-
-## Skills
-- gitea
-- issue-writing
-- backlog-grooming
-- roadmap-planning
-```
-
-When spawned, the agent has access to all listed skills as part of its context.
 
 ### Skills Can Reference Other Skills
 
@@ -430,14 +486,26 @@ Keep skills current:
 
 ## Checklist: Before Submitting a New Skill
 
+### Frontmatter (Critical)
+- [ ] YAML frontmatter starts on line 1 (no blank lines before `---`)
+- [ ] `name` field uses lowercase letters, numbers, and hyphens only
+- [ ] `name` matches the directory name
+- [ ] `description` lists specific capabilities
+- [ ] `description` includes "Use when..." with trigger terms
+
+### File Structure
 - [ ] File is at `skills/<name>/SKILL.md`
 - [ ] Name follows kebab-case convention
+
+### Content Quality
 - [ ] Skill focuses on a single domain
 - [ ] Guidelines are specific and actionable
 - [ ] Examples illustrate each major point
 - [ ] Templates are provided where appropriate
 - [ ] Common mistakes are documented
-- [ ] Skill is referenced by at least one command or agent
+
+### Integration
+- [ ] Skill is listed in relevant subagent `skills` fields if needed
 
 ## See Also
 

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.

settings.json

@@ -1,5 +1,15 @@
 {
   "model": "opus",
+  "permissions": {
+    "allow": [
+      "Bash(git:*)",
+      "Bash(mkdir:*)",
+      "Bash(find:*)",
+      "Bash(curl:*)",
+      "Bash(tea:*)",
+      "WebSearch"
+    ]
+  },
   "statusLine": {
     "type": "command",
     "command": "input=$(cat); current_dir=$(echo \"$input\" | jq -r '.workspace.current_dir'); model=$(echo \"$input\" | jq -r '.model.display_name'); style=$(echo \"$input\" | jq -r '.output_style.name'); git_info=\"\"; if [ -d \"$current_dir/.git\" ]; then cd \"$current_dir\" && branch=$(git branch --show-current 2>/dev/null) && status=$(git status --porcelain 2>/dev/null | wc -l | tr -d ' ') && git_info=\" [$branch$([ \"$status\" != \"0\" ] && echo \"*\")]\"; fi; printf \"\\033[2m$(whoami)@$(hostname -s) $(basename \"$current_dir\")$git_info | $model ($style)\\033[0m\""

skills/backlog-grooming/SKILL.md

@@ -1,3 +1,8 @@
+---
+name: backlog-grooming
+description: Review and improve existing issues for clarity and actionability. Use when grooming the backlog, reviewing issue quality, cleaning up stale issues, or when the user wants to improve existing issues.
+---
+
 # Backlog Grooming
 
 How to review and improve existing issues.
@@ -28,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/code-review/SKILL.md

@@ -1,3 +1,8 @@
+---
+name: code-review
+description: Review code for quality, bugs, security, and style issues. Use when reviewing pull requests, checking code quality, looking for bugs or security vulnerabilities, or when the user asks for a code review.
+---
+
 # Code Review
 
 Guidelines for reviewing code changes in pull requests.

skills/gitea/SKILL.md

@@ -1,3 +1,8 @@
+---
+name: gitea
+description: View, create, and manage Gitea issues and pull requests using tea CLI. Use when working with issues, PRs, viewing issue details, creating pull requests, adding comments, merging PRs, or when the user mentions tea, gitea, issue numbers, or PR numbers.
+---
+
 # Gitea CLI (tea)
 
 Command-line interface for interacting with Gitea repositories.
@@ -65,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
@@ -78,7 +90,10 @@ tea pulls --state closed             # Closed/merged PRs
 # View PR
 tea pulls <number>                   # PR details
 tea pulls <number> --comments        # Include comments
-tea pulls <number> -f diff           # PR diff
+
+# View PR diff (tea doesn't have a diff command, use git)
+tea pulls checkout <number>          # First checkout the PR branch
+git diff main...HEAD                 # Diff against main branch
 
 # Create PR
 tea pulls create --title "<title>" --description "<body>"
@@ -119,15 +134,15 @@ tea clone <owner>/<repo>             # Clone repository
 tea comment <number> "<comment body>"
 tea comment 3 "LGTM, ready to merge"
 
-# Multiline comments (use heredoc)
+# Multiline comments (use quoted strings with literal newlines)
-tea comment 3 "$(cat <<'EOF'
+tea comment 3 "## Review Summary
-## Review Summary
+
 - Code looks good
-- Tests pass
+- Tests pass"
-EOF
-)"
 ```
 
+> **Warning**: Do not use heredoc syntax `$(cat <<'EOF'...EOF)` with `tea comment` - it causes the command to be backgrounded and fail silently.
+
 ### Notifications
 
 ```bash
@@ -155,6 +170,7 @@ tea issues -r owner/repo             # Specify repo directly
 ## Tips
 
 - **View single issue**: Use `tea issues <number>` (NOT `tea issues view <number>` - there is no `view` subcommand)
+- **PR description flag**: Use `--description` or `-d` (NOT `--body` like gh CLI)
 - Always verify you're in the correct repository before running commands
 - Use `tea issues` to find issue numbers before viewing/editing
 - Reference issues in PR bodies with `Closes #N` for auto-linking

skills/issue-writing/SKILL.md

@@ -1,3 +1,8 @@
+---
+name: issue-writing
+description: Write clear, actionable issues with proper structure and acceptance criteria. Use when creating issues, writing bug reports, feature requests, or when the user needs help structuring an issue.
+---
+
 # Issue Writing
 
 How to write clear, actionable issues.
@@ -99,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

@@ -1,3 +1,8 @@
+---
+name: roadmap-planning
+description: Plan features and break down work into implementable issues. Use when planning a feature, creating a roadmap, breaking down large tasks, or when the user needs help organizing work into issues.
+---
+
 # Roadmap Planning
 
 How to plan features and create issues for implementation.
@@ -75,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

@@ -0,0 +1,240 @@
+---
+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 |