claude.yml

name: Claude Assistant

on:
  issue_comment:
    types: [created]
  pull_request_review_comment:
    types: [created]
  issues:
    types: [assigned, labeled, opened]
  pull_request_review:
    types: [submitted]

jobs:
  # ================================================================
  # Job 1: Lightweight triage for ALL new issues (including external users)
  # Posts welcome comment + adds triage labels. No Claude code execution.
  # ================================================================
  issue-triage:
    if: |
      github.event_name == 'issues' &&
      github.event.action == 'opened' &&
      !contains(toJSON(github.event.issue.labels), 'claude')
    runs-on: ubuntu-latest
    permissions:
      issues: write
      contents: read
    steps:
      - name: Triage and acknowledge issue
        uses: actions/github-script@v7
        with:
          github-token: ${{ secrets.GH_TOKEN }}
          script: |
            const issue = context.payload.issue;
            const title = (issue.title || '').toLowerCase();
            const body = (issue.body || '').toLowerCase();
            const content = title + ' ' + body;
            const isOwner = ['OWNER', 'MEMBER', 'COLLABORATOR'].includes(
              issue.author_association
            );

            // --- Label triage ---
            const labels = [];

            // Kind labels
            if (content.includes('feature request') || content.includes('[feature')) {
              labels.push('enhancement');
            } else if (content.includes('bug') || content.includes('error') || content.includes('crash') || content.includes('traceback')) {
              labels.push('bug');
            } else if (content.includes('question') || content.includes('how do i') || content.includes('how to')) {
              labels.push('question');
            }

            // Area labels
            if (content.includes('security') || content.includes('cve') || content.includes('vulnerability')) {
              labels.push('security');
            }
            if (content.includes('performance') || content.includes('slow') || content.includes('memory leak')) {
              labels.push('performance');
            }
            if (content.includes('documentation') || content.includes('docs')) {
              labels.push('documentation');
            }
            if (content.includes('typescript') || content.includes('javascript') || content.includes('npm')) {
              labels.push('javascript');
            }

            // Apply labels
            if (labels.length > 0) {
              await github.rest.issues.addLabels({
                issue_number: issue.number,
                owner: context.repo.owner,
                repo: context.repo.repo,
                labels
              });
            }

            // --- Acknowledgment comment (external users only) ---
            if (!isOwner) {
              await github.rest.issues.createComment({
                issue_number: issue.number,
                owner: context.repo.owner,
                repo: context.repo.repo,
                body: [
                  `👋 Thanks for opening this issue, @${issue.user.login}!`,
                  '',
                  'A maintainer will review this shortly. In the meantime:',
                  '- Make sure you\'ve included steps to reproduce (for bugs)',
                  `- Check [existing issues](https://github.com/${context.repo.owner}/${context.repo.repo}/issues) for duplicates`,
                  '- Review the [documentation](https://docs.praison.ai) for related guides',
                ].join('\n')
              });
            }

            // Claude label: added by .github/workflows/auto-issue-comment.yml on issues:opened
            // (do not add 'claude' here — avoids duplicate labeled events and double Claude runs)

  # ================================================================
  # Job 2: Full Claude docs-fix
  # Triggers on: issues labeled `claude`, @claude issue comments, PR review threads, PR reviews
  # ================================================================
  claude-response:
    # Runs on: issues labeled "claude", @claude comments, PR review comments, PR reviews — not on opened/assigned/other labels
    env:
      ISSUE_NUMBER_RESOLVED: ${{ github.event.issue.number || github.event.pull_request.number }}
    if: |
      github.event.action != 'opened' &&
      (github.event_name != 'issues' || (github.event.action == 'labeled' && github.event.label.name == 'claude')) &&
      (github.event_name != 'issue_comment' || contains(github.event.comment.body, '@claude')) &&
      (
        !contains(github.actor, '[bot]') ||
        github.actor == 'github-actions[bot]' ||
        github.actor == 'praisonai-triage-agent[bot]'
      ) &&
      github.actor != 'dependabot[bot]' &&
      github.actor != 'cursor[bot]' &&
      github.actor != 'renovate[bot]'
    runs-on: ubuntu-latest
    permissions:
      contents: write
      pull-requests: write
      issues: write
      actions: read
    steps:
      - name: Checkout repository
        uses: actions/checkout@v4
        with:
          fetch-depth: 0
          token: ${{ secrets.GH_TOKEN }}

      - uses: anthropics/claude-code-action@beta
        env:
          GH_TOKEN: ${{ secrets.GH_TOKEN }}
        with:
          allowed_bots: 'praisonai-triage-agent[bot]'
          claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
          github_token: ${{ secrets.GH_TOKEN }}
          anthropic_model: claude-sonnet-4-6
          trigger_phrase: "@claude"
          label_trigger: "claude"

          direct_prompt: |
            You are a documentation engineer for PraisonAI. This is a DOCUMENTATION repository.
            Follow AGENTS.md strictly — it contains the exact page structure, Mintlify components,
            Mermaid diagram standards, and code example rules you MUST follow.

            STEP 0 — SETUP GIT IDENTITY & AUTH:
            git config --global user.name "MervinPraison"
            git config --global user.email "454862+MervinPraison@users.noreply.github.com"
            gh auth setup-git

            STEP 1 — READ AGENTS.md:
            Read AGENTS.md completely. It defines:
            - Page structure template (Section 2)
            - Mermaid diagram color scheme: #8B0000 dark red, #189AB4 teal, #fff white text (Section 3)
            - Mintlify components: Steps, AccordionGroup, CardGroup, Tabs, CodeGroup (Section 4)
            - Code example standards: copy-paste runnable, minimal, agent-centric (Section 5)
            - Writing style: concise, active voice, no forbidden phrases (Section 6)
            - Quality checklist (Section 9)
            Every documentation page you create MUST pass the quality checklist.

            STEP 2 — UNDERSTAND THE ISSUE:
            Read the issue title, body, and all comments carefully.
            Determine what documentation needs to be created or updated.

            STEP 3 — READ SDK SOURCE:
            Read `./praisonaiagents/` and `./praisonai/` first (AGENTS.md §1.4). Extract signatures,
            defaults, feature_configs.py, imports. If missing, clone: gh repo clone MervinPraison/PraisonAI /tmp/PraisonAI --depth=1
            NEVER guess — read the code.

            FOLDER RULES (CRITICAL — NEVER VIOLATE):
            - NEVER create or modify pages in docs/concepts/ — that folder is HUMAN-APPROVED ONLY
            - Always place new documentation pages in docs/features/ instead
            - If the issue mentions "concepts", still place the file in docs/features/
            - Update docs.json to add new pages under the "Features" group, NOT "Concepts"
            - Existing docs/concepts/ pages must NOT be touched without explicit human approval

            STEP 4 — CREATE DOCUMENTATION:
            - Create one feature branch and reuse its name in STEP 7, e.g. BRANCH="claude/issue-${{ env.ISSUE_NUMBER_RESOLVED }}-$(date +%Y%m%d)" then git checkout -b "$BRANCH"
            - Place ALL new .mdx files in docs/features/ (NEVER docs/concepts/)
            - Follow the page structure template in AGENTS.md Section 2
            - Start every page with an agent-centric Quick Start example
            - Use Mintlify components (Steps, AccordionGroup, CardGroup, Tabs)
            - Include Mermaid diagrams with the standard color scheme
            - All code examples must be copy-paste runnable with correct imports
            - User-friendly: non-developers and beginners should understand
            - Progressive disclosure: simple first, advanced later

            STEP 5 — UPDATE NAVIGATION:
            If creating new pages, add them to docs.json in the correct section.
            Check existing structure in docs.json to find the right group.

            STEP 6 — VERIFY:
            - Confirm all .mdx files exist and are valid
            - Verify docs.json is valid JSON
            - Check all code examples have correct imports
            - Ensure Mermaid diagrams use the standard color scheme

            STEP 7 — COMMIT, PUSH, OPEN PR (mandatory end state):
            - git add -A && git commit -m "docs: <description> (fixes #${{ env.ISSUE_NUMBER_RESOLVED }})"
            - git push -u origin "$BRANCH"   # same $BRANCH as STEP 4; never use a second $(date ...) for the branch name
            - gh pr create --base main --head "$BRANCH" --title "docs: <title>" --body "Fixes #${{ env.ISSUE_NUMBER_RESOLVED }}"
            Opening the PR is required for every run that produced commits. Do not finish after push only, do not ask a human to open a PR, and do not stop for a "summary" until `gh pr create` returns a PR URL. If `gh pr create` fails, read the error, fix (e.g. auth, duplicate PR, wrong head), and retry until it succeeds.
          allowed_tools: |
            Bash(git:*)
            Bash(python:*)
            Bash(pip:*)
            Bash(conda:*)
            Bash(pytest:*)
            Bash(gh:*)
            Bash(python -m pytest:*)
            Bash(python -m pip:*)
            Bash(poetry:*)
            View
            GlobTool
            GrepTool
            BatchTool
            Edit
            Replace
            mcp__github__get_issue
            mcp__github__get_issue_comments
            mcp__github__update_issue
          timeout_minutes: 30