dotfiles/agents/.agents/skills/claude-subagent-playbook/references/prompt-templates.md

# Сборка промптов конвейера

Постоянные блоки лежат готовыми файлами в
[prompts/](prompts/) — их не переписывают, а подшивают `cat`'ом прямо из
каталога скилла, через контекст оркестратора они не проходят вовсе:

- [prompts/review-boilerplate.md](prompts/review-boilerplate.md) — мандат
  ревьюера + формат индекса находок (этапы 2 и 4).
- [prompts/line-task.md](prompts/line-task.md) /
  [prompts/line-code.md](prompts/line-code.md) /
  [prompts/line-rev.md](prompts/line-rev.md) — файлы линий ревью: линза и
  префикс ID (две слепые линии / одиночный ревьюер).
- [prompts/line-taste.md](prompts/line-taste.md) — вкусовая линза с базой
  запахов Фаулера; подшивается к линии уместности (этап 4 SKILL.md).
- [prompts/self-review.md](prompts/self-review.md) — саморевью
  исполнителя (этап 3, resume тем же тредом).
- [prompts/triage-header.md](prompts/triage-header.md) — правила триажа
  для исполнителя (этап 5).
- [prompts/recheck-header.md](prompts/recheck-header.md) — узкая
  перепроверка (этап 5); может принести новую находку — это не нарушение
  узости, отправь её исполнителю тем же порядком.
- [prompts/result-contract.md](prompts/result-contract.md) — формат
  результата вспомогательных агентов (исследователь, fast-worker, раннер);
  исполнителю формат задаёт сам шаблон задачи.
- [prompts/runtime-language.md](prompts/runtime-language.md) — язык
  обмена (английский); подшивается в конец каждого собранного промпта,
  чтобы правило доехало до самих агентов.

Правила:

- **Обменные файлы — на английском** (правило SKILL.md): скелеты ниже уже
  английские. Русский — только формулировкам, попадающим в задачу-файл,
  коммиты и доклады пользователю.
- **Каталог прогона** — `$SCRATCH/<NN-slug>/` на задачу: `$SCRATCH` —
  временный каталог ОС (скретчпад сессии или `mktemp -d`), подпапка — чтобы
  обмен нескольких задач не сваливался в кучу. В репо не мусорит, ребут не
  переживает. Windows-кавеат из codex-exec.md в силе: путь —
  forward-slash, не голый `/tmp` Git Bash.
- Через Write оркестратор пишет **только параметрические блоки** ниже;
  секции «adapt» — по смыслу.

Сборка на прогон: `D="$SCRATCH/<NN-slug>"` — подпапка задачи; `P` —
`references/prompts` в базовом каталоге скилла (путь даётся в шапке
вызова скилла):

```bash
cat "$D/task-body.md" "$P/runtime-language.md" > "$D/task-prompt.md"
cat "$D/review-impl-params.md" "$P/line-task.md" "$P/line-taste.md" \
    "$P/review-boilerplate.md" "$P/runtime-language.md" \
    > "$D/review-prompt-task.md"
cat "$D/review-impl-params.md" "$P/line-code.md" \
    "$P/review-boilerplate.md" "$P/runtime-language.md" \
    > "$D/review-prompt-code.md"
    # одиночный ревьюер: line-rev.md (+ line-taste.md) -> review-prompt.md
    # line-taste.md едет с линией уместности — переставь, если её ведёт
    #   другая линия (назначение линий — этап 4 SKILL.md)
cat "$P/triage-header.md" "$D/review-impl-codex.md" \
    "$D/review-impl-claude.md" "$D/notes.md" "$P/runtime-language.md" \
    > "$D/fix-prompt.md"
    # notes.md опционален — нет, так не включай
cat "$P/recheck-header.md" "$D/recheck-params.md" \
    "$P/runtime-language.md" > "$D/recheck-prompt.md"
```

## 1. Задача исполнителю (`codex exec`, workspace-write)

Напиши параметрический текст в `$D/task-body.md`; финальный
`$D/task-prompt.md` собирается `cat`'ом с хвостом языка (сборка выше) —
под этим именем его ждут примеры codex-exec.md.

```markdown
# Task: {{ticket/goal in one line}}

Working directory: repo root {{repo}}. Branch {{branch}} — stay on it.

## What to do
Implement {{ticket NN}} from {{path to task file}}. The task is
self-contained: follow it literally; checkboxes are the acceptance
criteria. If something seems wrong — implement as written and flag the
doubt in your report.

## Read first (mandatory, before any code)
{{numbered list: task file, spec, code samples, conventions}}

## Order and discipline
{{adapt: TDD, layer order, test command}}

## End-to-end check   <-- опционально: только если в репо есть дешёвый сквозной прогон
Run {{command}} before finishing. If it is unavailable in your sandbox
(docker, live stand) — say so explicitly in the report: the orchestrator
will run it before the reviews start.

## Boundaries (do not touch)
- **No commits.** No `git commit` / `git add`.
{{adapt: stubs, foreign code, existing tests, files outside the repo}}

## Final report (return this)
1. Files changed, one-line "why" each.
2. Test command and result (counters, all green).
3. Checkboxes: which are closed, which are not and why.
4. Doubts, if any.
```

## 1а. Саморевью исполнителя (resume тем же тредом, effort medium)

Отдельным ходом после отчёта о реализации, до внешних ревью — смена рамки
«автор → критик» отдельным ходом ловит больше, чем финальный пункт
чек-листа в промпте задачи. Текст готов файлом:

```bash
cat "$P/self-review.md" | codex exec resume <thread-id> ...
```

Опус-исполнителю (`craftsman`) — тот же файл продолжением его треда:
запускай его с `name` и шли SendMessage
«read and execute $P/self-review.md».

