payload-billing/.github/CLAUDE_AUTOMATION.md

Claude Issue Implementation Automation

This repository includes GitHub workflow automation that allows Claude to implement issues automatically when requested via issue comments.

How to Use

1. Trigger Implementation

Comment on any open issue with one of these triggers:

• @claude implement
• @claude fix
• @claude create

Example:

@claude implement

Please add TypeScript support for the billing configuration options.

2. What Happens

When you trigger the automation:

1. Permission Check: Verifies you have write access to the repository
2. Branch Creation: Creates a new branch under claude/issue-{number}-{timestamp}
3. Implementation: Claude analyzes the issue and implements the requested changes
4. Pull Request: Automatically creates a PR with the implementation
5. Notification: Updates the issue with progress and results

3. Branch Naming Convention

Branches are created with the pattern:

claude/issue-{issue-number}-{timestamp}

Examples:

• claude/issue-123-20241218-143052
• claude/issue-456-20241218-151234

4. Requirements

Repository Setup

• The workflow must be merged into your default branch (usually main or dev)
• Required GitHub secrets:
  • CLAUDE_API_KEY - Your Claude API key for implementation

Issue Requirements

• Issue must be open
• Issue should have clear, actionable requirements
• Include relevant context, code examples, or specifications

User Permissions

• Only users with write access or higher can trigger implementations
• This includes repository collaborators, maintainers, and owners

Examples

Good Issue for Implementation

## Feature Request: Add Invoice PDF Export

**Description**: Users should be able to export invoices as PDF files

**Requirements**:
- Add "Export PDF" button to invoice detail page
- Generate PDF using existing invoice data
- Include company logo and styling
- Support both individual and bulk export

**Acceptance Criteria**:
- [ ] PDF export button appears on invoice page
- [ ] Generated PDF matches invoice design
- [ ] Bulk export works from invoice list
- [ ] Error handling for failed exports

Trigger Comment

@claude implement

Please implement the PDF export feature as described in the issue. Make sure to follow the existing code patterns and add appropriate tests.

Workflow Features

✅ Automated Branch Management

• Creates unique branches for each implementation
• Cleans up branches if no changes are made
• Prevents branch name conflicts

✅ Permission Control

• Validates user has write access before proceeding
• Provides clear error messages for unauthorized users

✅ Progress Tracking

• Real-time updates in issue comments
• Links to workflow execution logs
• Clear success/failure notifications

✅ Quality Assurance

• Follows existing code patterns
• Includes appropriate documentation
• Maintains project coding standards

Troubleshooting

Implementation Failed

If the workflow fails:

1. Check the Actions tab for detailed logs
2. Verify the issue has clear, actionable requirements
3. Ensure repository permissions are configured correctly
4. Try again with more specific requirements

No Changes Made

If Claude determines no changes are needed:

• The issue might already be implemented
• Requirements may need clarification
• The request might not be actionable as code

Permission Denied

If you get permission errors:

• Verify you have write access to the repository
• Contact a repository maintainer for access
• Check if you're commenting on the correct repository

Advanced Usage

Multiple Implementations

You can request multiple implementations on the same issue:

• Each trigger creates a new branch
• Previous implementations remain available
• Latest implementation gets priority

Custom Instructions

Provide specific implementation guidance:

@claude implement

Use the Stripe API for payment processing. Follow the existing payment provider pattern in src/providers/. Make sure to add proper error handling and webhook support.

Review Process

All implementations create pull requests that:

• Reference the original issue
• Include detailed implementation notes
• Require manual review before merging
• Follow standard PR review process

Configuration

Required Secrets

Add these secrets in repository settings:

Secret	Description	Required
CLAUDE_API_KEY	Claude API key for implementation	Yes

Workflow Permissions

The workflow requires these permissions:

• contents: write - Create branches and commits
• issues: write - Comment on issues
• pull-requests: write - Create pull requests

Limitations

• Only works with open issues
• Requires clear, actionable requirements
• Limited to repository collaborators
• May need manual refinement for complex features
• Cannot handle issues requiring external services or APIs without proper configuration

Support

If you encounter issues with the automation:

1. Check workflow logs in the Actions tab
2. Verify issue requirements are clear and actionable
3. Ensure you have proper repository permissions
4. Create a new issue describing the problem

---

Note: This automation is powered by Claude AI and creates production-ready code, but all implementations should be reviewed before merging to ensure they meet your specific requirements and quality standards.