docs: update all examples and docs to use version tags instead of @main

CLAUDE_WORKFLOW_MIGRATION.md

@@ -82,9 +82,27 @@ After setup, test the workflows by:
 
 1. **Ensure reusable workflows exist** in claude-workflows repository (already done here)
 2. **Test the migration** with a sample PR
-3. **Apply to other repositories** using the same pattern
+3. **Apply to other repositories** using the same pattern with version tags (e.g., `@v1.0.0`)
 4. **Document usage** for other teams
 
+## ⚠️ Important: Use Version Tags for Production
+
+When referencing the centralized workflows, **always use version tags** instead of `@main`:
+
+```yaml
+# ✅ Good - Production stable
+uses: dotCMS/claude-workflows/.github/workflows/claude-orchestrator.yml@v1.0.0
+
+# ❌ Bad - Can cause unexpected behavior
+uses: dotCMS/claude-workflows/.github/workflows/claude-orchestrator.yml@main
+```
+
+**Why version tags matter:**
+- **Stability**: Version tags are immutable and won't change unexpectedly
+- **Predictability**: You know exactly which version you're using
+- **Rollback**: Easy to rollback to previous versions if needed
+- **Production Safety**: Prevents breaking changes from affecting production workflows
+
 ## Benefits for Other Repositories
 
 Other dotCMS repositories can now easily add Claude support by:

README.md

@@ -15,13 +15,15 @@ Reusable Claude AI GitHub Actions workflows and config for dotCMS and related pr
 
 If you previously used the pilot Claude workflow in `dotcms/infrastructure-as-code`, follow these steps:
 
+### 📋 Migration Checklist
+
 1. **Remove references to the old pilot workflow** in your repository's workflow files.
-2. **Update your workflow to use the new orchestrator:**
+2. **Update your workflow to use the new orchestrator with version tags:**
 
    ```yaml
    jobs:
      claude:
-       uses: dotCMS/claude-workflows/.github/workflows/claude-orchestrator.yml@main
+       uses: dotCMS/claude-workflows/.github/workflows/claude-orchestrator.yml@v1.0.0
        with:
          trigger_mode: automatic  # or 'interactive' for @claude mentions
          # Customize as needed for your repo
@@ -34,8 +36,12 @@ If you previously used the pilot Claude workflow in `dotcms/infrastructure-as-co
        secrets:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
    ```
+
+   ⚠️ **Important**: Always use version tags (e.g., `@v1.0.0`) instead of `@main` for production stability. Using `@main` can cause unexpected behavior when the main branch is updated.
+
 3. **Configure your `ANTHROPIC_API_KEY` secret** as described below.
 4. **(Optional) Customize prompts, allowed tools, and runner as needed.**
+5. **Test your migration** with a sample PR or @claude mention.
 
 ---
 
@@ -136,7 +142,7 @@ on:
 jobs:
   # Interactive Claude mentions using built-in detection
   claude-interactive:
-    uses: dotCMS/claude-workflows/.github/workflows/claude-orchestrator.yml@main
+    uses: dotCMS/claude-workflows/.github/workflows/claude-orchestrator.yml@v1.0.0
     with:
       trigger_mode: interactive
       allowed_tools: |
@@ -149,7 +155,7 @@ jobs:
   # Automatic PR reviews (no @claude mention required)
   claude-automatic:
     if: github.event_name == 'pull_request'
-    uses: dotCMS/claude-workflows/.github/workflows/claude-orchestrator.yml@main
+    uses: dotCMS/claude-workflows/.github/workflows/claude-orchestrator.yml@v1.0.0
     with:
       trigger_mode: automatic
       direct_prompt: |
@@ -181,7 +187,7 @@ For advanced use cases beyond @claude mentions, use `custom_trigger_condition`:
 ```yaml
 jobs:
   claude-security-review:
-    uses: dotCMS/claude-workflows/.github/workflows/claude-orchestrator.yml@main
+    uses: dotCMS/claude-workflows/.github/workflows/claude-orchestrator.yml@v1.0.0
     with:
       trigger_mode: automatic
       custom_trigger_condition: |
