ddmitry/adversarial-review
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: rewrite README for agent-friendly setup, expand permissions

Browse Source 
- Restructure installation as step-by-step Quick Start with verification commands
- Expand permissions list: add Read(/tmp/codex-review-*), Read(/tmp/codex-stderr-*),
  Bash(rm -f /tmp/codex-*), Bash(tee *)
- Add guidance on global vs project config for permissions
- Add Troubleshooting section (model errors, timeouts, resume, Plan Mode)
- Add authentication docs (ChatGPT login vs CODEX_API_KEY)

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This commit is contained in:
ddadmin
2026-04-16 17:56:28 +03:00
co-authored by Claude Opus 4.6
parent 899591ebf0
commit 5966e2a388
1 changed files with 126 additions and 77 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+126 -77
View File
@@ -17,25 +17,15 @@ through an external AI model (currently OpenAI Codex).
## Key features
**Two stages** — works on both planning and implementation:
- **Plan review** — review the plan BEFORE writing code. Catch architecture
mistakes, missing steps, and risks early
- **Code review** — review the implementation. Bugs, security, data loss
- **Code-vs-plan** — verify the implementation matches the plan
**Lightweight** — one file, no server, no broker, no dependencies beyond
the reviewer CLI. Compare with [codex-plugin-cc](https://github.com/openai/codex-plugin-cc):
~15 JS modules, App Server, JSON-RPC broker, lifecycle hooks.
This skill is a text instruction that any AI agent can interpret.
**Iterative** — Claude doesn't just show the review and stop.
It actively fixes issues based on reviewer feedback and resubmits
for re-review. Up to 5 rounds until approved.
**Designed for extensibility** — the skill relies on basic agent capabilities:
run a command, read a file, edit a file. The prompts and review workflow
are model-agnostic. Currently uses OpenAI Codex as the reviewer;
adding other backends (Gemini, local models) is on the roadmap.
- **Iterative** — Claude fixes issues based on reviewer feedback and resubmits
for re-review. Up to 5 rounds until approved
- **Lightweight** — one `SKILL.md` file, no server, no broker. Compare with
[codex-plugin-cc](https://github.com/openai/codex-plugin-cc):
~15 JS modules, App Server, JSON-RPC broker, lifecycle hooks
## How it works
@@ -63,104 +53,168 @@ adding other backends (Gemini, local models) is on the roadmap.
Mode is auto-detected from context, or you can force it with an argument.
## Installation
## Quick start
### Requirements
### 1. Prerequisites
- [Claude Code](https://docs.anthropic.com/en/docs/claude-code)
- [OpenAI Codex CLI](https://github.com/openai/codex): `npm install -g @openai/codex`
- OpenAI API key (`OPENAI_API_KEY` environment variable)
[Claude Code](https://docs.anthropic.com/en/docs/claude-code) and
[OpenAI Codex CLI](https://github.com/openai/codex) must be installed.
### Setup
Verify both are available:
```bash
# Clone the repository
git clone https://github.com/<your-username>/adversarial-review.git
claude --version # Claude Code CLI
codex --version # OpenAI Codex CLI (>= 0.115.0)
```
# Symlink into Claude Code skills directory
If Codex is missing: `npm install -g @openai/codex`
**Authentication.** Codex needs an OpenAI account. Either:
- Sign in interactively: `codex` (opens browser)
- Or set `CODEX_API_KEY` env var for non-interactive use
### 2. Install the skill
```bash
git clone https://github.com/dementev-dev/adversarial-review.git
ln -s "$(pwd)/adversarial-review" ~/.agents/skills/adversarial-review
```
After symlinking, the skill is available as `/adversarial-review` in Claude Code.
Verify the skill is visible to Claude Code:
### Recommended permissions
```bash
ls -la ~/.agents/skills/adversarial-review/SKILL.md
```
The skill runs git, codex, and `/tmp` write commands that will trigger
permission prompts. To avoid repeated confirmations, add these to your
`.claude/settings.local.json`:
### 3. Add permissions
```json
The skill runs `git`, `codex exec`, and writes temp files to `/tmp`.
Without pre-approved permissions, Claude Code will prompt for each action.
**Where to add.** Since the skill is installed globally
(`~/.agents/skills/`), permissions should go into the global config
so they work in any project:
| Install scope | Config file |
|---------------|-------------|
| Global (recommended) | `~/.claude/settings.json` |
| Single project | `<project>/.claude/settings.local.json` |
Merge the following rules into the `permissions.allow` array of the
chosen config file:
```jsonc
// --- adversarial-review permissions ---
// Git: diff, status, branch detection
"Bash(git diff*)",
"Bash(git status*)",
"Bash(git symbolic-ref*)",
"Bash(git rev-parse*)",
// Codex: review execution (always wrapped in timeout)
"Bash(timeout 600 codex exec *)",
// Temp files: prompts, plans, output capture
"Write(/tmp/codex-plan-*)",
"Write(/tmp/codex-prompt-*)",
"Read(/tmp/codex-review-*)",
"Read(/tmp/codex-stderr-*)",
// Cleanup and output piping
"Bash(rm -f /tmp/codex-*)",
"Bash(tee *)"
```
<details>
<summary>Full example (if the config file is empty or does not exist)</summary>
```jsonc
{
"permissions": {
"allow": [
// adversarial-review
"Bash(git diff*)",
"Bash(git status*)",
"Bash(git symbolic-ref*)",
"Bash(git rev-parse*)",
"Bash(timeout 600 codex exec *)",
"Write(/tmp/codex-plan-*)",
"Write(/tmp/codex-prompt-*)"
"Write(/tmp/codex-prompt-*)",
"Read(/tmp/codex-review-*)",
"Read(/tmp/codex-stderr-*)",
"Bash(rm -f /tmp/codex-*)",
"Bash(tee *)"
]
}
}
```
**Note:** The `codex exec` rule allows any `codex exec` invocation wrapped
in `timeout 600`. The skill only uses read-only mode (`-s read-only`), but
Claude Code's permission patterns are prefix-based and cannot enforce flag
</details>
**Security note:** The `codex exec` rule allows any `codex exec` invocation
wrapped in `timeout 600`. The skill only uses read-only mode (`-s read-only`),
but Claude Code's permission patterns are prefix-based and cannot enforce flag
constraints. If you prefer tighter control, omit the `codex exec` rule and
approve each review invocation manually.
approve each invocation manually.
## Usage
### 4. Use
```
# Auto-detect what to review
/adversarial-review
# Review a plan
/adversarial-review plan
# Review code changes
/adversarial-review code
# Review a specific file
/adversarial-review path/to/plan.md
# Use higher reasoning effort
/adversarial-review xhigh
# Use a different model
/adversarial-review model:gpt-5.3-codex
```bash
/adversarial-review # auto-detect mode
/adversarial-review plan # force plan review
/adversarial-review code # force code review
/adversarial-review path/to/f # review a specific file
/adversarial-review xhigh # higher reasoning effort
/adversarial-review model:gpt-5.3-codex # use a different model
```
## Prompt architecture
The skill uses XML-structured prompts inspired by adversarial review methodology:
The skill uses XML-structured prompts with adversarial stance:
- **`<role>`** — adversarial reviewer, defaults to skepticism
- **`<operating_stance>`** — break confidence, not validate
- **`<attack_surface>`** — concrete checklist: auth, data integrity,
race conditions, rollback safety, schema drift, error handling, observability
- **`<finding_bar>`** — every finding must answer 4 questions:
what can go wrong, why this code is vulnerable, impact, recommendation
what can go wrong, why vulnerable, impact, recommendation
- **`<scope_exclusions>`** — no style, naming, or speculative comments
- **`<calibration>`** — one strong finding > five weak ones
## Example output
See [examples/review-output.md](examples/review-output.md) for a sample
adversarial review output.
See [examples/review-output.md](examples/review-output.md) for a sample review.
## Troubleshooting
**`codex exec` exits with model error.**
Some models are unavailable with ChatGPT accounts (e.g. `o3-mini`).
The default `gpt-5.4` works with both ChatGPT and API key auth.
Override with `/adversarial-review model:<name>`.
**Permission prompts on every action.**
Add the permissions from the [setup section](#3-add-permissions). Check that
the file is valid JSON and in the right location (project `.claude/settings.local.json`
or global `~/.claude/settings.json`).
**Codex hangs / timeout (exit code 124).**
All `codex exec` calls are wrapped in `timeout 600` (10 minutes). If you see
exit code 124, the reviewer did not respond in time. Retry — this is usually
transient.
**Resume fails with session error.**
The skill uses `codex exec resume <session-id>` for rounds 2+. If the session
expired or the ID was not captured, the skill falls back to a fresh `codex exec`
automatically. No action needed.
**Plan Mode exits when writing temp files.**
In Claude Code Plan Mode, writing to `/tmp` may trigger a permission prompt
or exit Plan Mode. This is a known Claude Code limitation. It does not affect
review correctness.
## Known limitations
- **Plan Mode and `/tmp` writes.** In Claude Code Plan Mode, writing review
prompts to `/tmp` may trigger a permission prompt or cause Plan Mode to exit.
This does not affect review correctness — the review mode is already determined,
and only the plan file and temp files are modified.
- **`resume` inherits sandbox.** The `codex exec resume` command does not accept
`-s` (sandbox) — sandbox is inherited from the original session. The first
`codex exec` call sets the sandbox to `read-only`, and all subsequent resume
rounds use the same setting.
- **Plan Mode and `/tmp` writes.** Writing review prompts to `/tmp` may trigger
a permission prompt or cause Plan Mode to exit. Does not affect review correctness.
- **`resume` inherits sandbox.** `codex exec resume` does not accept `-s` —
sandbox is inherited from the original session (always `read-only`).
## Roadmap
@@ -171,21 +225,16 @@ adversarial review output.
## Inspiration
The adversarial prompt structure was developed after studying
[openai/codex-plugin-cc](https://github.com/openai/codex-plugin-cc) (Apache-2.0)
— the official OpenAI plugin for code review with Codex in Claude Code.
Adversarial prompt structure developed after studying
[openai/codex-plugin-cc](https://github.com/openai/codex-plugin-cc) (Apache-2.0).
What we borrowed as ideas:
- XML-structured prompts (`<role>`, `<operating_stance>`, `<attack_surface>`, etc.)
- Adversarial stance: "break confidence, not validate"
- Attack surface checklist approach
- Finding bar: 4 questions each finding must answer
- Calibration rules: prefer strong findings over weak ones
Borrowed ideas: XML-structured prompts, adversarial stance, attack surface
checklist, finding bar, calibration rules.
What we did differently:
- **Iterative loop** — Claude actively fixes issues and resubmits (vs "stop and ask user")
- **Iterative loop** — Claude fixes issues and resubmits (not "stop and ask user")
- **Plan review** — reviews plans before code, not just code
- **Single file** — one SKILL.md vs 15+ JS modules with App Server
- **Single file** — one SKILL.md vs 15+ JS modules
- **Verbatim output** — reviewer findings shown as-is, not rephrased
## License