cbbee620cd
Introduces project README covering the composable component architecture (commands, skills, agents), quick start guide, available commands, and example workflows. This complements CLAUDE.md which serves as internal instructions for the AI. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
178 lines
6.2 KiB
Markdown
178 lines
6.2 KiB
Markdown
# Claude Code AI Workflow
|
|
|
|
A composable toolkit for enhancing [Claude Code](https://claude.ai/claude-code) with structured workflows, issue management, and AI-assisted development practices.
|
|
|
|
## Why This Project?
|
|
|
|
Claude Code is powerful, but its effectiveness depends on how you use it. This project provides:
|
|
|
|
- **Structured workflows** for common development tasks (issue tracking, PR reviews, planning)
|
|
- **Composable components** that build on each other (skills, agents, commands)
|
|
- **Forgejo integration** for seamless issue and PR management
|
|
- **Consistent patterns** that make AI assistance more predictable and effective
|
|
|
|
## Core Concepts
|
|
|
|
The project is built around three composable component types:
|
|
|
|
```
|
|
┌─────────────────────────────────────────────────────────┐
|
|
│ COMMANDS │
|
|
│ User-facing entry points (/work-issue) │
|
|
│ │ │
|
|
│ ▼ │
|
|
│ ┌─────────────────────────────────────────────────┐ │
|
|
│ │ AGENTS │ │
|
|
│ │ Subprocesses with isolated context │ │
|
|
│ │ (parallel processing, complex workflows) │ │
|
|
│ │ │ │ │
|
|
│ │ ▼ │ │
|
|
│ │ ┌───────────────────────────────────────────┐ │ │
|
|
│ │ │ SKILLS │ │ │
|
|
│ │ │ Reusable knowledge modules │ │ │
|
|
│ │ │ (forgejo, issue-writing, planning) │ │ │
|
|
│ │ └───────────────────────────────────────────┘ │ │
|
|
│ └─────────────────────────────────────────────────┘ │
|
|
└─────────────────────────────────────────────────────────┘
|
|
```
|
|
|
|
| Component | Purpose | Example |
|
|
|-----------|---------|---------|
|
|
| **Commands** | Entry points users invoke directly | `/work-issue 42` starts implementation workflow |
|
|
| **Skills** | Domain knowledge modules | `issue-writing` knows how to structure good issues |
|
|
| **Agents** | Autonomous subprocesses | `product-manager` combines skills for complex planning |
|
|
|
|
## Quick Start
|
|
|
|
### Prerequisites
|
|
|
|
- [Claude Code CLI](https://claude.ai/claude-code) installed
|
|
- [Forgejo CLI](https://code.forgejo.org/forgejo/forgejo-cli) (`fj`) for issue/PR management
|
|
|
|
### Installation
|
|
|
|
```bash
|
|
# Clone the repository
|
|
git clone ssh://git@code.flowmade.one/flowmade-one/ai.git
|
|
cd ai
|
|
|
|
# Install symlinks to ~/.claude/
|
|
make install
|
|
```
|
|
|
|
### Forgejo Setup
|
|
|
|
```bash
|
|
# Install forgejo-cli
|
|
brew install forgejo-cli
|
|
|
|
# Authenticate (one-time)
|
|
echo "YOUR_TOKEN" | fj -H code.flowmade.one auth add-key username
|
|
|
|
# Required token scopes: read:user, read:repository, write:issue, write:repository
|
|
```
|
|
|
|
## Available Commands
|
|
|
|
| Command | Description |
|
|
|---------|-------------|
|
|
| `/dashboard` | Show open issues and PRs for the current repo |
|
|
| `/work-issue <n>` | Fetch issue, create branch, implement, and create PR |
|
|
| `/review-pr <n>` | Review a PR with diff analysis and feedback |
|
|
| `/create-issue` | Create single or batch issues interactively |
|
|
| `/plan-issues <desc>` | Break down a feature into discrete issues |
|
|
| `/groom [n]` | Improve issue quality (single or batch) |
|
|
| `/roadmap` | Visualize issues by status and dependencies |
|
|
|
|
## Project Structure
|
|
|
|
```
|
|
ai/
|
|
├── commands/ # Slash commands invoked by users
|
|
│ ├── work-issue.md
|
|
│ ├── dashboard.md
|
|
│ ├── review-pr.md
|
|
│ ├── create-issue.md
|
|
│ ├── plan-issues.md
|
|
│ ├── groom.md
|
|
│ └── roadmap.md
|
|
├── skills/ # Reusable knowledge modules
|
|
│ ├── forgejo/ # Forgejo CLI integration
|
|
│ ├── issue-writing/ # Issue structure best practices
|
|
│ ├── backlog-grooming/ # Backlog maintenance
|
|
│ └── roadmap-planning/ # Feature breakdown
|
|
├── agents/ # Specialized subagents
|
|
│ └── product-manager/ # Combines skills for PM tasks
|
|
├── scripts/ # Git hooks and utilities
|
|
│ └── pre-commit-checks.sh
|
|
├── settings.json # Claude Code configuration
|
|
├── Makefile # Symlink management
|
|
└── CLAUDE.md # Instructions for Claude Code
|
|
```
|
|
|
|
## Example Workflows
|
|
|
|
### Working on an Issue
|
|
|
|
```
|
|
> /work-issue 42
|
|
|
|
Fetching issue #42: "Add user authentication"
|
|
Creating branch: feature/42-add-user-authentication
|
|
Planning implementation...
|
|
[Claude implements the feature]
|
|
Creating PR with reference to issue...
|
|
```
|
|
|
|
### Planning a Feature
|
|
|
|
```
|
|
> /plan-issues Add dark mode support
|
|
|
|
Proposed Issues:
|
|
1. Create theme context and provider
|
|
2. Add theme toggle component
|
|
3. Update components to use theme variables
|
|
4. Add system preference detection
|
|
|
|
Create these issues? [y/n]
|
|
```
|
|
|
|
### Daily Standup
|
|
|
|
```
|
|
> /dashboard
|
|
|
|
Open Issues (3):
|
|
| # | Title | Labels |
|
|
|----|--------------------------|-------------|
|
|
| 42 | Add user authentication | feature |
|
|
| 38 | Fix login redirect | bug |
|
|
| 35 | Update dependencies | maintenance |
|
|
|
|
Open PRs (1):
|
|
| # | Title | Status |
|
|
|----|--------------------------|-------------|
|
|
| 41 | Add password reset flow | review |
|
|
```
|
|
|
|
## Configuration
|
|
|
|
The `settings.json` configures Claude Code behavior:
|
|
|
|
- **Model selection**: Uses Opus for complex tasks
|
|
- **Status line**: Shows git branch and status
|
|
- **Hooks**: Pre-commit validation for secrets and YAML
|
|
|
|
## Uninstall
|
|
|
|
```bash
|
|
make uninstall
|
|
```
|
|
|
|
This removes symlinks from `~/.claude/` and restores any backed-up files.
|
|
|
|
## License
|
|
|
|
MIT
|