--- name: goal-pipeline description: > Планировщик-исполнитель поверх нативной /goal Claude Code (Windows + pwsh): recon проекта, декомпозиция на фазы с измеримыми критериями, вшитые гейты качества по типу фазы, артефакты на диск и ОДНА готовая строка /goal — свежая сессия исполняет фазы с авто-ретраем, чекпоинтами на рискованных фазах и финальным аудитом. Заточен под brownfield. Используй когда пользователь говорит «прогон под goal», «разбей на фазы и запусти», «доведи до готового через goal», «автономно доделай». Для документа без исполнения — spec-writer; для in-session петли — ralph-loop; для greenfield — feature-dev. metadata: version: 1.1.0 --- # Goal Pipeline Лёгкая обвязка вокруг **нативной команды `/goal`** Claude Code. `/goal <условие>` переводит сессию в автономный режим: после каждого хода отдельный быстрый оценщик (Haiku) проверяет твоё условие по транскрипту и продолжает работу, пока условие не выполнится. Автономность даёт **хост**, а не этот навык. Задача навыка — *хорошо подготовить* прогон (recon → фазы → измеримые критерии → вшитые гейты), выдать **одну** строку `/goal` для вставки и описать протокол, по которому исполняющая сессия читает фазы с диска и доводит задачу до конца. Два актёра: - **Планировщик** — текущая сессия. Делает этапы 0–7, пишет артефакты, выдаёт строку `/goal`. На этом его работа заканчивается. - **Исполнитель** — свежая `/goal`-сессия, которую запускает твоя вставка. У неё нет контекста планировщика: всё, что ей нужно, лежит в файлах на диске. ## Чем НЕ является (анти-коллизия) | Похоже на | Разница | |---|---| | `spec-writer` | Тот только *пишет документ* (spec/plan/brief), ничего не исполняет. goal-pipeline планирует И запускает исполнение под `/goal`. | | `ralph-loop` | In-session петля внутри текущей сессии, без хостового evaluator. goal-pipeline отдаёт работу хостовому `/goal` — отдельная сессия, отдельный оценщик завершения. | | `feature-dev` | Тяжёлый greenfield-флоу design→architecture→build с суб-агентами. goal-pipeline легче, brownfield-first, опирается на `/goal`. | ## Когда брать / когда не брать **Брать:** нетривиальная задача (≈ 3+ фазы, > часа работы) в существующем проекте, которую хочешь довести до конца без ручного пинка на каждом шаге — рефакторинг, миграция кода, новая фича поверх существующего, добавление тестов, сквозная правка по многим файлам. **Не брать:** - Задача < 1 часа / 1–2 файла → просто сделай её, не разворачивай машинерию. - Нужен только проектный документ → `spec-writer`. - Нужно просто покрутить одну петлю в текущей сессии → `ralph-loop`. - Крупный greenfield с нуля → `feature-dev`. ## Предусловия 1. **`/goal` включён** в этой сборке Claude Code (у тебя — да). Проверка: команда `/goal` принимается из ввода и появляется индикатор `◎ /goal active`. 2. **Git-репозиторий** — страховка. Прогон правит исходники автономно; без git откат болезненный. Если репо нет — предложи `git init` и первый коммит до старта. 3. **pwsh + понятные команды** проекта (build/type/lint/test) — `make`-цели или прямые команды (`ruff check .`, `pyright`, `pytest -q`, `python manage.py check`). ## Профили автономности Выбирается в этапе 0 (дефолт — **checkpoint-on-risky**). Профиль пишется в `STATE.md` и зашивается в условие `/goal`. | Профиль | Поведение | Когда | |---|---|---| | **checkpoint-on-risky** (дефолт) | Автономно гонит обычные фазы; перед **рискованной** фазой печатает `GP_HALT` и возвращает управление — ты смотришь и ре-диспатчишь `/goal`. | Дефолт для brownfield. Рутина идёт сама, необратимое — под подтверждением. | | **full-auto** | После ревью плана руки прочь до `GP_RUN_COMPLETE`; останавливается только на 3-strike блоке. | Низкорисковая задача (чистый рефакторинг под git, добавление тестов). | | **per-phase** | `GP_HALT` после каждой фазы. | Незнакомый/хрупкий код, где хочешь видеть каждый шаг. Почти ручной режим. | **Что считается «рискованной» фазой** (для checkpoint-on-risky) — фаза, чьи deliverables или mandatory-команды включают хоть одно: - миграции БД (`**/migrations/**`, Alembic `versions/`, `makemigrations`, `migrate`, `alembic upgrade`); - `git push`, любые деплой-команды (`vps-deploy`, `systemctl`, `rsync`, `scp` на сервер); - destructive операции с ФС/БД (массовое `Remove-Item`/`rm`, `DROP`, `TRUNCATE`, `flush`, удаление/переименование каталогов); - смена публичного контракта (сигнатуры API-эндпоинтов, формат ответа, схема внешнего интерфейса, breaking-change в библиотечном API). Всё остальное (правки логики, рефакторинг внутри модуля, тесты, шаблоны, стили) — не рискованное, идёт автономно. Локальная dev-машина + git = откат дёшев. --- ## Этап 0 — Контекст 1. **Профиль автономности** — спроси одним `AskUserQuestion`, если не задан явно (дефолт checkpoint-on-risky). Запиши в `STATE.md`. 2. **Git baseline** — `git rev-parse HEAD` (pwsh). Запиши в `STATE.md` как `Baseline ref:`; аудит диффает результат против него. Нет git → `no-git`, предложи инициализировать. 3. **Память** — определи memory-каталог и подгрузи индекс. Путь бери из того, что харнесс показывает в начале сессии (он зависит от проекта — `…\.claude\projects\\memory` с `MEMORY.md`). Прочитай `MEMORY.md`, выборочно подними релевантные задаче файлы (предпочтения по стеку, project-факты). Не тащи всё. Применённые факты вынеси в ревью плана как «Из памяти: …». --- ## Этап 1 — Интейк (0–2 вопроса) Эхо задачи в **одно предложение**. Затем — только **истинные пробелы**, которые recon + память + промт не закрывают (brownfield почти всегда отвечает на стек, команды, конвенции сам): - граница scope («только этот модуль, или смежные тоже?»); - совместимость («ломаем старый путь или держим backward-compat?»); - развилка при двух равноправных существующих паттернах. Если вопросов нет — скажи «Уточняющих вопросов нет, иду от промта + recon + памяти» и переходи к этапу 2. Микро-детали (имена, пути, формулировки) не спрашивай — они идут в ревью плана как предположения для правки в один клик. --- ## Этап 2 — Recon (штатными инструментами, без скриптов) Recon делает **планировщик сам** через `Glob`/`Grep`/`Read` и короткие pwsh-команды (`PowerShell`-инструмент) — никаких `.sh`. Определи: - **Стек и менеджер пакетов** — `pyproject.toml` / `requirements*.txt` / `Pipfile` / `package.json`; Django (`manage.py`) / FastAPI / aiogram / прочее. - **Команды build/type/lint/test** — из `Makefile` (цели), `pyproject.toml` (`[tool.ruff]`, `[tool.pytest]`, `[tool.mypy]`), CI-конфига. Зафиксируй точные строки — они станут mandatory-командами фаз. - **Релевантная область** — модули/файлы, которые задача затронет; существующие конвенции, которые новый код обязан повторить. - **Тонкие места** — есть ли тесты на затрагиваемый код (если нет → нужна safety-net фаза), есть ли миграции, есть ли публичные контракты. Выведи пользователю **сводку в 5 строк**: стек · менеджер · build/type/lint/test · затрагиваемая область · риск-зоны. Это доказывает, что ты понял проект до плана. --- ## Этап 3 — Декомпозиция на фазы Столько фаз, сколько реально нужно (нет фикс-лимита). Правила нарезки: - Каждая фаза **проверяема сама по себе** (билдится, проходит свои тесты, её можно показать как инкремент). - Явные **зависимости** между фазами. - **Safety-net первой** — если тесты на затрагиваемый код тонкие, первая фаза добавляет характеризующие тесты *до* изменения поведения (brownfield-страховка). - **Polish & Harden последней** — edge cases, error/empty/loading states, ввод, безопасность, перф, копирайт. Здесь «всё идеально» становится измеримым. Каждая фаза описывается полями: - **Имя** (≤ 5 слов, действие-первым: «Add characterization tests»); - **Зачем** (1 предложение); - **Deliverables** (конкретные файлы/функции, которые появятся); - **Критерии приёмки** (5–10 измеримых, yes/no — не «работает», а проверяемый предикат); - **Mandatory commands** (pwsh/make: что обязано пройти зелёным); - **Гейты** (вшитые навыки/команды по таблице ниже); - **Evidence** (что агент печатает в транскрипт как доказательство); - **Зависимости** (какие фазы должны быть готовы); - **Risky?** (да/нет — по определению из «Профили автономности»). ### Вшитые гейты по типу фазы Это главное отличие от голого `/goal` — пайплайн знает про **твой** toolkit. Гейты ставятся **точечно по типу фазы**, не на каждую (чтобы не жечь токены), и финальным sweep в Polish-фазе. | Если фаза трогает… | Вшить гейт в её VERIFY | |---|---| | миграции БД (`**/migrations/**`, Alembic) | `migration-safety-auditor` на дифф миграции → **фаза risky** (чекпоинт) | | код (любой) | `/code-review` на дифф фазы + типы (`pyright` / `make type`) | | auth, ввод, внешний контракт, секреты | `/security-review` на дифф фазы | | тесты как deliverable | `test-coverage-auditor` (assertions, моки, критический путь) | | Polish & Harden (финал) | финальный sweep: `/code-review` по всему диффу прогона; для «production-ready» — опц. `python-project-audit` (дорого, только по явному запросу) | Гейты вызываются **внутри** `/goal`-сессии через Skill-инструмент (они доступны исполнителю). Лёгкие проверки (build/type/lint/test) — каждую фазу; тяжёлые навыки — по таблице, точечно. --- ## Этап 4 — Артефакты прогона на диск Всё в `.goalrun/` в корне проекта (исполнитель читает их с диска — у `/goal` нет контекста планировщика). Напомни добавить `.goalrun/` в `.gitignore`. 1. **`.goalrun/ROADMAP.md`** — план: профиль автономности, baseline ref, список фаз с полями из этапа 3. 2. **`.goalrun/STATE.md`** — живой прогресс: `Status`, `Current phase`, `Baseline ref`, `Profile`, лог событий. Исполнитель обновляет после каждой фазы. 3. **`.goalrun/PROTOCOL.md`** — копия `references/executor-protocol.md` (цикл исполнителя, 3-strike, финальный аудит, маркеры, memory writeback). Исполнитель — свежая сессия; протокол обязан лежать на диске, а не в контексте планировщика. 4. **`.goalrun/phases/phase-N.md`** — по файлу-спеке на фазу. Любой длины (читается с диска, не идёт в аргумент `/goal`). Начинается маркер-блоком: ``` GP_PHASE_START Phase: of — <имя> Risky: Mandatory commands: Gates: <список вшитых гейтов или "none"> Acceptance criteria: Evidence required: <список> Depends on: <фазы или "none"> [... полное описание работы, критерии, требования к доказательствам ...] ``` Пример полной спеки фазы и готовой строки `/goal` — `references/phase-spec-example.md`. --- ## Этап 5 — Ревью плана (жёсткий гейт) Прогон идёт без надзора — это последний дешёвый момент поправить курс. **5a. Self-critique (один проход).** Перед печатью сводки ответь на 3 вопроса и покажи результат честно (находки ИЛИ «clean», не театр): 1. **Фальсифицируемость** — каждый критерий приёмки yes/no? Помечай «работает», «готово», «корректно» без измеримого предиката и **перепиши на месте** в `phase-N.md`. 2. **Атомарность** — нет ли фазы, которая втайне две (имя с «и», deliverables без общего verify-гейта)? 3. **Слабейшая зависимость** — где частичный провал каскадит хуже всего? **5b. Сводка** — компактно: число фаз · профиль автономности · список фаз (имя — однострочный deliverable, risky-фазы помечены ⚠) · стек и команды · ключевые предположения (правь любое) · топ-3 риска и митигейшн · что из памяти применено · находки self-critique · путь к артефактам. **5c.** `AskUserQuestion` с одним вопросом «Старт?» и конкретными режимами правки (не размытое «исправить план»): **Старт** · **Поправить предположение** · **Тронуть фазу** (критерии/scope/команды) · **Переструктурировать фазы**. При правке — примени, обнови артефакты, пере-покажи сводку, спроси снова. Не диспатчь `/goal`, пока не выбрано «Старт». Никогда не считай молчание подтверждением. --- ## Этап 6 — Pre-flight После «Старт» и **до** выдачи строки `/goal` прогони объединённый (дедуплицированный) набор mandatory-команд **один раз** через `PowerShell`. Это ловит уже-сломанный baseline (например `pytest` красный ещё до фазы 1). - Всё зелёное → запиши `Pre-flight green` в `STATE.md`, переходи к этапу 7. - Что-то красное → покажи падающую команду (код выхода + последние ~5 строк), верни меню этапа 5 с опцией **«Игнорировать pre-flight, диспатчить»** (вдруг чинить красный baseline — и есть задача фазы 1). Любой другой выбор → обычная правка плана. --- ## Этап 7 — Выдать строку `/goal` (одна вставка) Слэш-команды срабатывают **только от ввода пользователя** — планировщик не может запустить `/goal` сам. Поэтому этап 7 — честная передача в одну вставку. 1. Обнови `STATE.md`: `Status: READY_TO_DISPATCH`, `Current phase: 1`, baseline ref. 2. Проверь, что все `.goalrun/phases/phase-N.md` существуют и содержат маркер `GP_PHASE_START`. 3. Напечатай fenced-блок с **готовой строкой `/goal`** (условие короткое и измеримое от транскрипта, профиль зашит): ```` ``` /goal "Исполни фазы .goalrun/ROADMAP.md последовательно по профилю в .goalrun/STATE.md. Для каждой фазы прочитай .goalrun/phases/phase-N.md; сделай работу; прогони mandatory-команды и вшитые гейты; напечатай GP_PHASE_VERIFY (каждый критерий pass|fail + build/type/lint/test + результаты гейтов) затем GP_PHASE_DONE; обнови STATE.md. При провале критерия — 3-strike (probe → авто-ретрай → fix-спека инлайн → GP_HALT). Если профиль checkpoint-on-risky и следующая фаза Risky=yes (или профиль per-phase) — напечатай GP_HALT и верни управление, НЕ начиная фазу. После последней фазы прогони финальный аудит: перечитай ROADMAP.md, переrun mandatory-команды, проверь deliverables против рабочего дерева (baseline ref), на дыры — fix-спека инлайн (до 2 раундов), затем GP_AUDIT. Только после GP_AUDIT напечатай GP_RUN_COMPLETE. Done when GP_RUN_COMPLETE напечатан с одним GP_PHASE_DONE на фазу и GP_AUDIT перед ним, ИЛИ напечатан GP_HALT (вернуть управление)." ``` ```` 4. Под блоком — ровно одна строка инструкции: > **Вставь строку `/goal` выше в ввод, чтобы запустить прогон.** Дальше идёт > автономно (авто-ретрай, fix-спеки, аудит); на рискованных фазах остановится на > `GP_HALT` — посмотри и вставь ту же строку снова, чтобы продолжить. 5. **Стоп.** Больше ничего не выводи. Прогон начинается с вставки пользователя. --- ## Протокол исполнителя, маркеры, память Полный цикл исполнителя (чекпоинты, 3-strike восстановление, финальный аудит), таблица маркеров транскрипта (`GP_PHASE_START` … `GP_RUN_COMPLETE`) и правила memory writeback — в [references/executor-protocol.md](references/executor-protocol.md). Планировщик копирует его в `.goalrun/PROTOCOL.md` на этапе 4 — исполнитель читает протокол с диска, а не из контекста. --- ## Связанные навыки - `spec-writer` — если перед прогоном нужен проектный документ (spec/plan), напиши его, затем скорми goal-pipeline как вход. spec-writer не исполняет. - `ralph-loop` — альтернатива, когда хочешь in-session петлю без отдельной `/goal`-сессии и хостового оценщика. - `feature-dev` — для крупного greenfield с архитектурным дизайном. - `harness-engineering` — вшитые здесь гейты (migration-safety-auditor, /code-review, test-coverage-auditor, pyright) — те же, что harness-engineering кладёт в Definition of Done проекта. goal-pipeline исполняет DoD внутри прогона. - `migration-safety-auditor` / `techlead-ai` / `python-project-audit` / `test-coverage-auditor` — вызываются как гейты по типу фазы (таблица в этапе 3).