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

**CRITICAL**: Tea REQUIRES being run from within a git repository directory that has a Gitea remote configured. It reads `.git/config` to determine the Gitea remote and repository.

**Before running ANY tea command, you MUST:**
1. Navigate to a repository directory: `cd /path/to/repo`
2. Verify a Gitea remote exists: `git remote -v` (should show git.ajet.fyi or similar)
3. Confirm you're authenticated: `tea whoami`

Most tea commands will FAIL if these requirements aren't met. The `--repo owner/repo` flag exists but is unreliable for many operations.

### 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

### Critical Pre-requisites (CHECK THESE FIRST!)

**BEFORE suggesting or running ANY `tea` command, you MUST verify:**

1. **Repository Context**: User is in a git repository directory with a Gitea remote
   ```bash
   pwd                # Verify current directory
   ls .git            # Confirm it's a git repo
   git remote -v      # Must show a Gitea remote (git.ajet.fyi, etc.)
   ```

2. **Authentication**: User is logged in to tea
   ```bash
   tea whoami
   ```

**If not in a repository:** Guide the user to navigate to their repository first:
```bash
cd /path/to/repo
```

**If no Gitea remote exists:** Tea will not work. User must add a Gitea remote:
```bash
git remote add origin https://git.ajet.fyi/owner/repo.git
```

**If not authenticated:** Guide the user to login:
```bash
tea login add --url https://git.ajet.fyi
```

**IMPORTANT**: The `--repo owner/repo` flag is unreliable and should NOT be used as a workaround. Always ensure proper repository context first.

### 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**: This is the #1 cause of tea command failures. Tea REQUIRES being in a git repository directory with a Gitea remote. Always verify with `pwd`, `ls .git`, and `git remote -v` before running tea commands.
- **Missing Gitea remote**: Tea only works with Gitea remotes (e.g., git.ajet.fyi). It will NOT work with GitHub, GitLab, or other Git hosting services.
- **Using `--repo` flag as workaround**: The `--repo owner/repo` flag is unreliable. Don't use it as a substitute for proper repository context.
- **Missing authentication**: Always check `tea whoami` before running commands
- **Insufficient token permissions**: Token needs appropriate scopes for the operations you're performing
- **Branch not pushed**: Can't create PR for unpushed branches - ensure `git push` succeeds first

## 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