docs: clarify agent mode only works with workflow_dispatch and schedule events (#378)

* docs: clarify agent mode only works with workflow_dispatch and schedule events

Updates documentation to match the current implementation where agent mode
is restricted to workflow_dispatch and schedule events only. This addresses
the confusion reported in issues #364 and #376.

Changes:
- Updated README to clearly state agent mode limitations
- Added explicit note that agent mode does NOT work with PR/issue events
- Updated example workflows to only show supported event types
- Updated CLAUDE.md internal documentation

Fixes #364
Fixes #376

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>

* minor formatting update

* update agent mode docs

---------

Co-authored-by: km-anthropic <km-anthropic@users.noreply.github.com>
Co-authored-by: Claude <noreply@anthropic.com>

CLAUDE.md

@@ -53,7 +53,7 @@ Execution steps:
 #### Mode System (`src/modes/`)
 
 - **Tag Mode** (`tag/`): Responds to `@claude` mentions and issue assignments
-- **Agent Mode** (`agent/`): Automated execution without trigger checking
+- **Agent Mode** (`agent/`): Automated execution for workflow_dispatch and schedule events only
 - Extensible registry pattern in `modes/registry.ts`
 
 #### GitHub Integration (`src/github/`)
@@ -118,7 +118,7 @@ src/
 
 - Modes implement `Mode` interface with `shouldTrigger()` and `prepare()` methods
 - Registry validates mode compatibility with GitHub event types
-- Agent mode bypasses all trigger checking for automation scenarios
+- Agent mode only works with workflow_dispatch and schedule events
 
 ### Comment Threading
 

README.md

@@ -223,19 +223,32 @@ The traditional implementation mode that responds to @claude mentions, issue ass
 
 ### Agent Mode
 
-For automation and scheduled tasks without trigger checking.
+**Note: Agent mode is currently in active development and may undergo breaking changes.**
 
-- **Triggers**: Always runs (no trigger checking)
+For automation with workflow_dis`patch and scheduled events only.
-- **Features**: Perfect for scheduled tasks, works with `override_prompt`
+
-- **Use case**: Maintenance tasks, automated reporting, scheduled checks
+- **Triggers**: Only runs on `workflow_dispatch` and `schedule` events
+- **Features**: Bypasses mention/assignment checking for automation scenarios
+- **Use case**: Manual workflow runs, scheduled maintenance tasks, cron jobs
+- **Note**: Does NOT work with `pull_request`, `issues`, or `issue_comment` events
 
 ```yaml
-- uses: anthropics/claude-code-action@beta
+# Example with workflow_dispatch
-  with:
+on:
-    mode: agent
+  workflow_dispatch:
-    anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
+  schedule:
-    override_prompt: |
+    - cron: "0 0 * * 0" # Weekly on Sunday
-      Check for outdated dependencies and create an issue if any are found.
+
+jobs:
+  automated-task:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: anthropics/claude-code-action@beta
+        with:
+          mode: agent
+          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
+          override_prompt: |
+            Check for outdated dependencies and create an issue if any are found.
 ```
 
 ### Experimental Review Mode

examples/claude-modes.yml

@@ -1,13 +1,17 @@
 name: Claude Mode Examples
 
 on:
-  # Common events for both modes
+  # Events for tag mode
   issue_comment:
     types: [created]
   issues:
     types: [opened, labeled]
   pull_request:
     types: [opened]
+  # Events for agent mode (only these work with agent mode)
+  workflow_dispatch:
+  schedule:
+    - cron: "0 0 * * 0" # Weekly on Sunday
 
 jobs:
   # Tag Mode (Default) - Traditional implementation
@@ -28,13 +32,12 @@ jobs:
           # - Creates tracking comments with progress checkboxes
           # - Perfect for: Interactive Q&A, on-demand code changes
 
-  # Agent Mode - Automation without triggers
+  # Agent Mode - Automation for workflow_dispatch and schedule events
-  agent-mode-auto-review:
+  agent-mode-scheduled-task:
-    # Automatically review every new PR
+    # Only works with workflow_dispatch or schedule events
-    if: github.event_name == 'pull_request' && github.event.action == 'opened'
     runs-on: ubuntu-latest
     permissions:
-      contents: read
+      contents: write
       pull-requests: write
       issues: write
       id-token: write
@@ -44,13 +47,10 @@ jobs:
           mode: agent
           anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
           override_prompt: |
-            Review this PR for code quality. Focus on:
+            Check for outdated dependencies and security vulnerabilities.
-            - Potential bugs or logic errors
+            Create an issue if any critical problems are found.
-            - Security concerns
-            - Performance issues
-
-            Provide specific, actionable feedback.
           # Agent mode behavior:
-          # - NO @claude mention needed - runs immediately
+          # - ONLY works with workflow_dispatch and schedule events
-          # - Enables true automation (impossible with tag mode)
+          # - Does NOT work with pull_request, issues, or issue_comment events
-          # - Perfect for: CI/CD integration, automatic reviews, label-based workflows
+          # - No @claude mention needed for supported events
+          # - Perfect for: scheduled maintenance, manual automation runs