From 6bec709ec27e1dad9ace224e53a93f349ae920f5 Mon Sep 17 00:00:00 2001 From: Sergey <93754860+slaid098@users.noreply.github.com> Date: Fri, 31 Jul 2026 23:36:04 +0300 Subject: [PATCH] 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 --- AGENTS.md | 20 +++++++++++-- ...83-pr-189-strengthen-orchestrator-model.md | 24 +++++++++++++++ .../pr-189-strengthen-orchestrator-model.md | 29 +++++++++++++++++++ docs/project-map/README.md | 2 +- 4 files changed, 72 insertions(+), 3 deletions(-) create mode 100644 docs/decisions/083-pr-189-strengthen-orchestrator-model.md create mode 100644 docs/handoff/pr-189-strengthen-orchestrator-model.md diff --git a/AGENTS.md b/AGENTS.md index 2a81701..db7a523 100644 --- a/AGENTS.md +++ b/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. diff --git a/docs/decisions/083-pr-189-strengthen-orchestrator-model.md b/docs/decisions/083-pr-189-strengthen-orchestrator-model.md new file mode 100644 index 0000000..33a6966 --- /dev/null +++ b/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`), иначе оркестратор снова начнёт читать всё сам. \ No newline at end of file diff --git a/docs/handoff/pr-189-strengthen-orchestrator-model.md b/docs/handoff/pr-189-strengthen-orchestrator-model.md new file mode 100644 index 0000000..a26ac86 --- /dev/null +++ b/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`). \ No newline at end of file diff --git a/docs/project-map/README.md b/docs/project-map/README.md index dba8385..aac02f8 100644 --- a/docs/project-map/README.md +++ b/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 ```