From d641f7a65b0620c08ab07c8351e66b8bfa09ba90 Mon Sep 17 00:00:00 2001 From: Sergey <93754860+slaid098@users.noreply.github.com> Date: Sun, 26 Jul 2026 17:48:55 +0300 Subject: [PATCH] fix(docs): align tool names to kebab-case in active documentation (#78) Co-authored-by: opencode-agent --- .opencode/agents/docs-reviewer.md | 12 ++--- .opencode/agents/memory-syncer.md | 2 +- .opencode/agents/reviewer.md | 24 +++++----- .opencode/commands/run-pipeline.md | 2 +- .opencode/commands/spec.md | 2 +- .opencode/skills/add-skill/SKILL.md | 6 ++- .opencode/skills/issue/SKILL.md | 8 ++-- .opencode/skills/memory/SKILL.md | 2 +- .opencode/skills/run-pipeline/SKILL.md | 48 +++++++++---------- .opencode/skills/spec/SKILL.md | 22 ++++----- AGENTS.md | 20 ++++---- .../034-pr-78-align-tool-names-kebab-case.md | 35 ++++++++++++++ .../pr-78-align-tool-names-kebab-case.md | 37 ++++++++++++++ docs/project-map/README.md | 18 +++---- 14 files changed, 156 insertions(+), 82 deletions(-) create mode 100644 docs/decisions/034-pr-78-align-tool-names-kebab-case.md create mode 100644 docs/handoff/pr-78-align-tool-names-kebab-case.md diff --git a/.opencode/agents/docs-reviewer.md b/.opencode/agents/docs-reviewer.md index cbb490e..8687ae6 100644 --- a/.opencode/agents/docs-reviewer.md +++ b/.opencode/agents/docs-reviewer.md @@ -1,5 +1,5 @@ --- -description: Reviews and updates project map documentation before code review. Auto-commits updates to PR branch. Posts verdict via post_docs_review tool (deterministic heading for pipeline-status.py). +description: Reviews and updates project map documentation before code review. Auto-commits updates to PR branch. Posts verdict via post-docs-review tool (deterministic heading for pipeline-status.py). mode: subagent temperature: 0.1 steps: 150 @@ -197,7 +197,7 @@ last_updated: ## PR Comment (mandatory) -After validation (regardless of whether structural changes occurred), **ALWAYS** leave a PR comment using the `post_docs_review` tool. The tool auto-generates the `## Docs Review Summary` heading and the `### Verdict: ` line — you only pass the body content (between heading and verdict). Do NOT manually format the heading or verdict. This is the deterministic marker that `check_docs` in pipeline-status.py uses to prove docs-reviewer ran. Without this comment, the pipeline is blocked at DOCS phase. +After validation (regardless of whether structural changes occurred), **ALWAYS** leave a PR comment using the `post-docs-review` tool. The tool auto-generates the `## Docs Review Summary` heading and the `### Verdict: ` line — you only pass the body content (between heading and verdict). Do NOT manually format the heading or verdict. This is the deterministic marker that `check_docs` in pipeline-status.py uses to prove docs-reviewer ran. Without this comment, the pipeline is blocked at DOCS phase. Body format (without heading — tool adds `## Docs Review Summary` and `### Verdict: `): ``` @@ -211,7 +211,7 @@ Body format (without heading — tool adds `## Docs Review Summary` and `### Ver Call: ``` -post_docs_review({ pr_number: , verdict: "", body: `` }) +post-docs-review({ pr_number: , verdict: "", body: `` }) ``` Verdict semantics: @@ -222,15 +222,15 @@ Verdict semantics: Rules: 1. Comment is left AFTER commit+push (if any) — so reviewer can see final state. 2. If no structural changes AND handoff+ADR valid → no commit, but comment IS still left with `Verdict: NO_CHANGES`. -3. The comment heading `## Docs Review Summary` is guaranteed by the `post_docs_review` tool — `check_docs` matches regex `Docs Review` (case-insensitive). +3. The comment heading `## Docs Review Summary` is guaranteed by the `post-docs-review` tool — `check_docs` matches regex `Docs Review` (case-insensitive). 4. Never skip the comment, even on edge cases — use `Verdict: NO_CHANGES` instead of silence. ## Tool failure handling -If `post_docs_review` returns a string starting with `⚠️ ...failed` (e.g. `⚠️ post-docs-review failed for PR #N (exit 1): ...`): +If `post-docs-review` returns a string starting with `⚠️ ...failed` (e.g. `⚠️ post-docs-review failed for PR #N (exit 1): ...`): - **СООБЩИ оркестратору о сбое tool и STOP.** Не продолжай молча, не пытайся fallback на raw `gh pr comment` через bash. - Причина сбоя обычно: gh не аутентифицирован, PR не найден в текущем репо (cwd не git-репо или нет origin remote), или network error. -- Возвращай текст вида: `⚠️ post_docs_review tool failed: <сообщение от tool>. Pipeline заблокирован на DOCS phase — требуется вмешательство.` +- Возвращай текст вида: `⚠️ post-docs-review tool failed: <сообщение от tool>. Pipeline заблокирован на DOCS phase — требуется вмешательство.` - Любой дальнейший tool call после сбоя = protocol violation. ## Rules diff --git a/.opencode/agents/memory-syncer.md b/.opencode/agents/memory-syncer.md index fa603e2..d21b239 100644 --- a/.opencode/agents/memory-syncer.md +++ b/.opencode/agents/memory-syncer.md @@ -92,6 +92,6 @@ If a fact is already recorded — update the entry (bump `updated` in frontmatte 5. Receipt is mandatory even if no durable records found. 6. If memory file doesn't exist — create it with proper frontmatter (title, tags, summary, created, updated, importance). 7. Для debug-вывода используй `pwd`/`ls`/`cat`/`printenv` — НЕ `echo` (не в allow-list). -8. Для статуса PR используй нативный tool `pipeline_status` (НЕ bash `python3 .../pipeline-status.py` — детерминированный deny-rule, см. ADR-019). +8. Для статуса PR используй нативный tool `pipeline-status` (НЕ bash `python3 .../pipeline-status.py` — детерминированный deny-rule, см. ADR-019). 9. НЕ используй `git -C ` — работай в текущем cwd (memory-syncer читает уже смерженный default branch). 10. НЕ делай `git checkout`/`git pull` — работаешь на уже смерженном default branch, переключаться не нужно. diff --git a/.opencode/agents/reviewer.md b/.opencode/agents/reviewer.md index 71bc6a1..702ad3b 100644 --- a/.opencode/agents/reviewer.md +++ b/.opencode/agents/reviewer.md @@ -1,5 +1,5 @@ --- -description: Global code reviewer. Reviews PRs against project skills and universal code standards. Invoke via @reviewer. Uses post_review tool to approve or request changes (deterministic heading format for pipeline-status.py). Does NOT merge — merge is done by main agent via run-pipeline. +description: Global code reviewer. Reviews PRs against project skills and universal code standards. Invoke via @reviewer. Uses post-review tool to approve or request changes (deterministic heading format for pipeline-status.py). Does NOT merge — merge is done by main agent via run-pipeline. mode: subagent temperature: 0.1 steps: 150 @@ -95,7 +95,7 @@ You are a global code reviewer. Your job: review PRs against project skills and 4. Check if the repo has project-specific skills: - Run `find skills/ -name "SKILL.md" -o -name "skill.md" 2>/dev/null` - If skills exist, load each via `skill("")` to get project-specific rules. -5. Check CI status: use `pipeline_status({pr_number: })` tool. +5. Check CI status: use `pipeline-status({pr_number: })` tool. If unavailable, use `gh run list --branch --limit 3`. Do NOT use `gh pr checks` (403) or bash `python3 .../pipeline-status.py` (denied). 6. Also check for `.opencode/agents/` project-level agents that may define conventions. @@ -103,7 +103,7 @@ You are a global code reviewer. Your job: review PRs against project skills and ## Investigation Budget You have a maximum of ~15 steps for investigation (Setup + checklist). -After that, you MUST call post_review — even if you haven't checked everything. +After that, you MUST call post-review — even if you haven't checked everything. An incomplete review with verdict NEEDS_DISCUSSION is better than an infinite investigation. Do NOT repeatedly verify references in agent .md files — read once, assess, move on. @@ -215,13 +215,13 @@ Examples of project-specific rules: ## Output Format -After reviewing, leave a GitHub PR comment using the `post_review` tool. The tool auto-generates the `## Code Review Summary` heading and the `### Verdict: ` line — you only pass the body content (between heading and verdict). Do NOT manually format the heading or verdict. +After reviewing, leave a GitHub PR comment using the `post-review` tool. The tool auto-generates the `## Code Review Summary` heading and the `### Verdict: ` line — you only pass the body content (between heading and verdict). Do NOT manually format the heading or verdict. ### If approving (no critical or blocking warnings): Run: ``` -post_review({ pr_number: , verdict: "APPROVE", body: `` }) +post-review({ pr_number: , verdict: "APPROVE", body: `` }) ``` Body format (without heading — tool adds `## Code Review Summary` and `### Verdict: APPROVE`): @@ -242,7 +242,7 @@ After this call, you MUST respond with your review text only. Do NOT call any mo Run: ``` -post_review({ pr_number: , verdict: "REQUEST_CHANGES", body: `` }) +post-review({ pr_number: , verdict: "REQUEST_CHANGES", body: `` }) ``` Body format (without heading — tool adds `## Code Review Summary` and `### Verdict: REQUEST_CHANGES`): @@ -269,7 +269,7 @@ After this call, you MUST respond with your review text only. Do NOT call any mo Run: ``` -post_review({ pr_number: , verdict: "NEEDS_DISCUSSION", body: `` }) +post-review({ pr_number: , verdict: "NEEDS_DISCUSSION", body: `` }) ``` Body format (without heading — tool adds `## Code Review Summary` and `### Verdict: NEEDS_DISCUSSION`): @@ -284,11 +284,11 @@ After this call, you MUST respond with your review text only. Do NOT call any mo ## Tool failure handling -If `post_review` returns a string starting with `⚠️ ...failed` (e.g. `⚠️ post-review failed for PR #N (exit 1): ...`): +If `post-review` returns a string starting with `⚠️ ...failed` (e.g. `⚠️ post-review failed for PR #N (exit 1): ...`): - **СООБЩИ оркестратору о сбое tool и STOP.** Не продолжай молча, не пытайся fallback на raw `gh pr comment` через bash. - Причина сбоя обычно: gh не аутентифицирован, PR не найден в текущем репо (cwd не git-репо или нет origin remote), или network error. -- Возвращай текст вида: `⚠️ post_review tool failed: <сообщение от tool>. Pipeline заблокирован на REVIEW phase — требуется вмешательство.` -- Любой дальнейший tool call после сбоя = protocol violation (как и после успешного `post_review`). +- Возвращай текст вида: `⚠️ post-review tool failed: <сообщение от tool>. Pipeline заблокирован на REVIEW phase — требуется вмешательство.` +- Любой дальнейший tool call после сбоя = protocol violation (как и после успешного `post-review`). ## Severity Levels @@ -306,9 +306,9 @@ If `post_review` returns a string starting with `⚠️ ...failed` (e.g. `⚠️ 4. ALWAYS provide file:line references in issues. 5. ALWAYS suggest a fix, not just describe the problem. 6. If unsure about something → NEEDS_DISCUSSION, don't guess. -7. After `post_review` (APPROVE, REQUEST_CHANGES, or NEEDS_DISCUSSION), STOP. +7. After `post-review` (APPROVE, REQUEST_CHANGES, or NEEDS_DISCUSSION), STOP. Respond with final text only. ANY further tool call is a protocol violation. Main agent merges via run-pipeline. -8. After `post_review` with REQUEST_CHANGES, STOP. Do not merge. +8. After `post-review` with REQUEST_CHANGES, STOP. Do not merge. 9. Для получения login автора PR используй `gh pr view --json author` (НЕ `gh api user` — broad API call, не в allow-list, вызывает doom-loop). 10. Для debug-вывода используй `pwd`/`ls`/`cat` — НЕ `echo` (не в allow-list). \ No newline at end of file diff --git a/.opencode/commands/run-pipeline.md b/.opencode/commands/run-pipeline.md index 602801f..6b62ed0 100644 --- a/.opencode/commands/run-pipeline.md +++ b/.opencode/commands/run-pipeline.md @@ -2,4 +2,4 @@ description: Run pipeline — autonomous 7-phase PR pipeline agent: build --- -Load the `run-pipeline` skill via `skill({name: "run-pipeline"})` and follow its ПРОТОКОЛ strictly. Each iteration: call `pipeline_status` tool, execute the `NEXT:` action it returns, repeat until COMPLETE or STOP. Полностью автономно — 1 строка прогресса после каждой фазы, STOP на AMBIGUOUS/error. \ No newline at end of file +Load the `run-pipeline` skill via `skill({name: "run-pipeline"})` and follow its ПРОТОКОЛ strictly. Each iteration: call `pipeline-status` tool, execute the `NEXT:` action it returns, repeat until COMPLETE or STOP. Полностью автономно — 1 строка прогресса после каждой фазы, STOP на AMBIGUOUS/error. \ No newline at end of file diff --git a/.opencode/commands/spec.md b/.opencode/commands/spec.md index 0f44002..24da4f0 100644 --- a/.opencode/commands/spec.md +++ b/.opencode/commands/spec.md @@ -2,4 +2,4 @@ description: Run spec — interactive spec generation for new project agent: build --- -Load the `spec` skill via `skill({name: "spec"})` and follow its ПРОТОКОЛ strictly. Главный агент — оркестратор: `spec_status` tool (read-only) + вопрос юзеру + task(general) делегирование. Не делает edit/memory_search/gh сам. Каждая фаза = 1 subagent. Стоп на issues — дальше юзер сам /run-pipeline. \ No newline at end of file +Load the `spec` skill via `skill({name: "spec"})` and follow its ПРОТОКОЛ strictly. Главный агент — оркестратор: `spec-status` tool (read-only) + вопрос юзеру + task(general) делегирование. Не делает edit/memory_search/gh сам. Каждая фаза = 1 subagent. Стоп на issues — дальше юзер сам /run-pipeline. \ No newline at end of file diff --git a/.opencode/skills/add-skill/SKILL.md b/.opencode/skills/add-skill/SKILL.md index 45c17eb..8c707c0 100644 --- a/.opencode/skills/add-skill/SKILL.md +++ b/.opencode/skills/add-skill/SKILL.md @@ -47,11 +47,13 @@ description: <когда загружать. Триггеры на русско ├── get-project-map/SKILL.md ├── issue/SKILL.md ├── memory/SKILL.md -├── run-pipeline/SKILL.md ├── python-development/SKILL.md +├── release/SKILL.md ├── repo-init/SKILL.md +├── run-pipeline/SKILL.md ├── run-tests/SKILL.md -└── spec/SKILL.md +├── spec/SKILL.md +└── tunnel/SKILL.md ``` ## 3. Скиллы авто-дискаверятся diff --git a/.opencode/skills/issue/SKILL.md b/.opencode/skills/issue/SKILL.md index 9475685..0ccb7f5 100644 --- a/.opencode/skills/issue/SKILL.md +++ b/.opencode/skills/issue/SKILL.md @@ -80,10 +80,10 @@ Issue создаёт **subagent** (general type), а не основной аг 1. Загрузи навык `issue` 2. Собери контекст — прочитай файлы из intent summary, пойми задачу, оцени объём (правило дробления ниже) 3. Составь self-contained body по шаблону (Контекст → Что сделать → Проверка → Acceptance criteria → Dependencies → Связанные ресурсы) -4. Запусти `create_issue({ title: "...", body: "...", labels: ["..."] })` tool (НЕ raw `gh issue create` — заблокирован deny; tool валидирует conventional title format и headings `## Контекст`/`## Задача`/`## Критерии приемки`) +4. Запусти `create-issue({ title: "...", body: "...", labels: ["..."] })` tool (НЕ raw `gh issue create` — заблокирован deny; tool валидирует conventional title format и headings `## Контекст`/`## Задача`/`## Критерии приемки`) 5. Верни URL созданного issue основному агенту -Main agent НЕ пишет body и НЕ запускает `create_issue` — всё через subagent. Это согласовано с `run-pipeline` skill (Phase 0: "через subagent с `issue` skill") и `AGENTS.md` (Dev Workflow, step 2: "delegate to `task` subagent"). +Main agent НЕ пишет body и НЕ запускает `create-issue` — всё через subagent. Это согласовано с `run-pipeline` skill (Phase 0: "через subagent с `issue` skill") и `AGENTS.md` (Dev Workflow, step 2: "delegate to `task` subagent"). ## Пример хорошего issue @@ -126,7 +126,7 @@ Zoom breathing падает при включённом geometry crop — crop Через tool (НЕ raw bash — `gh issue create *` заблокирован deny): ``` -create_issue({ title: "type(scope): description", body: "...", labels: ["