Merge branch 'adenhq:main' into main

Author: PatrickChen928

.claude/skills/building-agents-construction/SKILL.md

@@ -520,6 +520,8 @@ class RuntimeConfig:
     model: str = "cerebras/zai-glm-4.7"
     temperature: float = 0.7
     max_tokens: int = 4096
+    api_key: str | None = None
+    api_base: str | None = None
 
 default_config = RuntimeConfig()
 
@@ -972,7 +974,11 @@ class {agent_class_name}:
         llm = None
         if not mock_mode:
             # LiteLLMProvider uses environment variables for API keys
-            llm = LiteLLMProvider(model=self.config.model)
+            llm = LiteLLMProvider(
+                model=self.config.model,
+                api_key=self.config.api_key,
+                api_base=self.config.api_base,
+            )
 
         self._graph = GraphSpec(
             id="{agent_name}-graph",

.claude/skills/building-agents-construction/examples/online_research_agent/agent.py

@@ -233,7 +233,11 @@ def _create_runtime(self, mock_mode=False) -> AgentRuntime:
         llm = None
         if not mock_mode:
             # LiteLLMProvider uses environment variables for API keys
-            llm = LiteLLMProvider(model=self.config.model)
+            llm = LiteLLMProvider(
+                model=self.config.model,
+                api_key=self.config.api_key,
+                api_base=self.config.api_base,
+            )
 
         self._graph = GraphSpec(
             id="online-research-agent-graph",

.claude/skills/building-agents-construction/examples/online_research_agent/config.py

@@ -7,6 +7,8 @@ class RuntimeConfig:
     model: str = "groq/moonshotai/kimi-k2-instruct-0905"
     temperature: float = 0.7
     max_tokens: int = 16384
+    api_key: str | None = None
+    api_base: str | None = None
 
 
 default_config = RuntimeConfig()

.github/workflows/claude-issue-triage.yml

@@ -0,0 +1,68 @@
+name: Claude Issue Triage
+
+on:
+  issues:
+    types: [opened]
+
+jobs:
+  triage:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      issues: write
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 1
+
+      - name: Run Claude Issue Triage
+        id: claude-triage
+        uses: anthropics/claude-code-action@v1
+        with:
+          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          allowed_non_write_users: '*'
+          prompt: |
+            REPO: ${{ github.repository }}
+            ISSUE NUMBER: ${{ github.event.issue.number }}
+            TITLE: ${{ github.event.issue.title }}
+            BODY: ${{ github.event.issue.body }}
+            AUTHOR: ${{ github.event.issue.user.login }}
+
+            Analyze this new issue and perform the following:
+
+            1. **Categorize the issue type using ONLY these labels:**
+               - bug: Something isn't working
+               - enhancement: New feature or request
+               - question: Further information is requested
+               - documentation: Improvements or additions to documentation
+               - good first issue: Good for newcomers (if issue is well-defined and small scope)
+               - help wanted: Extra attention is needed (if issue needs community input)
+               - backlog: Tracked for the future, but not currently planned or prioritized
+
+            2. **Check for duplicates:**
+               Search for similar existing issues using:
+               `gh issue list --state all --search "<key terms from title/body>"`
+
+               If a duplicate exists:
+               - Add the "duplicate" label
+               - Comment mentioning the original issue number
+
+            3. **Check for invalid issues:**
+               If the issue lacks sufficient information, is spam, or doesn't make sense:
+               - Add the "invalid" label
+               - Comment asking for clarification or explaining why it's invalid
+
+            4. **Apply labels:**
+               Based on your analysis, add appropriate labels using:
+               `gh issue edit ${{ github.event.issue.number }} --add-label "label1,label2"`
+
+               You may apply multiple labels if appropriate (e.g., "bug,help wanted").
+
+            5. **Add a brief comment** summarizing your triage decision to help maintainers.
+
+          claude_args: |
+            --model claude-3-5-haiku-20241022
+            --allowedTools "Bash(gh issue:*),Bash(gh search:*)"

.gitignore

@@ -6,6 +6,32 @@ Thank you for your interest in contributing to the Aden Agent Framework! This do
 
 By participating in this project, you agree to abide by our [Code of Conduct](CODE_OF_CONDUCT.md).
 
+## Issue Assignment Policy
+
+To prevent duplicate work and respect contributors' time, we require issue assignment before submitting PRs.
+
+### How to Claim an Issue
+
+1. **Find an Issue:** Browse existing issues or create a new one
+2. **Claim It:** Leave a comment (e.g., *"I'd like to work on this!"*)
+3. **Wait for Assignment:** A maintainer will assign you within 24 hours
+4. **Submit Your PR:** Once assigned, you're ready to contribute
+
+> **Note:** PRs for unassigned issues may be delayed or closed if someone else was already assigned.
+
+### The 5-Day Momentum Rule
+
+To keep the project moving, issues with **no activity for 5 days** (no PR or status update) will be unassigned. If you need more time, just drop a quick comment!
+
+### Exceptions (No Assignment Needed)
+
+You may submit PRs without prior assignment for:
+- **Documentation:** Fixing typos or clarifying instructions
+- **Micro-fixes:** Minor tweaks or obvious linting errors
+- **Small Refactors:** Tiny improvements that don't change core logic
+
+If a high-quality PR is submitted for a "stale" assigned issue (no activity for 7+ days), we may proceed with the submitted code.
+
 ## Getting Started
 
 1. Fork the repository
@@ -59,11 +85,12 @@ docs(readme): update installation instructions
 
 ## Pull Request Process
 
-1. Update documentation if needed
-2. Add tests for new functionality
-3. Ensure all tests pass
-4. Update the CHANGELOG.md if applicable
-5. Request review from maintainers
+1. **Get assigned to the issue first** (see [Issue Assignment Policy](#issue-assignment-policy))
+2. Update documentation if needed
+3. Add tests for new functionality
+4. Ensure all tests pass
+5. Update the CHANGELOG.md if applicable
+6. Request review from maintainers
 
 ### PR Title Format
 

CONTRIBUTING.md

@@ -596,10 +596,11 @@ pip install -e .
 # Option 1: Use Claude Code skill (recommended)
 claude> /building-agents
 
-# Option 2: Copy from example
-cp -r exports/support_ticket_agent exports/my_new_agent
+# Option 2: Create manually
+# Note: exports/ is initially empty (gitignored). Create your agent directory:
+mkdir -p exports/my_new_agent
 cd exports/my_new_agent
-# Edit agent.json, tools.py, README.md
+# Create agent.json, tools.py, README.md (see Agent Package Structure below)
 
 # Option 3: Use the agent builder MCP tools (advanced)
 # See core/MCP_BUILDER_TOOLS_GUIDE.md

DEVELOPER.md

@@ -152,6 +152,31 @@ Creates comprehensive test suites for your agent.
 
 ## Troubleshooting
 
+### "externally-managed-environment" error (PEP 668)
+
+**Cause:** Python 3.12+ on macOS/Homebrew, WSL, or some Linux distros prevents system-wide pip installs.
+
+**Solution:** Create and use a virtual environment:
+
+```bash
+# Create virtual environment
+python3 -m venv .venv
+
+# Activate it
+source .venv/bin/activate  # macOS/Linux
+# .venv\Scripts\activate   # Windows
+
+# Then run setup
+./scripts/setup-python.sh
+```
+
+Always activate the venv before running agents:
+
+```bash
+source .venv/bin/activate
+PYTHONPATH=core:exports python -m your_agent_name demo
+```
+
 ### "ModuleNotFoundError: No module named 'framework'"
 
 **Solution:** Install the core package:
@@ -188,7 +213,7 @@ pip install --upgrade "openai>=1.0.0"
 
 **Cause:** Not running from project root or missing PYTHONPATH
 
-**Solution:** Ensure you're in `/home/timothy/oss/hive/` and use:
+**Solution:** Ensure you're in the project root directory and use:
 
 ```bash
 PYTHONPATH=core:exports python -m support_ticket_agent validate

ENVIRONMENT_SETUP.md

@@ -8,7 +8,8 @@
   <a href="README.es.md">Español</a> |
   <a href="README.pt.md">Português</a> |
   <a href="README.ja.md">日本語</a> |
-  <a href="README.ru.md">Русский</a>
+  <a href="README.ru.md">Русский</a> |
+  <a href="README.ko.md">한국어</a>
 </p>
 
 [![Apache 2.0 License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://github.com/adenhq/hive/blob/main/LICENSE)
@@ -288,11 +289,14 @@ Usamos [Discord](https://discord.com/invite/MXE49hrKDk) para soporte, solicitude
 
 ¡Damos la bienvenida a las contribuciones! Por favor consulta [CONTRIBUTING.md](CONTRIBUTING.md) para las directrices.
 
-1. Haz fork del repositorio
-2. Crea tu rama de funcionalidad (`git checkout -b feature/amazing-feature`)
-3. Haz commit de tus cambios (`git commit -m 'Add amazing feature'`)
-4. Haz push a la rama (`git push origin feature/amazing-feature`)
-5. Abre un Pull Request
+**Importante:** Por favor, solicita que se te asigne un issue antes de enviar un PR. Comenta en el issue para reclamarlo y un mantenedor te lo asignará en 24 horas. Esto ayuda a evitar trabajo duplicado.
+
+1. Encuentra o crea un issue y solicita asignación
+2. Haz fork del repositorio
+3. Crea tu rama de funcionalidad (`git checkout -b feature/amazing-feature`)
+4. Haz commit de tus cambios (`git commit -m 'Add amazing feature'`)
+5. Haz push a la rama (`git push origin feature/amazing-feature`)
+6. Abre un Pull Request
 
 ## Únete a Nuestro Equipo
 

README.es.md

@@ -8,7 +8,8 @@
   <a href="README.es.md">Español</a> |
   <a href="README.pt.md">Português</a> |
   <a href="README.ja.md">日本語</a> |
-  <a href="README.ru.md">Русский</a>
+  <a href="README.ru.md">Русский</a> |
+  <a href="README.ko.md">한국어</a>
 </p>
 
 [![Apache 2.0 License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://github.com/adenhq/hive/blob/main/LICENSE)
@@ -288,11 +289,14 @@ timeline
 
 貢献を歓迎します！ガイドラインについては[CONTRIBUTING.md](CONTRIBUTING.md)をご覧ください。
 
-1. リポジトリをフォーク
-2. 機能ブランチを作成 (`git checkout -b feature/amazing-feature`)
-3. 変更をコミット (`git commit -m 'Add amazing feature'`)
-4. ブランチにプッシュ (`git push origin feature/amazing-feature`)
-5. プルリクエストを開く
+**重要：** PRを提出する前に、まずIssueにアサインされてください。Issueにコメントして担当を申請すると、メンテナーが24時間以内にアサインします。これにより重複作業を防ぐことができます。
+
+1. Issueを見つけるか作成し、アサインを受ける
+2. リポジトリをフォーク
+3. 機能ブランチを作成 (`git checkout -b feature/amazing-feature`)
+4. 変更をコミット (`git commit -m 'Add amazing feature'`)
+5. ブランチにプッシュ (`git push origin feature/amazing-feature`)
+6. プルリクエストを開く
 
 ## チームに参加