Update AGENTS.md and various SKILL.md files to improve documentation structure, clarify design phase references, and ensure consistency in file paths. Adjust links to design documents for better navigation and organization across phases.
ci / server (push) Failing after 3m41s
ci / client (push) Successful in 21s

This commit is contained in:
Leonid Pershin
2026-08-20 12:26:21 +03:00
parent a37a5eb82d
commit 9a6cbff55a
30 changed files with 116 additions and 95 deletions
+16 -11
View File
@@ -22,13 +22,18 @@ description: Берёт ровно одну фазу из среза в docs/pha
**Номера нет** — выбираешь сам. Волну «запусти троих» так не раздавай — это `/phase-orch`.
1. Читаешь `docs/phases/README.md`: находишь первый срез, где есть ⬜.
2. Внутри среза берёшь первую ⬜, у которой закрыты зависимости — они перечислены в шапке фазы.
1. `rg "⬜" docs/phases/*/README.md` — не читай индексы всех срезов. Оглавление
`docs/phases/README.md` — каталог папок, без таблиц фаз.
2. В первом срезе с ⬜ берёшь первую ⬜, у которой закрыты зависимости — они в шапке фазы.
3. Проверяешь, что её никто не взял: `git branch --list "phase/<номер>-*"` пусто.
**Статус в `README.md` — первый источник правды, ветка — только арбитр гонки.** 🔄 значит занято,
✅ значит сделано, ⬜ значит свободно. Ветка может существовать и при ✅ — её просто не убрали после
слияния; это не заявка, а мусор, см. «Кто убирает ветку».
Номер дали — файл `docs/phases/*/<N>-*.md`. Читай его, `README.md` этой папки и дизайн
среза по ссылке в индексе. Чужие срезы и `reviewed.md` не открывать.
**Статус в индексе среза (`docs/phases/<slice>/README.md`) — первый источник правды, ветка —
только арбитр гонки.** 🔄 значит занято, ✅ значит сделано, ⬜ значит свободно. Ветка может
существовать и при ✅ — её просто не убрали после слияния; это не заявка, а мусор, см.
«Кто убирает ветку».
Фаза 🔄 — чужая работа в процессе. Не трогай её, даже если кажется, что там застряли —
кроме случая выше: номер передали и ветка уже есть, тебя посадили продолжить.
@@ -49,7 +54,7 @@ git branch phase/25-golden-fixtures main
Команда упала с «already exists» — значит фазу взял другой агент между твоей проверкой и попыткой.
Не спорь, вернись к выбору и возьми следующую.
Ветка создалась — фаза твоя. Сразу пометь её 🔄 в `docs/phases/README.md` **на `main`**, отдельным
Ветка создалась — фаза твоя. Сразу пометь её 🔄 в `docs/phases/<slice>/README.md` **на `main`**, отдельным
коммитом из одной этой строки. Соседи читают занятость с `main`, а пустая свежая ветка ещё ничем
не отличается от слитой — по ней одной понять, что фаза в работе, нельзя.
@@ -84,10 +89,10 @@ git worktree add <путь-в-scratchpad>/wt-phase-25 phase/25-golden-fixtures
Cursor workspace по умолчанию — корень IDE, не этот worktree. После `worktree add` каждый
`Read` / `Write` / `StrReplace` / `Shell` идёт **абсолютным путём** (или `working_directory`)
внутрь `…/wt-phase-25`. Относительный `docs/phases/README.md` пишется в ветку, которую сейчас
внутрь `…/wt-phase-25`. Относительный `docs/phases/<slice>/README.md` пишется в ветку, которую сейчас
держит пользователь. `git add` / `commit` без `-C` worktree — то же самое.
Занятость чужих фаз читай так: `git show main:docs/phases/README.md` и
Занятость чужих фаз читай так: `git show main:docs/phases/<slice>/README.md` и
`git branch --list "phase/*"` — не рабочую копию на `bug/…`.
Дальше вся работа там. В конце worktree удаляется (`git worktree remove --force`), ветка остаётся.
@@ -184,7 +189,7 @@ git -C <корень> merge --no-ff phase/25-golden-fixtures
`--no-ff` — чтобы фаза осталась видимой в истории одним куском, а не растворилась в линии.
**5. Конфликты разрешай только те, что понимаешь.** Почти всегда это строка статуса в
`docs/phases/README.md` — там обе стороны правы, надо оставить обе. Конфликт в коде, смысл
`docs/phases/<slice>/README.md` — там обе стороны правы, надо оставить обе. Конфликт в коде, смысл
которого тебе неясен, — `git merge --abort`, снять замок, оставить ветку и написать в отчёте, с
чем именно она не сходится.
@@ -235,8 +240,8 @@ git branch --merged main --list "phase/*" --format="%(refname:short)"
работай там, статус не возвращай в ⬜.
- **Не меняй молча** версию протокола, форму сейва и публичное поведение API — даже когда это
очевидно правильно. Если фаза этого требует, так и написано в её задачах.
- **Общие файлы трогай минимально.** `AGENTS.md`, `docs/protocol.md`, `README.md` правят все ветки
сразу — чем точечнее правка, тем дешевле слияние.
- **Общие файлы трогай минимально.** `AGENTS.md`, `docs/protocol.md` правят все ветки сразу.
Индекс — только свой `docs/phases/<slice>/README.md`. Каталог срезов не трогать.
## Окружение: что укусит