Include comments when viewing issues and PRs

Updated work-issue and review-pr commands to use --comments flag,
ensuring discussion context is available when working on issues or
reviewing pull requests.

Closes #32

🤖 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/product-manager/AGENT.md

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

commands/create-issue.md

@@ -7,13 +7,34 @@ argument-hint: [title] or "batch"
 
 @~/.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)
 
 ## 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, and milestone assignments
-4. Create each issue
+4. Show for approval
-5. Display all created issue numbers
+5. Create each issue with milestone
+6. Display all created issue numbers

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/plan-issues.md

@@ -1,5 +1,5 @@
 ---
-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>
 ---
 
@@ -8,29 +8,41 @@ argument-hint: <feature-description>
 @~/.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 current goals and focus
-2. **Explore the codebase** if needed to understand context
+2. **Understand the feature**: Analyze what "$1" involves
-3. **Break down** into discrete, actionable issues:
+3. **Explore the codebase** if needed to understand context
+4. **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**:
+5. **Present the plan** (include vision alignment if vision exists):
    ```
    ## Proposed Issues for: $1
 
+   Vision Alignment: Supports [Goal N: description]
+
    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
    ```
 
-5. **Ask for approval** before creating issues
+   If the feature doesn't align with any vision goal, note this and ask if:
-6. **Create issues** in order
+   - The vision should be updated to include this as a goal
-7. **Update dependencies** with actual issue numbers after creation
+   - This should be added as a non-goal
-8. **Present summary** with links to created issues
+   - Proceed anyway (with justification)
+
+6. **Ask for approval** before creating issues
+7. **Create issues** in order
+8. **Update dependencies** with actual issue numbers after creation
+9. **Present summary** with links to created issues

commands/retro.md

@@ -1,11 +1,13 @@
 ---
-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 learnings, creates improvement issues, and updates product vision.
 argument-hint: [task-description]
 ---
 
 # Retrospective
 
-Capture learnings from completed AI-assisted work to improve the workflow.
+Capture learnings from completed AI-assisted work to improve the workflow and refine the product vision.
+
+@~/.claude/skills/vision-management/SKILL.md
 
 ## Process
 
@@ -22,12 +24,38 @@ Capture learnings from completed AI-assisted work to improve the workflow.
    - **Tool issues**: Problems with tea CLI, git, or other tools
    - **Context gaps**: Missing documentation or skills
 
-4. **Generate improvement issues**: For each actionable improvement, create an issue in the AI repo using:
+4. **Connect to vision** (if `vision.md` exists in the target repo):
+   - 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>"
+tea issues create -r flowmade-one/ai --title "<title>" --description "<body>" --milestone "<milestone>"
 ```
 
+## 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
+
 ## Issue Format
 
 Use this structure for retrospective issues:

commands/review-pr.md

@@ -7,7 +7,7 @@ argument-hint: <pr-number>
 
 @~/.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/vision.md

@@ -0,0 +1,78 @@
+---
+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
+
+## Architecture
+
+The vision system has two layers:
+
+| Layer | Purpose | Location |
+|-------|---------|----------|
+| **vision.md** | North star philosophy (why, principles, non-goals) | File in repo root |
+| **Milestones** | Goals with progress tracking | Gitea milestones |
+
+Issues are assigned to milestones. Progress is visible through milestone completion.
+
+## Process
+
+1. **Check for existing vision**: Look for `vision.md` in the current repo root.
+
+2. **If no vision exists**:
+   - 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**:
+   - Display the vision philosophy 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)**:
+   ```bash
+   # List milestones with progress
+   tea milestones
+
+   # Create a new goal
+   tea milestones create --title "<goal>" --description "<success criteria>"
+
+   # View issues in a milestone
+   tea milestones issues <milestone-name>
+
+   # Close a completed goal
+   tea milestones close <milestone-name>
+   ```
+
+## Output Format
+
+```
+## Vision
+
+[Summary of vision.md purpose/principles]
+
+## Goals (Milestones)
+
+| Goal | Progress | Due |
+|------|----------|-----|
+| [title] | 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
+- Milestones are the actionable goals - create/close as needed
+- Assign issues to milestones to track progress
+- Use milestone descriptions for success criteria
+- Due dates on milestones are optional but help prioritization

commands/work-issue.md

@@ -7,7 +7,7 @@ argument-hint: <issue-number>
 
 @~/.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

skills/vision-management/SKILL.md

@@ -0,0 +1,143 @@
+---
+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.
+---
+
+# Vision Management
+
+How to create, maintain, and evolve a product vision for continuous improvement.
+
+## Architecture
+
+The vision system has two layers:
+
+| Layer | Purpose | Location |
+|-------|---------|----------|
+| **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
+
+The vision.md file should contain the stable "why" - not progress tracking:
+
+```markdown
+# Vision
+
+## The Problem
+What problem does this product solve? Who benefits?
+
+## The Solution
+How does this product solve the problem?
+
+## Guiding Principles
+Core beliefs that guide decisions.
+
+## Non-Goals
+What we're explicitly NOT doing.
+```
+
+Do NOT include goals, progress, or focus in vision.md - that's what milestones are for.
+
+## Creating a Vision
+
+When no vision exists:
+
+1. **Identify the problem**: What pain point does this solve?
+2. **Define the solution**: How does the product address it?
+3. **Set guiding principles**: What beliefs guide decisions?
+4. **Document non-goals**: What are you explicitly NOT doing?
+5. **Create initial milestones**: 3-5 measurable goals
+
+### Good Goals (Milestones)
+
+- Specific and measurable
+- Outcome-focused (not activity-focused)
+- Have clear success criteria in the 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
+tea milestones -f title,items_open,items_closed,state
+
+# 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
+
+When creating issues, assign them to the relevant milestone:
+
+```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?
+2. **Assign to milestone**: Link the issue to the relevant goal
+3. **Prioritize by focus**: Issues in priority milestones get worked first
+4. **Flag misalignment**: Issues without a milestone need justification
+
+### Identifying Gaps
+
+Compare milestones to current backlog:
+
+- 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)
+```
+
+1. **Vision** defines why and principles (stable)
+2. **Milestones** define measurable goals
+3. **Issues** are work items toward those goals
+4. **Work** implements the issues
+5. **Retros** capture learnings
+6. **Updates** refine vision and create/close milestones
+
+The vision is stable. The milestones evolve as you learn and achieve goals.