Modes for different types of workflows

[ashwin-ant]

Currently this action is very tied to the concept of tagging Claude on an issue or PR, and getting results either in the original Claude comment or in commits added to a branch. But for use cases like code review, we post the entire review in a single tracking comment, which isn't great. And for other types of workflows like schedule or workflow_dispatch (which we'd like to support), the current structure is even more limiting.

One way to make space for new types of workflows might be modes. We could start with three:

• tag mode: The mode that exists right now. Used when Claude is tagged, and always posts back in a tracking comment. We always put Claude on the correct branch before it begins working.
• review mode: A more purpose-built code review mode. Would do without the tracking comment but still work on a specified branch, and would always use inline comments and proper GitHub code revews.
• freeform mode (or some better name): Even fewer constraints, more flexibility for automated workflows like schedule. No specified branch, no tracking comment.

Open to thoughts here!

[ashwin-ant]

Another approach may be separate actions for each mode. This would keep the inputs cleaner since we wouldn't have to support tons of inputs for a single action.

[ashwin-ant]

Mode-Based Architecture Plan

Overview

We're introducing a flexible mode system to make claude-code-action suitable for different use cases beyond just tagging Claude for implementation tasks.

New Inputs

mode

• Values: tag (default), review, freeform
• Purpose: Controls the action's behavior and defaults
• Default: tag (maintains backward compatibility)

use_tracking_comment

• Purpose: Controls whether to create/update progress tracking comments
• Default: Depends on mode
  • tag: true (shows progress)
  • review: false (cleaner for reviews)
  • freeform: true (configurable)

override_prompt

• Purpose: Complete replacement of Claude's prompt with custom template
• Features: Supports variable substitution for dynamic content

Mode Behaviors

Tag Mode (Default)

Current behavior - ideal for implementation tasks:

• Responds to @claude mentions, assignments, and labels
• Creates tracking comment showing progress
• Updates branches and commits changes
• Full implementation capabilities

Review Mode

Optimized for code reviews:

• No tracking comment by default (cleaner PR experience)
• Focused on providing review feedback
• Uses GitHub's PR review API for inline comments
• Review-specific MCP tools enabled by default
• Prompts tuned for code review, not implementation

Freeform Mode

For automation and workflow_dispatch:

• No trigger checking (always runs)
• Highly flexible for custom workflows
• Works well with override_prompt
• Suitable for scheduled tasks, documentation checks, etc.

Override Prompt Variables

When using override_prompt, these variables are available:

$REPOSITORY        - Repository name (owner/repo)
$PR_NUMBER         - Pull request number
$ISSUE_NUMBER      - Issue number
$PR_TITLE          - Pull request title
$ISSUE_TITLE       - Issue title
$PR_BODY           - Pull request description
$ISSUE_BODY        - Issue description
$PR_COMMENTS       - Formatted PR comments
$ISSUE_COMMENTS    - Formatted issue comments
$REVIEW_COMMENTS   - PR review comments
$CHANGED_FILES     - List of changed files in PR
$TRIGGER_COMMENT   - The comment that triggered Claude
$TRIGGER_USERNAME  - Username who triggered
$BRANCH_NAME       - Current branch name
$BASE_BRANCH       - Base/target branch
$EVENT_TYPE        - GitHub event type
$IS_PR             - "true" or "false"

Example Configurations

Code Review Workflow

- uses: anthropics/claude-code-action@main
  with:
    mode: review
    anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}

Custom Security Review

- uses: anthropics/claude-code-action@main
  with:
    mode: review
    override_prompt: |
      Analyze PR #$PR_NUMBER for security vulnerabilities.
      Focus on: SQL injection, XSS, authentication bypasses.
      
      Files changed:
      $CHANGED_FILES
      
      Provide severity ratings for any issues found.

Automated Documentation Check

- uses: anthropics/claude-code-action@main
  with:
    mode: freeform
    override_prompt: |
      Check if the documentation in $REPOSITORY is up to date.
      Changed files: $CHANGED_FILES
      
      Verify:
      1. README reflects new features
      2. API docs match implementation
      3. Examples are working

Traditional Usage (Unchanged)

- uses: anthropics/claude-code-action@main
  with:
    anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
    # Defaults to mode: tag

Architecture Benefits

1. Backward Compatible: Existing workflows continue working without changes
2. Clear Separation: Each mode has distinct behavior and use cases
3. Flexible Prompting: Override prompts enable specialized workflows
4. Better UX: Review mode provides cleaner PR experience without progress tracking
5. Extensible: Easy to add new modes or variables in the future

Implementation Approach

The mode system will be implemented through:

• Conditional logic in prepare.ts for trigger checking and comment creation
• Mode-specific prompt templates in create-prompt/index.ts
• Variable substitution system for override prompts
• Mode-aware tool configuration (different defaults per mode)
• Updated comment handling to respect use_tracking_comment setting