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

---
name: codex-review
description: Ревью плана или кода через OpenAI Codex. Автодетект режима, итеративные правки до одобрения.
user_invocable: 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:`)

## Инструкции

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

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

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

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

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

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

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

```bash
REVIEW_ID="$(date +%s)-${RANDOM}"
```

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

**Ревью плана:**

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

**Ревью кода:**

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

```bash
# 1. Unstaged changes
git diff > /tmp/claude-diff-${REVIEW_ID}.diff

# 2. Если пусто — staged changes
if [ ! -s /tmp/claude-diff-${REVIEW_ID}.diff ]; then
  git diff --cached > /tmp/claude-diff-${REVIEW_ID}.diff
fi

# 3. Если пусто — все коммиты ветки относительно main
if [ ! -s /tmp/claude-diff-${REVIEW_ID}.diff ]; then
  git diff main...HEAD > /tmp/claude-diff-${REVIEW_ID}.diff
fi
```

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

**Ревью кода против плана:** подготовить и путь к плану, И 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` — файл для записи ответа

```bash
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-файле):

```bash
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`** — экономит токены, сохраняет контекст сессии:

```bash
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" > /tmp/codex-review-${REVIEW_ID}.md 2>&1
```

**Примечание:** `resume` не поддерживает `-o`. Вывод перенаправляется в файл через `>`. Затем читай файл как обычно (Шаг 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: Очистка

```bash
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`
- Если правка противоречит явным требованиям пользователя — пропустить и объяснить почему