Docs audit: align existing pages with AGENTS.md (friendly imports, hero diagrams, agent-centric Quick Starts) #6508
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| 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 |