# Командная разработка OpenWC ## Цель Этот workflow позволяет нескольким людям и Codex-агентам работать параллельно, не перезаписывая изменения друг друга и не разрушая архитектурные границы. Единица параллельной работы — не milestone целиком, а ограниченный `work package`. ## Основные правила 1. Каждый агент работает в отдельном clone или Git worktree и собственной ветке. 2. Никто не разрабатывает напрямую в `master`. 3. До изменений задача получает ID, владельца, claim и список затрагиваемых путей. 4. Один work package имеет только одного активного владельца. 5. Общие contracts согласуются до параллельной реализации producers/consumers. 6. Статус milestone и `OPENWC_TARGET_DONE` изменяет только интегратор. 7. Merge выполняется только после handoff, локальных проверок и синхронизации с актуальным `master`. ## Идентификаторы ### Agent ID Каждый человек/агент выбирает стабильный ID на весь work package: ```text --codex ``` Примеры: ```text sindo-main-codex alex-laptop-codex ``` ID записывается в claim, ветке, PR/MR и handoff. Нельзя использовать просто `codex`, потому что таких агентов несколько. ### Work Package ID ```text --- ``` Примеры: ```text M01-FND-COORDS-001 M03-RND-SCHEDULER-001 M08-NET-SRP-001 M12-UIA-LUA-SPIKE-001 ``` Program codes определены в [`../targets/DEVELOPMENT_ROADMAP.md`](../targets/DEVELOPMENT_ROADMAP.md). ## Claim protocol Предпочтительный канал координации — issue + ранний draft PR/MR на общем Git forge. Если forge недоступен, используется отдельный файл в `coordination/claims/`, который сначала публикуется в общей ветке. Claim marker: ```text ``` Последнее поле — дата истечения claim в UTC. Рекомендуемый срок — 48 часов; владелец продлевает его коротким status update. Истёкший claim нельзя забирать молча: сначала оставить сообщение владельцу и интегратору. Claim содержит: - target и work package; - owner/agent ID; - outcome и non-goals; - exclusive paths; - shared/hotspot paths; - contracts/schema/format changes; - dependencies и blockers; - verification commands; - expected fidelity evidence. - documentation deliverables: inline API, module spec, diagrams и source map. ## Ветки и worktrees Имя ветки: ```text work//- ``` Пример: ```text work/sindo-main-codex/m01-coordinate-mapper ``` Начало работы: ```powershell git fetch origin git worktree add ..\open-wc-m01 -b work/sindo-main-codex/m01-coordinate-mapper origin/master ``` Правила: - один worktree принадлежит одному агенту; - не запускать двух агентов в одном dirty worktree; - не менять и не удалять чужой worktree; - generated caches и proprietary data не переносятся commit/cherry-pick; - перед handoff ветка синхронизируется с актуальным `origin/master`. ## Разделение задач Хороший work package: - даёт один наблюдаемый результат; - принадлежит преимущественно одной подсистеме; - имеет явные входы/выходы; - меняет не более одного публичного contract одновременно; - имеет собственные tests/diagnostics; - может быть review и merged независимо либо после одной явно указанной dependency. Плохое разделение: - «сделать сеть»; - один агент меняет protocol и UI напрямую; - два агента одновременно рефакторят один monolithic file; - задача зависит от незаписанного устного соглашения; - work package оставляет временный второй источник истины. ## Parallelization patterns ### Contract first Для cross-layer feature сначала отдельным маленьким work package фиксируются: - domain types; - commands/events/read models; - version/capabilities; - failure states; - contract tests. После merge независимо работают producer и consumers. Пример: ```text WP-A: MovementSnapshot contract ├─ WP-B: network movement decoder ├─ WP-C: gameplay reconciliation └─ WP-D: character/camera presentation ``` ### Fixtures in parallel Пока один агент реализует pure logic, второй может готовить: - synthetic fixtures; - original-client comparison procedure; - server-core matrix; - visual checkpoints; - documentation/reference analysis. Fixture agent не изменяет production contract без согласования. ### Adapter split После merge canonical interface допустимо параллельно реализовать TrinityCore и AzerothCore adapters, если у каждого разные файлы и общая contract suite. ### Hotspot extraction first Если работа требует одного большого файла, сначала один владелец извлекает стабильный seam. Параллельная работа начинается только после merge seam, а не внутри разных участков монолита. ## Hotspot-файлы Следующие пути требуют явного указания в claim и согласования с интегратором: - `project.godot`; - `AGENTS.md`, `docs/README.md`, `targets/README.md`; - текущий `targets/[0-9][0-9]-*.md`; - `RENDER.md`; - `src/scenes/streaming/streaming_world_loader.gd` до декомпозиции; - native registration/CMake/GDExtension manifests; - editor `plugin.cfg` и root plugin lifecycle; - shared schema/version/format constants; - dependency lockfiles и submodules. Два активных work packages не должны редактировать один hotspot. При необходимости интегратор выделяет serial integration window. ## Изменение contracts и форматов Contract/schema change обязан иметь: - owner и потребителей; - backward compatibility или migration; - old/new fixtures; - version bump policy; - rollout order; - ADR для существенного решения. Merge order: 1. contract + compatibility layer; 2. producers; 3. consumers; 4. removal deprecated path отдельным work package. Нельзя одновременно удалить старый API и ожидать, что незамердженная ветка другого агента уже использует новый. ## Commits Формат заголовка: ```text (): ``` Примеры: ```text fnd(M01): add canonical coordinate mapper net(M08): decode auth challenge safely rnd(M03): extract streaming target planner test(M00): add paired checkpoint manifest ``` Описание commit/PR содержит: ```text Work-Package: M01-FND-COORDS-001 Agent: sindo-main-codex Tests: Fidelity: ``` Не смешивать formatting unrelated files, generated artifacts и функциональное изменение в одном commit. ## Handoff protocol Готовый work package получает marker: ```text ``` Handoff обязан содержать: - точный commit/branch; - outcome и изменённые paths; - публичные contracts/schema changes; - verification commands и результаты; - fidelity evidence/known gaps; - migration/cache/rebuild requirements; - unresolved risks; - recommended merge order; - updated API/module documentation и перечень diagrams. Если работа частичная: ```text ``` `PARTIAL` не считается завершением и не разрешает ставить target `DONE`. ## Integration protocol Интегратор: 1. Проверяет claim и отсутствие overlapping ownership. 2. Проверяет diff на unrelated/user changes. 3. Синхронизирует branch с `master` без уничтожения чужой истории. 4. Запускает package verification и затронутые общие gates. 5. Проверяет docs, migrations, cache versions и fidelity statement. 6. Проверяет documentation gate из `docs/DOCUMENTATION_STANDARD.md`: API docs, inputs/outputs, diagrams, ownership и recovery. 7. Merge/squash выполняет в соответствии с историей work package. 8. После merge запускает post-merge smoke. 9. Закрывает claim marker-ом: ```text ``` Только после интеграции всех обязательных work packages интегратор обновляет target Evidence/status. ## Конфликты При обнаружении overlapping edits агент должен остановить изменение затронутого файла и связаться с владельцем. Запрещено: - разрешать конфликт через слепое `ours/theirs`; - копировать чужой файл поверх своего; - делать `reset --hard` или checkout чужих изменений; - «временно» дублировать contract без migration plan. Порядок разрешения: 1. определить semantic owner; 2. выбрать merge order; 3. первый владелец публикует минимальный contract/seam; 4. второй rebase и адаптирует свою ветку; 5. integration tests подтверждают совместимость. ## Status updates и stale work Владелец обновляет claim после значимого результата или не реже срока lease. Status краткий: ```text State: active | waiting | ready | partial Done: ... Next: ... Blocked by: ... Touched paths: ... ``` Если работа прекращена, claim явно освобождается. Незавершённую ветку не удаляют до handoff с описанием пригодных commits и известных проблем. ## Минимальная схема для двух разработчиков - Один человек назначается интегратором текущего milestone. - Второй берёт work package без пересечения файлов либо готовит fixtures/reference/adapter. - Роль интегратора можно менять после каждого milestone. - Перед началом дня оба выполняют `git fetch` и сверяют claims/draft PRs. - Перед merge второй агент не начинает работу поверх непроверенного commit, если dependency не опубликована как contract branch. Пример для M01: ```text Developer A / integrator: M01-FND-COORDS-001 — coordinate types and mapper Developer B: M01-QAR-COORD-FIXTURES-001 — known ADT/server points and tests После merge contract: A — StreamingFocus migration B — placement/SQL conversion audit ``` ## Автоматическая проверка Перед handoff и merge запускать: ```powershell .\tools\verify_coordination.ps1 .\tools\verify_documentation.ps1 ``` Первая проверка требует ровно один `ACTIVE` numbered target, соответствие `Current target`, валидные и уникальные fallback claim markers. Вторая проверяет обязательные documentation files, структуру module specs, наличие data-flow diagram и относительные ссылки. Истёкший claim выдаёт warning и требует человеческого решения, но не удаляется автоматически.