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/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-params.md" "$D/line-task.md" "$P/review-boilerplate.md" \
    "$P/runtime-language.md" > "$D/review-prompt-task.md"
    # вторая линия: line-code.md -> review-prompt-code.md;
    # одиночный ревьюер: line-rev.md -> review-prompt.md
cat "$P/triage-header.md" "$D/review-codex.md" "$D/review-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)

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

```text
Now switch roles: you are a reviewer of your own diff. Walk it against the
task's acceptance criteria and boundaries. Fix what you find, stay inside
the task scope. Return one line: SELF-REVIEW: found N, fixed N — plus one
phrase per unfixed item, if any.
```

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

Общий параметрический блок (`review-params.md`) один на обе линии и не
знает, кто его читает; линзу и префикс ID задаёт файл линии, поэтому
собранных промптов — по одному на линию, с разными путями. Куда класть
вердикт, задаёт обёртка вызова, и пути вердиктов у ревьюеров тоже разные
(иначе коллизия). Codex получает свой собранный файл через stdin (вердикт
= его `-o`-отчёт); Клод-субагенту в prompt — короткая английская обёртка:

```text
Read {{path to this line's review prompt}} and execute it. Working directory:
{{repo root}}. Write the full findings index to
{{$D/review-claude.md}} — it is outside the repo, so the mandate allows
it (via Write or a Bash heredoc, whichever you have). 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.)

```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}}
```

Файлы линий (`line-task.md` / `line-code.md`), по одному на слепую линию:

```markdown
## Your line
FINDING PREFIX: TASK
Lens: compliance with the statement, acceptance criteria, boundaries,
intended observable result.
Taste: formally correct but substantively wrong is a finding — work out of
proportion to the task, an added artifact that does not earn its
existence, a check that passes without proving its own claim. Grade a
taste finding by the cost of living with the code, not by whether it
breaks a test.
```

```markdown
## Your line
FINDING PREFIX: CODE
Lens: correctness, invariants, regressions, security, test honesty.
```

Одиночному ревьюеру (простая ступень шкалы этапа 4) — один `line-rev.md`
с обеими линзами и префиксом `REV`. По эмпирике прогонов естественное
распределение: Codex — CODE (дефекты нового кода), Клод — TASK (уровень
задачи и архитектуры).

Блок `Taste:` едет с **родословной**, а не с буквой линии: он адресован
Клоду (решение пользователя 2026-07-23, запись в
[lessons.md](lessons.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}}
```

Файл линии — тем же механизмом: только префикс (`SPEC-A` / `SPEC-B`,
одиночному обзору — `SPEC`); линза уже задана рамкой блока.

## 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). Если нет — резолюции по
его находкам передай текстом (только его находки, не весь отчёт).