Add Claude AI Assistant GitHub Actions Workflow

.github/workflows/claude.yml

@@ -0,0 +1,197 @@
+# Copyright(C) 2025-2026 Advanced Micro Devices, Inc. All rights reserved.
+# SPDX-License-Identifier: MIT
+
+name: Claude AI Assistant
+
+on:
+  issues:
+    types: [opened, labeled]
+  issue_comment:
+    types: [created]
+  pull_request:
+    types: [opened, ready_for_review]
+  pull_request_review_comment:
+    types: [created]
+
+permissions:
+  contents: read
+  issues: write
+  pull-requests: write
+  id-token: write
+
+jobs:
+  # Auto-review new PRs
+  pr-review:
+    if: |
+      github.event_name == 'pull_request' &&
+      (github.event.pull_request.draft == false ||
+       contains(github.event.pull_request.labels.*.name, 'ready_for_ci'))
+    runs-on: ubuntu-latest
+    concurrency:
+      group: claude-pr-review-${{ github.event.pull_request.number }}
+      cancel-in-progress: true
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+      - uses: anthropics/claude-code-action@v1
+        with:
+          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
+          model: claude-opus-4-5-20251101
+          prompt: |
+            You are reviewing a GAIA pull request. Provide a thorough, professional code review following GAIA standards.
+
+            ## Review Checklist
+
+            ### 1. Copyright & Licensing
+            - ✅ All NEW files must have: `Copyright(C) 2025-2026 Advanced Micro Devices, Inc. All rights reserved.`
+            - ✅ All NEW files must have: `SPDX-License-Identifier: MIT`
+            - Flag any missing headers
+
+            ### 2. Code Quality & Patterns
+            - Verify code follows existing patterns in `src/gaia/`
+            - Check consistency with similar components
+            - Review error handling and edge cases
+            - Assess code readability and maintainability
+            - Reference CLAUDE.md and docs/reference/dev.md for standards
+
+            ### 3. Security Review (CRITICAL)
+            - 🔒 SQL injection vulnerabilities
+            - 🔒 Command injection (especially in shell tools, Bash usage)
+            - 🔒 XSS vulnerabilities (web UIs, HTML generation)
+            - 🔒 Secrets exposure (API keys, tokens in code/logs)
+            - 🔒 Path traversal vulnerabilities
+            - 🔒 Unsafe deserialization
+
+            **If security issues found:** Comment "🔒 SECURITY CONCERN" and describe the issue. Tag @kovtcharov-amd immediately.
+
+            ### 4. Testing
+            - Check if tests exist in `tests/` for new functionality
+            - Review test quality (not just coverage):
+              - Do tests cover edge cases?
+              - Are tests readable and maintainable?
+              - Do they test the right things?
+            - Verify existing tests still pass (check CI status)
+
+            ### 5. Documentation
+            - If API changes: Check for docs updates in `docs/`
+            - If new features: Verify user-facing documentation exists
+            - Check if README or guides need updates
+            - Validate code comments for complex logic
+
+            ### 6. Breaking Changes & Compatibility
+            - Identify any breaking changes to public APIs
+            - Check backward compatibility considerations
+            - Review migration impact for existing users
+
+            ### 7. Performance & Architecture
+            - Flag potential performance issues (N+1 queries, inefficient algorithms)
+            - Review architectural decisions
+            - Check for code duplication that should be refactored
+
+            ### 8. Commit Quality
+            - Review commit messages for clarity
+            - Check if commits are logically organized
+
+            ## Output Format
+
+            Provide a clear, organized review with:
+            - **Summary:** 2-3 sentences on overall quality
+            - **Strengths:** What's done well
+            - **Issues:** Numbered list with severity (🔴 Critical, 🟡 Important, 🟢 Minor)
+            - **Recommendations:** Specific, actionable suggestions
+            - **File References:** Use format `file.py:123` when referencing code
+
+            Be professional, constructive, and specific. Assume the author is skilled but may not know GAIA conventions.
+          claude_args: "--max-turns 5"
+
+  # Respond to @claude in PRs
+  pr-comment:
+    if: |
+      github.event_name == 'pull_request_review_comment' &&
+      contains(github.event.comment.body, '@claude')
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - uses: anthropics/claude-code-action@v1
+        with:
+          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
+          model: claude-opus-4-5-20251101
+          prompt: |
+            You are GAIA's AI assistant helping with pull request discussions.
+
+            Follow the Issue Response Guidelines in CLAUDE.md:
+            - Reference specific files and line numbers
+            - Check docs/ for relevant documentation
+            - Provide GAIA-specific context and examples
+            - Be concise but thorough
+            - If you don't know, say so and suggest who to ask (@kovtcharov-amd)
+
+            Maintain a helpful, professional tone. You're assisting both maintainers and contributors.
+          claude_args: "--max-turns 5"
+
+  # Respond to new issues or @claude mentions
+  issue-handler:
+    if: |
+      github.event_name == 'issues' ||
+      (github.event_name == 'issue_comment' &&
+       contains(github.event.comment.body, '@claude'))
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - uses: anthropics/claude-code-action@v1
+        with:
+          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
+          model: claude-opus-4-5-20251101
+          prompt: |
+            You are GAIA's helpful AI assistant. Follow the Issue Response Guidelines in CLAUDE.md.
+
+            ## Response Protocol
+
+            ### 1. Check for Duplicates First
+            Search existing issues/PRs before providing a detailed response.
+            If duplicate found, link to it: "This appears related to #123"
+
+            ### 2. For Questions
+            Check docs/ folder (see docs/docs.json for structure):
+            - **Getting Started:** docs/setup.md, docs/quickstart.md
+            - **User Guides:** docs/guides/chat.md, docs/guides/talk.md, docs/guides/code.md, docs/guides/blender.md, docs/guides/jira.md
+            - **SDK Reference:** docs/sdk/core/agent-system.md, docs/sdk/sdks/chat.md, docs/sdk/sdks/rag.md, docs/sdk/infrastructure/mcp.md
+            - **CLI Reference:** docs/reference/cli.md, docs/reference/features.md
+            - **FAQ:** docs/reference/faq.md, docs/glossary.md
+            - **Development:** docs/reference/dev.md, docs/sdk/testing.md, docs/sdk/best-practices.md
+
+            ### 3. For Bugs
+            - Search src/gaia/ for related code
+            - Check tests/ for related test cases
+            - Reference docs/sdk/troubleshooting.md
+            - Check security implications using docs/sdk/security.md
+            - Ask for reproduction steps if not provided
+            - **If security bug:** Tag @kovtcharov-amd and suggest opening a private security advisory instead
+
+            ### 4. For Feature Requests
+            - Check if similar exists in src/gaia/agents/ or src/gaia/apps/
+            - Reference docs/sdk/examples.md and docs/sdk/advanced-patterns.md
+            - Suggest approaches following docs/sdk/best-practices.md
+            - Consider AMD hardware optimization opportunities
+
+            ### 5. Response Guidelines
+            - **Be concise:** 1-3 paragraphs for simple questions, more for complex issues
+            - **Reference files:** Use format `src/gaia/agents/base.py:123` when possible
+            - **Link to docs:** Always include relevant documentation links
+            - **Code examples:** Provide when helpful, following GAIA conventions
+            - **Next steps:** End with clear action items
+            - **Escalate when needed:** Tag @kovtcharov-amd for:
+              - Security issues
+              - Architecture decisions
+              - Issues you can't resolve
+              - Requests for roadmap/timeline info
+
+            ### 6. Tone
+            - Friendly and professional
+            - Assume good intent
+            - Welcome contributors
+            - Acknowledge AMD's open-source commitment
+
+            Always reference specific files with line numbers when possible.
+          claude_args: "--max-turns 4"

