opencode-config/docs/decisions/034-pr-78-align-tool-names-kebab-case.md

ADR-034: Align local tool names to kebab-case in documentation

Статус

Accepted (2026-07-26)

Контекст

Реальные имена opencode tools в runtime registry — kebab-case (подтверждено анализом opencode.db: 397 runtime вызовов локальных .opencode/tools/*.ts tools в kebab-case, 0 в snake_case). SDK @opencode-ai/plugin@1.18.5 tool() функция не имеет поля name — имя tool'а резолвится из filename (create-pr.ts → registry name "create-pr").

В AGENTS.md / SKILL.md / agents промптах tool'ы были написаны в snake_case (create_pr, merge_pr, pipeline_status и т.д.) — документационная конвенция эпохи написания (ADR-009, 2026-07-23). Runtime резолвит snake→kebab автоматически через utility Re=(X)=>X.replace(/_/g,"-") в opencode.exe — система работала, НО агент спотыкался: читал "вызови pipeline_status", искал такой tool в tool-списке сессии, находил только pipeline-status, не совпадало → вызывал не тот tool или fallback на raw bash (который deny → блок).

PR#71 GOTCHA memory (2026-07-26) зафиксировала расхождение: "Фактические tool names (как их вызывает opencode runtime) = дефис. Underscore в AGENTS.md — документационная конвенция, не runtime."

Решение

1. Заменить snake_case имена ЛОКАЛЬНЫХ opencode tools на kebab-case в активной документации: AGENTS.md, 6 SKILL.md, 3 agents/.md, 2 commands/.md, docs/project-map/README.md. 12 файлов, 84 insertions / 82 deletions.

2. Локальные tools (правки): create-issue, create-pr, merge-pr, post-review, post-docs-review, pipeline-status, spec-status, memory-setup. Однословные commit/tunnel — без изменений.

3. MCP plugin tools (memory_search, memory_list, memory_save, memory_access) — НЕ трогать. Это другой namespace: имена задаёт плагин в export-коде (snake_case), не filename. opencode.db подтверждает: memory_search (65 calls), memory_save (13), memory_access (22) — все snake_case.

4. Исторические docs/handoff/* и docs/decisions/* НЕ трогать — сохраняют оригинальное написание эпохи написания (включая snake_case в ADR-009, handoff pr-29). Правка исторических ADR/handoff исказит историю.

5. opencode.json agent.tools map keys — НЕ трогать (snake_case keys работают через runtime Re-utility, смена требует проверки JSON-схемы + test_permissions.py — отдельный PR).

6. Аргументы tool'ов (pr_number, issue_number, verdict, body) остаются snake_case — это имена параметров в JSON schema, не tool names.

Доп. правки: broken ADR-026 ref в spec/SKILL.md:28 → ADR-019; путь скрипта config/scripts/ → .opencode/scripts/; список скиллов в add-skill/SKILL.md 12 → 14.

Альтернативы

1. Сменить agent.tools map keys в opencode.json на kebab — отклонено (требует проверки JSON-схемы + test_permissions.py, отдельный PR, snake keys работают через Re-utility).

2. Править исторические ADR/handoff на kebab — отклонено (исказит историю, ADR-009 фиксирует intent "tools не переименовывались" — написание snake_case там документационная конвенция, не runtime assertion).

3. Добавить поле name в .ts tools с явным kebab — отклонено (SDK tool() не имеет этого поля в signature, имя уже корректно резолвится из filename).

4. Оставить snake_case в документации + rely on Re-utility — отклонено (агент спотыкается, читает "pipeline_status" и не находит такого tool в tool-списке сессии; документация должна совпадать с runtime).