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:

tea whoami

Common Operations

Pull Requests:

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:

tea issues ls                                # List issues
tea issues create -t "Title" -d "Body"      # Create issue
tea issues close 42                          # Close issue

Releases:

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:

tea whoami

If not authenticated, guide the user to run:

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:

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

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

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:

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:

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:

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