vtube/docs/BOT_WORKFLOW.md

Bot & goboss workflow — обов'язкові правила

Durable spec для всіх Claude-ботів (gocc1..4) і goboss-планувальника. Project-agnostic.

Головне правило: не патчимо "на око". Думай → план → роби. No hardcodes, no patches, SSOT-first, architectural over patches.

NO MAKE-WORK rule (CRITICAL)

НЕ давати ботам задачі з пустого в порожнє. Кожен dispatch має конкретну причину:

• ✅ developer запитав audit / refactor / fix
• ✅ HIGH severity finding з попереднього report потребує follow-up verify
• ✅ нова area не покрита попередніми звітами (concrete gap)
• ✅ regression/test після коміту з реальними змінами

Не валідні тригери (НЕ робити):

• ❌ "давай ще раз перевіримо" без нової причини
• ❌ "audit того ж самого через тиждень — раптом щось зміниться"
• ❌ make-work cross-audit / regression / research коли нічого не змінилось
• ❌ дублювання попереднього task'у з той ж scope

Якщо нема валідного тригера — task file = Чекай.. Не вигадуй роботу.

Recommendations cadence (для goboss)

На початку кожної session goboss перевіряє docs/RECOMMENDATIONS.md:

• Скільки items OPEN по severity
• Що додано з last session
• Згадай developer-у (1 рядок: 📋 RECOMMENDATIONS: N OPEN (X HIGH, Y MEDIUM, Z LOW). Найпріоритетніше: ...)
• НЕ виконуй items самостійно — чекай developer-go

---

Частина A — для goboss (planner)

A1. Планування перед dispatch

Перед task file для бота goboss МУСИТЬ:

1. Scope — one-liner: що зробити, які файли, який контракт.
2. Якщо multi-step (≥3 discrete steps) АБО architectural — Agent(subagent_type: Plan). Результат — concrete step-by-step з critical files і trade-offs.
3. Якщо brainstorming (невідомий підхід / 2+ competing options) — superpowers:brainstorming skill. Записати decision + reasoning у task.
4. SSOT check — чи є вже helper/module для цього? Використовуй існуюче.
5. Recent commits — git log --oneline -20 — щоб не дублювати.

A2. Architectural fixes, not patches

Якщо помилка зустрічається 2+ рази з того ж root cause → REDESIGN, не FIX по одному разу.

feedback_architectural_not_patches memory — якщо існує.

A3. Перевірка cherry-pick'ів

Після cherry-pick bot-зміни:

1. Smoke (pytest tests/test_<feature>.py -q)
2. Full regression (./run_tests.sh або pytest -q)
3. ≥3 commits разом без verify → gocc2 на drift-check audit
4. Push + verify health endpoint
5. Update docs/ROADMAP.md (якщо проект має) у тій самій сесії

A4. Code review після great IMPL

Після кожного MAJOR step (refactor, new SSOT module, multi-file migration):

1. Agent(superpowers:code-reviewer) на результат
2. Передати: commit hash, changed files, task spec link
3. Issue → fix inline АБО queue follow-up PR

---

Частина B — для ботів (executor)

B1. Before coding — planning phase

Перед першим code edit:

1. Прочитай task ПОВНІСТЮ.
2. Multi-step (≥3 кроків) АБО scope нечіткий → Agent(subagent_type: Plan) з task context. Plan = checklist.
3. Architectural decision → superpowers:brainstorming skill. ## Decision block у report.
4. Unclear → ЗАПИТАЙ goboss (через partial report з QUESTION: block). НЕ ВГАДУЙ.

B2. No hardcodes — SSOT first

Перед кожним новим літералом (path, model name, URL, retry count, language code):

1. grep -rn "<literal>" config/ lib/
2. Існує → IMPORT
3. Немає → додай у config/<domain>.py як module-level const, потім import

Never:

• API_KEYS = ['xxx'] у коді (use env)
• DATA_DIR = '/var/lib/...' у коді (use config)
• MAX_RETRIES = 3 у двох файлах (extract до config.retry)

B3. No patches — architectural fixes

Bug знайдено:

1. Root cause (не симптом)
2. Локальний → fix inline + regression test
3. ≥2 місцях АБО ≥2 commits → architectural refactor (SSOT, validator, dedup). НЕ копіюй fix у N місць.

B4. Test coverage

Кожна нова public function / class / module:

• 1 smoke (happy path)
• 1 edge (empty/invalid/failure)
• 1 integration якщо side effects (DB, HTTP, FS)

Test name: tests/test_<module>_<feature>.py. Новий endpoint = новий test.

B5. Pre-push code review

Після commit, ДО report:

