From c9533050b8df1538b34e6588244d36c4f6166e00 Mon Sep 17 00:00:00 2001 From: Sergey <93754860+slaid098@users.noreply.github.com> Date: Wed, 29 Jul 2026 05:14:28 +0300 Subject: [PATCH] refactor(agents): extract bug-discovery skill, AGENTS.md to English, EN descriptions (#120) Co-authored-by: opencode-agent --- .opencode/skills/add-skill/SKILL.md | 4 +- .opencode/skills/bug-discovery/SKILL.md | 15 +++++ .opencode/skills/code-standards/SKILL.md | 2 +- .opencode/skills/get-project-map/SKILL.md | 2 +- .opencode/skills/issue/SKILL.md | 2 +- .opencode/skills/memory/SKILL.md | 2 +- .opencode/skills/python-development/SKILL.md | 2 +- .opencode/skills/release/SKILL.md | 2 +- .opencode/skills/run-pipeline/SKILL.md | 2 +- .opencode/skills/run-tests/SKILL.md | 2 +- .opencode/skills/spec/SKILL.md | 2 +- .opencode/skills/tunnel/SKILL.md | 2 +- AGENTS.md | 36 +++++------- .../053-pr-120-agents-extract-skill-en.md | 55 ++++++++++++++++++ .../handoff/pr-120-agents-extract-skill-en.md | 56 +++++++++++++++++++ docs/project-map/README.md | 1 + 16 files changed, 154 insertions(+), 33 deletions(-) create mode 100644 .opencode/skills/bug-discovery/SKILL.md create mode 100644 docs/decisions/053-pr-120-agents-extract-skill-en.md create mode 100644 docs/handoff/pr-120-agents-extract-skill-en.md diff --git a/.opencode/skills/add-skill/SKILL.md b/.opencode/skills/add-skill/SKILL.md index a9a98b3..b2357ea 100644 --- a/.opencode/skills/add-skill/SKILL.md +++ b/.opencode/skills/add-skill/SKILL.md @@ -21,7 +21,7 @@ description: Use when creating a new opencode skill. Covers file location, front ```markdown --- name: -description: <когда загружать. Триггеры на русском и английском. Например: Use when ... Also when user says "..."> +description: --- # 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` diff --git a/.opencode/skills/bug-discovery/SKILL.md b/.opencode/skills/bug-discovery/SKILL.md new file mode 100644 index 0000000..570dc43 --- /dev/null +++ b/.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: ...". \ No newline at end of file diff --git a/.opencode/skills/code-standards/SKILL.md b/.opencode/skills/code-standards/SKILL.md index cb245a3..ac38372 100644 --- a/.opencode/skills/code-standards/SKILL.md +++ b/.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 diff --git a/.opencode/skills/get-project-map/SKILL.md b/.opencode/skills/get-project-map/SKILL.md index f17fcaa..0652b24 100644 --- a/.opencode/skills/get-project-map/SKILL.md +++ b/.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) diff --git a/.opencode/skills/issue/SKILL.md b/.opencode/skills/issue/SKILL.md index 05247f5..bb5a47a 100644 --- a/.opencode/skills/issue/SKILL.md +++ b/.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 diff --git a/.opencode/skills/memory/SKILL.md b/.opencode/skills/memory/SKILL.md index e8cba8a..6ed6bbc 100644 --- a/.opencode/skills/memory/SKILL.md +++ b/.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) diff --git a/.opencode/skills/python-development/SKILL.md b/.opencode/skills/python-development/SKILL.md index 2390fb8..249d1a9 100644 --- a/.opencode/skills/python-development/SKILL.md +++ b/.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 diff --git a/.opencode/skills/release/SKILL.md b/.opencode/skills/release/SKILL.md index a289b94..ce8bd91 100644 --- a/.opencode/skills/release/SKILL.md +++ b/.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", "затегай". --- ## Релиз diff --git a/.opencode/skills/run-pipeline/SKILL.md b/.opencode/skills/run-pipeline/SKILL.md index d6100f0..380fdcd 100644 --- a/.opencode/skills/run-pipeline/SKILL.md +++ b/.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 diff --git a/.opencode/skills/run-tests/SKILL.md b/.opencode/skills/run-tests/SKILL.md index 6ae9649..5af12cb 100644 --- a/.opencode/skills/run-tests/SKILL.md +++ b/.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 diff --git a/.opencode/skills/spec/SKILL.md b/.opencode/skills/spec/SKILL.md index f76a436..fd1cb49 100644 --- a/.opencode/skills/spec/SKILL.md +++ b/.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 diff --git a/.opencode/skills/tunnel/SKILL.md b/.opencode/skills/tunnel/SKILL.md index b07009d..18e09bd 100644 --- a/.opencode/skills/tunnel/SKILL.md +++ b/.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 diff --git a/AGENTS.md b/AGENTS.md index 1034732..3dd735b 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,12 +1,12 @@ # Global Rules -## Orchestrator Model (главное) +## Orchestrator Model -- Главный чат = ТОЛЬКО план. Все исследования, команды, edits, реализации — ТОЛЬКО через subagents. -- Никогда не делать самому: research файловой системы, grep/glob, bash-команды, file edits, тесты, git ops. -- Максимум: верхнеуровневый план + отчёты пользователю + делегирование `task` subagent'ам. -- Pipeline: каждую фазу (ISSUE → IMPLEMENT → DOCS → CI → REVIEW → MERGE → MEMORY) делегировать subagent'у. -- Subagent error → 1 retry, потом STOP + report. +- Main chat = planning ONLY. All research, commands, edits, implementation — ONLY via subagents. +- Never do yourself: filesystem research, grep/glob, bash commands, file edits, tests, git ops. +- Maximum: high-level plan + reports to user + delegation to `task` subagents. +- Pipeline: delegate each phase (ISSUE → IMPLEMENT → DOCS → CI → REVIEW → MERGE → MEMORY) to a subagent. +- Subagent error → 1 retry, then STOP + report. ## Pipeline @@ -15,26 +15,20 @@ Pipeline: ISSUE → IMPLEMENT → DOCS → CI → REVIEW → MERGE → MEMORY. ## Bug Discovery Protocol -Если в процессе работы найден баг вне scope текущей задачи: -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: ...". +If a bug is found outside current task scope — load skill `bug-discovery`. ## Linear Execution -- В рамках одного репозитория — строго линейное выполнение pipeline. -- Нельзя запускать второй pipeline, пока не завершён первый (merge или close). -- Issues создаёт ОДИН агент за раз (batch creation), не параллельные агенты. -- Параллельные исследования (explore agents, 3-4 concurrently) — можно. -- Параллельное исполнение (implementation/review/docs) — ЗАПРЕЩЕНО. -- Причина: агенты прыгают между ветками → конфликты, потеря работы, хаос. +- Within a single repository — strictly linear pipeline execution. +- Cannot start a second pipeline until the first is complete (merge or close). +- Issues are created by ONE agent at a time (batch creation), not parallel agents. +- Parallel research (explore agents, 3-4 concurrently) — allowed. +- 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 diff --git a/docs/decisions/053-pr-120-agents-extract-skill-en.md b/docs/decisions/053-pr-120-agents-extract-skill-en.md new file mode 100644 index 0000000..ffc74c7 --- /dev/null +++ b/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. \ No newline at end of file diff --git a/docs/handoff/pr-120-agents-extract-skill-en.md b/docs/handoff/pr-120-agents-extract-skill-en.md new file mode 100644 index 0000000..07788d8 --- /dev/null +++ b/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 + (скиллы загружаются при старте). \ No newline at end of file diff --git a/docs/project-map/README.md b/docs/project-map/README.md index 4c62f71..475cc91 100644 --- a/docs/project-map/README.md +++ b/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/