worktree-skill

Плагин Claude Code для параллельного исполнения фазового плана: независимые фазы идут одновременно, каждая в своей git-worktree от базовой ветки, затем ветки серилизованно вливаются в базу с авто-резолвом конфликтов по контрактам плана. Параллельный аналог circle-skill (тот исполняет план последовательно, по фазе на сессию). Цель — ускорить реализацию плана при минимизации конфликтов.

Как работает

1. /worktree-skill:worktree-skill <путь-или-имя-плана> — препролёт: находит план, проверяет окружение (git-репо, чистое рабочее дерево, существование базовой ветки), нормализует формат (проставляет worktree-маркеры, статусы выводит из «## Журнал»), классифицирует риск и спрашивает, какие рискованные фазы разрешить выполнять без тебя.
2. Запускает фоновый оркестратор. Он идёт волнами:
   • Волна = все pending+auto фазы, чьи deps уже влиты в базу. В идеально независимом плане волна одна — все фазы разом.
   • Для каждой фазы волны — своя git-worktree от базы; сессии стартуют параллельно (под PTY, как настоящие интерактивные сессии claude), каждая выполняет ровно свою фазу и коммитит в свою ветку.
   • После барьера волны ветки серилизованно вливаются в базу. Чистый мерж → интеграционный verify-гейт. Конфликт → отдельная merge-сессия резолвит его строго по контрактам плана. Неразрешимо (или verify красный) → фаза blocked, её ветка сохраняется, база остаётся зелёной.
   • Следующая волна стартует от обновлённой базы.
3. Останавливается, когда подходящих фаз не осталось. Затем — консолидированный отчёт: влитые фазы, blocked (с именами сохранённых веток для ручного добора), skipped, needs-human.

Ключевой инвариант: база всё время консистентна и зелёна — фаза попадает в базу только после успешного мержа И verify; иначе откатывается в blocked. Неразрешимые конфликты не дёргают тебя посреди рана — собираются в финальный хэндофф.

Почему интерактивные сессии, а не claude -p

claude -p (headless) тарифицируется как API. Плагин гоняет настоящие интерактивные сессии под PTY — они идут по подписке, видят установленные плагины и умеют спавнить субагентов.

Требования

• git, claude (логин по подписке; ANTHROPIC_API_KEY оркестратор намеренно сбрасывает), python3 (только стандартная библиотека). macOS/Linux; Windows — через WSL.
• Проект — git-репозиторий с чистым рабочим деревом и существующей базовой веткой (dev по умолчанию). Нет базовой ветки → ран не стартует (никакого фолбэка).

Установка

claude plugin marketplace add https://github.com/SI-IC/worktree-skill.git
claude plugin install worktree-skill@worktree-skill

Формат плана

Markdown. Фазы — секции ## Фаза <id> — <title> с маркером под заголовком:

## Фаза 2 — API-слой
<!-- worktree: status=pending order=20 deps=[1] autonomy=auto obstacle="" -->

Поля: status (pending|in_progress|done|blocked|skipped), order (int, шаг 10), deps (id предшественников — удовлетворяются ТОЛЬКО когда те влиты в базу), autonomy (auto|needs-human), obstacle.

Специфика параллельного плана (в преамбуле, до первой фазы — попадает в срез каждой фазы):

• ## Контракты — общие интерфейсы для пересекающихся фаз: сигнатуры функций/типов, форматы данных, файлы-владельцы (кто единолично правит какой файл). Это механизм минимизации конфликтов — каждая worktree обязана их соблюдать, а merge-сессия по ним разрешает конфликты.
• <!-- worktree-verify: <cmd> --> — команда интеграционного verify-гейта после каждого мержа (либо env WORKTREE_VERIFY_CMD; не задано — гейт пропускается с предупреждением).
• <!-- worktree-setup: <cmd> --> — провижн-хук: команда, исполняемая в каждой свежей worktree сразу после её создания, ДО фазовой сессии (либо env WORKTREE_SETUP_CMD). Сюда кладут провижн зависимостей, отсутствующих в свежем checkout (gitignored node_modules и т.п.). Fail-closed: провал setup → фаза blocked, сессия не запускается. Пример (pnpm-монорепо): симлинк node_modules из базы + CI=true pnpm install --frozen-lockfile; verify тогда звать бинарями напрямую (./node_modules/.bin/tsc), не через pnpm <script> (обёртка pnpm может разъехаться с базовым .modules.yaml). Команда пишется в loop.log — секреты (registry-токены и т.п.) передавай через env/файлы, не инлайном в команду.
• В теле каждой фазы — строка «Контракт для пересечений»: какие файлы её, какие чужие не трогает, какой публичный интерфейс отдаёт downstream-фазам.

Плюс append-only ## Журнал: оркестратор сводит туда записи фаз в конце рана.

Как авторить план под параллельное исполнение — см. worktree-plan-authoring.md в плагине main-skill.

Рабочая папка и логи

Оркестратор пишет рантайм рядом с планом, в отдельную папку на каждый план: .worktree/<имя-плана>/ (loop.log, summary.txt, state.json, status/, journal/, phase-context-*.md, prompt-*.md, wt-* — worktree фаз, lock.d). Вся .worktree/ гарантированно вне git (оркестратор кладёт туда .gitignore с *). Логи несут сырой вывод сессий — там возможны секреты, коммитить их нельзя.

Безопасность и доверие к плану

План-файл исполняется как код. Интеграционный verify-гейт (WORKTREE_VERIFY_CMD или <!-- worktree-verify: <cmd> --> из плана) запускается через eval в корне репозитория после каждого мержа. Относись к плану как к Makefile: запускай /worktree-skill:worktree-skill только на доверенных планах (своих или отревьюенных). План из внешнего источника может нести произвольную команду в worktree-verify — слэш-команда показывает её тебе перед запуском для подтверждения.

worktree-setup (env WORKTREE_SETUP_CMD или маркер плана) исполняется через eval в каждой worktree — та же модель доверия, что и worktree-verify. Внешний план может нести произвольную команду и там.

Git-хуки сняты на весь ран (HUSKY=0). Иначе husky-репо ломает интеграцию: commit-msg→commitlint отвергает non-conventional merge-коммит, pre-commit→lint-staged валит коммиты фаз → все фазы blocked. Скоуп — только дерево процессов рана (глобальный/репо git-конфиг не трогается). Гейт качества у нас — worktree-verify, не хуки репо. Компромисс: если в pre-commit репо стоит секрет-сканер (gitleaks и т.п.), на коммитах фаз он не отработает — работа фаз идёт на ревью владельцу перед сводкой в план.

Прочие границы:

• id фаз валидируются ([A-Za-z0-9._-]) — /, .. и спецсимволы отклоняются (иначе был бы path traversal при записи файлов рантайма и в именах веток).
• Логи сессий (сырой PTY-вывод, возможны секреты) держатся вне git: .worktree/.gitignore = '*' (fail-closed — не смог записать, не стартуем).
• Merge-сессии не верят на слово: после RESOLVED оркестратор независимо перепроверяет, что не осталось незамерженных путей и конфликт-маркеров — иначе фаза уходит в blocked, база не портится.
• Свод журнала обратно в план нейтрализует HTML-комментарии из недоверенного вывода сессий (чтобы фаза не подсадила в план worktree/worktree-verify-маркер к следующему прогону).

Настройки (env)

• WORKTREE_BASE — базовая ветка (по умолч. dev). Нет такой ветки → ран не стартует.
• WORKTREE_MAX_PARALLEL — макс. одновременных фаза-сессий. По умолч. min(4, cores-1), где cores — реальный лимит из cgroup (cpu-квота v2/v1), а не хостовый nproc (в контейнере он врёт → OOM); дефолт дополнительно клампится по RAM-лимиту cgroup. Явное значение переопределяет расчёт (превышение бюджета — лог-предупреждение, но выбор за оператором).
• WORKTREE_PHASE_MEM_MB — оценка пиковой памяти одной фазы для RAM-клампа дефолта (по умолч. 1536).
• WORKTREE_VERIFY_CMD — команда интеграционного verify (переопределяет worktree-verify из плана).
• WORKTREE_SETUP_CMD — провижн-хук worktree (переопределяет worktree-setup из плана).
• WORKTREE_TIMEOUT — таймаут сессии (сек, по умолч. 3600) — жёсткий SIGALRM-детектор зависания.
• WORKTREE_PYTHON / WORKTREE_CLAUDE_BIN — интерпретатор / бинарь claude.
• ANTHROPIC_API_KEY — намеренно сбрасывается перед сессиями (принудительно подписка, не API).

Версионирование и релиз

Версия живёт в .claude-plugin/plugin.json и зеркалится в .claude-plugin/marketplace.json (значения обязаны совпадать). Каждый push main поднимает версию. Релиз — одной командой:

./scripts/release.sh            # patch (по умолчанию)
./scripts/release.sh minor
./scripts/release.sh major

Правило навязывается git-хуком .githooks/pre-push (прямой git push origin main без поднятой версии отклоняется; разовый обход — git push --no-verify). После git clone выполни один раз:

git config core.hooksPath .githooks

Тесты

python3 -m unittest discover -s tests -v

Ручной smoke (реальная сессия, под подпиской)

Юнит/интеграционные тесты используют поддельный claude. Для проверки на реальных сессиях: git-репо с веткой dev, план с двумя независимыми auto-фазами (каждая создаёт свой файл), /worktree-skill:worktree-skill <plan>, подтверди — и убедись, что обе фазы влиты в dev, отчёт complete.