diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..03b31f5 --- /dev/null +++ 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--.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] `, 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. \ No newline at end of file diff --git a/docker-compose.yml b/docker-compose.yml index 7dc2e57..fd3715a 100644 --- 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 diff --git a/docs/decisions/011-pr-31-orchestrator-agents-md.md b/docs/decisions/011-pr-31-orchestrator-agents-md.md new file mode 100644 index 0000000..60003f4 --- /dev/null +++ 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) \ No newline at end of file diff --git a/docs/handoff/pr-31-orchestrator-agents-md.md b/docs/handoff/pr-31-orchestrator-agents-md.md new file mode 100644 index 0000000..ed3b10d --- /dev/null +++ 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 \ No newline at end of file diff --git a/docs/project-map/README.md b/docs/project-map/README.md index e2af986..2eb5b09 100644 --- 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 ```