Add Claude Code GitHub Workflow

[ThomasHoussin]

🤖 Installing Claude Code GitHub App

This PR adds a GitHub Actions workflow that enables Claude Code integration in our repository.

What is Claude Code?

Claude Code is an AI coding agent that can help with:

• Bug fixes and improvements
• Documentation updates
• Implementing new features
• Code reviews and suggestions
• Writing tests
• And more!

How it works

Once this PR is merged, we'll be able to interact with Claude by mentioning @claude in a pull request or issue comment.
Once the workflow is triggered, Claude will analyze the comment and surrounding context, and execute on the request in a GitHub action.

Important Notes

• This workflow won't take effect until this PR is merged
• @claude mentions won't work until after the merge is complete
• The workflow runs automatically whenever Claude is mentioned in PR or issue comments
• Claude gets access to the entire PR or issue context including files, diffs, and previous comments

Security

• Our Anthropic API key is securely stored as a GitHub Actions secret
• Only users with write access to the repository can trigger the workflow
• All Claude runs are stored in the GitHub Actions run history
• Claude's default tools are limited to reading/writing files and interacting with our repo by creating comments, branches, and commits.
• We can add more allowed tools by adding them to the workflow file like:

allowed_tools: Bash(npm install),Bash(npm run build),Bash(npm run lint),Bash(npm run test)

There's more information in the Claude Code action repo.

After merging this PR, let's try mentioning @claude in a comment on any PR to get started!

[claude]

Claude Code Review - PR #1

Summary

This PR adds two GitHub Actions workflows to integrate Claude Code into the repository:

1. claude.yml - Responds to @claude mentions in issues and PRs
2. claude-code-review.yml - Automatically reviews PRs on open/update

---

✅ Code Quality & Best Practices

Positive aspects:

• Clean, well-structured workflow files following GitHub Actions best practices
• Appropriate use of permissions with least-privilege principle
• Good use of comments for optional configurations
• Proper checkout action with minimal fetch depth for efficiency

Recommendations:

1. Version pinning: Consider pinning the Claude Code action to a specific version instead of @v1 for better reproducibility:

   uses: anthropics/claude-code-action@v1.0.0  # or specific SHA

2. Auto-review scope: The claude-code-review.yml currently runs on ALL PRs. Given this is a novel-writing project with a specific orchestrator workflow, consider:

   • Filtering by paths (uncomment and adapt lines 7-11) to only review structural/workflow changes
   • OR filtering by author (uncomment lines 16-19) to review external contributions
   • Otherwise, every chapter draft PR will trigger an AI review, which may not be necessary

---

🔒 Security Considerations

Good:

• Uses CLAUDE_CODE_OAUTH_TOKEN as a secret (not hardcoded)
• Limited permissions scope (read for most, write only for id-token)
• Explicit allowed tools list in code review workflow

Concerns:

1. Missing write permissions: The workflows only have read permissions for contents/PRs. If Claude needs to:

   • Create commits
   • Push branches
   • Comment on PRs (via API, not just gh CLI)

   You may need to add:

   permissions:
     contents: write
     pull-requests: write

2. Unrestricted tools in claude.yml: Line 49 has the claude_args commented out. When Claude is mentioned in comments, it will have access to default tools. Consider uncommenting and restricting based on your needs.

3. Secret verification: Ensure CLAUDE_CODE_OAUTH_TOKEN is properly configured in repository secrets before merging.

---

🐛 Potential Issues

1. Recursive trigger risk: If claude-code-review.yml posts comments on PRs, and those comments contain "@claude", it could trigger the claude.yml workflow. This seems intentional based on the design, but be aware of potential feedback loops.

2. Context for novel-writing project: This repository appears to be a novel-writing orchestrator (based on CLAUDE.md). The code review workflow is designed for traditional software projects and may not align with your workflow:

   • Reviews focus on "code quality, bugs, performance, tests"
   • Your project focuses on story chapters, style guides, character consistency
   • Consider adapting the review prompt (lines 43-48) to focus on:
     • Story structure consistency
     • Character development
     • Timeline coherence
     • Style guide adherence

---

📊 Test Coverage

Missing:

• No tests for the workflow files themselves (this is acceptable for GitHub Actions)
• Consider adding a comment in the PR description about how to test this after merge:
  1. Create a test PR
  2. Verify claude-code-review.yml triggers automatically
  3. Comment with "@claude" to test claude.yml
  4. Verify secret is properly configured

---

🎯 Project-Specific Recommendations

Based on your CLAUDE.md orchestrator workflow, consider:

1. Custom workflow for chapter reviews: Create a third workflow that triggers on chapter-related PRs and uses Claude to validate:

   • Chapter follows the 13-step orchestrator workflow
   • State files are properly updated
   • Timeline files are correctly maintained
   • French language consistency

2. Protect orchestrator patterns: Add allowed/blocked tools that align with your workflow:

   claude_args: '--allowed-tools "Bash(uv run:*),Bash(cd:*),Bash(mkdir:*),Skill(perplexity-improver),Skill(perplexity-improver:*)"'

---

Overall Assessment

Status: ✅ Approved with suggestions

The workflows are well-implemented and follow best practices. The main considerations are:

1. Ensure this aligns with your novel-writing workflow (not just code reviews)
2. Add write permissions if Claude needs to create commits/comments
3. Consider scoping auto-reviews to avoid reviewing every chapter draft
4. Verify the secret is configured before merging

The PR is safe to merge, but I recommend addressing the permission and scope concerns to avoid surprises in production.