Add VISION.md documenting project philosophy and goals

Covers:
- The problem: inconsistent AI-assisted workflows
- The solution: composable toolkit for Claude Code
- Component types: skills, agents, commands
- Target users: developers using Claude Code with Forgejo
- Guiding principles: encode don't repeat, composability,
  approval before action, dogfooding, progressive disclosure

Closes #1

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

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

VISION.md

@@ -0,0 +1,102 @@
+# Vision
+
+## The Problem
+
+AI-assisted development is powerful but inconsistent. Claude Code can help with nearly any task, but without structure:
+
+- Workflows vary between sessions and team members
+- Knowledge about good practices stays in heads, not systems
+- Context gets lost when switching between tasks
+- There's no shared vocabulary for common patterns
+
+The gap isn't in AI capability—it's in how we use it.
+
+## The Solution
+
+This project provides a **composable toolkit** for Claude Code that turns ad-hoc AI assistance into structured, repeatable workflows.
+
+Instead of asking Claude to "help with issues" differently each time, you run `/work-issue 42` and get a consistent workflow: fetch the issue, create a branch, plan the work, implement, commit with proper references, and create a PR.
+
+The key insight: **encode your team's best practices into reusable components** that Claude can apply consistently.
+
+## Composable Components
+
+The system is built from three types of components that stack together:
+
+### Skills
+
+Skills are knowledge modules—focused documents that teach Claude how to do something well.
+
+Examples:
+- `issue-writing`: How to structure clear, actionable issues
+- `forgejo`: How to use the Forgejo CLI for issue/PR management
+- `backlog-grooming`: What makes a healthy backlog
+
+Skills don't do anything on their own. They're building blocks.
+
+### Agents
+
+Agents combine multiple skills into specialized personas that can work autonomously.
+
+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.
+
+Agents enable:
+- **Parallel processing**: Multiple agents can work simultaneously
+- **Context preservation**: Each agent maintains its own focused context
+- **Complex workflows**: Combine skills for multi-step tasks
+
+### Commands
+
+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
+3. Guides you through the workflow with approvals
+4. Takes action (creates issues, PRs, etc.)
+
+Commands make the power of skills and agents accessible through simple invocations.
+
+## Target Users
+
+This toolkit is for:
+
+- **Developers using Claude Code** who want consistent, efficient workflows
+- **Teams** who want to encode and share their best practices
+- **Forgejo/Git users** who want seamless issue and PR management integrated into their AI workflow
+
+You should have:
+- Claude Code CLI installed
+- A Forgejo instance (or adapt the tooling for GitHub/GitLab)
+- Interest in treating AI assistance as a structured tool, not just a chat interface
+
+## Guiding Principles
+
+### Encode, Don't Repeat
+
+If you find yourself explaining the same thing to Claude repeatedly, that's a skill waiting to be written. Capture it once, use it everywhere.
+
+### Composability Over Complexity
+
+Small, focused components that combine well beat large, monolithic solutions. A skill should do one thing. An agent should serve one role. A command should trigger one workflow.
+
+### Approval Before Action
+
+Destructive or significant actions should require user approval. Commands should show what they're about to do and ask before doing it. This builds trust and catches mistakes.
+
+### Use the Tools to Build the Tools
+
+This project uses its own commands to manage itself. Issues are created with `/create-issue`. Features are planned with `/plan-issues`. PRs are reviewed with `/review-pr`. Dogfooding ensures the tools actually work.
+
+### Progressive Disclosure
+
+Simple things should be simple. `/dashboard` just shows your issues and PRs. But the system supports complex workflows when you need them. Don't require users to understand the full architecture to get value.
+
+## What This Is Not
+
+This is not:
+- A replacement for Claude Code—it enhances it
+- A rigid framework—adapt it to your needs
+- Complete—it grows as we discover new patterns
+
+It's a starting point for treating AI-assisted development as a first-class engineering concern.