1. Re-read diff (git diff HEAD~1)
2. Constraint check проти task spec
3. Large refactor (≥200 LOC АБО ≥5 files): Agent(superpowers:code-reviewer) з task spec, diff, own trade-offs.
4. Code-reviewer feedback → fix inline АБО record у report BUGLOG як deferred.

B6. Report structure

Кожен report МУСИТЬ мати у цьому порядку:

1. Status (READY / BLOCKED / FAILED)
2. Deliverable (branch, base commit, commit hash, files, LOC delta, tests added)
3. Scope summary (3-5 bullets)
4. Decision notes (якщо archi — варіант + чому)
5. Test coverage (per-module)
6. Full regression (pytest tail)
7. Hardcode self-check (grep — 0 hits)
8. BUGLOG (touched OR deferred)
9. Deviation (де відхилився від spec + чому)
10. Signal (filename for auto-hook trigger)

---

Частина C — task file template

# Task: <one-line scope>

**Assignee:** gocc<N> (<READ-ONLY AUDIT | IMPL | DECISION>)
**Origin:** <link to prior report / TODO / audit finding>
**Base:** `origin/main` @ `<commit-sha>`

## Workflow requirements (per docs/BOT_WORKFLOW.md)

- **Before coding:** `Plan` agent якщо multi-step; `brainstorming` skill якщо archi
- **SSOT check:** grep existing constants; import not copy
- **After major step:** `Agent(superpowers:code-reviewer)` на commit+diff
- **No patches:** recurring bug = root cause refactor
- **Report:** 10 sections per §B6

<!-- task spec -->

---

Частина D — enforcement + exceptions

D1. Enforcement

• Report без required sections (§B6) → goboss повертає MISSING: <sections>
• Bot patch замість architectural → goboss queue додатковий PR на refactor
• Bot пропустив SSOT, hardcode landed → goboss inline-fix + memory update

D2. Exceptions (без планів)

Не потрібно planning overhead для:

• Trivial 1-file fix (typo, rename, const update)
• READ-ONLY audit (план = task spec sections)
• Doc-only update
• Emergency rollback (git revert — явно)

Bot вважає task — exception → ЗАПИШИ у report ## Planning skipped з reasoning. goboss review.

D3. Rollback on violation

Architectural violation post-merge (hardcode landed, patch замість refactor):

1. git revert <commit> (not --force, not amend)
2. Dispatch новий PR з proper fix
3. Update feedback_<violation>.md memory

---

Частина E — operational procedures (goboss → bot dispatch)

E1. Порядок dispatch

1. Запиши task у ~/comms/gocc{N}-task.md з унікальним Task ID.
2. Тригер: ~/bin/trigger-bots gocc{N} (або ~/bin/trigger-bots для всіх).

trigger-bots робить: clear stale reports → git pull → signal через ~/scripts/trigger_bot.sh (flock-serialized, paste-buffer + dual-Enter + verify).

E2. Якщо бот не реагує

• ❯ prompt — Claude процес мертвий
• НЕ Ctrl-C (вбиває Claude)
• Use ~/bin/restart-bots gocc{N} — kill-session → start-devs → wait 20s → trigger одним скриптом

E3. Тригер ботів (нова задача)

~/bin/trigger-bots             # всі gocc1-4
~/bin/trigger-bots gocc2       # один
~/bin/trigger-bots gocc1 gocc3 # subset

E4. Повний перезапуск

~/bin/restart-bots             # всі: kill+start+wait+trigger
~/bin/restart-bots gocc4       # один

⛔ НІКОЛИ ручний tmux kill-session — використовуй restart-bots.

E5. Task ID правила

• Кожна нова task = новий унікальний Task ID
• Формат: [goboss YYYY-MM-DD] Task ID: НАЗВА-ЗАДАЧІ
• Бот порівнює task Task ID vs report Task ID — якщо однакові → "Чекаю.", різні → виконує
• При restart — clear report files перед trigger (restart-bots робить автоматично)

E6. Context clear policy

~/bin/clear-bots (per-bot subset) — використовуй коли:

• Новий епох незалежний від попереднього (different feature/area)
• Контекст ≥30% з 1M (бот сам пише ⚠️ CONTEXT HEAVY у report)
• Послідовний follow-up на ту саму задачу — НЕ кліри

E7. Communication scripts (КАНОНІЧНІ)

• ~/scripts/send_to_goboss.sh "<msg>" — bot → goboss (flock, idle-wait, verify)
• ~/scripts/trigger_bot.sh <session> "<msg>" — goboss → bot (flock, idle-wait, verify)
• НІКОЛИ raw tmux send-keys для quoted text — guard блокує

---

Reference memories: feedback_bot_verification, feedback_pre_push_subagent, feedback_signal_flood_mutex, feedback_simple_no_details, reference_bot_comms.