Hugo Nijhuis
68675a7e12
- Replace fj CLI with tea CLI across all commands - Create new gitea skill, remove forgejo skill - Update all agents to use gitea skill - Update commands to use skill-based approach (reference skills instead of embedding CLI commands) - Update all documentation (README, ARCHITECTURE, VISION, writing guides) - Swap git remotes: origin now points to git.flowmade.one (Gitea) 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
103 lines
4.1 KiB
Markdown
103 lines
4.1 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 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
|
|
- **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.
|