.github/workflows/test_gaia_cli_windows.yml

@@ -8,6 +8,7 @@
 name: GAIA CLI Tests (Windows)
 
 on:
+  workflow_call:
   push:
     branches: ["main"]
     paths:

CLAUDE.md

@@ -135,22 +135,178 @@ gaia/
 - General tasks: `Qwen2.5-0.5B-Instruct-CPU`
 - Code/Jira: `Qwen3-Coder-30B-A3B-Instruct-GGUF`
 
-## Documentation
+## Documentation Index
+
+**User:** [`docs/cli.md`](docs/cli.md), [`docs/chat.md`](docs/chat.md), [`docs/talk.md`](docs/talk.md), [`docs/code.md`](docs/code.md), [`docs/blender.md`](docs/blender.md), [`docs/jira.md`](docs/jira.md), [`docs/features.md`](docs/features.md), [`docs/faq.md`](docs/faq.md)
+
+**Developer:** [`docs/dev.md`](docs/dev.md), [`docs/apps/dev.md`](docs/apps/dev.md), [`docs/mcp.md`](docs/mcp.md), [`docs/eval.md`](docs/eval.md), [`CONTRIBUTING.md`](CONTRIBUTING.md)
+
+**Platform:** [`docs/installer.md`](docs/installer.md), [`docs/ui.md`](docs/ui.md)
+
+## Issue Response Guidelines
+
+When responding to GitHub issues and pull requests, follow these guidelines:
+
+### Documentation Structure
 
 **External Site:** https://amd-gaia.ai
 - [Quickstart](https://amd-gaia.ai/quickstart) - Build your first agent in 10 minutes
 - [SDK Reference](https://amd-gaia.ai/sdk) - Complete API documentation
 - [Guides](https://amd-gaia.ai/guides) - Chat, Code, Talk, Blender, Jira, and more
 - [FAQ](https://amd-gaia.ai/reference/faq) - Frequently asked questions
 
-**Local Documentation** (Mintlify MDX format in `docs/`):
+The documentation is organized in [`docs/docs.json`](docs/docs.json) with the following structure:
 - **SDK**: `docs/sdk/` - Agent system, tools, core SDKs (chat, llm, rag, vlm, audio)
-- **Guides**: `docs/guides/` - Feature guides for chat, code, talk, blender, jira, docker, etc.
-- **Specs**: `docs/spec/` - 47 technical specifications for all components
-- **Playbooks**: `docs/playbooks/` - Step-by-step tutorials (chat-agent, code-agent, emr-agent, etc.)
-- **Reference**: `docs/reference/` - CLI reference, API reference, dev guide, troubleshooting
+- **User Guides** (`docs/guides/`): Feature-specific guides (chat, talk, code, blender, jira, docker, routing)
+- **Playbooks** (`docs/playbooks/`): Step-by-step tutorials for building agents
+- **SDK Reference** (`docs/sdk/`): Core concepts, SDKs, infrastructure, mixins, agents
+- **Specifications** (`docs/spec/`): Technical specs for all components
+- **Reference** (`docs/reference/`): CLI, API, features, FAQ, development
 - **Integrations**: `docs/integrations/` - MCP, n8n, VSCode
-- **Deployment**: `docs/deployment/` - Installer, UI, Electron testing
+- **Deployment** (`docs/deployment/`): Packaging, installers, UI
+
+### Response Protocol
+
+1. **Check documentation first:** Always search `docs/` folder before suggesting solutions
+   - See [`docs/docs.json`](docs/docs.json) for the complete documentation structure
+
+2. **Check for duplicates:** Search existing issues/PRs to avoid redundant responses
+
+3. **Reference specific files:** Use precise file references with line numbers when possible
+   - Agent implementations: `src/gaia/agents/` (base.py, chat_agent.py, code_agent.py, jira_agent.py, blender_agent.py)
+   - CLI commands: `src/gaia/cli.py`
+   - MCP integration: `src/gaia/mcp/`
+   - LLM backend: `src/gaia/llm/`
+   - Audio processing: `src/gaia/audio/` (ASR, TTS)
+   - RAG system: `src/gaia/rag/` (document Q&A, embeddings)
+   - Evaluation: `src/gaia/eval/` (batch experiments, ground truth)
+   - Applications: `src/gaia/apps/` (jira, llm, summarize)
+   - Chat SDK: `src/gaia/chat/`
+
+4. **Link to relevant documentation:**
+   - **Getting Started:** [`docs/setup.md`](docs/setup.md), [`docs/quickstart.md`](docs/quickstart.md)
+   - **User Guides:** [`docs/guides/chat.md`](docs/guides/chat.md), [`docs/guides/talk.md`](docs/guides/talk.md), [`docs/guides/code.md`](docs/guides/code.md), [`docs/guides/blender.md`](docs/guides/blender.md), [`docs/guides/jira.md`](docs/guides/jira.md)
+   - **SDK Reference:** [`docs/sdk/core/agent-system.md`](docs/sdk/core/agent-system.md), [`docs/sdk/sdks/chat.md`](docs/sdk/sdks/chat.md), [`docs/sdk/sdks/rag.md`](docs/sdk/sdks/rag.md), [`docs/sdk/infrastructure/mcp.md`](docs/sdk/infrastructure/mcp.md)
+   - **CLI Reference:** [`docs/reference/cli.md`](docs/reference/cli.md), [`docs/reference/features.md`](docs/reference/features.md)
+   - **Development:** [`docs/reference/dev.md`](docs/reference/dev.md), [`docs/sdk/testing.md`](docs/sdk/testing.md), [`docs/sdk/best-practices.md`](docs/sdk/best-practices.md)
+   - **FAQ & Help:** [`docs/reference/faq.md`](docs/reference/faq.md), [`docs/glossary.md`](docs/glossary.md)
+
+5. **For bugs:**
+   - Search `src/gaia/` for related code
+   - Check `tests/` for related test cases that might reveal the issue or need updating
+   - Reference [`docs/sdk/troubleshooting.md`](docs/sdk/troubleshooting.md)
+   - Check security implications using [`docs/sdk/security.md`](docs/sdk/security.md)
+
+6. **For feature requests:**
+   - Check if similar functionality exists in `src/gaia/agents/` or `src/gaia/apps/`
+   - Reference [`docs/sdk/examples.md`](docs/sdk/examples.md) and [`docs/sdk/advanced-patterns.md`](docs/sdk/advanced-patterns.md)
+   - Suggest approaches following [`docs/sdk/best-practices.md`](docs/sdk/best-practices.md)
+
+7. **Follow contribution guidelines:**
+   - Reference [`CONTRIBUTING.md`](CONTRIBUTING.md) for code standards
+   - Ensure AMD copyright headers on new files
+   - Point to [`docs/reference/dev.md`](docs/reference/dev.md) for development workflow
+
+### Response Quality Guidelines
+
+#### Tone & Style
+- **Professional but friendly:** Welcome contributors warmly while maintaining technical accuracy
+- **Concise:** Aim for 1-3 paragraphs for simple questions, expand for complex issues
+- **Specific:** Reference actual files with line numbers (e.g., `src/gaia/agents/base.py:123`)
+- **Helpful:** Provide next steps, code examples, or links to documentation
+- **Honest:** If you don't know something, say so and suggest escalation to @kovtcharov-amd
+
+#### Security Handling Protocol (CRITICAL)
+
+**For security issues reported in public issues:**
+1. **DO NOT** discuss specific vulnerability details publicly
+2. **Immediately** respond with: "Thank you for reporting this. This appears to be a security concern. Please open a private security advisory instead: [GitHub Security Advisories](https://github.com/amd/gaia/security/advisories/new)"
+3. **Tag** @kovtcharov-amd in your response
+4. **Do not** provide exploit details, proof-of-concept code, or technical analysis in public
+
+**For security issues found in PR reviews:**
+1. Comment with: "🔒 SECURITY CONCERN"
+2. Tag @kovtcharov-amd immediately
+3. Describe the issue type (e.g., "Potential command injection") but not exploitation details
+4. Suggest the PR author discuss privately with maintainers
+
+#### Escalation Protocol
+
+**Escalate to @kovtcharov-amd for:**
+- Security vulnerabilities
+- Architecture or design decisions
+- Roadmap or timeline questions
+- Breaking changes or deprecations
+- Issues you cannot resolve with available documentation
+- External integration or partnership requests
+- Questions about AMD hardware specifics or roadmap
+
+**Do not escalate for:**
+- Questions answered in existing documentation
+- Simple usage questions
+- Duplicate issues (just link to the original)
+- Feature requests that need community discussion first
+
+#### Response Length Guidelines
+
+- **Quick answers:** 1 paragraph + link to docs
+- **How-to questions:** 2-3 paragraphs + code example + links
+- **Bug reports:** Ask for reproduction steps (if missing), check similar issues, reference relevant code
+- **Feature requests:** 2-4 paragraphs discussing feasibility, existing patterns, AMD optimization opportunities
+- **Complex technical discussions:** Be thorough but use headers/bullets for readability
+
+**Never:**
+- Write walls of text without structure
+- Repeat information already in the issue
+- Provide generic advice not specific to GAIA
+
+#### Examples
+
+**Good Response (Bug Report):**
+```
+Thanks for reporting this! The error you're seeing in `gaia chat` appears to be related to RAG initialization.
+
+Looking at src/gaia/rag/embeddings.py:145, the initialization expects a model path. Could you confirm:
+1. Did you run `gaia chat init` first?
+2. What's the output of `gaia chat status`?
+
+See docs/guides/chat.md for the full setup process. This might also be related to #123.
+```
+
+**Bad Response (Too Generic):**
+```
+This looks like a configuration issue. Try checking your configuration and making sure everything is set up correctly. Let me know if that helps!
+```
+
+**Good Response (Feature Request):**
+```
+Interesting idea! GAIA doesn't currently have built-in Slack integration, but you could build this using:
+
+1. The Chat SDK (docs/sdk/sdks/chat.md) for message handling
+2. The MCP protocol (docs/sdk/infrastructure/mcp.md) for Slack connectivity
+3. Similar pattern to our Jira agent (src/gaia/agents/jira_agent.py)
+
+For AMD optimization: Consider using the local LLM backend (src/gaia/llm/) to keep conversations private and leverage Ryzen AI NPU acceleration.
+
+Would you be interested in contributing this? See CONTRIBUTING.md for how to get started.
+```
+
+**Bad Response (Security Issue):**
+```
+Looking at your code, the issue is on line 45 where you're using subprocess.call() with user input. Here's how an attacker could exploit it: [detailed exploit]. You should use shlex.quote() like this: [code example].
+```
+*This is bad because it discusses exploit details publicly. Should escalate privately instead.*
+
+#### Community & Contributor Management
+
+- **Welcome first-time contributors:** Acknowledge their effort and guide them gently
+- **Assume good intent:** Even for unclear or duplicate issues
+- **Be patient:** External contributors may not know GAIA conventions yet
+- **Recognize contributions:** Thank people for bug reports, feature ideas, and PRs
+- **AMD's commitment:** Remind users that GAIA is AMD's open-source commitment to accessible AI
+
+## File Path Rules (Workaround for Claude Code v1.0.111 Bug)
+- When reading or editing a file, **ALWAYS use relative paths.**
 
 ## File Path Rules
 - When reading or editing files, **ALWAYS use relative paths** starting with `./`