architecture/VISION.md

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.