Main no longer Reads references/runner.md. The Agent prompt now
passes RUNNER_SPEC_PATH as a short bootstrap instruction; the
subagent Reads the spec itself. Saves ~12K per round from main
context (Read result + inlined-spec duplication in Agent prompt).
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
AGENTS.md gets a new Architecture section with boundary
invariants. DESIGN.md §12 explains the residue problem, the
Agent-tool split, and why Haiku is sufficient for the runner.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Reflects the new main + runner split. Removes rules that now
live exclusively in references/runner.md (ATTEMPT_ID generation,
two-tier session capture, strict check order). Adds two new
/tmp paths to Step 9 cleanup: codex-body and codex-runner-result.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Step 7 now delegates codex-exec-resume to the runner. Fallback
path (resume failure → fresh exec) also goes through the runner
with OPERATION=fresh-exec. Severity classification and user
interaction stay in main thread.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Round-3 spec review finding — the RUNNER_SPEC_PATH resolver
must explicitly warn against attempting to extract the path
from the "Base directory for this skill:" header, which is
a system injection Claude cannot reliably read.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Replaces inline codex-exec + strict checks + session-id capture
in Step 4 with Agent tool dispatch. Runner spec lives in
references/runner.md. Main thread reads only the final review file
(~5K) instead of stdout/stderr/rollout artifacts (~48M residue).
Also updates Step 5 "VERY NEXT MESSAGE" wording to permit a
preceding one-line user_warning diagnostic message.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Defines input/output JSON contract, step-by-step mechanics, and
cleanup ownership for the thin Haiku runner.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
- Зачем:
- конвенция AGENTS.md (codex, aider и др. агенты её автодетектят) даёт свежему агенту быструю навигацию по репо без прочтения всех 50 KB DESIGN.md перед началом работы.
- Что:
- Короткий (~25 строк) pointer-файл: one-paragraph what-is-this, три main-docs с one-line описанием, три "don't"-правила про cross-refs / session marker / silent-recovery, верификация через §7 smoke-test + dogfood.
- Всё содержательное остаётся в DESIGN.md; AGENTS.md только ориентирует.
- Проверка:
- Файл существует, читаем, ссылается на реальные §-номера в DESIGN.md (§4.1b, §6.7, §6.8, §7, §9.6, §10).
- Зачем:
- round-5 adversarial review (claude-team-review) нашёл 2 HIGH и 3 MEDIUM, которых не увидел round-4 self-review. Основное — регрессия в b213678, где при рефакторе primary-path silently дропнуло malformed-JSON-first-line handling, и противоречие в Step 7 step 4 между «same approach as Step 4 check 4» и «keep previous id».
- Что:
- SKILL.md Step 4 check 4: primary-path с явными ветками — valid UUID → save; любой другой случай (empty / malformed / missing thread_id / partial output) → fallthrough на secondary. Secondary описан как двухпричинный (sandbox suppression + format drift), не только «0 bytes».
- SKILL.md Step 7 step 4: явно разведено с Step 4 check 4 — zero-find в resume НЕ абортит round, а keep previous CODEX_SESSION_ID (§2.4.4 гарантирует что thread id не ротируется). Добавлен warning-сообщение.
- SKILL.md Step 2/4/7/Rules: убран `echo $(($(date +%s) - 1))` Bash-вызов, timestamp считается Opus'ом в reasoning и подставляется литералом. Убирает compound-command permission-матч проблему (`$()` + `- 1` арифметика) и один Bash-круг на раунд.
- SKILL.md Step 7 fresh-exec fallback: архивирует failed-resume артефакты через `mv` в `*-failed-resume.{jsonl,txt}` ПЕРЕД fresh exec. Step 9 cleanup glob расширен.
- DESIGN.md §9.5: cross-ref «Step 4 check 3» → «Step 4 check 4».
- DESIGN.md §4.1 trade-offs: описание CODEX_SESSIONS_BEFORE переписано под in-reasoning capture.
- README.md: убрана `Bash(date +%s)` permission, добавлены `Bash(mv ...)` для архивации.
- Проверка:
- Повторно прогнать self-review с фокусом на: (а) понятен ли novice reader malformed-case fallthrough, (б) не противоречит ли Step 7 step 4 Step 4 check 4 после правки.
- Зачем:
- `-newermt "@<epoch>"` и `-printf` в secondary session-id capture — GNU-специфичные; на macOS BSD find они не работают, а тестировать на маке негде.
- Что:
- SKILL.md: добавлена one-paragraph platform note рядом с `find` — формулирует цель шага ("найти свежие rollout-файлы, выбрать последний, извлечь UUID") и приглашает Opus/пользователя подставить BSD-эквивалент.
- docs/DESIGN.md §9.5: новое known-limitation с обоснованием template+understanding подхода вместо platform-detection.
- README.md Known limitations: user-facing note, что end-to-end на macOS не тестировался.
- Проверка:
- Ничего не ломается на Linux (команды без изменений).
- На macOS оператор читает note и адаптирует.
- Зачем:
- Opus последней версии выполняет инструкции буквально; длинный пайплайн `find | sort | tail -1 | xargs basename | grep -oE UUID` создаёт permission-матчинг проблему (Claude Code матчит всю команду с пайпами) и не оставляет модели свободы адаптироваться к среде.
- Что:
- SKILL.md Step 4 check 3 secondary: один `find -printf '%T@ %f\n'`, парсинг отдан ведущему (Claude выбирает max-mtime и извлекает UUID из filename).
- SKILL.md Step 7 check 4: компактная ссылка на ту же логику Step 4, без дублирования пайплайна.
- README.md permission упрощён до `Bash(find ~/.codex/sessions*)` — матчит любой find в правильном поддереве.
- Проверка:
- `find ~/.codex/sessions -name 'rollout-*.jsonl' -newermt "@$(date -d '-1 minute' +%s)" -printf '%T@ %f\n'` на живой среде возвращает 0+ строк, парсятся корректно.
- Зачем:
- остатки документации ссылались на `- < file` и старый одноуровневый session-id, расходились с SKILL.md после основной правки.
- Что:
- §3.2 теперь рекомендует `cat file | cmd -` со ссылкой на §4.13.
- §7.2 smoke-test resume переведён на pipe-форму и включает secondary filesystem session-id capture.
- §7.3 (bad-UUID) тоже на pipe-форме для изоляции от §6.6.
- §2.5 разделяет success-row на reference и affected окружения, добавлен row для `- < file` exit-1-empty-stderr.
- Проверка:
- `grep -n '\- < ' docs/DESIGN.md` остаются только контекстные упоминания (§2.1 описание обеих форм, §4.13 decision, §6.6 lesson, §8 log).
- Зачем:
- форма `codex exec ... - < file` exit=1 с пустым stderr, а `--json` stdout оказывается пустым в части Claude Code песочниц; без обхода скилл не может захватить session ID и теряет resume на раундах 2-5.
- Что:
- SKILL.md Step 4/7 переведены на `cat file | codex exec ... -` как canonical; добавлен two-tier захват session ID (primary = first JSONL line, secondary = UUID из имени `~/.codex/sessions/**/rollout-*.jsonl` с mtime > CODEX_SESSIONS_BEFORE).
- README.md обновлены permissions (pipe-форма, `find rollout-*`, `date +%s`) и добавлен troubleshooting про env-specific пустой JSONL.
- docs/DESIGN.md: §2.1 описывает обе формы, §2.2 фиксирует env-specific suppression, §2.3 добавляет filesystem-recovery путь, §4.1 переделан на two-tier decision, добавлены §4.13 (canonical pipe) и §6.6 (lesson от 2026-04-17), в §8 новая строка с окружением yantar-k8s.
- Проверка:
- DESIGN.md §7.1 smoke test (обновлён на pipe-форму + проверка filesystem secondary path).
- Оба окружения (reference WSL2 + containerized sandbox) должны давать валидный session ID и успешный resume.
1082-line design note covering:
- Empirical facts about Codex CLI 0.121.0 (invocation, streams,
resume semantics, known failure modes) with copy-pasteable
verification commands.
- Claude Code harness facts (Bash truncation, cwd drift, Opus
literal-interpretation tendencies).
- 12 design decisions in a uniform format: what, where in SKILL.md,
alternatives considered, why chosen, trade-offs accepted.
- Rejected ideas (marker files, per-round naming, $(pwd), etc.) with
reasons, so future contributors don't re-propose them.
- Prior diagnostic errors from a previous agent-auditor's dump that
turned out to be wrong when verified, kept as a methodological
lesson.
- Smoke-test protocol (§7) with concrete commands and expected
outputs so any maintainer can verify the Codex contract still holds
in minutes.
- Update protocol: when and how to revise this file, with a pointer
that future Opus generations interpret instructions more literally
and SKILL.md hardening must track that.
- Mermaid flow diagram of the round-trip.
Intended audiences: future Claude sessions resuming work on the skill,
human developers, and new contributors. The file is self-contained —
does not rely on conversation history that produced the current design.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Address 10+ findings from two rounds of adversarial review of the
previous Step 4/5/7 design. Major changes:
- Use `codex exec --json` so `thread_id` can be parsed deterministically
from the first JSONL line on stdout (bypasses the ~30KB Bash-tool
truncation that could drop stderr metadata in the old flow).
- Capture REPO_ROOT via `git rev-parse --show-toplevel` at Step 2 and
substitute the absolute path literally. Pin the initial exec with
`-C "${REPO_ROOT}"` and prefix every resume with `cd '${REPO_ROOT}' &&`
because `codex exec resume` has no `-C` flag and inherits cwd from
the invoking shell.
- Drop `resume --last` from the fallback chain (cwd filtering is not
enough to distinguish our session from unrelated parallel codex runs).
- Update CODEX_SESSION_ID only on full success (exit 0, no stderr error
line, review file contains VERDICT and findings on REVISE); rotate
to the resumed session's new thread_id each round.
- Harden the "show review" gate (Step 5 "YOUR NEXT MESSAGE" instruction
and Step 6 precondition check) now that --json stdout no longer leaks
review text into the Bash tool result.
- Add strict check order for launch and resume (exit → stderr → review
file) so we never commit a broken session-id on a half-failed run.
- Replace silent fresh-exec fallback with interactive ask / headless
severity-based decision. Fresh-exec prompt rebuilds prior rounds from
conversation history.
- Bare repo / submodule / shell-hostile paths abort at Step 2 with a
clear message rather than failing silently later.
- Conditional cleanup: keep temp files on abort paths for diagnostics.
- Expand REVIEW_ID random to 8 digits.
README: update permissions (add stdout JSONL read, resume-prompt write,
narrower `cd * && ... codex exec resume *` pattern) and troubleshooting
(NOT VERIFIED outcome, bare repo, submodule).
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
When the skill is available in shared ~/.agents/skills/, Codex CLI
picks it up and tries to follow its instructions — launching itself
recursively. The blockquote explains the architectural constraint
and tells Codex to review directly instead.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
- Fix recommended permissions: add missing Write(/tmp/codex-prompt-*),
remove overbroad rm rule (cleanup is best-effort)
- Rename claude-plan-* → codex-plan-* so all temp files share codex-* prefix
- Extract session ID via Read tool instead of grep (no extra permission needed)
- Add UUID format spec for session ID validation
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
- Add Plan Mode /tmp write limitation to SKILL.md (Step 4) and README
- Document that `codex exec resume` inherits sandbox from original session
- Remove none/low reasoning effort options (minimum is now medium)
- Add .claude to .gitignore (plan files from testing)
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
- Зачем:
- длинные XML-промпты (60+ строк) ломали shell quoting при inline-передаче в codex exec.
- session ID терялся из-за 2>/dev/null на stderr, делая resume невозможным.
- Что:
- промпт записывается в temp-файл, передаётся через stdin: `codex exec ... - < file`.
- stderr перенаправлен в temp-файл, session ID извлекается через grep.
- resume унифицирован: тот же stdin-механизм вместо inline-аргумента.
- fallback fresh exec явно обновляет CODEX_SESSION_ID.
- cleanup дополнен новыми temp-файлами (prompt, stderr).
- Проверка:
- smoke test: plan review → 2 раунда с resume через session ID — OK.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
- Why:
- English makes the skill accessible to a wider audience
- Permission prompts on every git/codex call hurt UX
- What:
- Translated all SKILL.md instructions and rules to English
- Added recommended permissions section to README
- Removed literal ## from output_format to avoid Claude Code
security warning about # in quoted arguments
- Removed overly broad Bash(codex *) permission rule
- Added explicit note about codex exec scope limitations
- Verify:
- /adversarial-review produces structured output with markdown headers
- No "Newline followed by #" security warning on codex exec
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Fixes from adversarial code-vs-plan review (3 rounds):
- Verdict format in prompts now matches parser (bare tokens)
- Missing verdict treated as parse failure, not approval
- README: softened backend swappability to "designed for extensibility"
- Example: replaced incorrect FK scenario with valid transaction bug
- Example: aligned fixes and round-2 summary with round-1 finding
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Baseline copy of the working codex-review SKILL.md from dotfiles
before adversarial prompt rewrite and rebranding.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
ddadminandGitHub
