dotfiles/agents/.agents/skills/codex-review/SKILL.md

name, description, user_invocable

name	description	user_invocable
codex-review	Ревью плана или кода через OpenAI Codex. Автодетект режима, итеративные правки до одобрения.	true

Итеративное ревью через Codex

Отправляет текущую работу в OpenAI Codex на adversarial-ревью. Автоматически определяет, что ревьюить: план или код. Claude правит по замечаниям Codex и переотправляет до одобрения. Максимум 5 раундов.

---

Когда вызывать

• /codex-review — автодетект что ревьюить
• /codex-review plan — принудительно ревью плана
• /codex-review code — принудительно ревью кода
• /codex-review <путь-к-файлу> — ревью конкретного файла (аргумент содержит / или .)
• Переопределение reasoning: /codex-review xhigh или /codex-review low (одно из: none, low, medium, high, xhigh)
• Переопределение модели: /codex-review model:gpt-5.3-codex (аргумент с префиксом model:)

Инструкции

Плейсхолдеры: ${REVIEW_ID} и ${CODEX_SESSION_ID} в шагах ниже — это шаблонные плейсхолдеры, НЕ shell-переменные. Подставляй литеральные значения напрямую в каждый tool call.

Шаг 1: Определить режим ревью

Определи, что ревьюить, по контексту и аргументам:

Автодетект (без явного аргумента):

1. Проверь git diff --stat и git diff --cached --stat на наличие изменений кода.
2. Проверь, есть ли план в текущем контексте разговора (из plan mode, задач или обсуждения).

Изменения кода?	План в контексте?	Режим
Нет	Да	plan — ревью плана
Да	Да	code-vs-plan — ревью реализации против плана
Да	Нет	code — ревью изменений кода
Нет	Нет	Спросить пользователя, что ревьюить

Явные аргументы имеют приоритет над автодетектом: plan, code или путь к файлу.

Шаг 2: Сгенерировать Session ID

Сгенерируй уникальный REVIEW_ID самостоятельно, формат: {unix_timestamp}-{случайное_4значное_число}. Пример: 1711872000-4821. НЕ используй bash — подставляй значение напрямую в команды следующих шагов.

Шаг 3: Подготовить материал для ревью

Ревью плана:

• Если план уже существует как файл (в project/, memory или где-то в репо) — использовать путь напрямую. НЕ копировать.
• Если план только в контексте разговора — записать через Write tool в /tmp/claude-plan-${REVIEW_ID}.md.
• Обязательно вывести путь к файлу плана пользователю, чтобы он мог открыть его в IDE: 📄 План для ревью: <путь-к-файлу>

Ревью кода:

Собрать diff — выполняй по одной команде, используй первый непустой результат:

1. git diff — unstaged changes
2. Если stdout пуст — git diff --cached — staged changes
3. Если пуст — git diff main...HEAD — все коммиты ветки

Каждую команду запускай отдельным Bash tool call (без перенаправлений). Результат (stdout первой непустой команды) сохрани через Write tool в /tmp/claude-diff-${REVIEW_ID}.diff.

Если все три пусты — нет изменений для ревью, сообщи пользователю.

Большие diff-ы (best-effort preflight): перед захватом полного diff проверь размер через --shortstat в том же порядке приоритета, что и основной diff:

1. git diff --shortstat — если непусто, оценивай по нему
2. Если пусто — git diff --cached --shortstat
3. Если пусто — git diff main...HEAD --shortstat

Вывод вида 3 files changed, 4200 insertions(+), 100 deletions(-). Если insertions + deletions > 1500 — останови сбор diff, сообщи пользователю что полный diff может быть обрезан Bash tool, и потребуй использовать /codex-review <путь> для конкретных файлов. НЕ продолжай с потенциально неполным diff — частичное ревью хуже, чем отсутствие ревью. Это best-effort проверка: --shortstat считает строки, а не байты. Diff с малым числом очень длинных строк (минифицированный JSON, lockfile) может пройти порог, но быть огромным по размеру.

