Global Agent Rules

Global workflows are located in the workflows/ directory.

Academic Paper Download & Search Guideline

When a user requests research, literature search, or paper downloading, follow these rules to choose and execute the correct tool:

1. Tool Selection Criteria

• Case A: You have specific DOIs, titles, or PMCIDs
  • Tool: paper-fetch
  • Reason: It has zero external dependencies, uses a 7-source fallback chain to prioritize open access first, and includes an active Cloudflare-bypassing cloak mode.
  • Execution: Run the Python script directly (output is saved to /Users/keira/Documents/GitHub/docs by default): bash python3 paper-fetch/skills/paper-fetch/scripts/fetch.py <DOI>
• Case B: You have a general topic search query (e.g., "[machine learning] AND [healthcare]")
  • Tool: findpapers
  • Reason: It runs boolean searches in parallel across 8 major academic databases, handles deduplication, and supports citation snowballing.
  • Execution: Run via the virtual environment interpreter or packages: bash .venv/bin/python3 -c "import findpapers; ..."

2. Bypassing and Banned Practices

• Do NOT use scihub2pdf, PyPaperBot, or SciDownl—they are deprecated, abandoned, or blocked by modern anti-bot challenges.
• If paper-fetch encounters 403 or 429 errors from publishers, enable CloakBrowser mode by setting the environment variable: bash export PAPER_FETCH_CLOAK=1

Brand Logo Downloading & Processing Guideline

When a user requests downloading or fetching a company or brand logo for the blog or other projects, follow these rules:

1. Logo Discovery and WebP Conversion

• Workflow: Use the /logo-fetch workflow (logo-fetch-wf.md).
• Execution: Run the Python processor script directly: bash .venv/bin/python3 .agents/skills/logo-processor/scripts/process_logo.py --domain <domain>
• WebP/SVG rule: The script automatically fetches the logo from public APIs (Hunter.io, Clearbit, or Google) and saves vector logos as .svg or raster logos as .webp.

2. Skip Grayscale by Default

• Rule: Always perform the initial download and WebP conversion WITHOUT grayscaling (do not pass --grayscale).
• Reason: Keeps the color asset preserved in storage. The blog styles logos to grayscale dynamically using CSS classes.
• Grayscale Request: Only convert the logo to grayscale if the user explicitly asks to do so after the initial fetch and conversion workflow is complete. Run with --grayscale then.

Project Context Rule (Multi-tool Workspace)

Khi làm việc với bất kỳ project nào trong thư mục Projects/: 1. Đọc Context trước khi code: BẮT BUỘC đọc file CONTEXT.md trong folder project đó (nếu có) để nắm bắt trạng thái sprint, kiến trúc và các quyết định kỹ thuật trước đó. 2. Cập nhật Session Log: Sau khi hoàn thành một task, refactor hoặc tính năng lớn, cập nhật mục "Session log" trong CONTEXT.md với định dạng tag [AG] kèm ngày và tóm tắt công việc. 3. Commit Message Format: Tuân thủ quy ước feat/fix/docs/chore: <mô tả> [AG] để phân biệt rõ ràng với các commit từ Hermes Desktop ([HM]). 4. Đồng bộ Git: Chủ động commit và push sau mỗi phiên làm việc lớn để dữ liệu luôn sẵn sàng trên VPS và cho Hermes Desktop.

Code Simplicity & The Decision Ladder (Ponytail Pattern)

Trước khi viết mã, tạo file hoặc thêm dependency, Agent BẮT BUỘC duyệt qua 7 bậc quyết định: 1. YAGNI: Tính năng/thành phần này có thực sự cần thiết không? Nếu không, bỏ qua. 2. Reuse: Codebase hiện tại đã có hàm/module tương tự chưa? Tái sử dụng, cấm viết lại. 3. Stdlib: Thư viện chuẩn của ngôn ngữ đã có sẵn không? Dùng stdlib. 4. Native Platform: Platform/OS/Web API có sẵn không (e.g. HTML5 inputs, POSIX CLI)? Dùng native. 5. Existing Dependencies: Project đã cài package nào giải quyết được chưa? Cấm tự tiện cài thêm lib mới. 6. One-liner: Có thể giải quyết ngắn gọn trong 1-2 dòng code không? 7. Minimal Code: Chỉ viết lượng code tối thiểu đáp ứng bài toán (không lược bỏ bảo mật, bắt lỗi, validation).

Token & Output Optimization (RTK & Graft Guidelines)

1. RTK (Rust Token Killer): Ưu tiên tiền tố rtk cho các lệnh shell (rtk git status, rtk pytest, rtk npm test, rtk docker ps) để giảm 60-90% token rác trong ngữ cảnh hội thoại.
2. Graft Context Layer:
3. Thư mục graft/ và .graph/ là local cache (tương tự node_modules), BẮT BUỘC phải nằm trong .gitignore. Tuyệt đối không commit lên git để tránh xung đột sync 2 chiều với VPS.
4. Khi cần khảo sát kiến trúc hoặc call-graph của một project, ưu tiên dùng graft map hoặc graft callers thay vì quét grep/read mù quáng hàng chục file.