dotfiles/AGENTS.md

GEMINI.md - Project Context & Instructions

This repository contains personal dotfiles and configurations for a highly productive development environment, integrating Bash, Tmux, Vim, VS Code, and various AI assistants (Gemini CLI, Claude, Codex, Opencode).

📂 Project Overview

• Type: Non-Code Project (Dotfiles / Configuration)
• Management: Uses stow for Linux/WSL and chezmoi for Windows/WSL.
• Key Focus:
  • Unified configuration across editors and terminals.
  • Deep integration with AI tools via shared "skills".
  • Automated environment setup (proxy handling, secret loading).

🛠 Key Components

1. Shell & Terminal (Bash & Tmux)

• Bash: Custom prompt (.bash_prompt), utility functions (.bash_functions like proxy_on/off), and core customizations (.bash_custom).
• Tmux: Dual prefix (C-b and C-Space), Vi-mode for copying, and optimized pane management.
• Secrets: Managed via ~/.env.secrets (not tracked in Git).

2. Editors (Vim, VS Code, Zed)

• Vim: Minimalist .vimrc, 2-space indentation, leader-key mappings (Space).
• VS Code (WSL): Uses server-env-setup to automatically load secrets and configure proxy settings upon startup.
• Zed: Placeholder directory for future configuration.

3. AI Agents & Skills

• Shared Skills: Located in agents/.agents/skills/. This is the single source of truth for AI instructions.
• Gemini CLI: Configured via gemini/.gemini/.
  • Policies: readonly-commands.toml allows critical commands like git status, git diff, and git add to run without confirmation.
• Opencode: MCP-based assistant configuration (opencode.json) with support for documentation, search, and web-reading.
• Skill Bridges: Claude gets skills via the ~/.claude/skills symlink; Opencode reads ~/.agents/skills natively, no bridge needed.

🚀 Usage & Maintenance

Deployment

• Linux/WSL: Use stow <package_name> from the root directory.
• Windows: Use chezmoi apply.

Adding/Updating Skills

1. Modify files in agents/.agents/skills/.
2. Ensure symlinks in other tool directories are updated if new skills are added.
3. Устаревшие скиллы время от времени удаляем. Убирай каталог целиком, а вместе с ним ссылки из других скиллов и строку в .gitignore, если скилл был внешним. Упоминания в архивах и handoff-записках — история, их не трогаем.

📋 TODO

Планы на будущее — см. TODO.md.

🗣 Язык и рассуждения

Пиши на ясном русском языке. Иностранные слова оставляй только там, где у термина нет устоявшегося русского аналога: имена технологий и инструментов (Kafka, ClickHouse, Airflow) и названия из кода. Если для понятия есть обычное русское слово — используй его, не выдумывай транслитерации (пиши «приведение в соответствие», а не «реконсиляция»; «точка отсчёта», а не «origin»).

Документы, комментарии и объяснения держи короткими и понятными читателю, который их не писал: простые слова, короткие фразы, сложную мысль поясняй при первом упоминании (помни про менти-неспециалиста). Если понятность и буквальная точность спорят — выбирай понятность. Правило касается и текста, и заголовков разделов.

Внутренние рассуждения и промежуточные пометки по ходу работы веди на английском — он экономнее по токенам (кириллица занимает примерно в 1,5–2 раза больше). На русском остаётся всё, что видит и хранит проект: итоговые ответы пользователю, документы, комментарии в коде и сообщения коммитов.

Навыки агентов

Хранилище задач

Задачи хранятся в Gitea Issues (git.dementev.space), работа с ними — через CLI tea. См. docs/agents/issue-tracker.md.

Состояния triage

Состояния triage — метки Gitea со стандартными названиями. См. docs/agents/triage-labels.md.

Документы предметной области

Одна предметная область на весь репозиторий: корневой CONTEXT.md и общие ADR в docs/adr/. См. docs/agents/domain.md.

Записки для передачи работы

Записки для продолжения работы в новой сессии — .scratch/handoffs/YYYYMMDD-HHMM-<slug>.md (одноразовые, уборка best-effort; скилл /handoff пишет сюда).

.scratch/ — локальная рабочая зона

Весь .scratch/ — заметки по ходу дела: handoffs и черновики (задачи живут в Gitea). Каталог в .gitignore: он живёт только на этой машине и в Git не попадает.

Долговечное знание держим вне .scratch/ (в docs/, CONTEXT.md) и коммитим вместе с работой. Прежде чем сливать фиче-ветку, убедись, что долговечная часть уже вынесена туда: остальное из .scratch/ потом не восстановить.

Субагенты и экономия контекста

Объёмную и механическую работу делегируем субагентам (Sonnet или аналогичная, в зависимости от сложности задачи), чтобы не засорять контекст основной сессии: проверки (реперы/линт/валидация), пакетные и файловые операции, отладка и прочее. Субагент сам читает «шумный» ввод-вывод и возвращает только результат.

• Мелочь делегировать не стоит — кроме случая, когда она даёт объёмный вывод: пусть субагент прочитает его у себя и вернёт выжимку.