refactor(agents): extract bug-discovery skill, AGENTS.md to English, EN descriptions (#120)

Co-authored-by: opencode-agent <agent@opencode.local>

.opencode/skills/add-skill/SKILL.md

@@ -21,7 +21,7 @@ description: Use when creating a new opencode skill. Covers file location, front
 ```markdown
 ---
 name: <skill-name>
-description: <когда загружать. Триггеры на русском и английском. Например: Use when ... Also when user says "...">
+description: <when to load this skill, in English. Example: Use when ... Also when user says "русские фразы-триггеры">
 ---
 
 # Skill Title
@@ -32,7 +32,7 @@ description: <когда загружать. Триггеры на русско
 ### Правила
 
 - `name` — kebab-case, совпадает с именем директории
-- `description` — содержит конкретные триггеры (когда агент должен загрузить этот скилл)
+- `description` — must be in English. Contains specific triggers (when the agent should load this skill). Format: `Use when ... Also when user says "..."`. The `Also when user says "..."` part may contain Russian trigger phrases since the user speaks Russian.
 - Язык тела — русский с английскими техническими терминами (как в существующих скиллах)
 - Один скилл — одна директория с одним `SKILL.md`
 

.opencode/skills/bug-discovery/SKILL.md

@@ -0,0 +1,15 @@
+---
+name: bug-discovery
+description: Use when a bug is found outside the current task scope. Covers duplicate check, issue creation via create-issue tool, and continuation protocol. Also when user says "нашёл баг", "bug found", "создай issue для бага", "bug outside scope".
+---
+
+# Bug Discovery Protocol
+
+If a bug is found during work that is outside the scope of the current task:
+
+1. Check `gh issue list` for duplicates.
+2. Create a GitHub issue via `create-issue` tool (NOT raw `gh issue create`).
+3. Title: `fix(scope): short description` in English.
+4. Body: `## Контекст` / `## Задача` / `## Критерии приемки` (in Russian).
+5. Continue the current task. Do NOT fix the bug yourself.
+6. Report to orchestrator: "Created issue #N: ...".

.opencode/skills/code-standards/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: code-standards
-description: Универсальные правила разработки для любого языка. Используй когда пишешь, рефакторишь или ревьювишь код.
+description: Universal code standards for any language. Use when writing, refactoring, or reviewing code. Also when user says "стандарты кода", "code review", "правила разработки".
 ---
 
 # Code Standards

.opencode/skills/get-project-map/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: get-project-map
-description: Используй этот навык, когда тебе нужно увидеть или актуализировать текущую структуру папок и файлов проекта (особенно после создания/удаления файлов или переключения веток), либо понять расположение пакетов в воркспейсе. Также содержит шаблон для поддержки docs/project-map/.
+description: Use when you need to view or update the current project folder/file structure (especially after creating/deleting files or switching branches), or understand package layout in the workspace. Also contains a template for maintaining docs/project-map/. Also when user says "структура проекта", "project map", "дерево файлов".
 ---
 
 # Навык получения карты проекта (Project Map)

.opencode/skills/issue/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: issue
-description: Создаёт GitHub issue. Issue должны быть самодостаточными — агент в пустом чате может выполнить без доп. контекста. Если задача большая — разбей на несколько маленьких. Используй subagent для создания чтобы не засорять контекст. Also when user says "создай ишью", "создай issue", "заведи задачу", "разбей на подзадачи", "create issue".
+description: Creates GitHub issues. Issues must be self-contained — an agent in an empty chat can execute without extra context. If a task is large, split it into smaller ones. Use a subagent for creation to avoid cluttering context. Also when user says "создай ишью", "создай issue", "заведи задачу", "разбей на подзадачи", "create issue".
 ---
 
 ## Принцип: один issue = один PR

.opencode/skills/memory/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: memory
-description: Инструкция по работе с файловой памятью opencode-memory (search + save + retro).
+description: Instructions for opencode-memory file-based memory system (search + save + retro). Also when user says "память", "memory", "запомни", "найди в памяти".
 ---
 
 # File Memory (opencode-memory)

.opencode/skills/python-development/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: python-development
-description: Python-специфика: импорты, логирование, обработка ошибок, тесты. Используй вместе с code-standards для Python-проектов.
+description: Python-specific standards: imports, logging, error handling, tests. Use alongside code-standards for Python projects. Also when user says "python", "питон", "python开发".
 ---
 
 # Python Development

.opencode/skills/release/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: release
-description: Выполняет релиз после мерджа PR — обновляет CHANGELOG, создаёт git tag и GitHub Release. Используй когда пользователь говорит "сделай релиз", "выпусти версию", "опубликуй", "release", "затегай". Also when user says "сделай релиз", "выпусти версию".
+description: Performs a release after PR merge — updates CHANGELOG, creates git tag and GitHub Release. Use when the user says "сделай релиз", "выпусти версию", "опубликуй", "release", "затегай".
 ---
 
 ## Релиз

.opencode/skills/run-pipeline/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: run-pipeline
-description: Автономный исполнитель PR-пайплайна. Делегирует 7 фаз subagent'ам, не импровизирует порядок, не мержит при красном CI.
+description: Autonomous PR pipeline executor. Delegates 7 phases to subagents, does not improvise order, does not merge on red CI. Also when user says "запусти пайплайн", "pipeline", "run pipeline".
 ---
 
 # Run Pipeline

.opencode/skills/run-tests/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: run-tests
-description: Используй этот навык, когда пользователь просит запустить тесты, проверить работоспособность кода, исправить ошибки после правок или запустить pytest.
+description: Use when the user asks to run tests, verify code works, fix errors after edits, or run pytest. Also when user says "запусти тесты", "run tests", "проверь код", "pytest".
 ---
 
 # Навык запуска тестов и исправления ошибок через Pytest

.opencode/skills/spec/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: spec
-description: Автономный исполнитель spec-генерации для нового проекта. Детерминированно ведёт агента по 9 фазам через spec-status tool. Главный агент — оркестратор, делегирует ВСЮ работу subagent'ам. Also when user says "создай спеку", "новый проект", "спецификация проекта", "spec", "project spec".
+description: Autonomous spec generation executor for new projects. Deterministically guides the agent through 9 phases via spec-status tool. Main agent is orchestrator, delegates ALL work to subagents. Also when user says "создай спеку", "новый проект", "спецификация проекта", "spec", "project spec".
 ---
 
 # Spec

.opencode/skills/tunnel/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: tunnel
-description: Подними cloudflare туннель когда пользователь просит "подними тоннель", "пробрось порт", "tunnel"
+description: Set up a Cloudflare tunnel when the user asks to expose a port or create a tunnel. Also when user says "подними тоннель", "пробрось порт", "tunnel".
 ---
 
 # Tunnel

AGENTS.md

@@ -1,12 +1,12 @@
 # Global Rules
 
-## Orchestrator Model (главное)
+## Orchestrator Model
 
-- Главный чат = ТОЛЬКО план. Все исследования, команды, edits, реализации — ТОЛЬКО через subagents.
+- Main chat = planning ONLY. All research, commands, edits, implementation — ONLY via subagents.
-- Никогда не делать самому: research файловой системы, grep/glob, bash-команды, file edits, тесты, git ops.
+- Never do yourself: filesystem research, grep/glob, bash commands, file edits, tests, git ops.
-- Максимум: верхнеуровневый план + отчёты пользователю + делегирование `task` subagent'ам.
+- Maximum: high-level plan + reports to user + delegation to `task` subagents.
-- Pipeline: каждую фазу (ISSUE → IMPLEMENT → DOCS → CI → REVIEW → MERGE → MEMORY) делегировать subagent'у.
+- Pipeline: delegate each phase (ISSUE → IMPLEMENT → DOCS → CI → REVIEW → MERGE → MEMORY) to a subagent.
-- Subagent error → 1 retry, потом STOP + report.
+- Subagent error → 1 retry, then STOP + report.
 
 ## Pipeline
 
@@ -15,26 +15,20 @@ Pipeline: ISSUE → IMPLEMENT → DOCS → CI → REVIEW → MERGE → MEMORY.
 
 ## Bug Discovery Protocol
 
-Если в процессе работы найден баг вне scope текущей задачи:
+If a bug is found outside current task scope — load skill `bug-discovery`.
-1. Проверь `gh issue list` на дубликаты.
-2. Создай GitHub issue через `create-issue` tool (НЕ raw `gh issue create`).
-3. Title: `fix(scope): краткое описание` на английском.
-4. Body: `## Контекст` / `## Задача` / `## Критерии приемки` (на русском).
-5. Продолжай текущую задачу. НЕ исправляй баг сам.
-6. В отчёте orchestrator'у укажи: "Создан issue #N: ...".
 
 ## Linear Execution
 
-- В рамках одного репозитория — строго линейное выполнение pipeline.
+- Within a single repository — strictly linear pipeline execution.
-- Нельзя запускать второй pipeline, пока не завершён первый (merge или close).
+- Cannot start a second pipeline until the first is complete (merge or close).
-- Issues создаёт ОДИН агент за раз (batch creation), не параллельные агенты.
+- Issues are created by ONE agent at a time (batch creation), not parallel agents.
-- Параллельные исследования (explore agents, 3-4 concurrently) — можно.
+- Parallel research (explore agents, 3-4 concurrently) — allowed.
-- Параллельное исполнение (implementation/review/docs) — ЗАПРЕЩЕНО.
+- Parallel execution (implementation/review/docs) — PROHIBITED.
-- Причина: агенты прыгают между ветками → конфликты, потеря работы, хаос.
+- Reason: agents jump between branches → conflicts, lost work, chaos.
 
 ## Read Path
 
-Перед началом задачи в репо: просмотри имена файлов в `docs/handoff/` (если есть) — открой релевантные по теме.
+Before starting a task in a repo: scan filenames in `docs/handoff/` (if any) — open relevant ones by topic.
 
 ## Code Style
 
@@ -45,7 +39,7 @@ Pipeline: ISSUE → IMPLEMENT → DOCS → CI → REVIEW → MERGE → MEMORY.
 
 ## Tools
 
-Используй tool вместо bash. При сбое tool — STOP + репорт, НЕ fallback на raw bash, НЕ обход через `gh api`. Deny-список — в `permission.bash` файла `opencode.json`.
+Use tools instead of bash. On failure — STOP + report. Deny-list in `permission.bash` of `opencode.json`.
 
 ## Language
 

docs/decisions/053-pr-120-agents-extract-skill-en.md

@@ -0,0 +1,55 @@
+# ADR-053: Extract bug-discovery skill, AGENTS.md to English
+
+## Статус
+Accepted (2026-07-29)
+
+## Контекст
+
+AGENTS.md (project-local, bind-mounted глобально) накопил процедурные детали,
+ухудшающие читаемость:
+
+- **Bug Discovery Protocol** — 8-строчный протокол (проверка дубликатов, шаги
+  создания issue, формат title/body, отчёт). Процедура, не правило — тянет в
+  скилл.
+- **Tools секция** — содержала мягкую enforcement-фразу "НЕ fallback на raw
+  bash, НЕ обход через `gh api`". Но реальный enforcement — deny-list в
+  `permission.bash` файла `opencode.json`. Мягкие инструкции не работают (агент
+  всё равно попытается fallback если нет жёсткого block).
+- **Skill descriptions** — смесь RU/EN. Descriptions используются для semantic
+  skill selection (matching). RU-only descriptions (`run-pipeline`,
+  `code-standards`, `memory` и др.) ухудшают matching против EN intent.
+- **`add-skill` инструкция** — не уточняла язык description, оставляя
+  произвол — новые скиллы плодили RU descriptions.
+
+## Решение
+
+1. **Извлечь Bug Discovery Protocol в скилл `bug-discovery`** — 6-шаговый
+   протокол в `.opencode/skills/bug-discovery/SKILL.md`. В AGENTS.md оставить
+   1 строку: "If a bug is found outside current task scope — load skill
+   `bug-discovery`."
+2. **Перевести AGENTS.md на английский** — все 8 секций. Язык остаётся
+   "Always respond to the user in Russian" (взаимодействие с юзером), но
+   правила/directives на EN для consistency с global AGENTS.md (тоже EN).
+3. **Упростить Tools** — убрать мягкую enforcement-фразу. Оставить:
+   "Use tools instead of bash. On failure — STOP + report. Deny-list in
+   `permission.bash` of `opencode.json`." Real enforcement = deny-list.
+4. **EN descriptions для 10 скиллов** — перевести frontmatter `description` на
+   английский (форматы `Use when ... Also when user says "..."` с RU-триггерами).
+   Тела скиллов НЕ трогать (могут оставаться на русском).
+5. **Обновить `add-skill`** — инструкция и шаблон явно требуют EN description
+   для новых скиллов. RU фразы разрешены только в `Also when user says "..."`.
+
+## Альтернативы
+
+- **Оставить Bug Discovery Protocol в AGENTS.md, не извлекать** — отвергнуто:
+   AGENTS.md перегружен процедурами. Скиллы — правильное место для процедур
+   (загружаются по триггеру, не загромождают always-loaded directive).
+- **Принудительная миграция ВСЕХ скиллов на EN descriptions** — отвергнуто: 5
+   скиллов (`branch`, `repo-init`, `repo-readme`, `configure-opencode`,
+   `add-skill`) уже имели EN descriptions. Принудительный обход всех —
+   лишний churn. Мигрированы 10 с RU-only. Будущие — через обновлённый
+   `add-skill` instruction.
+- **Оставить мягкую enforcement в Tools ("НЕ fallback")** — отвергнуто: не
+   работает. Deny-list — реальный enforcement (raw `git commit`, `gh issue
+   create *`, `gh pr merge *` заблокированы). Дублирование мягкой инструкции
+   создаёт ложное ощущение enforcement.

docs/handoff/pr-120-agents-extract-skill-en.md

@@ -0,0 +1,56 @@
+---
+pr: 120
+title: refactor(agents): extract bug-discovery skill, AGENTS.md to English, EN descriptions
+---
+
+## Что сделано
+
+- **Новый скилл `bug-discovery`** (`.opencode/skills/bug-discovery/SKILL.md`) —
+  6-шаговый протокол, извлечённый из AGENTS.md (проверка дубликатов →
+  `create-issue` tool → EN title / RU body → продолжить задачу → отчёт
+  оркестратору).
+- **AGENTS.md переведён на английский** (все 8 секций). Bug Discovery Protocol
+  сокращён с 8 строк до 1 строки + ссылка на скилл `bug-discovery`. Tools
+  упрощён — убрана мягкая enforcement-фраза ("НЕ fallback на raw bash, НЕ обход
+  через `gh api`"), оставлен только deny-list указатель.
+- **10 skill descriptions переведены на английский** (только frontmatter, тела
+  НЕ трогались): run-pipeline, code-standards, memory, python-development,
+  run-tests, get-project-map, release (убран дубль триггеров), tunnel, spec,
+  issue.
+- **`add-skill` тело обновлено** — инструкция про description: теперь явно
+  требует EN. Формат `Use when ... Also when user says "..."` (RU фразы в
+  триггерах OK, т.к. юзер говорит по-русски). Шаблон frontmatter обновлён.
+- **`docs/project-map/README.md`** — добавлен `bug-discovery/SKILL.md` в
+  дерево `.opencode/skills/`.
+- **Handoff + ADR-053** созданы.
+
+Проверки: `pytest tests/test_permissions.py` 13 passed; `ruff check` OK;
+`ruff format --check` OK (40 files); `check-permissions.py` OK; кириллицы в
+AGENTS.md нет (verified via python regex).
+
+## Почему
+
+AGENTS.md перегружен процедурными деталями (8-строчный Bug Discovery Protocol).
+RU descriptions мешают semantic matching (descriptions используются для
+skill selection). Мягкая enforcement ("НЕ fallback на raw bash, НЕ обход
+через `gh api`") не работает — реальный enforcement это deny-list в
+`permission.bash` файла `opencode.json`. Извлечение протокола в скилл держит
+AGENTS.md компактным (52 → 45 строк), а EN descriptions улучшают matching.
+
+## Pending
+
+—
+
+## Watch out
+
+- Глобальный `~/.config/opencode/AGENTS.md` НЕ трогался — он монтируется через
+  docker volume (Dockerfile/docker-compose), изменения project-local AGENTS.md
+  подхватятся после rebuild/restart контейнера.
+- `add-skill` теперь инструктирует EN descriptions для новых скиллов —
+  существующие скиллы с RU description НЕ мигрированы принудительно (только 10
+  в этом PR). `branch`, `repo-init`, `repo-readme`, `configure-opencode`,
+  `add-skill` уже имели EN descriptions — не тронуты.
+- Тела скиллов (кроме `add-skill`) НЕ изменялись — остаются на русском с
+  английскими техническими терминами (как было).
+- `bug-discovery` появится в `available_skills` только после рестарта opencode
+  (скиллы загружаются при старте).

docs/project-map/README.md

@@ -25,6 +25,7 @@ opencode-config/
 │   │   └── spec.md                  # /spec — 9-phase spec generation
 │   ├── skills/
 │   │   ├── add-skill/SKILL.md      # Create new opencode skill
+│   │   ├── bug-discovery/SKILL.md   # Bug Discovery Protocol — create issue for out-of-scope bugs (create-issue tool, duplicate check) — PR#120
 │   │   ├── branch/SKILL.md         # Branch naming conventions
 │   │   ├── code-standards/SKILL.md # Universal code style rules
 │   │   ├── configure-opencode/SKILL.md # Canonical rule: write to .opencode/