a9db23dfa4
- CLAUDE.md lean entry-point + index - BOT_WORKFLOW.md dispatch rules + no-make-work + recommendations cadence - SITES.md 14 ports inventory - SYNC_WORKFLOW.md 2 sync paradigms - MODULES.md module map + DEL_/test/obfuscated flags - REFACTOR_RULES.md REFACTOR vs CLEANUP vs BUG vs FEATURE - RECOMMENDATIONS.md initial backlog from gocc1+2+3+4 audits 2026-04-30 - docs/roles/ 4 bot roles
235 lines
10 KiB
Markdown
235 lines
10 KiB
Markdown
# 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
|
||
|
||
```markdown
|
||
# 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. Тригер ботів (нова задача)
|
||
|
||
```bash
|
||
~/bin/trigger-bots # всі gocc1-4
|
||
~/bin/trigger-bots gocc2 # один
|
||
~/bin/trigger-bots gocc1 gocc3 # subset
|
||
```
|
||
|
||
### E4. Повний перезапуск
|
||
|
||
```bash
|
||
~/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`.
|