Ревью кода против плана: подготовить и путь к плану, И diff.

Шаг 4: Сформировать промпт и запустить первый раунд

Сформируй промпт в зависимости от режима:

Промпт для ревью плана:

Review the implementation plan in <plan-path>. Focus on:
1. Correctness — will this plan achieve the stated goals?
2. Risks — what could go wrong? Edge cases? Data loss?
3. Missing steps — is anything forgotten?
4. Alternatives — is there a simpler or better approach?
5. Security — any security concerns?

Промпт для ревью кода:

Review the code changes in <diff-path>. You can also read the full files in the repo for context. Focus on:
1. Bugs — logic errors, off-by-one, null handling, race conditions
2. Edge cases — what inputs or states could break this?
3. Style — does the code follow existing project conventions?
4. Security — injection, credential exposure, unsafe operations
5. Tests — is the change adequately tested?

Промпт для ревью кода против плана:

Review the code changes in <diff-path> against the implementation plan in <plan-path>.
You can also read the full files in the repo for context. Focus on:
1. Completeness — does the implementation cover all plan steps?
2. Deviations — where does the code differ from the plan? Are deviations justified?
3. Bugs — logic errors, edge cases, null handling
4. Security — injection, credential exposure, unsafe operations
5. Missing — what from the plan is not yet implemented?

Все промпты заканчиваются:

Be specific and actionable. Reference file paths and line numbers where possible.

If the work is solid and ready, end your review with exactly: VERDICT: APPROVED
If changes are needed, end with exactly: VERDICT: REVISE

Запуск Codex — шаблон команды:

Флаги:

• -m gpt-5.4 — модель (переопределяется аргументом model:...)
• -c model_reasoning_effort=high — глубина рассуждения (переопределяется аргументом xhigh, low и т.д.)
• -s read-only — Codex только читает, не пишет
• -o /tmp/codex-review-${REVIEW_ID}.md — файл для записи ответа

timeout 600 codex exec \
  -m gpt-5.4 \
  -c model_reasoning_effort=high \
  -s read-only \
  -o /tmp/codex-review-${REVIEW_ID}.md \
  "ПРОМПТ"

Важно:

• Всегда оборачивай codex exec в timeout 600 (10 минут). Если Codex зависнет — команда завершится с кодом 124.
• Используй параметр timeout: 620000 в Bash tool для запаса.
• Команда синхронная: когда она вернулась, файл -o уже готов. НЕ используй poll-loop (while/sleep).
• Если exit code = 124 (таймаут) — сообщи пользователю и предложи повторить.

Пример для режима code (diff в temp-файле):

timeout 600 codex exec \
  -m gpt-5.4 \
  -c model_reasoning_effort=high \
  -s read-only \
  -o /tmp/codex-review-${REVIEW_ID}.md \
  "Review the code changes in /tmp/claude-diff-${REVIEW_ID}.diff. You can also read the full files in the repo for context. Focus on:
1. Bugs — logic errors, off-by-one, null handling, race conditions
...
If changes are needed, end with exactly: VERDICT: REVISE"

После запуска: найди в выводе строку session id: <uuid> и сохрани значение как CODEX_SESSION_ID — оно нужно для resume в последующих раундах.

Примечания:

• Модель по умолчанию: gpt-5.4 с model_reasoning_effort=high. Пользователь может переопределить через аргументы.
• Всегда -s read-only — Codex не должен писать файлы.
• -o для захвата вывода в файл. НЕ запускай в background — команда сама вернёт управление.

Шаг 5: Прочитать ревью и проверить вердикт

1. Прочитать /tmp/codex-review-${REVIEW_ID}.md
2. Показать пользователю:

## Codex Review — Раунд N (режим: <plan|code|code-vs-plan>, модель: gpt-5.4)

[Отзыв Codex]

