architecture/README.md

# 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
│   └── code-review/    # Code review best practices
├── agents/             # Specialized subagents
│   ├── product-manager/  # Combines skills for PM tasks
│   └── code-reviewer/  # Automated PR code review
├── 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