## 2. Ревью: общий блок + файл линии

Общий параметрический блок (`review-impl-params.md`) один на обе линии
этапа и не знает, кто его читает; линзу и префикс ID задаёт файл линии,
поэтому собранных промптов — по одному на линию, с разными путями. Куда
класть вердикт, задаёт обёртка вызова, и пути вердиктов у ревьюеров тоже
разные (иначе коллизия). **Имя вердикта несёт этап, а не линию**:
`review-impl-<семейство>.md` на этапе 4, `review-spec-<семейство>.md` на
этапе 2. Линии внутри этапа различает семейство — их и назначают разным;
совпало семейство (замена молчащего) — путь задаёшь руками, правило ниже.
Этап в имени нужен потому, что `$D` у задачи один на весь прогон: под
общим именем вердикт этапа 4 лёг бы поверх вердикта этапа 2, а упавшая
линия этапа 4 оставила бы файл этапа 2 на месте — и триаж молча ушёл бы
чинить по чужому вердикту. Разные имена делают такой отказ громким:
сборка `fix-prompt.md` падает на `cat`. Codex получает свой собранный
файл через stdin (вердикт = его `-o`-отчёт); Клод-субагенту в prompt —
короткая английская обёртка:

```text
Read {{path to this line's review prompt}} and execute it. Working directory:
{{repo root}}. Write the findings index to
{{$D/review-<spec|impl>-claude.md}} — it is outside the repo, so the
mandate allows it (via Write or a Bash heredoc, whichever you have).
Append each finding to that file as you go — incremental writing keeps a
partial index alive if the session dies. Keep the index strict: ONE line
per finding and per confirmation, as the boilerplate demands — no
multi-line entries. Final
message: ONLY the VERDICT line, severity counters and the file path.
```

(Однострочность продублирована в обёртке не случайно: boilerplate это уже
требует, но Клод-семейство держит формат хуже Codex — эмпирика
2026-07-12/13, многострочные находки и развёрнутые confirmations.)
Замене молчащего ревьюера давай **другой** путь вердикта — правило в
«Сбоях координации» SKILL.md.

```markdown
# Code review: {{ticket NN — essence}}

You are an independent adversarial reviewer. Working directory: repo root
{{repo}}, branch {{branch}}.

## What you review
{{task file + spec; what is already committed and NOT under review}}
Changes under review: {{exact paths, prepared diff path, or diff command —
must let the reviewer tell reviewed work from unrelated tree noise}}
Test command (expect {{N}} passed): {{command}}

## Focus
{{adapt: 2–3 extra points for this task — math/edge cases, artifacts,
shared code}}
```

Файлы линий — готовые константы в `prompts/`, оркестратор их не
перепечатывает: `line-task.md` (уместность: постановка, критерии,
границы), `line-code.md` (дефекты: корректность, инварианты, регрессии),
одиночному ревьюеру — `line-rev.md` (обе линзы, префикс `REV`).
Осторожно с именем: `task` — это **линия уместности этапа 4** (префикс
`TASK`), а не ревью постановки; ревью постановки — этап 2 с префиксами
`SPEC-*` и своими именами файлов (ниже).
Вкусовая линза с базой запахов — `line-taste.md`; она едет с **линией
уместности** (её ведёт модель со вкусом — назначение линий в этапе 4
SKILL.md), поэтому разрез — выбором файла в `cat`, не пересказом
границы. Стенд делится между линиями? Явный запрет ломающих команд
второй линии — отдельным параметрическим файлом `$D/access-<line>.md`,
подшитым после файла линии (правило — этап 4 SKILL.md).

Вариант для **этапа 2** (ревью постановки, кода изменений ещё нет) — тот же
boilerplate, другой параметрический блок:

```markdown
# Spec review: {{ticket NN — essence}}

You review a TASK STATEMENT, not an implementation. Go into implementation
details only where the statement silently pre-decides a solution. The task
goes to an implementer with no session context — they will do literally
what is written. Working directory: repo root {{repo}}, branch {{branch}}.

## What you review
Statement: {{path to task file}}. Related context (not under review):
{{parent PRD, sibling tickets}}.
Code to check the statement's facts against: {{file list with why}}

## Focus
{{adapt: facts vs code, hidden one-liner decisions/forks, acceptance
criteria checkable and gameable?, observability}}
```

Файл линии здесь — двухстрочный Write (`## Your line` +
`FINDING PREFIX: SPEC-A|SPEC-B|SPEC`): константного файла нет
намеренно — префикс варьируется, а линза уже задана рамкой блока.
Имена этапа: блок — `review-spec-params.md`, промпты —
`review-prompt-spec-<a|b>.md`, вердикты — `review-spec-<семейство>.md`.

## 3. Параметрические хвосты триажа и перепроверки

`notes.md` (опционально, коротко, по-английски): фактура, которой нет у
исполнителя, решения уровня задачи (вне скоупа / принять риск), приоритеты.

`recheck-params.md` — три строки:

```markdown
Implementer's report with resolutions: read {{$D/fix-result.md}}.
Test command (expect {{N}} passed): {{command}}
```

Вердикт узкой перепроверки Клода бери прямо из строки task-notification —
обёртка требует финальным актом только VERDICT-строку; файл перепроверки
читай лишь при `ISSUES_REMAIN` или споре (эмпирика 2026-07-13: экономит
чтение без потерь).

Кавеат: проверь, что Codex-ревьюер может читать `$SCRATCH` из песочницы
(temp-каталоги обычно читаемы в workspace-write). Если нет — резолюции по
его находкам передай текстом (только его находки, не весь отчёт).