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:

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

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

   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

   tea whoami
   

If not in a repository: Guide the user to navigate to their repository first:

cd /path/to/repo

If no Gitea remote exists: Tea will not work. User must add a Gitea remote:

git remote add origin https://git.ajet.fyi/owner/repo.git

If not authenticated: Guide the user to login:

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:

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