From 9c49c8b3a6c240edbbd1744a903a9761b3080d32 Mon Sep 17 00:00:00 2001 From: Leonid Pershin Date: Thu, 20 Aug 2026 10:29:56 +0300 Subject: [PATCH] Update SKILL documentation for phase and bug workflows. Clarified branch creation commands to specify `main` instead of `HEAD`, emphasized the importance of not committing phase changes to the bug tree, and provided detailed instructions for managing worktrees and agent interactions. Enhanced clarity on handling dependencies and worktree paths to prevent conflicts. --- .claude/skills/bug-work/SKILL.md | 5 +-- .claude/skills/phase-orch/SKILL.md | 16 +++++++-- .claude/skills/phase-orch/hangs.md | 12 +++++-- .claude/skills/phase-orch/worker-prompt.md | 26 ++++++++++----- .claude/skills/phase-review/SKILL.md | 9 ++--- .claude/skills/phase-work/SKILL.md | 39 +++++++++++++++++----- .claude/skills/side-work/SKILL.md | 3 +- 7 files changed, 82 insertions(+), 28 deletions(-) diff --git a/.claude/skills/bug-work/SKILL.md b/.claude/skills/bug-work/SKILL.md index 9dceb97..f26bdde 100644 --- a/.claude/skills/bug-work/SKILL.md +++ b/.claude/skills/bug-work/SKILL.md @@ -70,8 +70,9 @@ description: >- ## 4. Работа -Заявка `git branch bug/-` **до** кода. Новые файлы и 🔄 живут на этой -ветке. +Заявка `git branch bug/- main` **до** кода (от `main`, не от чужого +HEAD). Новые файлы и 🔄 живут на этой ветке. Не коммить заявку фазы в дерево +бага и наоборот. Дальше — как [phase-work](../phase-work/SKILL.md), с отличиями: diff --git a/.claude/skills/phase-orch/SKILL.md b/.claude/skills/phase-orch/SKILL.md index 4805d47..3be7031 100644 --- a/.claude/skills/phase-orch/SKILL.md +++ b/.claude/skills/phase-orch/SKILL.md @@ -49,7 +49,9 @@ N — **одновременные** агенты, не «запусти N и з ## Старт -1. Прочитай `docs/phases/README.md` и `docs/phases/reviewed.md`. +1. Прочитай `docs/phases/README.md` и `docs/phases/reviewed.md`. Если IDE не + на `main` — статусы с `git show main:docs/phases/README.md`, не с рабочей + копии (там может быть чужой 🔄 из бага). 2. Посчитай, сколько ⬜ с **закрытыми** зависимостями (шапка фазы). 🔄 не бери как новый захват. 3. Проверь `git branch --list "phase/*"` и `review/*` — заявка уже стоит. @@ -99,6 +101,7 @@ N — **одновременные** агенты, не «запусти N и з | Пользователь: пауза, только слияние | interrupt разработчикам: коммит WIP **на своей ветке**, не merge, не main. Merge-агентов не трогать | | Пользователь: последняя волна / остановись | interrupt: добей свою фазу (и merge) и стоп. **Новых** агентов не запускать, в том числе по completion | | Пользователь: продолжи | снять паузу с WIP-ветки (`resume` с хешем коммита), не начинать фазу с нуля | +| Агент коммитит в `bug/…` / нет worktree | interrupt: стоп в корне IDE, `worktree add` на уже существующую ветку фазы, 🔄 на `main` через `wt-claim-main`. Историю `bug/…` не revert | Зависимую ⬜ не открывать, пока зависимость 🔄 или лежит неслитой веткой. @@ -107,8 +110,10 @@ N — **одновременные** агенты, не «запусти N и з Транскрипт из 1–2 сообщений («читаю скилл» / `GetMcpTools`) при живом агенте дольше ~15 минут, или тишина после interrupt — **завис**. -1. `resume` + `interrupt`: брось MCP (`cursor-app-control` не звать), не читай - скилл заново, продолжай с ветки/worktree. +1. `resume` + `interrupt`: брось MCP (`GetMcpTools` на `cursor-app-control` не + звать), не читай скилл заново, продолжай с ветки/worktree. Корень IDE не + трогай. Если worktree нет — `git worktree add` на существующую `phase/-*`, + не создавай вторую ветку. 2. Второй раз — старый: «уступи, git не трогай». Новый агент — **продолжение** того же 🔄: та же ветка и worktree, промпт «замена зависшего». Это не новый захват ⬜ и не второй автор. @@ -145,6 +150,10 @@ N — **одновременные** агенты, не «запусти N и з Замена зависшего — существующая ветка в промпте, не пустой `git branch --list`. +Ветка фазы — `git branch phase/- main` (не от HEAD). 🔄 только на +`main`: если IDE на `bug/…`, одноразовый worktree `wt-claim-main`, не коммит в +дерево пользователя. После `worktree add` правки — абсолютным путём worktree. + Шаблон: [`worker-prompt.md`](worker-prompt.md). ## Чего не делать @@ -158,6 +167,7 @@ N — **одновременные** агенты, не «запусти N и з - `git push`. - Переставлять чужие 🔄/✅ (замена зависшего 🔄 не трогает: статус тот же). - Снимать чужой `merge/lock` или `checkout` основного дерева с `bug/…` на `main`. +- Коммитить 🔄 фазы в дерево `bug/…` или править код фазы в корне IDE. - Заканчивать ответ без списка агентов (ниже). ## Список агентов diff --git a/.claude/skills/phase-orch/hangs.md b/.claude/skills/phase-orch/hangs.md index 026dd25..4b700f2 100644 --- a/.claude/skills/phase-orch/hangs.md +++ b/.claude/skills/phase-orch/hangs.md @@ -15,8 +15,9 @@ ## MCP `GetMcpTools` на `cursor-app-control` и ожидание echovault держали агента -полчаса. В промпте: **не звать cursor-app-control**; memory — один раз или -без неё. +полчаса. В промпте: **не открывай этот сервер через `GetMcpTools`**. После +готового worktree можно один `move_agent_to_root` с известной схемой +`{ rootPath }`. Memory — один раз или без неё. ## Interrupt @@ -36,6 +37,13 @@ Первая сборка в worktree длинная — это не завис. +`git branch phase/-` без `main` берёт HEAD IDE. Коммит 🔄 «в основном +дереве» на `bug/…` оставляет заявку в истории бага, а worktree иногда так и не +появляется — агент пишет фазу в дерево пользователя. Лечение: interrupt, не +`checkout`, `worktree add` на уже существующую `phase/-*`, 🔄 донести на +`main` через `wt-claim-main`. Коммиты на `bug/…` не revert. Правки после +захвата — только абсолютным путём worktree. + ## Грязный main и чужая ветка `merge/lock` общий: фаза, баг, ревью, side. Чужой — ждать, не снимать. diff --git a/.claude/skills/phase-orch/worker-prompt.md b/.claude/skills/phase-orch/worker-prompt.md index 4371ba3..e7daa68 100644 --- a/.claude/skills/phase-orch/worker-prompt.md +++ b/.claude/skills/phase-orch/worker-prompt.md @@ -8,8 +8,10 @@ трогали `src/HSchool.Client`. `HSchool.AppHost.Tests` — только HTTP / сокет / хост. Общее во все промпты: не пушь; `HSchool.Server` не убивай; dev-сервер не -поднимай; `cursor-app-control` не вызывай; memory — один раз или без неё; -stash с пометкой portraits / чужой wip не pop. +поднимай; `GetMcpTools` на `cursor-app-control` не зови (висит). После +`worktree add` можно один `move_agent_to_root` с `rootPath` = путь worktree, +без открытия сервера; иначе все правки — абсолютным путём worktree. +Memory — один раз или без неё; stash с пометкой portraits / чужой wip не pop. ## Разработчик — новый захват ⬜ @@ -30,10 +32,16 @@ Windows Vitest: при падении параллели — `--maxWorkers=1`. Застолбить до кода: 1. git branch --list "phase/-*" — пусто, иначе стоп (это чужой захват). -2. git branch phase/- -3. 🔄 в README основного дерева, отдельный коммит только этой строки. + Занятость: `git show main:docs/phases/README.md`, не рабочую копию IDE. +2. git branch phase/- main + От **main**, не от HEAD (HEAD часто bug/…). Не checkout основного дерева. +3. 🔄 в README **на main**, отдельный коммит только этой строки. + Дерево уже на main — коммить там. Иначе: worktree add /wt-claim-main + main, коммит там, worktree remove. В bug/… не коммить и не revert чужое. 4. git worktree add /wt-phase- phase/- Клиент: npm ci или копия node_modules (не рекурсивно в себя). +5. Дальше только этот worktree: абсолютные пути / working_directory. Корень + IDE не трогать (ни Write, ни git commit). Задачи и обязательные тесты — как в файле фазы целиком. Гоняй только проект(ы) из Testing policy в AGENTS.md, `--filter` на новый @@ -61,12 +69,12 @@ HTTP/протокол — docs/protocol.md тем же коммитом; вер Следуй `.claude/skills/phase-work/SKILL.md`. Блок «Как застолбить» пропусти. Фаза: **. <имя>**. Ветка уже есть: **phase/-**. -Worktree: <путь>/wt-phase- — работай там. +Worktree: <путь>/wt-phase- — работай там (абсолютные пути). 🔄 не сбрасывай и вторую ветку не создавай. `git branch --list "phase/-*"` не обязан быть пустым — это не гонка. -Не начинай фазу с нуля. Брось MCP (cursor-app-control не звать). -Дочитай незакоммиченное в worktree, не выкидывай его. +Не начинай фазу с нуля. Брось MCP (`GetMcpTools` на cursor-app-control не звать). +Корень IDE / bug/… не трогай. Дочитай незакоммиченное в worktree, не выкидывай его. Дальше — как обычный разработчик: задачи фазы, тесты по Testing policy (`--filter`, не весь solution), слияние по скиллу (грязный main / не на @@ -115,7 +123,9 @@ phase-work; stash — только если ниже явно сказано, ч – (этап среза <имя>), не весь срез и не следующий. Свой заголовок в docs/phases/reviewed.md. Чужие разделы журнала не затирай. -Ветка review/, worktree вне репо: /wt-review-. +Ветка `git branch review/ main` (от main, не от HEAD). +Worktree вне репо: /wt-review- — дальше только его пути. +Журнал коммить в этом worktree, не в bug/… пользователя. Слияние как у phase-work: merge/lock общий, --no-ff, не пушь. Основное дерево уже на main; не checkout bug/…. Тесты — Testing policy, `--filter`, не весь solution. diff --git a/.claude/skills/phase-review/SKILL.md b/.claude/skills/phase-review/SKILL.md index dddd9ee..f22057d 100644 --- a/.claude/skills/phase-review/SKILL.md +++ b/.claude/skills/phase-review/SKILL.md @@ -57,10 +57,11 @@ description: Ревью срезов и фаз проекта h-school по их а не получит через час одну кучу правок в семи проектах. `/phase-orch` мог отдать **часть** среза (этап A, фазы 29–31). Это всё ещё один проход: только -эти фазы, свой заголовок в журнале, ветка `review/`, worktree вне репо, слияние как у -`/phase-work` (`merge/lock` общий с фазами и багами — чужой не снимать; `--no-ff`; не пушь; -основное дерево уже на `main`, не `checkout` `bug/…`). Чужой раздел `reviewed.md` не затирай. -Следующий срез сам не бери. Два ревьюера на один и тот же этап не садятся. +эти фазы, свой заголовок в журнале, ветка `git branch review/ main` (не от HEAD), worktree +вне репо, дальше абсолютные пути этого worktree — журнал не коммитить в `bug/…` пользователя. +Слияние как у `/phase-work` (`merge/lock` общий с фазами и багами — чужой не снимать; `--no-ff`; +не пушь; основное дерево уже на `main`, не `checkout` `bug/…`). Чужой раздел `reviewed.md` не +затирай. Следующий срез сам не бери. Два ревьюера на один и тот же этап не садятся. ## Что именно проверять diff --git a/.claude/skills/phase-work/SKILL.md b/.claude/skills/phase-work/SKILL.md index e3c8265..813ebec 100644 --- a/.claude/skills/phase-work/SKILL.md +++ b/.claude/skills/phase-work/SKILL.md @@ -39,26 +39,41 @@ description: Берёт ровно одну фазу из среза в docs/pha **пропусти**: ветку не создавай, 🔄 не сбрасывай, садись в существующий worktree. «already exists» здесь не гонка. -Ветка — и есть заявка, потому что git не даст создать её дважды: +Ветка — и есть заявка, потому что git не даст создать её дважды. Указывай **`main`**, не текущий +HEAD: IDE пользователя часто стоит на `bug/…`, и ветка от HEAD утащит фазу на чужую историю. ```bash -git branch phase/25-golden-fixtures +git branch phase/25-golden-fixtures main ``` Команда упала с «already exists» — значит фазу взял другой агент между твоей проверкой и попыткой. Не спорь, вернись к выбору и возьми следующую. -Ветка создалась — фаза твоя. Сразу пометь её 🔄 в `docs/phases/README.md` **в основном дереве**, -отдельным коммитом, состоящим только из этой строки. Это единственная правка, которую ты делаешь -вне своего worktree, и она нужна по двум причинам: соседние агенты видят занятое, а пустая свежая -ветка ещё ничем не отличается от слитой — по ней одной понять, что фаза в работе, нельзя. +Ветка создалась — фаза твоя. Сразу пометь её 🔄 в `docs/phases/README.md` **на `main`**, отдельным +коммитом из одной этой строки. Соседи читают занятость с `main`, а пустая свежая ветка ещё ничем +не отличается от слитой — по ней одной понять, что фаза в работе, нельзя. -Пометить 🔄 надо **до** первой строчки кода, а не после. +Как доставить этот коммит, зависит от основного дерева (`git -C <корень> branch --show-current`): + +- дерево **уже на `main`** — правь README там и коммить. Это единственная правка вне своего + worktree фазы. +- дерево на `bug/…` или другой ветке пользователя — **не** `checkout`, **не** коммить в это + дерево. Одноразовый worktree `main`: + +```bash +git worktree add /wt-claim-main main +# README ⬜→🔄, commit, затем: +git worktree remove /wt-claim-main +``` + +Пометить 🔄 надо **до** первой строчки кода, а не после. Коммит «Mark phase N…», который уже +уехал в `bug/…`, не revertь и не переписывай историю пользователя — доведи 🔄 на `main` через +`wt-claim-main` (cherry-pick, если коммит тот же). ## Где работать В своём worktree, а не в общем дереве. Иначе два агента правят одни файлы и роняют друг другу -сборку. +сборку — или, хуже, пишут код фазы в `bug/…` пользователя. ```bash git worktree add <путь-в-scratchpad>/wt-phase-25 phase/25-golden-fixtures @@ -67,6 +82,14 @@ git worktree add <путь-в-scratchpad>/wt-phase-25 phase/25-golden-fixtures Путь — **вне репозитория**; каталог scratchpad этой сессии подходит. Worktree внутри репозитория засоряет `git status` и попадёт в глаза следующему ревью. +Cursor workspace по умолчанию — корень IDE, не этот worktree. После `worktree add` каждый +`Read` / `Write` / `StrReplace` / `Shell` идёт **абсолютным путём** (или `working_directory`) +внутрь `…/wt-phase-25`. Относительный `docs/phases/README.md` пишется в ветку, которую сейчас +держит пользователь. `git add` / `commit` без `-C` worktree — то же самое. + +Занятость чужих фаз читай так: `git show main:docs/phases/README.md` и +`git branch --list "phase/*"` — не рабочую копию на `bug/…`. + Дальше вся работа там. В конце worktree удаляется (`git worktree remove --force`), ветка остаётся. Что нужно знать про worktree: diff --git a/.claude/skills/side-work/SKILL.md b/.claude/skills/side-work/SKILL.md index 14f0b6d..133a9a4 100644 --- a/.claude/skills/side-work/SKILL.md +++ b/.claude/skills/side-work/SKILL.md @@ -64,7 +64,8 @@ description: >- Прочитай [phase-work](../phase-work/SKILL.md) и следуй ему. -Отличия: фазу ты завёл сам; заявка `git branch phase/-` **до** кода; +Отличия: фазу ты завёл сам; заявка `git branch phase/- main` **до** кода +(от `main`, не от HEAD); тесты — как Testing policy в `AGENTS.md`, не весь solution; новые файлы и 🔄 живут на этой ветке. `merge/lock` общий с фазами, багами и ревью. Один цикл — одна фаза. «Сделай всё» — по порядку, каждая своим циклом `/phase-work`. Независимые фазы