BMAD-METHOD/.github/workflows/claude-code-review.yaml

# Sample Claude Code Review Workflow
#
# This is a template workflow that demonstrates how to set up automated code reviews
# using Claude via GitHub Actions. Customize the prompt and focus areas for your project.
#
# To use this workflow:
# 1. Use Claude Code command in your terminal:  /install-github-app  , this holds your hand throughout the setup
# 2. Copy this file over to your repository's .github/workflows/claude-code-review.yml , which gets auto-generated
# 3. Add ANTHROPIC_API_KEY to your repository secrets
# 4. Customize the prompt section for your project's specific needs
# 5. Adjust the focus areas, tools, and model as needed

name: Claude Code Review - BMAD Method

on:
  pull_request:
    types: [opened, synchronize, ready_for_review, reopened]

# if this branch is pushed back to back, cancel the older branch's workflow
concurrency:
  group: ${{ github.workflow }}-${{ github.head_ref || github.ref }}
  cancel-in-progress: true

jobs:
  claude-review:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      pull-requests: write
      issues: read
      id-token: write

    steps:
      - name: Checkout repository
        uses: actions/checkout@v4
        with:
          fetch-depth: 1

      - name: Run Claude Code Review
        id: claude-review
        uses: anthropics/claude-code-action@v1
        with:
          # Using API key for per-token billing plan
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}

          # Track progress creates a comment showing review progress
          track_progress: true

          prompt: |
            REPO: ${{ github.repository }}
            PR NUMBER: ${{ github.event.pull_request.number }}

            # BMAD-METHOD Repository - AI Agent Framework

            IMPORTANT: Skip reviewing files in these directories:
            - docs/ (user-facing documentation)
            - bmad/ (compiled installation output, not source)
            - test/fixtures/ (test data files)
            - node_modules/ (dependencies)

            **Context:** This is BMAD-CORE, a universal human-AI collaboration framework with YAML-based agent definitions and XML-tagged workflow instructions.

            Perform comprehensive code review focusing on BMAD-specific patterns:

            ## 1. Agent YAML Schema Compliance (CRITICAL)

            **For files in `src/modules/*/agents/*.agent.yaml`:**
            - ✅ Required fields: metadata (id, name, title, icon, module), persona (role, identity, communication_style, principles), menu items
            - ✅ Menu triggers must reference valid workflow paths: `{project-root}/bmad/{module}/workflows/{path}/workflow.yaml`
            - ✅ Critical actions syntax (if TEA agent): Must reference tea-index.csv and knowledge fragments
            - ✅ Schema validation: Run `npm run validate:schemas` to verify compliance
            - ❌ No hardcoded file paths outside {project-root} or {installed_path}
            - ❌ No duplicate menu triggers within an agent

            ## 2. Workflow Definition Integrity

            **For files in `src/modules/*/workflows/**/workflow.yaml`:**
            - ✅ Required fields: name, config_source, instructions, default_output_file (if template-based)
            - ✅ Variable resolution: Use {config_source}, {project-root}, {installed_path}, {output_folder}
            - ✅ Instructions path must exist: `{installed_path}/instructions.md`
            - ✅ Template path (if template workflow): `{installed_path}/template.md`
            - ❌ No absolute paths - use variable placeholders

            **For `instructions.md` files:**
            - ✅ XML tag syntax: `<step n="1">`, `<action>`, `<template-output>section</template-output>`, `<check if="condition">`
            - ✅ Steps must have sequential numbering (1, 2, 3...)
            - ✅ All XML tags must close properly (e.g., `</check>`, `</step>`)
            - ✅ Template-output tags reference actual template sections
            - ❌ No malformed XML that breaks workflow execution engine

            ## 3. TEA Knowledge Base Integrity

            **For changes in `src/modules/bmm/testarch/`:**
            - ✅ tea-index.csv must match knowledge/ directory (21 fragments indexed)
            - ✅ Fragment file names match csv entries exactly
            - ✅ TEA agent critical_actions reference tea-index.csv correctly
            - ✅ Knowledge fragments maintain consistent format
            - ❌ Don't break the index-fragment relationship

            ## 4. Documentation Consistency (Phase & Track Terminology)

            **For changes in `src/modules/bmm/docs/`:**
            - ✅ Use 3-track terminology: Quick Flow, BMad Method, Enterprise Method (not Level 0-4)
            - ✅ Phase numbering: Phase 1 (Analysis), Phase 2 (Planning), Phase 3 (Solutioning), Phase 4 (Implementation)
            - ✅ TEA operates in Phase 2 and Phase 4 only (not "all phases")
            - ✅ `*test-design` is per-epic in Phase 4 (not per-project in Phase 2/3)
            - ❌ Don't mix YAML phase numbers (0-indexed) with doc phase numbers (1-indexed) without context

            **For changes in workflow-status YAML paths:**
            - ✅ Only include phase-gate workflows (prd, architecture, sprint-planning)
            - ❌ Don't include per-epic/per-story workflows (test-design, create-story, atdd, automate)
            - Note: Per-epic/per-story workflows tracked in sprint-status.yaml, not workflow-status.yaml

            ## 5. Cross-Module Dependencies

            - ✅ Verify workflow invocations reference valid paths
            - ✅ Module dependencies declared in installer-manifest.yaml
            - ✅ Shared task references resolve correctly
            - ❌ No circular dependencies between modules

            ## 6. Compilation & Installation

            **For changes affecting `tools/cli/`:**
            - ✅ Agent compilation: YAML → Markdown/XML for both IDE and web bundle targets
            - ✅ forWebBundle flag changes compilation behavior (inline vs file paths)
            - ✅ Manifest generation creates agent-manifest.csv and workflow-manifest.csv
            - ✅ Platform-specific hooks execute for IDE integrations

            ## 7. Code Quality (Node.js/JavaScript)

            - ✅ Modern JavaScript (ES6+, async/await, proper error handling)
            - ✅ Schema validation with Zod where applicable
            - ✅ Proper YAML parsing with js-yaml
            - ✅ File operations use fs-extra for better error handling
            - ❌ No synchronous file I/O in async contexts

            ## Review Guidelines

            - Reference CLAUDE.md for repository architecture
            - Check CONTRIBUTING.md for contribution guidelines
            - **Validation commands** (deterministic tests):
              - `npm test` - Comprehensive quality checks (all validations + linting + formatting)
              - `npm run test:schemas` - Agent schema validation tests (fixture-based)
              - `npm run test:install` - Installation component tests (compilation)
              - `npm run validate:schemas` - YAML schema validation
              - `npm run validate:bundles` - Web bundle integrity
              - `npm run lint` - ESLint compliance
              - `npm run format:check` - Prettier formatting
            - Prioritize issues: **Critical** (breaks workflows/compilation) > **High** (schema violations) > **Medium** (inconsistency) > **Low** (style)
            - Be specific with file paths and line numbers

            Use `gh pr comment` with your Bash tool to leave your review as a comment on the PR.

          # Using Sonnet 4.5 for comprehensive reviews
          # Available models: claude-opus-4-1-20250805, claude-sonnet-4-5-20250929, etc.
          # Tools can be restricted based on what review actions you want to allow
          claude_args: '--model claude-sonnet-4-5-20250929 --allowed-tools "mcp__github_inline_comment__create_inline_comment,Bash(gh issue view:*),Bash(gh search:*),Bash(gh issue list:*),Bash(gh pr comment:*),Bash(gh pr diff:*),Bash(gh pr view:*),Bash(gh pr list:*)"'

      # SETUP INSTRUCTIONS
