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
• gitea: How to use the Gitea 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 are small, focused units that handle specific subtasks in isolated context.

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 isolation: Complex subtasks don't pollute the main conversation
• Reusability: Same agent can be spawned by different commands

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. References skills for knowledge (how to write issues, use Gitea, etc.)
3. Optionally spawns agents for complex subtasks
4. Guides you through the workflow with approvals
5. Takes action (creates issues, PRs, etc.)

Commands run in the main conversation context, using skills for knowledge and spawning agents only when isolated processing is beneficial.

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
• Gitea/Git users who want seamless issue and PR management integrated into their AI workflow

You should have:

• Claude Code CLI installed
• A Gitea 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.