Hugo Nijhuis
e1ed17e2bf
- 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>
111 lines
4.5 KiB
Markdown
111 lines
4.5 KiB
Markdown
# 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.
|