35 lines
4.4 KiB
Markdown
35 lines
4.4 KiB
Markdown
# 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).
|