From 55a95140cd34d4ab3ff092c0ce38c984ee210053 Mon Sep 17 00:00:00 2001
From: Sergey <93754860+slaid098@users.noreply.github.com>
Date: Fri, 24 Jul 2026 00:31:19 +0300
Subject: [PATCH] refactor: issue + repo-init skills rewrite (#28)

* refactor(issue): full subagent delegation + acceptance criteria + dependencies

* refactor(repo-init): Phase A/B split + git init prerequisite + remove private refs

* docs(handoff): add pr-13 handoff + ADR-008

* docs(handoff): set PR number in filenames

---------

Co-authored-by: opencode-agent <agent@slaid098.dev>
---
 .opencode/skills/issue/SKILL.md               | 60 +++++++++++++++----
 .opencode/skills/repo-init/SKILL.md           | 34 ++++++++++-
 .../008-pr-28-issue-repo-init-rewrite.md      | 23 +++++++
 docs/handoff/pr-28-issue-repo-init-rewrite.md | 17 ++++++
 4 files changed, 119 insertions(+), 15 deletions(-)
 create mode 100644 docs/decisions/008-pr-28-issue-repo-init-rewrite.md
 create mode 100644 docs/handoff/pr-28-issue-repo-init-rewrite.md

diff --git a/.opencode/skills/issue/SKILL.md b/.opencode/skills/issue/SKILL.md
index f7ca7d2..fd3c688 100644
--- a/.opencode/skills/issue/SKILL.md
+++ b/.opencode/skills/issue/SKILL.md
@@ -38,6 +38,19 @@ Issue должно содержать всё необходимое, чтобы
 - `ruff check path/to/file.py` → All checks passed
 - `mypy path/to/file.py` → no issues
 
+## Acceptance criteria
+(явный чек-лист — что должно быть верно в результате, не команды проверки)
+- [ ] Эффект A работает в случае B
+- [ ] Файл C не содержит паттерн D
+- [ ] Тест E покрывает ветку F
+- [ ] Coverage ≥ 80% на изменённых файлах
+
+## Dependencies
+(связи с другими issue/PR — блокировки и порядок)
+- Blocked by #N (этот PR нельзя начать пока #N не смержен)
+- Do not merge until #N merges (этот PR готов, но ждёт #N)
+- Part of #N (подзадача родительского issue)
+
 ## Связанные ресурсы
 - Ref #33
 - [PR #34](https://github.com/...)
@@ -59,15 +72,18 @@ Issue должно содержать всё необходимое, чтобы
 
 ## Использование subagent для создания issue
 
-Когда получает задачу создать issue:
+Issue создаёт **subagent** (general type), а не основной агент. Это сохраняет контекст основного агента — длинный body issue не попадает в его историю.
 
+**Main agent** передаёт subagent'у только **intent summary** — короткое описание задачи (1-3 предложения: что и зачем). Subagent делает всё остальное.
+
+**Subagent (полная ответственность):**
 1. Загрузи навык `issue`
-2. Собери контекст (прочитай файлы, пойми задачу)
-3. **Запусти subagent** для выполнения `gh issue create` — передай ему готовый title и body
-4. Subagent создаёт issue и возвращает URL
-5. Сообщи URL пользователю
+2. Собери контекст — прочитай файлы из intent summary, пойми задачу, оцени объём (правило дробления ниже)
+3. Составь self-contained body по шаблону (Контекст → Что сделать → Проверка → Acceptance criteria → Dependencies → Связанные ресурсы)
+4. Запусти `gh issue create --title "..." --body "..."` (labels — см. guidance ниже)
+5. Верни URL созданного issue основному агенту
 
-Это нужно чтобы длинный body issue не засорял контекст основного агента.
+Main agent НЕ пишет body и НЕ запускает `gh issue create` — всё через subagent. Это согласовано с `pipeline-driver` skill (Phase 0: "через subagent с `issue` skill") и `AGENTS.md` (Dev Workflow, step 2: "delegate to `task` subagent").
 
 ## Пример хорошего issue
 
@@ -84,6 +100,14 @@ Zoom breathing падает при включённом geometry crop — crop 
 - `pytest tests/test_effects.py -x -q --no-cov` → all passed
 - `pytest tests/test_new_effects_real.py::test_geometry_crop_with_zoom_breathing_real` → passed
 
+## Acceptance criteria
+- [ ] Geometry crop использует `iw`/`ih`, не `probe.width`/`probe.height`
+- [ ] Zoom breathing не падает при включённом geometry crop
+- [ ] Регрессионный тест покрывает комбинацию zoom breathing + geometry crop
+
+## Dependencies
+- Closes #33
+
 ## Связанные ресурсы
 - Closes #33
 ```
@@ -103,19 +127,31 @@ Zoom breathing падает при включённом geometry crop — crop 
 gh issue create \
   --title "type(scope): description" \
   --body "..." \
-  --label "enhancement"
+  --label "<label>"
 ```
 
+Label выбирай по типу задачи (совпадает с commit `type`):
+- `enhancement` — новая функциональность (`feat`)
+- `bug` — исправление (`fix`)
+- `refactor` — рефакторинг без изменения поведения (`refactor`)
+- `documentation` — доки (`docs`)
+- `chore` — обслуживание, зависимости, конфиг (`chore`)
+- `performance` — производительность (`perf`)
+
+Если label не существует в репо — `gh issue create` упадёт. Создай через `gh label create <name> --color <hex>` (один раз) или опусти `--label`.
+
 ## Пути навыков
 
-Навыки создаются в `.opencode/skills/` в репозитории opencode. НЕ в `~/.config/opencode/skills/` — это маунт из репо. После изменения навыка нужен `git pull` на хосте + рестарт opencode.
+Навыки создаются в `.opencode/skills/` в репозитории opencode-config. НЕ в `~/.config/opencode/skills/` — это маунт из репо. После изменения навыка нужен `git pull` на хосте + рестарт opencode.
 
 ## Полный workflow
 
-После создания issue, цикл продолжается:
+После создания issue, цикл продолжается (см. `pipeline-driver` skill для деталей PR процесса):
 
 1. **Subagent** — `task(general)` читает issue, реализует, коммитит, push, создаёт PR. Оркестрация — через `pipeline-driver` skill.
-2. **Review** — `@reviewer` subagent ревьюит PR (diff, skills, standards), постит комментарий
-3. **Merge or Repeat** — APPROVE → squash merge; замечания → fix subagent → re-review → merge
+2. **Docs review** — `@docs-reviewer` subagent валидирует handoff + ADR, обновляет project map (pre-merge).
+3. **Code review** — `@reviewer` subagent ревьюит PR (diff, skills, standards), постит `## Code Review Summary` комментарий.
+4. **Merge or Repeat** — APPROVE → `gh pr merge N --squash --delete-branch` (после CI ✅); замечания → fix subagent → re-review → merge.
+5. **Memory-sync** — `@memory-syncer` дистиллирует handoff + ADR в `app_data/opencode-memory/repos/{host}/{org}/{repo}.md`.
 
-См. `pipeline-driver` skill для деталей PR процесса.
\ No newline at end of file
+См. `AGENTS.md` (Development Workflow) и `pipeline-driver` skill — все три документа описывают одну и ту же full-subagent модель делегирования.
\ No newline at end of file
diff --git a/.opencode/skills/repo-init/SKILL.md b/.opencode/skills/repo-init/SKILL.md
index bffb3b4..74a8162 100644
--- a/.opencode/skills/repo-init/SKILL.md
+++ b/.opencode/skills/repo-init/SKILL.md
@@ -1,11 +1,16 @@
 ---
 name: repo-init
-description: Use when creating a new repository or initializing repo settings. Covers GitHub repo creation, branch protection, squash merge, pre-commit hooks, linters (ruff/mypy/xenon for Python, Biome/Knip/Vitest for JS/TS), CI/CD, Dependabot, LICENSE, .gitignore. Also when user says "новый репо", "создай репозиторий", "настрой репо".
+description: Sequential checklist: create GitHub remote → configure settings/branch protection → scaffold project files (Python/JS). Use when starting a new repo. Also when user says "новый репо", "создай репозиторий", "настрой репо".
 ---
 
 # Repo Init
 
-Полный чек-лист инициализации нового репозитория. Все шаблоны — внутри, берутся из эталонных репо (video_uniq, yt-video-downloader, opencode-voice-dictation, slaid098-dev).
+Полный чек-лист инициализации нового репозитория. Все шаблоны — внутри, берутся из эталонных репозиториев (reference repos).
+
+## Фазы
+
+- **Phase A — GitHub remote** (шаги 1-3, выполняется один раз): создание репо, настройки merge, защита ветки. Требует локального git-репо с initial commit.
+- **Phase B — Project scaffolding** (шаги 4-9, по шаблонам): Python/JS файлы, Dependabot, LICENSE, .editorconfig, pre-commit, верификация. Можно повторно использовать для существующего репо (skip Phase A).
 
 ## Содержание
 
@@ -21,6 +26,25 @@ description: Use when creating a new repository or initializing repo settings. C
 
 ---
 
+## Phase A — GitHub remote
+
+> Шаги 1-3 выполняются один раз для нового репо. Требуют локального git-репо с initial commit.
+
+## 0. Prerequisite: git init + initial commit
+
+Перед `gh repo create --source=.` локальный каталог должен быть git-репо с хотя бы одним коммитом (`--source=.` пушит текущую ветку; без коммита — пустой репо).
+
+```bash
+git init
+echo "# <repo-name>" > README.md
+git add README.md
+git commit -m "chore: initial commit"
+```
+
+Если bare-repo без initial commit — `gh repo create --source=.` создаст remote, но push будет пустым, а main branch не появится → branch protection упадёт.
+
+---
+
 ## 1. Создание репозитория
 
 ```bash
@@ -43,7 +67,7 @@ gh auth setup-git
 
 ## 2. Настройки репозитория
 
-Squash-only merge, auto-delete branch после merge. Эталон — video_uniq:
+Squash-only merge, auto-delete branch после merge:
 
 ```bash
 gh api repos/<owner>/<repo-name> \
@@ -109,6 +133,10 @@ EOF
 
 ---
 
+## Phase B — Project scaffolding
+
+> Шаги 4-9 — шаблоны файлов для Python или JS/TS проекта. Можно применять к существующему репо (skip Phase A). Не зависят от GitHub remote.
+
 ## 4. Python-проект
 
 ### Инструменты
diff --git a/docs/decisions/008-pr-28-issue-repo-init-rewrite.md b/docs/decisions/008-pr-28-issue-repo-init-rewrite.md
new file mode 100644
index 0000000..9d5a0af
--- /dev/null
+++ b/docs/decisions/008-pr-28-issue-repo-init-rewrite.md
@@ -0,0 +1,23 @@
+# ADR-008: issue + repo-init skills rewrite
+
+## Статус
+Accepted
+
+## Контекст
+`issue` skill имел 3-way contradiction на delegation model: `issue/SKILL.md` описывал "main agent writes body, subagent runs `gh issue create`" (split responsibility), `pipeline-driver/SKILL.md` Phase 0 говорил "через subagent с `issue` skill" (full subagent), `AGENTS.md` Development Workflow step 2 говорил "delegate to `task` subagent" (subagent, но без уточнения что пишет body). Три документа описывали разные модели → агент не понимал кто пишет body.
+
+`repo-init` skill: ambiguous "or" в description ("creating a new repository or initializing repo settings" — два разных интента в одной фразе), missing `git init` prerequisite перед `gh repo create --source=.` (bare-repo без initial commit → empty push → main branch не появляется → branch protection падает), private-repo references (video_uniq, yt-video-downloader, opencode-voice-dictation, slaid098-dev) не релевантны публичному шаблону.
+
+## Решение
+- **issue skill — full subagent delegation:** main agent передаёт только intent summary (1-3 предложения), subagent грузит `issue` skill, читает файлы, пишет self-contained body, запускает `gh issue create`. Main agent НЕ пишет body и НЕ запускает gh. Согласовано с `pipeline-driver` Phase 0 и `AGENTS.md` Dev Workflow.
+- **issue skill — template sections:** добавлены `## Acceptance criteria` (явный чек-лист результата, не команды проверки) и `## Dependencies` (Blocked by #N / Do not merge until #N / Part of #N). В шаблон и в пример хорошего issue.
+- **issue skill — stale workflow:** "Полный workflow" расширен с 3 до 5 шагов (добавлены docs-reviewer и memory-syncer). "репозитории opencode" → "репозитории opencode-config". `--label "enhancement"` → guidance по выбору label по commit `type`.
+- **repo-init skill — description rewrite:** "Sequential checklist: create GitHub remote → configure settings/branch protection → scaffold project files (Python/JS). Use when starting a new repo." — без ambiguous "or".
+- **repo-init skill — Phase A/B split:** Phase A (GitHub remote, steps 1-3, run once), Phase B (project scaffolding, steps 4-9, reusable). Позволяет jump к Phase B для существующего репо.
+- **repo-init skill — git init prerequisite:** добавлен Step 0 (`git init` + initial commit) перед `gh repo create --source=.`.
+- **repo-init skill — remove private refs:** private-repo names → generic "reference repos", "Эталон — video_uniq" removed.
+
+## Альтернативы
+- **Drop issue skill (use raw `gh`)** — отклонено: template (Контекст → Что сделать → Проверка → Acceptance criteria → Dependencies) и правило дробления ценны; без skill агенты пишут abstract issues без путей к файлам.
+- **Split repo-init into repo-create + repo-init skills** — отклонено: Phase A (create) слишком тонкая для отдельного skill (3 шага); Phase A/B split внутри одного skill даёт нужную гибкость без увеличения skill count.
+- **Править `AGENTS.md` Dev Workflow** — отклонено: step 2 уже говорил "delegate to `task` subagent" — консистентно с full-subagent моделью без правок.
\ No newline at end of file
diff --git a/docs/handoff/pr-28-issue-repo-init-rewrite.md b/docs/handoff/pr-28-issue-repo-init-rewrite.md
new file mode 100644
index 0000000..a27e2a9
--- /dev/null
+++ b/docs/handoff/pr-28-issue-repo-init-rewrite.md
@@ -0,0 +1,17 @@
+# PR: issue + repo-init skills rewrite
+
+## Что сделано
+- issue skill: full subagent delegation model (main agent передаёт intent summary → subagent грузит skill, читает файлы, пишет body, запускает `gh issue create`), добавлены секции `## Acceptance criteria` (явный чек-лист) и `## Dependencies` (Blocked by / Do not merge until / Part of) в шаблон и пример, исправлен stale workflow (добавлены docs-reviewer + memory-sync шаги, теперь 5 шагов вместо 3), "репозитории opencode" → "репозитории opencode-config", добавлен guidance по выбору labels
+- repo-init skill: переписано description (нет ambiguous "or"), добавлен Phase A / Phase B split (Phase A — GitHub remote steps 1-3, Phase B — project scaffolding steps 4-9), добавлен prerequisite `git init` + initial commit перед Step 1, убраны private-repo references (video_uniq, yt-video-downloader, opencode-voice-dictation, slaid098-dev → generic "reference repos", "Эталон — video_uniq" removed)
+
+## Почему
+issue skill имел 3-way contradiction на delegation: `issue/SKILL.md` (main agent writes body, subagent runs gh) vs `pipeline-driver/SKILL.md` ("через subagent с issue skill") vs `AGENTS.md` Dev Workflow (subagent не упомянут). repo-init skill имел ambiguous "or" в description, missing `git init` prerequisite (bare-repo → empty push → branch protection fail), private-repo references (не релевантны публичному шаблону).
+
+## Pending
+- Нет
+
+## Watch out
+- issue skill: 3 документа (`issue/SKILL.md`, `pipeline-driver/SKILL.md`, `AGENTS.md` Dev Workflow) теперь описывают одну full-subagent модель делегирования. `AGENTS.md` Dev Workflow step 2 уже упоминал "delegate to `task` subagent" — консистентно без правок AGENTS.md
+- repo-init skill: Phase A/B split позволяет jump к Phase B для scaffolding-only (существующий репо). Phase A — run once для нового репо
+- `--label "enhancement"` заменён на guidance по выбору label по commit `type` (enhancement/bug/refactor/documentation/chore/performance) + примечание про `gh label create` если label не существует
+- Verification greps (issue #13): `subagent` ✓, `Acceptance criteria` ✓, `Dependencies` ✓, private refs ✓ пусто, `or initializing` ✓ пусто
\ No newline at end of file