diff --git a/.opencode/skills/configure-opencode/SKILL.md b/.opencode/skills/configure-opencode/SKILL.md index f4d7bb2..16321dd 100644 --- a/.opencode/skills/configure-opencode/SKILL.md +++ b/.opencode/skills/configure-opencode/SKILL.md @@ -16,6 +16,30 @@ description: Use when adding, changing, or removing MCP servers, providers, perm - **Исключение:** явный override-сценарий (project-local конфиг нужен для изоляции в конкретном проекте) — тогда указать явно в комментарии к изменению. - **Docker (опционально):** для контейнерного запуска можно bind-mount `.opencode/` → `~/.config/opencode/` (см. `docker-compose.yml`) — но это optional path, не канон. Репо обязан работать и bare-`opencode` в клона. +## 1.1. Scope правила «куда писать» (не только `opencode.json`) + +Каноническое правило «всегда workspace clone `slaid098/opencode-config`, никогда `~/.config/opencode/`» распространяется **на все артефакты конфига opencode**, а не только на `opencode.json`: + +- `.opencode/opencode.json` — конфиг (MCP, providers, permissions, …). +- `AGENTS.md` (корень репо) — глобальные правила/инструкции. +- `.opencode/skills//SKILL.md` — скиллы. +- `.opencode/agents/.md` — сабагенты. +- `.opencode/commands/.md` — слэш-команды. + +**Архитектура bind-mount (Docker-сетап):** + +- `~/.config/opencode/` внутри контейнера — это bind-mount из хост-сорса `/root/dockers/opencode-config/.opencode/` (НЕ `config/`). +- Глобальный `AGENTS.md` (`~/.config/opencode/AGENTS.md`) — отдельный ro-mount из корня репо. +- Любая правка файлов в `~/.config/opencode/` напрямую физически меняет файлы на хост-сорсе **в обход git**. Другой агент коммитит из workspace clone и пушит → на хосте `git pull` → конфликт (host-source уже имеет uncommitted изменения). + +**Правильно (sync процедура):** + +1. Правка в workspace clone `/root/workspace/opencode-config/` → `commit` + `git push`. +2. На хосте: `git pull` (обновляет `/root/dockers/opencode-config/.opencode/`). +3. `docker compose restart opencode` (MCP/skills/agents грузятся при старте контейнера — до рестарта правки не видны). + +**Запрещено:** редактировать `~/.config/opencode/` внутри контейнера напрямую (это bind-mount, ro `AGENTS.md`, bypass git → конфликты при `git pull` на хосте). + ## 2. Применение изменений - `commit` + `push` в репо `slaid098/opencode-config` (через `commit` tool). diff --git a/AGENTS.md b/AGENTS.md index 576548f..2a81701 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -43,6 +43,10 @@ Before starting a task in a repo: scan filenames in `docs/handoff/` (if any) — - No comments unless explicitly requested - Match surrounding code style (imports, naming, patterns) +## Config Edits + +All opencode config edits (`opencode.json`, `AGENTS.md`, `skills/`, `agents/`, `commands/`) go ONLY in workspace clone `/root/workspace/opencode-config/`, NEVER in `~/.config/opencode/` (bind-mount → edits bypass git → `git pull` conflicts on host). See skill `configure-opencode` for full sync procedure. + ## Tools Use tools instead of bash. On failure — STOP + report. Deny-list in `permission.bash` of `opencode.json`. diff --git a/docs/decisions/078-pr-181-agents-config-edits-rule.md b/docs/decisions/078-pr-181-agents-config-edits-rule.md new file mode 100644 index 0000000..86a663e --- /dev/null +++ b/docs/decisions/078-pr-181-agents-config-edits-rule.md @@ -0,0 +1,22 @@ +# ADR-078: Config Edits rule — workspace clone only, never ~/.config/opencode/ + +## Статус +Accepted (2026-07-31) + +## Контекст + +В Docker-сетапе opencode `~/.config/opencode/` — bind-mount из хост-сорса `/root/dockers/opencode-config/.opencode/`, а глобальный `AGENTS.md` — отдельный read-only mount из корня репо. Агенты, редактирующие файлы в `~/.config/opencode/` напрямую, физически меняют файлы на хост-сорсе в обход git. Потом другой агент коммитит из workspace clone `/root/workspace/opencode-config/` и пушит → на хосте `git pull` → конфликт, потому что хост-сорс уже имеет uncommitted изменения. + +Скилл `configure-opencode` фиксировал контракт «куда писать» только для `opencode.json` (в `.opencode/opencode.json` в workspace clone). Контракт НЕ покрывал `AGENTS.md`, `skills/`, `agents/`, `commands/` — и не было явного запрета редактировать `~/.config/opencode/` напрямую. Это приводило к рассинхрону и конфликтам `git pull`. + +## Решение + +1. В `AGENTS.md` (корень репо) добавлен блок `## Config Edits`: короткое правило — все правки конфига opencode (`opencode.json`, `AGENTS.md`, `skills/`, `agents/`, `commands/`) идут ТОЛЬКО в workspace clone `/root/workspace/opencode-config/`, НИКОГДА в `~/.config/opencode/` (bind-mount → bypass git → `git pull` конфликты на хосте). Ссылка на skill `configure-opencode` для полной sync-процедуры. Намеренно кратко (1 абзац) — дублирование со skill избегается. + +2. В `configure-opencode/SKILL.md` добавлен раздел `## 1.1. Scope правила «куда писать»`: расширяет scope правила с «только `opencode.json`» на все артефакты конфига (`AGENTS.md`, `skills/`, `agents/`, `commands/`). Содержит пояснение bind-mount архитектуры (rw `.opencode/` + ro `AGENTS.md`), описание почему правки в `~/.config/opencode/` bypass git, и каноническую sync-процедуру: правка в workspace clone → `commit` + `git push` → host `git pull` → `docker compose restart opencode`. + +## Альтернативы + +- **Расширить `AGENTS.md` блок до полной sync-процедуры** — отклонено: дублирование со skill `configure-opencode`, риск рассинхрона при правках. Краткое правило + ссылка на skill = единственный источник правды. +- **Запретить запись в `~/.config/opencode/` через `permission.bash` deny-правило** — отклонено: opencode permission контролирует bash-команды, а не file-write tools (`write`/`edit`); deny не покрыл бы основной вектор. Контракт в `AGENTS.md` + skill надёжнее для агентского поведения. +- **Сделать `~/.config/opencode/` полностью ro-mount** — отклонено: некоторые файлы (логи, кеш) пишутся opencode runtime; ro сломал бы их. Контракт на уровне инструкций агента выбран как достаточно. \ No newline at end of file diff --git a/docs/handoff/pr-181-agents-config-edits-rule.md b/docs/handoff/pr-181-agents-config-edits-rule.md new file mode 100644 index 0000000..126913a --- /dev/null +++ b/docs/handoff/pr-181-agents-config-edits-rule.md @@ -0,0 +1,31 @@ +--- +pr: +title: docs(config): add Config Edits rule to AGENTS.md, expand configure-opencode skill +--- + +## Что сделано + +Реализован issue #170 — зафиксировано каноническое правило «куда писать конфиг opencode» на двух уровнях и обновлена устаревшая память: + +1. **`AGENTS.md`** (корень репо): добавлен блок `## Config Edits` (после `## Code Style`) — 1 абзац. Правило: все правки конфига opencode (`opencode.json`, `AGENTS.md`, `skills/`, `agents/`, `commands/`) идут ТОЛЬКО в workspace clone `/root/workspace/opencode-config/`, НИКОГДА в `~/.config/opencode/` (bind-mount → bypass git → `git pull` конфликты на хосте). Ссылка на skill `configure-opencode` для полной sync-процедуры. + +2. **`.opencode/skills/configure-opencode/SKILL.md`**: добавлен раздел `## 1.1. Scope правила «куда писать»` (после канонического правила, до «Применение изменений»). Расширяет scope правила с «только `opencode.json`» на `AGENTS.md`, `skills/`, `agents/`, `commands/`. Содержит пояснение bind-mount архитектуры (`~/.config/opencode/` = bind-mount из `/root/dockers/opencode-config/.opencode/`, global `AGENTS.md` = отдельный ro-mount из корня репо), описание почему правки в `~/.config/opencode/` bypass git и ломают `git pull` на хосте, и каноническую sync-процедуру (`git push` workspace → `git pull` host → `docker compose restart opencode`). + +3. **Память `technical/opencode-config-global-vs-local.md`** (`~/.local/share/opencode/opencode-memory/`): обновлена устаревшая информация — репо `opencode`→`opencode-config`, layout `config/`→`.opencode/`, 14→17 skills, `.opencode/` git-tracked (105 файлов, не «empty/not git-tracked»), global `AGENTS.md` = ro-mount (отдельный bind-mount из корня репо), bind-mount source `/root/dockers/opencode-config/.opencode` (не `config`). Будет закоммичена и реиндексирована через `memory-save` после PR. + +4. **Handoff + ADR**: созданы через `.opencode/scripts/scaffold-handoff.sh` (ADR-078, без коллизии нумерации). + +## Почему + +В контейнере `~/.config/opencode/` — bind-mount из хост-сорса. Глобальный `AGENTS.md` смонтирован read-only. Агенты редактирующие `~/.config/opencode/` напрямую меняют файлы на хосте в обход git → другой агент коммитит из workspace clone, пушит → на хосте `git pull` → конфликт. Skill `configure-opencode` фиксировал контракт только для `opencode.json`; `AGENTS.md`/`skills/`/`agents/`/`commands/` не покрывались, и явного запрета редактировать `~/.config/opencode/` не было. Память описывала старый layout (`config/`, репо `opencode`, 14 skills) и вводила новых агентов в заблуждение. + +## Pending + +- `memory-save` для коммита и реиндекса обновлённой памяти `opencode-config-global-vs-local.md` (выполнить после merge PR или по указанию). +- Подставить реальный PR-номер в handoff/ADR frontmatter (отдельный коммит после `create-pr`). + +## Watch out + +- **Спека issue #170 содержала неточные числа**: указано «18 skills» и «88 файлов», по факту 17 skills и 105 git-tracked файлов в `.opencode/`. Использованы актуальные числа из `ls`/`git ls-files`, а не числа из спеки. +- **ADR numbering collision (issue #176)**: `scaffold-handoff.sh` считает номер ADR как `ls | wc -l + 1`. В этом PR коллизии НЕ возникло (получил 078, max существующий = 077), но баг скрипта не фиксировал — вне scope. Issue #176 остаётся открытым. +- В `AGENTS.md` блока `## Config Edits` намеренно краткий (1 абзац) — полная процедура в skill `configure-opencode`, дублирование избегается. \ No newline at end of file