feat: orchestrator AGENTS.md + docker bind-mount (#31)

* feat: add root AGENTS.md with orchestrator directive * feat(docker): add AGENTS.md bind-mount for global config * docs(handoff): add pr-10 handoff + ADR-011 * docs(handoff): rename pr-10 to pr-31 in filenames * docs(project-map): add root AGENTS.md entry (PR#31) --------- Co-authored-by: opencode-agent <agent@slaid098.dev>
2026-07-24 01:08:56 +03:00 · 2026-07-24 01:08:56 +03:00 · 109fff628f
commit 109fff628f
parent 6911a251d3
5 changed files with 110 additions and 0 deletions
--- a/AGENTS.md
+++ b/AGENTS.md
@ -0,0 +1,71 @@
+# Global Rules
+
+## Orchestrator Model (главное)
+
+- Главный чат = ТОЛЬКО план. Все исследования, команды, edits, реализации — ТОЛЬКО через subagents.
+- Никогда не делать самому: research файловой системы, grep/glob, bash-команды, file edits, тесты, git ops.
+- Максимум: верхнеуровневый план + отчёты пользователю + делегирование `task` subagent'ам.
+- Pipeline: каждую фазу (ISSUE → IMPLEMENT → DOCS → CI → REVIEW → MERGE → MEMORY) делегировать subagent'у.
+- Subagent error → 1 retry, потом STOP + report.
+
+## Commits
+
+- Language: English only — type, scope, and description all in English
+- Format: `type(scope): description` — ≤72 chars
+- Types: `feat`, `fix`, `chore`, `docs`, `refactor`, `test`, `style`, `perf`
+- Before ANY commit: load `commit` skill (`skill("commit")`), run `git log --oneline -20`, match existing style
+- Break large changes into multiple short commits by logical parts
+- No period at end, no body unless necessary
+
+## Pull Requests
+
+- Title: на английском, формат `type(scope): what changed` — same principle as commits
+- Body: на русском, в Markdown — сначала **что** сделано, затем **почему** (мотивация, контекст)
+- Reference issues if applicable
+- Before creating PR: load `commit` skill, inspect `git diff` from base branch
+
+## Development Workflow
+
+All PR work runs through `/run-pipeline` (7 phases: ISSUE → IMPLEMENT → DOCS → CI → REVIEW → MERGE → MEMORY). Load the `run-pipeline` skill for the protocol.
+
+1. **Plan** — discuss requirements in chat, understand scope
+2. **Issue** — create self-contained GitHub issue (full context, file list, exact content, acceptance criteria, dependencies). Load `issue` skill. Via subagent.
+3. **Subagent** — delegate to `task` subagent (general type):
+   - Reads issue via `gh issue view N`
+   - Branches off default branch, implements per spec, commits, pushes, creates PR with `Closes #N`
+   - Creates handoff `docs/handoff/pr-<N>-<slug>.md` and ADR if architectural decision
+   - Follows issue spec exactly — if spec has errors, report them, don't deviate
+4. **Review** — run docs-reviewer (`@docs-reviewer`, pre-merge) then reviewer (`@reviewer`):
+   - docs-reviewer: updates project map + validates/fixes handoff + ADR, commits to PR branch
+   - reviewer: posts `## Code Review Summary` comment with verdict APPROVE|REQUEST_CHANGES (does NOT merge)
+5. **Merge or Repeat**:
+   - APPROVE → `merge_pr` tool (orchestrator-safe, via `run-pipeline` skill, after CI ✅)
+   - Issues found → fix subagent (same branch, new commit) → re-loop → merge
+   - REQUEST_CHANGES → fix subagent → re-review → merge
+6. **Memory-sync** — run memory-syncer (`@memory-syncer`):
+   - Distills gotchas + ADR pointers from merged handoff into `app_data/opencode-memory/repos/{host}/{org}/{repo}.md`
+   - Format: `- [YYYY-MM-DD, PR#N] <summary>`, receipt always (even if empty)
+   - Calls `memory_save`, then guards against accidental commits to main repo
+
+## Pipeline
+
+Основной pipeline для любой задачи — `/run-pipeline` в UI opencode. Skill выполняет 7 фаз (ISSUE → IMPLEMENT → DOCS → CI → REVIEW → MERGE → MEMORY) автономно, не импровизируя порядок. `merge_pr` tool — после CI ✅ (transitive guard в `pipeline-status.py`).
+
+- Tool `pipeline_status` — read-only oracle, возвращает статус + NEXT action.
+- Tool `merge_pr` — orchestrator-safe merge wrapper (replaces raw `gh pr merge`).
+- Execution — через `/run-pipeline` (command `.opencode/commands/run-pipeline.md`).
+
+## Read Path
+
+Перед началом задачи в репо: просмотри имена файлов в `docs/handoff/` (если есть) — открой релевантные по теме.
+
+## Code Style
+
+- Follow existing conventions in the repo
+- Load `code-standards` skill for detailed rules
+- No comments unless explicitly requested
+- Match surrounding code style (imports, naming, patterns)
+
+## Language
+
+- Always respond to the user in Russian.
--- a/docker-compose.yml
+++ b/docker-compose.yml
@ -38,6 +38,7 @@ services:
      - GIT_COMMITTER_EMAIL=agent@opencode.local
    volumes:
      - ./.opencode:/root/.config/opencode
+      - ./AGENTS.md:/root/.config/opencode/AGENTS.md:ro
      - ./app_data:/root/.local/share/opencode
      - ./app_data/workspaces:/root/workspace
      - ./app_data/ssh:/root/.ssh:ro
--- a/docs/decisions/011-pr-31-orchestrator-agents-md.md
+++ b/docs/decisions/011-pr-31-orchestrator-agents-md.md
@ -0,0 +1,17 @@
+# ADR-011: Orchestrator AGENTS.md (root, bind-mount global)
+
+## Статус
+Accepted
+
+## Контекст
+Main agent должен быть pure orchestrator (chat = plan only, all via subagents). AGENTS.md должен быть global (all projects in container) + committed (source of truth).
+
+## Решение
+- AGENTS.md in root repo (committed, auto-loaded for project)
+- Docker bind-mount ./AGENTS.md:/root/.config/opencode/AGENTS.md:ro (global for container)
+- Orchestrator directive: all research/implementation via subagents, chat = plan only
+- References /run-pipeline (#14) and merge_pr tool (#16)
+
+## Альтернативы
+- .opencode/AGENTS.md (project-local only) — отклонено (not global)
+- config/AGENTS.md + bind-mount (old pattern) — отклонено (config/ → .opencode/ migration, ADR-002)
--- a/docs/handoff/pr-31-orchestrator-agents-md.md
+++ b/docs/handoff/pr-31-orchestrator-agents-md.md
@ -0,0 +1,18 @@
+# PR: Orchestrator AGENTS.md + docker bind-mount
+
+## Что сделано
+- Created root AGENTS.md with orchestrator directive (chat = plan only, all via subagents)
+- Added docker bind-mount: ./AGENTS.md:/root/.config/opencode/AGENTS.md:ro
+- AGENTS.md references /run-pipeline (renamed in #14) and merge_pr tool (created in #16)
+- Preserved existing rules: commits, PRs, code style, language (Russian), read path
+
+## Почему
+Main agent = pure orchestrator. AGENTS.md in root (committed, auto-loaded for project) + bind-mount makes it global for all projects in container.
+
+## Pending
+- Нет (завершающий PR для AGENTS.md)
+
+## Watch out
+- AGENTS.md in root = auto-loaded for opencode-config project itself
+- bind-mount :ro = read-only in container (source of truth = root file)
+- merge_pr tool reference (not raw gh pr merge) — aligns with ADR-010
--- a/docs/project-map/README.md
+++ b/docs/project-map/README.md
@ -2,6 +2,8 @@

 opencode-config — Docker-based AI coding assistant with persistent memory (opencode configuration). Runs in Docker via `docker-compose.yml` (dind + opencode services).

+Root `AGENTS.md` — orchestrator directive (chat = plan only, all via subagents) + global rules (commits, PRs, code style, language RU). Auto-loaded for project + bind-mounted globally in container — PR#31.
+
 ## Structure

 ```
@ -91,6 +93,7 @@ opencode-config/
 ├── .editorconfig
 ├── .gitignore
 ├── .python-version
+├── AGENTS.md                       # Orchestrator directive + global rules (bind-mounted globally) — PR#31
 ├── LICENSE
 └── README.md
 ```