fix: Update Claude workflow to actually create PRs

The previous workflow just edited files but didn't create a PR. Now it:
1. Creates a new branch (auto/jsdoc-enhancement-<run-number>)
2. Makes JSDoc additions to files
3. Commits the changes
4. Pushes the branch
5. Creates a PR back to the source branch

This ensures Claude's JSDoc enhancements come as reviewable PRs, not direct commits.

🖖 Generated with Claude Code

Co-Authored-By: Claude <[email protected]>

Author: flyingrobots

.github/workflows/claude-jsdoc.yml

@@ -54,9 +54,27 @@ jobs:
         with:
           claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
           prompt: |
-            Analyze these JavaScript files and add comprehensive JSDoc where missing:
+            You need to add comprehensive JSDoc to these JavaScript files:
             ${{ steps.changed-files.outputs.files }}
             
-            Follow the patterns from docs/decisions/000-javascript-not-typescript.md
-            Create a PR with the enhancements.
-          claude_args: '--allowed-tools "Read,Edit,MultiEdit,Bash(gh pr create:*)"'
+            Follow these steps:
+            1. First, check if we're not already on a jsdoc branch: git branch --show-current
+            2. If not on a jsdoc branch, create a new branch: git checkout -b auto/jsdoc-enhancement-${{ github.run_number }}
+            3. Read each file and add JSDoc where missing (classes, functions, methods)
+            4. Follow the patterns from docs/decisions/000-javascript-not-typescript.md
+            5. After editing files, commit: git add -A && git commit -m "docs: Add comprehensive JSDoc documentation
+            
+            - Added @fileoverview headers
+            - Added @param and @returns annotations  
+            - Added @throws for error conditions
+            - Added @example for complex functions
+            
+            Auto-generated by Claude"
+            6. Push the branch: git push origin auto/jsdoc-enhancement-${{ github.run_number }}
+            7. Create a PR: gh pr create --base ${{ github.ref_name }} --title "📚 AI JSDoc Enhancement" --body "This PR adds comprehensive JSDoc documentation to recently modified JavaScript files.
+            
+            Files enhanced:
+            ${{ steps.changed-files.outputs.files }}
+            
+            Generated automatically by Claude following patterns from docs/decisions/000-javascript-not-typescript.md"
+          claude_args: '--allowed-tools "Read,Edit,MultiEdit,Bash(git:*),Bash(gh pr create:*)"'