gong-fu-cha/CLAUDE.md

# CLAUDE.md

This file provides guidance to Claude Code when working with the Gong Fu Cha repository.

## Repository Purpose

This repository provides Claude Code skills for working with Gitea's `tea` CLI tool. The skills enable seamless interaction with Gitea repositories (like git.ajet.fyi) directly through Claude Code conversations.

## Repository Structure

- **skills/SKILL.md** - Main Claude Code skill definition for the `tea` CLI
- **README.md** - User-facing documentation
- **CLAUDE.md** - This file (Claude Code instructions)

## Tea CLI Overview

The `tea` command-line tool is Gitea's official CLI for interacting with Gitea instances. It provides comprehensive functionality for:

- **Pull Requests**: Create, review, merge, checkout
- **Issues**: Create, edit, close, reopen
- **Releases**: Create, edit, delete, manage assets
- **Labels & Milestones**: Manage project organization
- **Comments**: Add comments to issues/PRs
- **Repositories**: Clone, view details
- **Notifications**: Check and manage notifications

## Key Commands

### Context Detection

Tea automatically detects repository context from the current working directory. It reads `.git/config` to determine the Gitea remote and repository.

### Authentication

Tea uses stored credentials in `$XDG_CONFIG_HOME/tea` (usually `~/.config/tea`). Check authentication with:

```bash
tea whoami
```

### Common Operations

**Pull Requests:**
```bash
tea pr ls                                    # List PRs
tea pr create -t "Title" -d "Description"   # Create PR
tea pr checkout 42                           # Checkout PR locally
tea pr approve 42                            # Approve PR
tea pr merge 42                              # Merge PR
```

**Issues:**
```bash
tea issues ls                                # List issues
tea issues create -t "Title" -d "Body"      # Create issue
tea issues close 42                          # Close issue
```

**Releases:**
```bash
tea releases ls                              # List releases
tea releases create --tag v1.0.0 -t "v1.0.0" -n "Release notes"
```

## Important Notes for Claude Code

### Always Check Authentication First

Before running `tea` commands, verify the user is logged in:

```bash
tea whoami
```

If not authenticated, guide the user to run:

```bash
tea login add --url https://git.ajet.fyi
```

### Repository Context

Tea works best when run from within a git repository directory. If tea commands fail with "no repository found", ensure:

1. You're in a git repository directory
2. The repository has a Gitea remote configured
3. Or use `--repo owner/repo` flag to specify repository explicitly

### Output Formats

Tea supports multiple output formats. For machine-readable output, use:

```bash
tea pr ls --output json
tea issues ls -o yaml
```

For user-friendly output, use the default table format or specify:

```bash
tea pr ls --output table
```

### Error Handling

Common errors:

- **"Login not found"**: User needs to run `tea login add`
- **"Repository not found"**: Check repository context or use `--repo` flag
- **"Token expired"**: User needs to refresh OAuth token: `tea login oauth-refresh`
- **"Permission denied"**: Token lacks required scopes

### Help and Documentation

- Use `tea --help` for general help
- Use `tea <command> --help` for command-specific help
- Use `tea man` for comprehensive manual pages

## Development Workflow Integration

### Creating PRs

When helping users create PRs:

1. Ensure changes are committed and pushed
2. Determine base and head branches
3. Generate meaningful PR title and description
4. Use `tea pr create` with appropriate flags

Example:
```bash
tea pr create --title "Feature: Add new capability" \
  --description "Detailed description of changes" \
  --base main \
  --head feature-branch
```

### Managing Issues

When helping users manage issues:

1. List existing issues to check for duplicates
2. Create issues with descriptive titles and labels
3. Link issues to PRs when relevant

Example:
```bash
tea issues create \
  --title "Bug: Fix authentication flow" \
  --description "Detailed description" \
  --labels bug,priority
```

### Release Management

When helping users create releases:

1. Verify the tag doesn't exist
2. Generate release notes from commits
3. Include relevant assets if needed

Example:
```bash
tea releases create \
  --tag v1.0.0 \
  --title "Version 1.0.0" \
  --note "Release notes here" \
  --asset ./binary
```

## Best Practices

1. **Always verify repository context** before running tea commands
2. **Check authentication status** with `tea whoami` first
3. **Use descriptive titles and descriptions** for PRs and issues
4. **Apply relevant labels** to improve organization
5. **Check for duplicates** before creating issues
6. **Use appropriate merge strategies** (merge, squash, rebase)
7. **Clean up branches** after merging PRs

## Integration with Other Tools

Tea works well with:

- **git**: For local repository operations
- **gh** (GitHub CLI): Similar workflow for GitHub repos
- **commitly**: For managing commits across multiple repos

## Skill Usage

The `/tea` skill can be invoked explicitly, but Claude Code should also recognize tea-related requests naturally:

- "Create a PR for my changes"
- "List open issues"
- "Review PR #42"
- "Create a release"

Claude should automatically use the tea skill when appropriate for Gitea operations.

## Extending the Skills

When adding new examples or workflows:

1. Test the commands manually first
2. Add to the appropriate section in `skills/SKILL.md`
3. Include both basic and advanced examples
4. Document any prerequisites or gotchas
5. Update this CLAUDE.md if needed

## Common Pitfalls

- **Not in repo directory**: Many tea commands require repository context
- **Missing authentication**: Always check `tea whoami` first
- **Wrong remote**: Tea looks for Gitea remotes, not GitHub/GitLab
- **Insufficient token permissions**: Token needs appropriate scopes
- **Branch not pushed**: Can't create PR for unpushed branches

## Testing

When testing tea commands:

1. Use a test repository when possible
2. Verify authentication first
3. Check repository context
4. Test with dry-run flags when available
5. Verify output format matches expectations