Plan for issue #8

plans/8.md

@@ -0,0 +1,219 @@
+# Implementation Plan for Issue #8
+
+## Issue Summary
+
+Users want to use LLM providers other than Anthropic Claude through the existing automated workflow system. Specifically mentioned are z.ai models and MiniMax models, but the solution should be extensible to any provider compatible with Claude Code.
+
+## Feasibility Assessment
+
+- **Status**: ✅ Feasible
+- **Complexity**: Medium
+- **Estimated Effort**: Moderate
+
+The `anthropics/claude-code-action@v1` GitHub Action supports custom base URLs and models through environment variables. This means we can support any OpenAI-compatible API (including z.ai, MiniMax, and many others) by leveraging the existing action with different configuration values.
+
+### Key Insight
+
+The `claude-code-action` can be configured to use any OpenAI-compatible endpoint by setting:
+- `ANTHROPIC_BASE_URL` - The API endpoint (e.g., `https://api.z.ai/v1`, `https://api.minimax.chat/v1`)
+- `ANTHROPIC_MODEL` - The model name (e.g., `gpt-4`, `claude-v3`, provider-specific model names)
+
+This means we **don't need separate GitHub Actions** for each provider. We only need to add configuration for provider selection.
+
+## Proposed Solution
+
+### Overview
+
+Instead of creating provider-specific workflows or GitHub Actions, we'll introduce a **provider configuration system** that allows users to specify their preferred provider through repository variables. The existing `anthropics/claude-code-action` will be used with different configuration values depending on the selected provider.
+
+### Architecture Changes
+
+```
+Current:  Anthropic only (hardcoded)
+          └── ANTHROPIC_BASE_URL, ANTHROPIC_MODEL
+
+New:      Provider-agnostic configuration
+          ├── PROVIDER_BASE_URL (new)
+          ├── PROVIDER_MODEL (new)
+          └── Provider name (for display/logging)
+```
+
+The workflows will remain structurally the same but will use provider-agnostic environment variables that can be configured to work with any OpenAI-compatible API.
+
+### Implementation Steps
+
+1. **Add Provider Configuration Variables**
+   - Files to modify: None (this is documentation for users to set up)
+   - Approach: Document that users should configure these repository variables:
+     - `PROVIDER_BASE_URL`: The API base URL (e.g., `https://api.anthropic.com`, `https://api.z.ai/v1`)
+     - `PROVIDER_MODEL`: The model identifier (e.g., `claude-sonnet-4-20250514`, `gpt-4`)
+   - Testing considerations: Verify that different base URLs work with the action
+
+2. **Update Workflow Files to Use Provider-Agnostic Variables**
+   - Files to modify:
+     - `.github/workflows/claude-plan.yml`
+     - `.github/workflows/claude-implement.yml`
+     - `.github/workflows/claude-review.yml`
+   - Approach: Replace `ANTHROPIC_BASE_URL` with `PROVIDER_BASE_URL` and `ANTHROPIC_MODEL` with `PROVIDER_MODEL` in the env sections
+   - Testing considerations: Test with different provider configurations
+
+3. **Add Provider Selection Documentation**
+   - Files to create: `docs/PROVIDER_SETUP.md` or `README.md` section
+   - Approach: Document how to configure different providers:
+     - Anthropic (default)
+     - z.ai
+     - MiniMax
+     - Any OpenAI-compatible API
+   - Testing considerations: Verify documentation is clear and complete
+
+4. **Update CLAUDE.md with Provider Guidelines**
+   - Files to modify: `CLAUDE.md`
+   - Approach: Add section about provider configuration and how to add new providers
+   - Testing considerations: Ensure the guidelines are clear for future maintainers
+
+5. **(Optional) Add Provider Validation Job**
+   - Files to modify: All three workflow files
+   - Approach: Add a validation step that checks if `PROVIDER_BASE_URL` and `PROVIDER_MODEL` are set before running the main job
+   - Testing considerations: Test with missing variables to ensure proper error handling
+
+### Detailed Changes
+
+#### Step 1: Update `.github/workflows/claude-plan.yml`
+
+Replace:
+```yaml
+env:
+  ANTHROPIC_BASE_URL: ${{ vars.ANTHROPIC_BASE_URL }}
+  ANTHROPIC_MODEL: ${{ vars.ANTHROPIC_MODEL }}
+```
+
+With:
+```yaml
+env:
+  PROVIDER_BASE_URL: ${{ vars.PROVIDER_BASE_URL }}
+  PROVIDER_MODEL: ${{ vars.PROVIDER_MODEL }}
+```
+
+Also update the action's env section:
+```yaml
+- name: Generate Plan with Claude
+  id: claude
+  uses: anthropics/claude-code-action@v1
+  env:
+    ANTHROPIC_BASE_URL: ${{ vars.PROVIDER_BASE_URL }}
+    ANTHROPIC_MODEL: ${{ vars.PROVIDER_MODEL }}
+```
+
+Note: We keep `ANTHROPIC_BASE_URL` and `ANTHROPIC_MODEL` in the action's env because that's what the action expects, but we populate them from the provider-agnostic variables.
+
+#### Step 2: Apply Same Changes to Other Workflows
+
+Apply identical changes to:
+- `.github/workflows/claude-implement.yml`
+- `.github/workflows/claude-review.yml`
+
+#### Step 3: Create Provider Configuration Documentation
+
+Create `docs/PROVIDER_SETUP.md` with:
+
+```markdown
+# Provider Configuration Guide
+
+This project supports any OpenAI-compatible LLM provider through the Claude Code GitHub Action.
+
+## Supported Providers
+
+### Anthropic (Default)
+- PROVIDER_BASE_URL: `https://api.anthropic.com`
+- PROVIDER_MODEL: `claude-sonnet-4-20250514` (or any Claude model)
+
+### z.ai
+- PROVIDER_BASE_URL: `https://api.z.ai/v1`
+- PROVIDER_MODEL: Contact z.ai for available model names
+
+### MiniMax
+- PROVIDER_BASE_URL: `https://api.minimax.chat/v1`
+- PROVIDER_MODEL: Contact MiniMax for available model names
+
+## Setup Instructions
+
+1. Go to your repository Settings → Secrets and variables → Actions
+2. Add the following repository variables:
+   - `PROVIDER_BASE_URL`: Your provider's API endpoint
+   - `PROVIDER_MODEL`: The model identifier you want to use
+3. Ensure your authentication token (e.g., `ANTHROPIC_AUTH_TOKEN`) is set as a secret
+```
+
+#### Step 4: Update CLAUDE.md
+
+Add a "Provider Configuration" section:
+
+```markdown
+## Provider Configuration
+
+This repository supports multiple LLM providers through a unified configuration system. Provider settings are configured via GitHub repository variables:
+
+- `PROVIDER_BASE_URL`: The API endpoint for the provider
+- `PROVIDER_MODEL`: The model identifier to use
+
+When implementing features, remember that the code should work with any configured provider, not just Anthropic.
+```
+
+### Dependencies
+
+- External dependencies: None
+- Internal dependencies: None (uses existing `anthropics/claude-code-action@v1`)
+
+### Risk Assessment
+
+| Risk | Mitigation |
+|------|------------|
+| Some providers may have different API behaviors | The Claude Code Action handles API differences internally |
+| Users may misconfigure provider URLs | Add validation step and clear error messages |
+| Provider-specific features may not work | Document that only standard features are guaranteed |
+| Authentication methods may differ | Users must ensure their token works with their provider |
+
+### Testing Strategy
+
+1. **Manual Testing**: Test with at least one non-Anthropic provider (e.g., a local OpenAI-compatible server)
+2. **Variable Validation**: Ensure workflows fail gracefully if provider variables are missing
+3. **Documentation Review**: Verify setup instructions are clear for new users
+
+## Alternatives Considered
+
+### Alternative 1: Separate Workflows per Provider
+**Rejected**: Would require maintaining duplicate workflow files for each provider. Harder to maintain and doesn't scale.
+
+### Alternative 2: Dynamic Action Selection
+**Rejected**: Would require finding equivalent GitHub Actions for each provider, which may not exist. The Claude Code Action already supports custom endpoints.
+
+### Alternative 3: Matrix Strategy for Multiple Providers
+**Rejected**: Would run workflows multiple times (once per provider), increasing costs. Users typically want one provider, not all of them simultaneously.
+
+## Backward Compatibility
+
+This change is **backward compatible**:
+- Existing users with `ANTHROPIC_BASE_URL` and `ANTHROPIC_MODEL` can simply rename their variables
+- Or, we can add fallback logic to check for old variable names
+
+**Recommended**: Add fallback in workflows:
+
+```yaml
+env:
+  PROVIDER_BASE_URL: ${{ vars.PROVIDER_BASE_URL || vars.ANTHROPIC_BASE_URL }}
+  PROVIDER_MODEL: ${{ vars.PROVIDER_MODEL || vars.ANTHROPIC_MODEL }}
+```
+
+## Implementation Order
+
+1. Update workflow files with new variable names and fallback logic
+2. Create provider setup documentation
+3. Update CLAUDE.md with provider guidelines
+4. Test with a non-Anthropic provider (if available)
+5. Create PR for review
+
+## References
+
+- Related issues: #8
+- Related PRs: (to be created)
+- Documentation: [Claude Code Action Documentation](https://github.com/anthropics/claude-code-action)