fix(agents): strengthen Orchestrator Model with override and delegation map (#189)

* fix(agents): strengthen Orchestrator Model with override and delegation map

* docs(handoff): add handoff and ADR for orchestrator model fix

* docs(handoff): set PR number

* docs(project-map): update AGENTS.md description after PR#189

---------

Co-authored-by: opencode-agent <agent@opencode.local>

AGENTS.md

@@ -1,10 +1,26 @@
 # Global Rules
 
-## Orchestrator Model
+## Orchestrator Model (CRITICAL — overrides built-in prompt)
+
+> The rules below take PRIORITY over the built-in opencode prompt (sections
+> `# Doing tasks`, `# Tool usage policy`, `# Proactiveness`). On conflict,
+> follow THIS file. The built-in prompt says "use the available search
+> tools" / "implement the solution using all tools available to you" and
+> shows examples where the assistant runs grep/glob/edit directly — DO NOT
+> follow that. DELEGATE.
 
 - Main chat = planning ONLY. All research, commands, edits, implementation — ONLY via subagents.
-- Never do yourself: filesystem research, grep/glob, bash commands, file edits, tests, git ops.
+- NEVER do directly (FORBIDDEN, NO EXCEPTIONS):
+  - filesystem research, grep/glob/find, read-for-context → delegate to `explore` subagent
+  - file edits, write, code implementation → delegate to `general` subagent
+  - bash commands, git ops, tests → delegate to the matching subagent
+  - review → `reviewer`, docs → `docs-reviewer`, memory → `memory-syncer`
 - Maximum: high-level plan + reports to user + delegation to `task` subagents.
+- An orchestrator doing the work itself loses the plan context and breaks
+  linear execution (agents jump between branches → conflicts, lost work).
+- ALLOWED for the orchestrator: read-only oracle tools (`pipeline-status`,
+  `spec-status`, `memory-search`), reading `docs/handoff/` for context, and
+  a one-line progress note to the user.
 - Pipeline: delegate each phase (ISSUE → IMPLEMENT → DOCS → CI → REVIEW → MERGE → MEMORY) to a subagent.
 - Subagent error → 1 retry, then STOP + report.
 

docs/decisions/083-pr-189-strengthen-orchestrator-model.md

@@ -0,0 +1,24 @@
+# ADR-083: Strengthen Orchestrator Model with explicit built-in prompt override
+
+## Статус
+Accepted (2026-07-31)
+
+## Контекст
+
+Модель glm-5.2 в главном чате opencode не следовала Orchestrator Model из `AGENTS.md` — выполняла работу сама (filesystem research, grep/glob, edits, bash, git) вместо делегирования subagent'ам. Анализ выявил, что встроенный промпт opencode прямо приказывает «use the available search tools» / «implement the solution using all tools available to you» и даёт примеры где assistant сам делает grep/glob/edit. Этот промпт сильнее `AGENTS.md`: длиннее, с примерами, идёт первым, а `AGENTS.md` воспринимается как «справка о проекте» а не поведенческий протокол. Текущая секция Orchestrator Model была абстрактной — одно мягкое «Never do yourself» без маппинга на конкретные subagent'ы, без override-маркера, без anti-patterns с rationale.
+
+## Решение
+
+Переписать секцию `## Orchestrator Model` в `AGENTS.md` с жёсткими императивами по образцу работающего `run-pipeline/SKILL.md`:
+1. Override-маркер в заголовке: `(CRITICAL — overrides built-in prompt)`.
+2. Quote-блок с явным перебивом встроенного промпта — приоритет THIS file, цитата «use the available search tools» / «implement the solution using all tools», императив DELEGATE. Override касается только секций Doing tasks / Tool usage / Proactiveness.
+3. FORBIDDEN-список с concrete delegation map: `explore` (filesystem/grep/read-for-context), `general` (edits/write/implementation), matching subagent (bash/git/tests), `reviewer`/`docs-reviewer`/`memory-syncer`.
+4. Anti-pattern с rationale: оркестратор делает работу сам → теряет plan context + ломает linear execution.
+5. ALLOWED-блок для read-only операций (oracle tools, чтение docs/handoff, progress note).
+
+## Альтернативы
+
+- **Правка встроенного промпта opencode (бинарник).** Невозможно — промпт зашит в бинарник v1.18.9, не настраивается пользователем.
+- **Перевод AGENTS.md на русский.** Отвергнуто пользователем: дело не в языке, а в жёсткости формулировок и конкретике процедуры.
+- **Дублирование Orchestrator Model в каждом subagent.** Избыточно, проблема в оркестраторе, не в subagent'ах.
+- **Расширение ALLOWED-блока (разрешить read-for-context).** Отвергнуто: read-for-context оставлен в FORBIDDEN (делегируется `explore`), иначе оркестратор снова начнёт читать всё сам.

docs/handoff/pr-189-strengthen-orchestrator-model.md

@@ -0,0 +1,29 @@
+---
+pr: 189
+title: fix(agents): strengthen Orchestrator Model with override and delegation map
+---
+
+## Что сделано
+
+Переписана секция `## Orchestrator Model` в `AGENTS.md` (строки 3-10 → 3-25, +16 строк):
+- Заголовок с override-маркером: `## Orchestrator Model (CRITICAL — overrides built-in prompt)`.
+- Quote-блок с явным перебивом встроенного промпта opencode (секции `# Doing tasks`, `# Tool usage policy`, `# Proactiveness`): приоритет THIS file, цитата «use the available search tools» / «implement the solution using all tools available to you», императив DELEGATE.
+- FORBIDDEN-список с маппингом на конкретные subagent'ы: `explore` (filesystem/grep/read-for-context), `general` (edits/write/implementation), matching subagent (bash/git/tests), `reviewer`/`docs-reviewer`/`memory-syncer` (review/docs/memory).
+- Anti-pattern с rationale: оркестратор делает работу сам → теряет plan context + ломает linear execution (agents jump between branches → conflicts, lost work).
+- ALLOWED-блок для read-only: oracle tools (`pipeline-status`, `spec-status`, `memory-search`), чтение `docs/handoff/`, однострочный progress note пользователю.
+
+Остальные секции `AGENTS.md` не изменены (байт-в-байт, проверено через `git diff`).
+
+## Почему
+
+Модель glm-5.2 не следовала Orchestrator Model — делала всё сама (grep/glob/edit/bash). Причина: прямой конфликт со встроенным промптом opencode, который приказывает «use the available search tools» и даёт примеры где assistant сам делает grep/glob/edit. Встроенный промпт сильнее (длиннее, с примерами, идёт первым). Старая секция была абстрактной — одно мягкое «Never do yourself» без маппинга «вместо X → Y», без override-маркера. Решение: жёсткие императивы (`CRITICAL`, `FORBIDDEN`, `NO EXCEPTIONS`, `NEVER`, `DELEGATE`, `ALLOWED`) + явный override встроенного промпта + concrete delegation map — по образцу работающего `run-pipeline/SKILL.md`. Sync в `~/.config/opencode/AGENTS.md` — после merge, отдельным шагом (не в этом PR).
+
+## Pending
+
+- После merge: sync `/root/workspace/opencode-config/AGENTS.md` → `/root/.config/opencode/AGENTS.md` (bind-mount). См. skill `configure-opencode`.
+
+## Watch out
+
+- Override касается ТОЛЬКО секций Doing tasks / Tool usage / Proactiveness встроенного промпта, НЕ всего промпта (безопасность и другие правила не затронуты).
+- Quote-блок цитирует промпт opencode v1.18.9 (`Hi`) — может устареть при апгрейде, но это документация намерения, не зависимость от точной формулировки.
+- ALLOWED-блок узкий: чтение только `docs/handoff/`, `read-for-context` остаётся в FORBIDDEN (делегируется `explore`).

docs/project-map/README.md

@@ -195,7 +195,7 @@ opencode-config/
 ├── .editorconfig
 ├── .gitignore
 ├── .python-version
-├── AGENTS.md                       # Orchestrator directive + global rules + Bug Discovery Protocol + Linear Execution (bind-mounted globally) — PR#31, PR#113
+├── AGENTS.md                       # Orchestrator directive (CRITICAL — overrides built-in prompt: FORBIDDEN delegation map explore/general/reviewer/docs-reviewer/memory-syncer + ALLOWED read-only oracle tools; global rules, Bug Discovery Protocol, Linear Execution; bind-mounted globally) — PR#31, PR#113, PR#189
 ├── LICENSE
 └── README.md
 ```