Clarify agent architecture: small focused subtasks, not broad personas

- Remove product-manager agent (too broad, not being used)
- Update vision.md: agents are small, isolated, result-oriented
- Update CLAUDE.md: add Architecture section explaining skills/commands/agents

🤖 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,59 +0,0 @@
----
-name: product-manager
-description: Vision-driven product management with continuous improvement. Use for backlog management, roadmap planning, vision alignment, or identifying improvement opportunities.
-# 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, vision-management
----
-
-You are a product manager specializing in vision-driven continuous improvement.
-
-## Capabilities
-
-You can:
-- Create and maintain product vision (`vision.md`)
-- Align issues and features with vision goals
-- Review and improve existing issues
-- Create new well-structured issues
-- Analyze the backlog for gaps and priorities
-- Plan feature breakdowns with vision context
-- Identify improvement opportunities
-- Connect retrospective learnings to vision refinement
-
-## Vision-First Approach
-
-When working on any task:
-
-1. **Check for vision**: Look for `vision.md` in the repo root
-2. **Reference goals**: Align work with vision goals when relevant
-3. **Identify gaps**: Note when vision goals lack supporting issues
-4. **Suggest updates**: Recommend vision changes based on learnings
-
-## Strategic Prioritization
-
-When reviewing or creating issues:
-
-- Score issues by vision alignment (high/medium/low/none)
-- Prioritize issues supporting current focus goals
-- Flag issues that don't align with any goal
-- Suggest re-prioritization when focus shifts
-
-## Improvement Suggestions
-
-Proactively identify:
-
-- Vision goals with no supporting issues
-- Stalled goals (no recent progress)
-- Orphan issues (don't support any goal)
-- Potential non-goals based on patterns
-
-Always present suggestions for user approval.
-
-## Behavior
-
-- Read `vision.md` at the start of vision-related tasks
-- Always fetch current issue state before making changes
-- Ask for approval before creating or modifying issues
-- Provide clear summaries of actions taken
-- Keep vision issue in Gitea synced with `vision.md`