@@ -212,15 +218,15 @@ See the `examples/` directory for complete workflow examples:
 
 **Basic @claude mention detection:**
 ```yaml
-uses: dotCMS/claude-workflows/.github/workflows/claude-orchestrator.yml@main
+uses: dotCMS/claude-workflows/.github/workflows/claude-orchestrator.yml@v1.0.0
 with:
   trigger_mode: interactive
   enable_mention_detection: true
 ```
 
 **Automatic PR reviews:**
 ```yaml
-uses: dotCMS/claude-workflows/.github/workflows/claude-orchestrator.yml@main
+uses: dotCMS/claude-workflows/.github/workflows/claude-orchestrator.yml@v1.0.0
 with:
   trigger_mode: automatic
   direct_prompt: "Review this PR for quality and security."
@@ -229,7 +235,7 @@ with:
 
 **Custom triggers for urgent issues:**
 ```yaml
-uses: dotCMS/claude-workflows/.github/workflows/claude-orchestrator.yml@main
+uses: dotCMS/claude-workflows/.github/workflows/claude-orchestrator.yml@v1.0.0
 with:
   trigger_mode: interactive
   custom_trigger_condition: |

examples/advanced-custom-triggers.yml

@@ -31,7 +31,7 @@ on:
 jobs:
   # Example 1: Custom trigger for urgent issues only
   claude-urgent-issues:
-    uses: dotCMS/claude-workflows/.github/workflows/claude-orchestrator.yml@main
+    uses: dotCMS/claude-workflows/.github/workflows/claude-orchestrator.yml@v1.0.0
     with:
       trigger_mode: interactive
       # Custom condition: Only trigger for issues labeled as "urgent" or "critical"
@@ -52,7 +52,7 @@ jobs:
 
   # Example 2: Custom trigger for specific file changes
   claude-config-changes:
-    uses: dotCMS/claude-workflows/.github/workflows/claude-orchestrator.yml@main
+    uses: dotCMS/claude-workflows/.github/workflows/claude-orchestrator.yml@v1.0.0
     with:
       trigger_mode: automatic
       # Custom condition: Only trigger for PRs that modify configuration files
@@ -81,7 +81,7 @@ jobs:
 
   # Example 3: Custom trigger combining multiple conditions
   claude-security-review:
-    uses: dotCMS/claude-workflows/.github/workflows/claude-orchestrator.yml@main
+    uses: dotCMS/claude-workflows/.github/workflows/claude-orchestrator.yml@v1.0.0
     with:
       trigger_mode: automatic
       # Custom condition: Security-related changes or mentions
@@ -115,7 +115,7 @@ jobs:
 
   # Example 4: Fallback with default @claude mention detection
   claude-general:
-    uses: dotCMS/claude-workflows/.github/workflows/claude-orchestrator.yml@main
+    uses: dotCMS/claude-workflows/.github/workflows/claude-orchestrator.yml@v1.0.0
     with:
       trigger_mode: interactive
       # No custom condition - will use default @claude mention detection

examples/consumer-repo-workflow.yml

@@ -31,7 +31,7 @@ on:
 jobs:
   # Interactive Claude mentions (simplified using centralized logic)
   claude-interactive:
-    uses: dotCMS/claude-workflows/.github/workflows/claude-orchestrator.yml@main
+    uses: dotCMS/claude-workflows/.github/workflows/claude-orchestrator.yml@v1.0.0
     with:
       trigger_mode: interactive
       allowed_tools: |
@@ -55,7 +55,7 @@ jobs:
       !contains(github.event.pull_request.body, '@claude') &&
       !contains(github.event.pull_request.body, '@Claude') &&
       !contains(github.event.pull_request.body, '@CLAUDE')
-    uses: dotCMS/claude-workflows/.github/workflows/claude-orchestrator.yml@main
+    uses: dotCMS/claude-workflows/.github/workflows/claude-orchestrator.yml@v1.0.0
     with:
       trigger_mode: automatic
       direct_prompt: |

examples/infrastructure-consumer-workflow.yml

@@ -38,7 +38,7 @@ on:
 jobs:
   # Interactive Claude mentions (simplified using centralized logic)
   claude-interactive:
-    uses: dotCMS/claude-workflows/.github/workflows/claude-orchestrator.yml@main
+    uses: dotCMS/claude-workflows/.github/workflows/claude-orchestrator.yml@v1.0.0
     with:
       trigger_mode: interactive
       allowed_tools: |
@@ -68,7 +68,7 @@ jobs:
       !contains(github.event.pull_request.body, '@claude') &&
       !contains(github.event.pull_request.body, '@Claude') &&
       !contains(github.event.pull_request.body, '@CLAUDE')
-    uses: dotCMS/claude-workflows/.github/workflows/claude-orchestrator.yml@main
+    uses: dotCMS/claude-workflows/.github/workflows/claude-orchestrator.yml@v1.0.0
     with:
       trigger_mode: automatic
       direct_prompt: |