# Claude Code AI Workflow

This repository contains configurations, prompts, and tools to improve the Claude Code AI workflow.

## Setup

```bash
# Clone and install symlinks
git clone ssh://git@code.flowmade.one/flowmade-one/ai.git
cd ai
make install
```

## Project Structure

```
ai/
├── commands/       # Slash commands (/work-issue, /dashboard)
├── skills/         # Knowledge modules (auto-triggered)
├── agents/         # Focused subtask handlers (isolated context)
├── scripts/        # Hook scripts (pre-commit, token loading)
├── settings.json   # Claude Code settings
└── Makefile        # Install/uninstall symlinks
```

All files symlink to `~/.claude/` via `make install`.

## Architecture

### Skills
Knowledge modules that teach Claude how to do something. Referenced by commands via `@~/.claude/skills/xxx/SKILL.md`.

- **Purpose**: Encode best practices and tool knowledge
- **Location**: `skills/<name>/SKILL.md`
- **Usage**: Included in commands for context, auto-triggered by Claude Code

Example: `gitea` skill teaches tea CLI usage, `issue-writing` teaches how to structure issues.

### Commands
User-facing entry points invoked with `/command-name`. Run in main conversation context.

- **Purpose**: Orchestrate workflows with user interaction
- **Location**: `commands/<name>.md`
- **Usage**: User types `/dashboard`, `/work-issue 42`, etc.

Commands reference skills for knowledge and optionally spawn agents for subtasks.

### Agents
Small, focused units that handle specific subtasks in isolated context.

- **Purpose**: Complex subtasks that benefit from isolation
- **Location**: `agents/<name>/agent.md`
- **Usage**: Spawned via Task tool, return results to caller

Good agent candidates:
- Code review (analyze diff, report issues)
- Content generation (write issue body, PR description)
- Analysis tasks (categorize, prioritize, summarize)

**When to use agents vs direct execution:**
- Use agents when: task is self-contained, benefits from isolation, can run in parallel
- Use direct execution when: task needs conversation history, requires user interaction mid-task

## Gitea Integration

Uses `tea` CLI for issue/PR management:

```bash
# Setup (one-time)
brew install tea
tea logins add --name flowmade --url https://git.flowmade.one --token <your-token>

# Create token at: https://git.flowmade.one/user/settings/applications
```

## Available Commands

| Command | Description |
|---------|-------------|
| `/work-issue <n>` | Fetch issue, create branch, implement, create PR |
| `/dashboard` | Show open issues and PRs |
| `/review-pr <n>` | Review PR with diff and comments |
| `/create-issue` | Create single or batch issues |
| `/retro` | Capture learnings, create improvement issues |
| `/vision` | View/manage product vision and milestones |
| `/plan-issues` | Break down features into issues |
| `/improve` | Identify gaps between vision and backlog |

## Vision & Goals

Product vision lives in `vision.md` (philosophy) and Gitea milestones (goals with progress tracking). See `/vision` command.