codex-plan-critique

Codex Plan Critique

A coding agent skill that invokes Codex CLI as a peer reviewer during planning phases. Get architectural critique on your implementation plans before committing to them.

Works with Claude Code and Codex (or any coding agent that supports skills).

What It Does

When you're planning an implementation, this skill runs Codex in your project directory to review the plan with full visibility into your codebase. Codex acts as a senior architect and evaluates:

1. Architecture - Patterns, structure, separation of concerns
2. Edge Cases - Security, error handling, missed scenarios
3. Simplicity - Is anything overengineered? Are there simpler alternatives?
4. File Locations - Do referenced files exist? Are there better locations?

It returns a structured critique with a verdict (APPROVE or CONCERNS), strengths, and actionable suggestions.

Install

As a plugin (recommended)

In Claude Code:

claude plugin marketplace add adrianleb/codex-plan-critique-skill
claude plugin install codex-plan-critique

Manual install

git clone https://github.com/adrianleb/codex-plan-critique-skill.git

# Copy into your global skills (available in all projects)
cp -r codex-plan-critique-skill/skills/codex-plan-critique ~/.claude/skills/

# Or copy into a specific project (available only in that project)
cp -r codex-plan-critique-skill/skills/codex-plan-critique your-project/.claude/skills/

Usage

The skill triggers automatically during planning phases. You can also invoke it explicitly:

> /codex-plan-critique
> critique this plan
> get a peer review

How It Works

1. Your agent writes the current plan to a temp file
2. The critique script runs Codex in your project directory
3. Codex reviews the plan with access to your actual codebase
4. The critique is displayed and incorporated into the final plan

Output Format

★ Codex Peer Review ─────────────────────────
## Verdict: APPROVE

## Strengths
- Clean separation between API and data layers
- Good use of existing middleware patterns

## Concerns
- Missing error handling for the webhook endpoint
- Consider using the existing EventBus instead of a new pub/sub
──────────────────────────────────────────────

If Codex is unavailable, the skill gracefully skips the review and continues without blocking.

Project Structure

.claude-plugin/
  plugin.json                             # Plugin manifest
skills/
  codex-plan-critique/
    SKILL.md                              # Skill definition
    scripts/
      codex-critique.sh                   # Codex invocation script

Requirements

• Codex CLI installed and authenticated
• OPENAI_API_KEY environment variable or codex login

Contributing

Ideas for improvement:

• Support for other review agents beyond Codex
• Configurable review criteria and depth
• Caching to avoid re-reviewing unchanged plans
• Integration with CI for automated plan review

PRs and ideas welcome. Open an issue to discuss before large changes.

License

MIT