# ==================
#
# 1. Repository Secrets Setup:
#    - Go to your repository <20> Settings <20> Secrets and variables <20> Actions
#    - Click "New repository secret"
#    - Name: ANTHROPIC_API_KEY
#    - Value: Your Anthropic API key (get one from https://console.anthropic.com/)
#
# 2. Permissions:
#    - The workflow needs 'pull-requests: write' to comment on PRs
#    - The workflow needs 'contents: read' to access repository code
#    - The workflow needs 'issues: read' for GitHub CLI operations
#
# 3. Customization:
#    - Update the prompt section to match your project's needs
#    - Add project-specific file/directory exclusions
#    - Customize the focus areas based on your tech stack
#    - Adjust the model (opus for more thorough reviews, sonnet for faster)
#    - Modify allowed tools based on what actions you want Claude to perform
#
# 4. Testing:
#    - Create a test PR to verify the workflow runs correctly
#    - Check that Claude can comment on the PR
#    - Ensure the review quality meets your standards
#
# 5. Advanced Customization:
#    - Add conditional logic based on file types or changes
#    - Integrate with other GitHub Actions (linting, testing, etc.)
#    - Set up different review levels based on PR size or author
#    - Add custom review templates for different types of changes
#
# TROUBLESHOOTING
# ===============
#
# Common Issues:
# - "Authentication failed" <20> Check ANTHROPIC_API_KEY secret
# - "Permission denied" <20> Verify workflow permissions in job definition
# - "No comments posted" <20> Check allowed tools and gh CLI permissions
# - "Review too generic" <20> Customize prompt with project-specific guidance
#
# For more help:
# - GitHub Actions documentation: https://docs.github.com/en/actions
# - Claude Code Action: https://github.com/anthropics/claude-code-action
# - Anthropic API documentation: https://docs.anthropic.com/