3. Проверить вердикт:
   • VERDICT: APPROVED → перейти к Шагу 8 (Готово)
   • VERDICT: REVISE → перейти к Шагу 6 (Правки)
   • Нет явного вердикта, но всё позитивно → считать одобренным
   • Достигнут максимум (5 раундов) → перейти к Шагу 8 с пометкой

Шаг 6: Внести правки

По замечаниям Codex:

Для ревью плана: исправить план — адресовать каждое замечание. Обновить файл плана (или temp-файл). Показать пользователю:

### Правки (Раунд N)
- [Что изменено и почему, один пункт на замечание]

Для ревью кода: исправить код напрямую — редактировать файлы, запустить тесты если применимо. Показать пользователю:

### Исправления (Раунд N)
- [Что исправлено и почему, один пункт на замечание]

Пропустить правку, если она противоречит явным требованиям пользователя — отметить это для пользователя.

Шаг 7: Переотправить в Codex (Раунды 2-5)

Предпочтительно: resume — экономит токены, сохраняет контекст сессии:

1. Запусти (без перенаправлений):

timeout 600 codex exec resume ${CODEX_SESSION_ID} \
  "I've revised based on your feedback.

Here's what I changed:
[Список правок]

Please re-review. End with VERDICT: APPROVED or VERDICT: REVISE"

Используй timeout: 620000 в параметрах Bash tool.

2. Bash tool захватывает и stdout, и stderr. Проверь результат по exit code:
   • exit 0 — успех. Сохрани stdout через Write tool в /tmp/codex-review-${REVIEW_ID}.md. Проверка полноты: убедись что последняя непустая строка stdout — это ровно VERDICT: APPROVED или VERDICT: REVISE. Если вердикт отсутствует или не на последней строке — вывод мог быть обрезан; перейди к Fallback (свежий codex exec -o, который пишет напрямую в файл без риска truncation).
   • exit 124 — таймаут. Сообщи пользователю: "Codex не ответил за 10 минут" и предложи повторить (аналогично шагу 4).
   • другой exit code — покажи пользователю stderr/stdout для диагностики, затем перейди к Fallback.

Примечание: resume не поддерживает -o, поэтому вывод идёт в stdout Bash tool. Затем читай файл как обычно (Шаг 5).

Fallback — если resume не сработал (сессия истекла, session ID не захвачен):

1. Пересобрать diff (аналогично Шагу 3).
2. Запустить свежий codex exec -o с описанием предыдущих раундов в промпте.

Вернуться к Шагу 5.

Шаг 8: Итоговый результат

Одобрено:

## Codex Review — Итог (режим: <режим>, модель: gpt-5.4)

**Статус:** ✅ Одобрено после N раунд(ов)

[Итоговый отзыв]

---
**Проверено и одобрено Codex. Ожидает вашего решения.**

Достигнут максимум раундов:

## Codex Review — Итог (режим: <режим>, модель: gpt-5.4)

**Статус:** ⚠️ Достигнут максимум (5 раундов) — не полностью одобрено

**Оставшиеся замечания:**
[Нерешённые вопросы]

---
**У Codex остались замечания. Просмотрите их и решите, как действовать дальше.**

Шаг 9: Очистка

rm -f /tmp/claude-plan-${REVIEW_ID}.md /tmp/claude-diff-${REVIEW_ID}.diff /tmp/codex-review-${REVIEW_ID}.md

НЕ удалять файлы планов, которые существовали до ревью (только temp-файлы, созданные этим скиллом).

Правила

• Claude активно правит по замечаниям Codex — это НЕ просто передача сообщений
• Автодетект режима ревью по контексту; аргументы пользователя имеют приоритет
• Предпочитать существующие файлы, не создавать лишние копии
• Всегда read-only sandbox — Codex никогда не пишет файлы
• Максимум 5 раундов для защиты от бесконечных циклов
• Показывать пользователю отзывы и правки каждого раунда
• Если Codex CLI не установлен или упал — сообщить пользователю: npm install -g @openai/codex
• Если правка противоречит явным требованиям пользователя — пропустить и объяснить почему