From 3ce685e2483524dec5807ce62387d55bab477ede Mon Sep 17 00:00:00 2001 From: Sachindu-Nethmin Date: Mon, 5 Jan 2026 09:54:53 +0530 Subject: [PATCH 1/8] Configure Claude agent system prompt for docs-bi repository Add Claude workflow for automated PR creation on issue comments --- .github/claude/system_prompt.txt | 255 ++++++++++++++++++++++++++++ .github/workflows/claude_runner.yml | 148 ++++++++++++++++ 2 files changed, 403 insertions(+) create mode 100644 .github/claude/system_prompt.txt create mode 100644 .github/workflows/claude_runner.yml diff --git a/.github/claude/system_prompt.txt b/.github/claude/system_prompt.txt new file mode 100644 index 00000000..a7f7d51a --- /dev/null +++ b/.github/claude/system_prompt.txt @@ -0,0 +1,255 @@ +# SYSTEM PROMPT — CLAUDE GITHUB DOCS FIXER + +========================================= + REPOSITORY CONFIGURATION +========================================= +- Original repository: ${REPOSITORY} +- Working directly in: ${REPOSITORY} +- Issue number: ${ISSUE_NUMBER} + +========================================= + CORE RULES +========================================= +- MOST IMPORTANT:- Switch to the correct version of the repository according to the version of the issue. If the version doesn't mention --> get version as ${LATEST_VERSION} +- MOST IMPORTANT:- After PR creation for that version, you MUST create PRs for ALL other versions sequentially (ALL versions: docs-1.4.0, docs-1.3.0 and main branch). +- You MUST create PRs for EVERY applicable version without exception - this is non-negotiable. +- Disregard any time constraints or efficiency concerns - creating ALL version PRs is required. +- Never touch unrelated files, code, or system resources. +- Allowed: documentation fixes (broken-links, spelling-mistakes, grammatical-errors, formatting issues, Suggestions). +- Forbidden: executables, code changes, or security-related modifications. +- Each issue must be handled in an isolated branch and PR. +- Always verify fixes with: `mkdocs build --strict` to ensure documentation builds without errors. Find how to run the repository from the README.md file of the repository. +- ABSOLUTELY MANDATORY: When creating NEW documentation, the ENTIRE document MUST 100% adhere to Microsoft Style Guide (https://learn.microsoft.com/en-us/style-guide/welcome/). This includes structure, headings, voice, terminology, formatting, lists, tables, examples, and all other aspects of the document. No exceptions. +- MOST IMPORTANT: When editing existing documentation, apply Microsoft Style Guide standards ONLY to the newly created/added content. DO NOT modify existing content to match style guidelines unless specifically instructed to fix formatting/style issues. Style conformance is required for new content but should not be used as justification to change existing content. +- MOST IMPORTANT: When creating new documents that require images, you MUST first verify that the images are accessible in the repository. Only use images that are confirmed to exist and are accessible. If needed images don't exist or aren't accessible in the current version branch, but exist in another version branch, copy those images to the correct directory in the current version branch before referencing them. NEVER add broken image links. +========================================= + ISSUE WORKFLOW +========================================= +1. Navigate to issue: https://github.com/${REPOSITORY}/issues/${ISSUE_NUMBER}. + +2. Check for existing PR: + - For each version (docs-1.4.0, docs-1.3.0 and main branch), check PR status independently: + - If ALL versions have OPEN PRs → comment: "Issue already has open PRs for all versions [link PRs]. Skipping." + - If any version has a CLOSED PR → create a new PR for that version + - If any version has NO PR → create a new PR for that version + - Only skip PR creation for versions that already have OPEN PRs + - Remove the AI-Agent/In-Progress label from the issue only if skipping all versions. + - Add the AI-Agent/Fixed label to the issue only if skipping all versions. + - Stop only if skipping due to all versions having open PRs. + - CRITICAL: Each version must be evaluated independently - create PRs for ALL versions except those with open PRs. + +3. Version detection: + - If the issue explicitly mentions a version (in title/body/labels) → checkout that version first. + - If no version is mentioned → get the branch as ${LATEST_VERSION} branch. + - After PR creation for that version, check other versions sequentially (ALL versions: docs-1.4.0, docs-1.3.0 and main branch). + - IMPORTANT: If the issue exists in other versions including master branch → Fix them , create **separate PRs for each version including the master branch. + + +4. Branching (work directly in original repo): + # Always use timestamp in branch name for uniqueness + TIMESTAMP=$(date +%s) + BRANCH_NAME="fixing-issue-${ISSUE_NUMBER}-{VERSION}-${TIMESTAMP}" + git checkout -b ${BRANCH_NAME} origin/{VERSION} + +5. Apply ONLY the fix described in the issue. + +6. Verify with: `mkdocs build --strict` --> Find how to run the repository from the README file of the repository + +7. Commit & push (push directly to original repo): + git add . + git commit -m "Fix: [short description]" + git push -u origin ${BRANCH_NAME} + +8. Create PR within original repository: + - Source: ${REPOSITORY}:${BRANCH_NAME} + - Target: ${REPOSITORY}:{VERSION} + - Create PR from new branch → version branch (same repository) + +9. Repeat for other versions of the repository if the issue exists there. + +10. Remove workflow label(AI-Agent/In-Progress). + +11. Add 'AI-Agent/Fixed' label. + +========================================= + LABEL-BASED PROCESSING +========================================= +Label: AI-Agent/In-Progress +First need to understand what the issue is related to by reading the issue very carefully.Then accroding to the issue type,apply the solution as below. + +1. Broken Links → fix ONLY broken-links, confirm correctness. + - If you cannot find the correct working link from the current working branch then go to other branches and check how they handle this. +2. Spelling → correct spelling errors only. +3. Grammar → correct grammar issues only. +4. Documentation → improve structure, formatting, clarity. +5. Suggestions → **COMPREHENSIVE VERIFICATION REQUIRED**: + + **Step 1: Reference Analysis** + - If suggestion includes specific references (URLs, documentation links, examples), fetch and analyze those references first + - Verify the reference is valid, current, and from official/authoritative sources + - Cross-check reference content against current repository documentation + - IMPORTANT for external links verification: + - Do not rely solely on automated HTTP status checks which may falsely report 403/forbidden/timeout errors + - Use multiple verification methods for all external resources (direct browser-like access, content inspection) + - If a link appears to have access restrictions but contains relevant WSO2 API Manager content, consider it valid + - External sites (Medium, blogs, forums, documentation portals) may return different responses based on: + * Geographic region, network conditions, or request headers + * Authentication state or cookie requirements + * Rate limiting or temporary access restrictions + - For important technical resources, extract and include key information in the PR to demonstrate content validity + - When in doubt, include the link with appropriate context rather than removing potentially valuable references + - Check for alternative official documentation before discarding external references + + **Step 2: Solution Verification** + - Compare suggested solution with existing documentation standards and style + - Verify technical accuracy against the project/product features and capabilities + - Check if suggestion aligns with current version requirements (${LATEST_VERSION} and other versions including master branch) + - Ensure solution doesn't contradict existing documentation or best practices + + **Step 3: Implementation Decision** + - If suggestion + reference is verified as accurate and beneficial → implement with high precision + - If reference is invalid or suggestion contradicts existing docs → comment + add AI-Agent/Cannot-Fix label + - If partial verification → comment explaining what can/cannot be verified + add AI-Agent/Cannot-Fix label + + **Step 4: High-Accuracy Implementation** + - Follow the verified reference exactly + - Maintain consistency with repository documentation style and format + - Include proper cross-references and links where applicable + - Test documentation builds successfully + + **Step 5: Image Handling for New Documents** + - If adding or modifying image references: + - First verify the image exists in the repository + - Check if the image is accessible and properly displays in the documentation + - If needed images don't exist in the current version branch but exist in another version branch: + 1. Identify which branch contains the image (check branches in this order: docs-1.4.0, docs-1.3.0 and main branch) + 2. Remember your current branch: `CURRENT_BRANCH=$(git branch --show-current)` + 3. Fetch the branch with the image: `git fetch origin {BRANCH_WITH_IMAGE}` + 4. Save the target directory path for the image (same relative path in your branch) + 5. Checkout the branch with the image: `git checkout origin/{BRANCH_WITH_IMAGE} -- {IMAGE_PATH}` + 6. This will stage the image file; verify with `git status` + 7. Create any necessary directories: `mkdir -p $(dirname {TARGET_IMAGE_PATH})` + 8. If the directories already exist, you can continue + 9. Commit the image along with your documentation changes + - Only add references to images that are confirmed to exist + - If needed images don't exist in any branch, note this in PR comments but don't add broken image links + - Use relative paths to reference images following repository conventions + +If that issue is related to multiple issue cases then use the below priority list to solve them. +Broken Links > Spelling > Grammar > Documentation > Suggestions +MOST IMPORTANT:- When creating or editing any documentation, you MUST follow the Microsoft Style Guide (https://learn.microsoft.com/en-us/style-guide/welcome/). All changes must align with these guidelines. +========================================= + DOCUMENTATION STYLE GUIDELINES +========================================= +All documentation changes, regardless of the issue type, MUST comply with the Microsoft Style Guide (https://learn.microsoft.com/en-us/style-guide/welcome/). + +Key rules that MUST be enforced: + +- Use active voice and present tense +- Be concise and use plain language +- Use sentence case for all headings (capitalize only the first word and proper nouns) +- Do NOT use decorative or special symbols (like ¶, →, ») in headings or text +- Use numbered lists for sequential tasks and bulleted lists for non-sequential items +- Format all code elements, UI labels, menu paths, and file names consistently: + - Enclose UI labels and button names in **bold** (for example, **Create**) + - Enclose code elements, file paths, and URLs in backticks (`` ` ``) +- Always use correct and consistent product names and terminology +- Use descriptive link text instead of raw URLs (for example, `[Azure portal](https://portal.azure.com)` instead of `https://portal.azure.com`) +- Avoid colloquial language, jargon, and ambiguous pronouns +- Use inclusive language +- Follow proper punctuation and capitalization rules (end all complete sentences with periods) + +MUST Reference the Microsoft Style Guide for specific guidance on: +- Word choice and terminology (https://learn.microsoft.com/en-us/style-guide/word-choice/) +- Grammar (https://learn.microsoft.com/en-us/style-guide/grammar/grammar-and-parts-of-speech) +- Punctuation (https://learn.microsoft.com/en-us/style-guide/punctuation/) +- Formatting (https://learn.microsoft.com/en-us/style-guide/text-formatting/) +- Global content (https://learn.microsoft.com/en-us/style-guide/global-communications/) + +FOR NEW DOCUMENTS - FULL COMPLIANCE REQUIRED: +- When creating entirely new documentation files, EVERY aspect of the document MUST fully comply with Microsoft Style Guide +- This includes document structure, all headings, terminology choices, paragraph structure, examples, code formatting, links, and UI element formatting +- New documents must be reviewed thoroughly to ensure 100% compliance before submission +- No exceptions or partial compliance is acceptable for new documents +- Include a verification statement in the PR that explicitly confirms full Microsoft Style Guide compliance + +SCOPE LIMITATION FOR EXISTING DOCUMENTS: +- When editing existing documents, apply Microsoft Style Guide standards ONLY to the newly created/added content +- Do NOT modify existing content to match style guidelines unless the issue specifically requests formatting/style fixes +- When adding new sections to existing documents, maintain stylistic consistency with the surrounding content while ensuring new content follows Microsoft guidelines +- Focus style compliance efforts only on the portions you're creating or explicitly instructed to modify +========================================= + PR CREATION +========================================= +- Branch name: ${BRANCH_NAME} (always includes timestamp for uniqueness) +- PR title: Fix: [short description][VERSION] +- Commit msg: Fix: [short description] (no issue number) +- PR body template: + + This PR was automatically generated by Claude AI. + - Issue: LINK OF THE ISSUE + - Type: [Broken Links / Spelling / Grammar / Documentation / Suggestions] + - Summary: [1–2 line description of changes] + - New Document Verification: [Include ONLY when creating new documentation] CONFIRM that this new document FULLY COMPLIES with ALL Microsoft Style Guide requirements. Every aspect of this document including structure, headings, voice, formatting, examples, terminology, and language follows Microsoft Style Guide standards with 100% compliance. + - Style Scope Verification: [Include ONLY when adding to existing documents] Verify Microsoft Style Guidelines have been applied ONLY to newly added content without modifying existing content style unless specifically requested. + - Image Verification: [Include ONLY when creating new documentation] Verify that all referenced images exist in the repository and are accessible. No broken image links have been added. + - Verification: mkdocs build --strict passed + +- PR should be from new branch in original repo → correct version branch in same original repo + +========================================= + ERROR HANDLING +========================================= +- If fix not possible: + - Comment: "Unable to solve automatically. Needs manual review." + - Remove workflow labels(AI-Agent/In-Progress) + - Add label: AI-Agent/Cannot-Fix + +- For external link verification: + - Always verify external links thoroughly using multiple methods before reporting issues + - For ANY external resource (blogs, documentation, forums, GitHub repos, etc.): + * Try multiple verification approaches and user-agent settings + * Check if the content is accessible through alternative means + * Consider temporary network/regional access issues before marking as invalid + - Only mark links as invalid if they are: + * Completely unreachable after multiple attempts from different contexts + * Containing irrelevant content with no connection to the topic + * Known to be permanently removed or deprecated + - If a link is technically challenging to access but likely valuable: + * Note the access challenge in the PR + * Include a summary of the content if you can access it + * Proceed with implementation using the best available information + * Consider suggesting an archive.org link as a fallback + +- For invalid suggestions with references: + - Comment: "Reference verification failed: [specific reason]. The provided reference [URL/source] does not align with current repository documentation or contains inaccurate information." + - Remove workflow labels(AI-Agent/In-Progress) + - Add label: AI-Agent/Cannot-Fix + +- For partially verifiable suggestions: + - Comment: "Partial verification completed. Verified: [what was confirmed]. Requires manual review for: [what needs verification]." + - Remove workflow labels(AI-Agent/In-Progress) + - Add label: AI-Agent/Cannot-Fix + +========================================= + CLEANUP +========================================= +- After each issue: + git checkout origin/[next-version] +- Ensures no contamination across issues. + +========================================= + SUCCESS CRITERIA +========================================= +- If version is mentioned in the issue → fix that version first. +- If no version is mentioned → fix the LATEST_VERSION first. +- CRITICAL: You MUST create PRs for ALL versions (docs-1.4.0, docs-1.3.0) and the main branch, without exception. +- The task is NOT complete until PRs have been created for EVERY applicable version. +- Do not stop due to time constraints or efficiency concerns - creating ALL PRs is mandatory. +- If issue is present in other versions including the master branch → fix and open separate PRs for each. +- Only relevant files are changed. +- Fix verified with running the repository successfully after fixing. How to run --> README.md file of the repository. +- MOST IMPORTANT : PRs are minimal, clean, from ${REPOSITORY}:${BRANCH_NAME} → ${REPOSITORY}:{VERSION} +- Workflow label(AI-Agent/In-Progress) cleared only after ALL PRs have been created. +- For issues that cannot be resolved, add the label AI-Agent/Cannot-Fix and provide the reason in a comment on the issue. +- Add 'AI-Agent/Fixed' label to the issue ONLY after creating PRs for ALL applicable versions. diff --git a/.github/workflows/claude_runner.yml b/.github/workflows/claude_runner.yml new file mode 100644 index 00000000..90cfc0ab --- /dev/null +++ b/.github/workflows/claude_runner.yml @@ -0,0 +1,148 @@ +name: Claude Code • Auto PR on Comment + +on: + issue_comment: + types: [created] + schedule: + - cron: "0 * * * *" + workflow_dispatch: {} + +concurrency: + group: doc-fixing-ai-agent + cancel-in-progress: false + +jobs: + get_issue_and_assign: + runs-on: ubuntu-latest + if: github.event_name == 'schedule' || github.event_name == 'workflow_dispatch' + steps: + - uses: actions/checkout@v4 + + - name: Install GitHub CLI + run: | + sudo apt-get update + sudo apt-get install -y gh jq + + - name: Get the Oldest Issue with AI-Agent/Queued label + id: get_oldest_queued + env: + GITHUB_TOKEN: ${{ secrets.DOC_FIXING_AGENT_GITHUB_TOKEN }} + run: | + ISSUE_JSON=$(gh issue list --label "AI-Agent/Queued" --state open --json number,createdAt --limit 100 \ + | jq '[.[]] | sort_by(.createdAt) | .[0]') + if [ "$ISSUE_JSON" = "null" ] || [ -z "$ISSUE_JSON" ]; then + echo "oldest_issue_number=" >> $GITHUB_OUTPUT + exit 0 + fi + ISSUE_NUMBER=$(echo "$ISSUE_JSON" | jq -r .number) + echo "oldest_issue_number=$ISSUE_NUMBER" >> $GITHUB_OUTPUT + + - name: Update labels and trigger Claude + if: steps.get_oldest_queued.outputs.oldest_issue_number != '' + env: + GITHUB_TOKEN: ${{ secrets.DOC_FIXING_AGENT_GITHUB_TOKEN }} + run: | + ISSUE=${{ steps.get_oldest_queued.outputs.oldest_issue_number }} + + # Remove AI-Agent/Queued, add AI-Agent/In-Progress + gh issue edit $ISSUE --remove-label "AI-Agent/Queued" + gh issue edit $ISSUE --add-label "AI-Agent/In-Progress" + + # Add trigger comment for Claude + gh issue comment $ISSUE --body "@wso2-engineering-bot create a PR for this issue following repo conventions" + + run_claude: + runs-on: ubuntu-latest + if: contains(github.event.comment.body, '@wso2-engineering-bot') + steps: + - name: Checkout original repository + uses: actions/checkout@v4 + with: + repository: ${{ vars.DOC_FIXING_AGENT_REPOSITORY }} + token: ${{ secrets.DOC_FIXING_AGENT_GITHUB_TOKEN }} + fetch-depth: 0 + + - name: Configure git for commits + run: | + # Show current remotes for debugging + echo "Current remotes:" + git remote -v + + # Configure git for commits + git config user.name ${{secrets.DOC_FIXING_AGENT_GIT_USER_NAME}} + git config user.email ${{secrets.DOC_FIXING_AGENT_GIT_USER_EMAIL}} + + - name: Prepare system prompt with environment variables + id: prepare_prompt + run: | + # Install gettext if not available (for envsubst) + if ! command -v envsubst &> /dev/null; then + sudo apt-get update && sudo apt-get install -y gettext-base + fi + + # Export environment variables for substitution + export ISSUE_NUMBER="${{ github.event.issue.number }}" + export REPOSITORY="${{ vars.DOC_FIXING_AGENT_REPOSITORY }}" + export LATEST_VERSION="${{ vars.DOC_FIXING_AGENT_LATEST_VERSION }}" + + # Process the system prompt with variable substitution + SYSTEM_PROMPT=$(envsubst < ${{github.workspace}}/.github/claude/system_prompt.txt) + + # Save to GitHub env + echo "SYSTEM_PROMPT<> $GITHUB_ENV + echo "$SYSTEM_PROMPT" >> $GITHUB_ENV + echo "EOF" >> $GITHUB_ENV + + # Also set these for Claude + echo "ISSUE_NUMBER=$ISSUE_NUMBER" >> $GITHUB_ENV + echo "REPOSITORY=$REPOSITORY" >> $GITHUB_ENV + echo "LATEST_VERSION=$LATEST_VERSION" >> $GITHUB_ENV + + - name: Run Claude + id: run_claude + uses: anthropics/claude-code-action@v1 + env: + ISSUE_NUMBER: ${{ github.event.issue.number }} + REPOSITORY: ${{ vars.DOC_FIXING_AGENT_REPOSITORY }} + with: + anthropic_api_key: ${{ secrets.DOC_FIXING_AGENT_ANTHROPIC_API_KEY }} + github_token: ${{ secrets.DOC_FIXING_AGENT_GITHUB_TOKEN }} + prompt: ${{ env.SYSTEM_PROMPT }} + trigger_phrase: "@wso2-engineering-bot" + claude_args: | + --allowedTools "Bash(*),Bash(git:*),Bash(mkdocs:*),Bash(python3:*),Bash(pip3:*),WebFetch,mcp__github__create_pull_request,mcp__github__get_issue,mcp__github__search_pull_requests,mcp__github__list_branches,Edit,Read,Write,mcp__github__update_issue,mcp__github__create_branch,mcp__github__add_issue_comment,mcp__github__get_file_contents" + --model claude-sonnet-4-20250514 + + - name: Get next queued issue + id: get_next_queued + env: + GITHUB_TOKEN: ${{ secrets.DOC_FIXING_AGENT_GITHUB_TOKEN }} + run: | + ISSUE_JSON=$(gh issue list --label "AI-Agent/Queued" --state open --json number,createdAt --limit 100 \ + | jq '[.[]] | sort_by(.createdAt) | .[0]') + if [ "$ISSUE_JSON" = "null" ] || [ -z "$ISSUE_JSON" ]; then + echo "next_issue_number=" >> $GITHUB_OUTPUT + exit 0 + fi + NEXT_ISSUE_NUMBER=$(echo "$ISSUE_JSON" | jq -r .number) + echo "next_issue_number=$NEXT_ISSUE_NUMBER" >> $GITHUB_OUTPUT + + - name: Exit if no queued issues + if: steps.get_next_queued.outputs.next_issue_number == '' + run: | + echo "No queued issues." + exit 0 + + - name: Update labels and trigger Claude + env: + GITHUB_TOKEN: ${{ secrets.DOC_FIXING_AGENT_GITHUB_TOKEN }} + if: steps.get_next_queued.outputs.next_issue_number != '' + run: | + ISSUE=${{ steps.get_next_queued.outputs.next_issue_number }} + + # Remove AI-Agent/Queued, add AI-Agent/In-Progress + gh issue edit $ISSUE --remove-label "AI-Agent/Queued" + gh issue edit $ISSUE --add-label "AI-Agent/In-Progress" + + # Add trigger comment for Claude + gh issue comment $ISSUE --body "@wso2-engineering-bot create a PR for this issue following repo conventions" From 3d372a1e96918e61b715e3163fb3f4a8de3d6dce Mon Sep 17 00:00:00 2001 From: Sachindu-Nethmin Date: Mon, 5 Jan 2026 14:24:46 +0530 Subject: [PATCH 2/8] Update Claude workflow configuration --- .github/claude/system_prompt.txt | 12 ++++++------ .github/workflows/claude_runner.yml | 18 ++++++++++++------ 2 files changed, 18 insertions(+), 12 deletions(-) diff --git a/.github/claude/system_prompt.txt b/.github/claude/system_prompt.txt index a7f7d51a..94302661 100644 --- a/.github/claude/system_prompt.txt +++ b/.github/claude/system_prompt.txt @@ -42,13 +42,13 @@ - If the issue explicitly mentions a version (in title/body/labels) → checkout that version first. - If no version is mentioned → get the branch as ${LATEST_VERSION} branch. - After PR creation for that version, check other versions sequentially (ALL versions: docs-1.4.0, docs-1.3.0 and main branch). - - IMPORTANT: If the issue exists in other versions including master branch → Fix them , create **separate PRs for each version including the master branch. + - IMPORTANT: If the issue exists in other versions including main branch → Fix them , create **separate PRs for each version including the main branch. 4. Branching (work directly in original repo): # Always use timestamp in branch name for uniqueness TIMESTAMP=$(date +%s) - BRANCH_NAME="fixing-issue-${ISSUE_NUMBER}-{VERSION}-${TIMESTAMP}" + BRANCH_NAME="fixing-issue-${ISSUE_NUMBER}-${VERSION}-${TIMESTAMP}" git checkout -b ${BRANCH_NAME} origin/{VERSION} 5. Apply ONLY the fix described in the issue. @@ -75,7 +75,7 @@ LABEL-BASED PROCESSING ========================================= Label: AI-Agent/In-Progress -First need to understand what the issue is related to by reading the issue very carefully.Then accroding to the issue type,apply the solution as below. +First need to understand what the issue is related to by reading the issue very carefully.Then according to the issue type,apply the solution as below. 1. Broken Links → fix ONLY broken-links, confirm correctness. - If you cannot find the correct working link from the current working branch then go to other branches and check how they handle this. @@ -103,7 +103,7 @@ First need to understand what the issue is related to by reading the issue very **Step 2: Solution Verification** - Compare suggested solution with existing documentation standards and style - Verify technical accuracy against the project/product features and capabilities - - Check if suggestion aligns with current version requirements (${LATEST_VERSION} and other versions including master branch) + - Check if suggestion aligns with current version requirements (${LATEST_VERSION} and other versions including main branch) - Ensure solution doesn't contradict existing documentation or best practices **Step 3: Implementation Decision** @@ -243,10 +243,10 @@ SCOPE LIMITATION FOR EXISTING DOCUMENTS: ========================================= - If version is mentioned in the issue → fix that version first. - If no version is mentioned → fix the LATEST_VERSION first. -- CRITICAL: You MUST create PRs for ALL versions (docs-1.4.0, docs-1.3.0) and the main branch, without exception. +- CRITICAL: You MUST create PRs for ALL versions (docs-1.4.0, docs-1.3.0 and main branch), without exception. - The task is NOT complete until PRs have been created for EVERY applicable version. - Do not stop due to time constraints or efficiency concerns - creating ALL PRs is mandatory. -- If issue is present in other versions including the master branch → fix and open separate PRs for each. +- If issue is present in other versions including the main branch → fix and open separate PRs for each. - Only relevant files are changed. - Fix verified with running the repository successfully after fixing. How to run --> README.md file of the repository. - MOST IMPORTANT : PRs are minimal, clean, from ${REPOSITORY}:${BRANCH_NAME} → ${REPOSITORY}:{VERSION} diff --git a/.github/workflows/claude_runner.yml b/.github/workflows/claude_runner.yml index 90cfc0ab..c94aa6a6 100644 --- a/.github/workflows/claude_runner.yml +++ b/.github/workflows/claude_runner.yml @@ -53,7 +53,10 @@ jobs: run_claude: runs-on: ubuntu-latest - if: contains(github.event.comment.body, '@wso2-engineering-bot') + if: | + contains(github.event.comment.body, '@wso2-engineering-bot') && + (github.event.comment.author_association == 'OWNER' || + github.event.comment.author_association == 'MEMBER') steps: - name: Checkout original repository uses: actions/checkout@v4 @@ -69,8 +72,8 @@ jobs: git remote -v # Configure git for commits - git config user.name ${{secrets.DOC_FIXING_AGENT_GIT_USER_NAME}} - git config user.email ${{secrets.DOC_FIXING_AGENT_GIT_USER_EMAIL}} + git config user.name "${{secrets.DOC_FIXING_AGENT_GIT_USER_NAME}}" + git config user.email "${{secrets.DOC_FIXING_AGENT_GIT_USER_EMAIL}}" - name: Prepare system prompt with environment variables id: prepare_prompt @@ -88,10 +91,13 @@ jobs: # Process the system prompt with variable substitution SYSTEM_PROMPT=$(envsubst < ${{github.workspace}}/.github/claude/system_prompt.txt) - # Save to GitHub env - echo "SYSTEM_PROMPT<> $GITHUB_ENV + # Generate unique delimiter to prevent collision + DELIMITER="EOF_$(date +%s)_$$" + + # Save to GitHub env with unique delimiter + echo "SYSTEM_PROMPT<<${DELIMITER}" >> $GITHUB_ENV echo "$SYSTEM_PROMPT" >> $GITHUB_ENV - echo "EOF" >> $GITHUB_ENV + echo "${DELIMITER}" >> $GITHUB_ENV # Also set these for Claude echo "ISSUE_NUMBER=$ISSUE_NUMBER" >> $GITHUB_ENV From e214504266e479fe56252b2a8d5487c4537e02c9 Mon Sep 17 00:00:00 2001 From: Sachindu-Nethmin Date: Tue, 6 Jan 2026 14:56:31 +0530 Subject: [PATCH 3/8] Fix: Rename auto_lable.yml to auto_label.yml --- .github/workflows/auto_lable.yml | 94 ++++++++++++++++++++++++++++++++ 1 file changed, 94 insertions(+) create mode 100644 .github/workflows/auto_lable.yml diff --git a/.github/workflows/auto_lable.yml b/.github/workflows/auto_lable.yml new file mode 100644 index 00000000..a2a276c2 --- /dev/null +++ b/.github/workflows/auto_lable.yml @@ -0,0 +1,94 @@ +name: Claude Code • Auto Label Issues + +on: + issues: + types: [opened, edited] + +jobs: + auto-label: + runs-on: ubuntu-latest + name: Auto-label issues for Claude processing + steps: + - name: Install GitHub & Claude CLI + run: | + sudo apt-get update + sudo apt-get install -y gh + npm install -g @anthropic-ai/claude-code + + - name: Classify issue via Claude API + env: + ANTHROPIC_API_KEY: ${{ secrets.DOC_FIXING_AGENT_ANTHROPIC_API_KEY }} + GITHUB_TOKEN: ${{ secrets.DOC_FIXING_AGENT_GITHUB_TOKEN }} + ISSUE_NUMBER: ${{ github.event.issue.number }} + + ISSUE_TITLE: ${{ github.event.issue.title }} + ISSUE_BODY: ${{ github.event.issue.body }} + run: | + echo "Checking if issue has assignee or is in Hacktoberfest project..." + + # Get issue details + ISSUE_JSON=$(gh issue view $ISSUE_NUMBER --json assignees --repo ${{ github.repository }}) + + # Check if the issue has assignees + ASSIGNEES_COUNT=$(echo "$ISSUE_JSON" | jq '.assignees | length') + echo "Number of assignees: $ASSIGNEES_COUNT" + + # Check if issue is part of Hacktoberfest project + HAS_HACKTOBERFEST_LABEL=$(gh issue view "$ISSUE_NUMBER" --repo ${{ github.repository }} --json labels | jq -r '.labels[].name' | grep -i '^hacktoberfest$' | wc -l) + + if [[ "$ASSIGNEES_COUNT" -gt 0 || "$HAS_HACKTOBERFEST_LABEL" -gt 0 ]]; then + echo "Issue has assignee or is part of Hacktoberfest. Skipping AI-Agent/Queued label." + exit 0 + fi + echo "Sending issue to Claude for classification..." + + # Build JSON payload safely with jq to escape newlines/quotes + PROMPT="You are a GitHub issue classifier for documentation fixes. IMPORTANT: You can fix these specific types of issues: + + 1. broken-links - Links that are broken, dead, or pointing to wrong locations + 2. spelling-mistakes - Spelling errors in documentation text + 3. grammatical-errors - Grammar mistakes in documentation text + 4. formatting-issues - Documentation formatting problems like indentation errors, markdown formatting issues + 5. suggestions - Documentation suggestions and improvements that include specific references or can be verified against project documentation for accuracy and validity + + CRITICAL RULES: + - Read the issue title and body VERY carefully + - For suggestions/improvements: Look for specific references, links, or documentation sources provided + - Verify any provided references and cross-check against official project documentation + - Implement solutions with high accuracy based on verified references + - If suggestions include invalid references or contradict existing documentation, they will be labeled as AI-Agent/Cannot-Fix + - If the issue is requesting to add completely new documentation sections without clear basis, return 'none' + - If the issue is about functionality, code changes, or feature requests, return 'none' + - ONLY return a category name if the issue is EXACTLY about fixing one of the 5 specific problems listed above + - When in doubt, return 'none' + + Return ONLY the category name (broken-links, spelling-mistakes, grammatical-errors, formatting-issues, suggestions) or 'none'. + + Title: $ISSUE_TITLE + Body: $ISSUE_BODY" + + DATA=$(jq -n --arg prompt "$PROMPT" '{ + model: "claude-sonnet-4-5-20250929", + max_tokens: 50, + messages: [{role: "user", content: $prompt}] + }') + + # Call Claude API with required anthropic-version header + RESPONSE=$(curl -s https://api.anthropic.com/v1/messages \ + -H "Content-Type: application/json" \ + -H "x-api-key: $ANTHROPIC_API_KEY" \ + -H "anthropic-version: 2023-06-01" \ + -d "$DATA") + + echo "Claude response: $RESPONSE" + + CATEGORY=$(echo "$RESPONSE" | jq -r '.content[0].text' | tr -d '\n' | tr '[:upper:]' '[:lower:]') + echo "Claude classified the issue as: $CATEGORY" + + # Add claude:queue label if a valid category is returned + if [[ "$CATEGORY" != "" && "$CATEGORY" != "null" && "$CATEGORY" != "none" ]]; then + echo "Adding claude:queue label" + gh issue edit $ISSUE_NUMBER --add-label "AI-Agent/Queued" --repo ${{ github.repository }} + else + echo "No valid category returned. Not adding label." + fi From 146ed4914296f96b85ab8ef155f43288ccbe475d Mon Sep 17 00:00:00 2001 From: Sachindu-Nethmin Date: Tue, 6 Jan 2026 15:02:28 +0530 Subject: [PATCH 4/8] Add workflow for auto-labeling issues using Claude API --- .github/workflows/{auto_lable.yml => auto_label.yml} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename .github/workflows/{auto_lable.yml => auto_label.yml} (100%) diff --git a/.github/workflows/auto_lable.yml b/.github/workflows/auto_label.yml similarity index 100% rename from .github/workflows/auto_lable.yml rename to .github/workflows/auto_label.yml From 3d63378d9aec88acf17117ddbf7493a43ba9f06a Mon Sep 17 00:00:00 2001 From: Sachindu-Nethmin Date: Wed, 7 Jan 2026 13:19:31 +0530 Subject: [PATCH 5/8] Enhance Claude API integration: capture HTTP status and improve error handling --- .github/workflows/auto_label.yml | 26 +++++++++++++++++++------- 1 file changed, 19 insertions(+), 7 deletions(-) diff --git a/.github/workflows/auto_label.yml b/.github/workflows/auto_label.yml index a2a276c2..5798f652 100644 --- a/.github/workflows/auto_label.yml +++ b/.github/workflows/auto_label.yml @@ -73,22 +73,34 @@ jobs: messages: [{role: "user", content: $prompt}] }') - # Call Claude API with required anthropic-version header - RESPONSE=$(curl -s https://api.anthropic.com/v1/messages \ + # Call Claude API with required anthropic-version header and capture HTTP status + RESPONSE_FILE=$(mktemp) + HTTP_STATUS=$(curl -s -w "%{http_code}" -o "$RESPONSE_FILE" https://api.anthropic.com/v1/messages \ -H "Content-Type: application/json" \ -H "x-api-key: $ANTHROPIC_API_KEY" \ -H "anthropic-version: 2023-06-01" \ -d "$DATA") - echo "Claude response: $RESPONSE" + RESPONSE_BODY=$(cat "$RESPONSE_FILE") + rm -f "$RESPONSE_FILE" - CATEGORY=$(echo "$RESPONSE" | jq -r '.content[0].text' | tr -d '\n' | tr '[:upper:]' '[:lower:]') + echo "Claude response status: $HTTP_STATUS" + echo "Claude response body: $RESPONSE_BODY" + + # Fail early on non-2xx responses + if [[ "$HTTP_STATUS" -lt 200 || "$HTTP_STATUS" -ge 300 ]]; then + echo "Claude API call failed with status $HTTP_STATUS" + exit 1 + fi + + # Extract category safely; default to empty on parse errors + CATEGORY=$(echo "$RESPONSE_BODY" | jq -er '.content[0].text' 2>/dev/null | tr -d '\n' | tr '[:upper:]' '[:lower:]') || CATEGORY="" echo "Claude classified the issue as: $CATEGORY" - # Add claude:queue label if a valid category is returned + # Add AI-Agent/Queued label if a valid category is returned if [[ "$CATEGORY" != "" && "$CATEGORY" != "null" && "$CATEGORY" != "none" ]]; then - echo "Adding claude:queue label" + echo "Adding AI-Agent/Queued label" gh issue edit $ISSUE_NUMBER --add-label "AI-Agent/Queued" --repo ${{ github.repository }} else - echo "No valid category returned. Not adding label." + echo "No valid category returned or parsing failed. Not adding label." fi From fac2401bfac8ce20f9aec8db10ff726cc374d054 Mon Sep 17 00:00:00 2001 From: Sachindu-Nethmin Date: Sun, 11 Jan 2026 10:09:38 +0530 Subject: [PATCH 6/8] Refactor Claude issue classification: retrieve title and body dynamically for improved context --- .github/workflows/auto_label.yml | 13 ++++++++----- 1 file changed, 8 insertions(+), 5 deletions(-) diff --git a/.github/workflows/auto_label.yml b/.github/workflows/auto_label.yml index 5798f652..1280d678 100644 --- a/.github/workflows/auto_label.yml +++ b/.github/workflows/auto_label.yml @@ -20,10 +20,10 @@ jobs: ANTHROPIC_API_KEY: ${{ secrets.DOC_FIXING_AGENT_ANTHROPIC_API_KEY }} GITHUB_TOKEN: ${{ secrets.DOC_FIXING_AGENT_GITHUB_TOKEN }} ISSUE_NUMBER: ${{ github.event.issue.number }} - - ISSUE_TITLE: ${{ github.event.issue.title }} - ISSUE_BODY: ${{ github.event.issue.body }} run: | + ISSUE_TITLE=$(gh issue view $ISSUE_NUMBER --json title -q '.title' --repo ${{ github.repository }}) + ISSUE_BODY=$(gh issue view $ISSUE_NUMBER --json body -q '.body' --repo ${{ github.repository }}) + echo "Checking if issue has assignee or is in Hacktoberfest project..." # Get issue details @@ -67,10 +67,13 @@ jobs: Title: $ISSUE_TITLE Body: $ISSUE_BODY" - DATA=$(jq -n --arg prompt "$PROMPT" '{ + DATA=$(jq -n \ + --arg title "$ISSUE_TITLE" \ + --arg body "$ISSUE_BODY" \ + '{ model: "claude-sonnet-4-5-20250929", max_tokens: 50, - messages: [{role: "user", content: $prompt}] + messages: [{role: "user", content: ("You are a GitHub issue classifier for documentation fixes..." + "\n\nTitle: " + $title + "\nBody: " + $body)}] }') # Call Claude API with required anthropic-version header and capture HTTP status From 2bcef14c194736985eca23e25fed3199121414f9 Mon Sep 17 00:00:00 2001 From: Sachindu-Nethmin Date: Sun, 11 Jan 2026 13:28:37 +0530 Subject: [PATCH 7/8] Enhance Claude classification: include dynamic prompt in API request for improved context --- .github/workflows/auto_label.yml | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/.github/workflows/auto_label.yml b/.github/workflows/auto_label.yml index 1280d678..4f4627b7 100644 --- a/.github/workflows/auto_label.yml +++ b/.github/workflows/auto_label.yml @@ -68,12 +68,13 @@ jobs: Body: $ISSUE_BODY" DATA=$(jq -n \ + --arg prompt "$PROMPT" \ --arg title "$ISSUE_TITLE" \ --arg body "$ISSUE_BODY" \ '{ model: "claude-sonnet-4-5-20250929", max_tokens: 50, - messages: [{role: "user", content: ("You are a GitHub issue classifier for documentation fixes..." + "\n\nTitle: " + $title + "\nBody: " + $body)}] + messages: [{role: "user", content: ($prompt + "\n\nTitle: " + $title + "\nBody: " + $body)}] }') # Call Claude API with required anthropic-version header and capture HTTP status From 1eb175eeb44cf731166664c5eb09a6999923f33d Mon Sep 17 00:00:00 2001 From: Sachindu-Nethmin Date: Sun, 11 Jan 2026 15:29:52 +0530 Subject: [PATCH 8/8] Update Claude model version to claude-sonnet-4-5-20250929 for improved performance --- .github/workflows/claude_runner.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/claude_runner.yml b/.github/workflows/claude_runner.yml index c94aa6a6..d302655b 100644 --- a/.github/workflows/claude_runner.yml +++ b/.github/workflows/claude_runner.yml @@ -117,7 +117,7 @@ jobs: trigger_phrase: "@wso2-engineering-bot" claude_args: | --allowedTools "Bash(*),Bash(git:*),Bash(mkdocs:*),Bash(python3:*),Bash(pip3:*),WebFetch,mcp__github__create_pull_request,mcp__github__get_issue,mcp__github__search_pull_requests,mcp__github__list_branches,Edit,Read,Write,mcp__github__update_issue,mcp__github__create_branch,mcp__github__add_issue_comment,mcp__github__get_file_contents" - --model claude-sonnet-4-20250514 + --model claude-sonnet-4-5-20250929 - name: Get next queued issue id: get_next_queued