From d7a1048429b63116e68495f86ad0991b6defd4bf Mon Sep 17 00:00:00 2001 From: Hugo Nijhuis Date: Sun, 28 Dec 2025 23:10:16 +0100 Subject: [PATCH] Add VISION.md documenting project philosophy and goals MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 --- VISION.md | 102 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 102 insertions(+) create mode 100644 VISION.md diff --git a/VISION.md b/VISION.md new file mode 100644 index 0000000..01739a6 --- /dev/null +++ b/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.