agentleFS
Sign inStart free
longranger2longranger2/claude-gpt-workflow/plan-review/SKILL.md

plan-review

Skill76 starsChanged 8 months agoMITView on GitHub

Use when the user says "/plan-review", "plan review", or "PRD review" and provides a plan file path that needs critical review and iterative refinement with Codex.

We split this skill into the rules it gives an agent

10 rules. 0 are common, 6 are distinctive, and 4 are very specific to this project.

  • 0

    Common

    Most of the 36 edited versions we read keep these.

  • 6

    Distinctive

    This author's own choices. Worth a look.

  • 4

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    When the user runs /plan-review {plan-file-path}, start the "adversarial plan iteration" workflow:

    line 10
  2. Very specific:

    If the review status is NEEDS_REVISION, I automatically ask Codex to review again.

    line 14
  3. Distinctive:

    If the review file already exists, this is not the first round, so Codex must track the resolution status of issues from the previous round.

    line 35
  4. Very specific:

    Use the /codex skill and give Codex the following instruction:

    line 39
  5. Distinctive:

    When the review file is created for the first time, add this header at the top:

    line 91
  6. Distinctive:

    After Codex finishes, I read the latest review round in the review file:

    line 102
  7. Distinctive:

    If rejecting an unreasonable suggestion, optionally note the reason briefly in the plan.

    line 106
  8. Distinctive:

    Update the original plan file directly: instead of creating a new file.

    line 107
  9. Very specific:

    Use the Consensus Status provided by Codex:

    line 111
  10. Distinctive:

    After the iteration is complete, report the following to the user:

    line 121

“Common” is measured: kept by at least 6 in 10 of the 36 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Plan Review Skill

Purpose

When the user runs /plan-review {plan-file-path}, start the "adversarial plan iteration" workflow:

  1. I (Claude Code) ask Codex to perform a critical review of the specified plan.
  2. I read the review produced by Codex and evaluate whether its suggestions are sound.
  3. I revise the plan based on valid suggestions and write changes back to the original plan file.
  4. If the review status is NEEDS_REVISION, I automatically ask Codex to review again.
  5. Repeat until consensus is reached as MOSTLY_GOOD or APPROVED.

Usage

/plan-review plans/my-feature-plan.md

Session Reuse

After each Codex invocation, extract session_id=xxx from the script output and save it as the session ID for the current task. In later Codex calls for the same task, pass --session <id> to reuse context so Codex remembers prior review history and can stay consistent across multiple rounds.

My Workflow (Claude Code)

Step 1: Determine the Review File

Derive the review file path from the plan file name:

  • plans/auth-refactor.md → reviews/auth-refactor-review.md
  • Rule: reviews/{plan-file-name-without-.md}-review.md

If the review file already exists, this is not the first round, so Codex must track the resolution status of issues from the previous round.

Step 2: Ask Codex to Review the Plan

Use the /codex skill and give Codex the following instruction:

Read the contents of {plan-file-path} and review it critically as an independent third-party reviewer.

Requirements:
- Raise at least 10 concrete and actionable improvement points
- Each issue must include: issue description + exact location/reference in the plan + improvement suggestion
- Use severity levels: Critical > High > Medium > Low > Suggestion
- If {review-file-path} already exists, read it first and track the resolution status of previous issues in the new round

Analysis dimensions, choosing the relevant ones based on the plan type:
- Architectural soundness: overdesign vs underdesign, module boundaries, single responsibility
- Technology choices: rationale, alternatives, compatibility with the existing project stack
- Completeness: missing scenarios, overlooked edge cases, dependency and impact scope
- Feasibility: implementation complexity, performance risks, migration and compatibility concerns
- Engineering quality: whether it follows the Code Quality Hard Limits in `CLAUDE.md`
- User experience: interaction flow, error/loading states, i18n when relevant
- Security: authentication, authorization, data validation when relevant

Append the current review round to {review-file-path}, creating the file if it does not exist.
Separate rounds with `---` and append new rounds at the end of the file. Use this format:

---

## Round {N} — {YYYY-MM-DD}

### Overall Assessment
{2-3 sentence overall assessment}
**Rating**: {X}/10

### Previous Round Tracking (R2+ only)
| # | Issue | Status | Notes |
|---|-------|--------|-------|

### Issues
#### Issue 1 ({severity}): {title}
**Location**: {location in the plan}
{issue description}
**Suggestion**: {improvement suggestion}
... (at least 10 issues)

### Positive Aspects
- ...

### Summary
{Top 3 key issues}
**Consensus Status**: NEEDS_REVISION / MOSTLY_GOOD / APPROVED

Key principle: be a critical reviewer, not a yes-man. Every issue must be specific enough that someone knows how to revise the plan.

When the review file is created for the first time, add this header at the top:

# Plan Review: {plan title}

**Plan File**: {plan-file-path}
**Reviewer**: Codex

Step 3: Read the Review and Revise the Plan

After Codex finishes, I read the latest review round in the review file:

  1. Evaluate each issue raised by Codex one by one.
  2. Adopt valid suggestions and revise the plan file.
  3. If rejecting an unreasonable suggestion, optionally note the reason briefly in the plan.
  4. Update the original plan file directly instead of creating a new file.

Step 4: Decide Whether to Continue Iterating

Use the Consensus Status provided by Codex:

StatusMy Action
NEEDS_REVISIONRevise the plan, then automatically ask Codex to review again and return to Step 2
MOSTLY_GOODRevise the plan, then tell the user the plan is mostly mature and ask whether another review round is needed
APPROVEDTell the user the plan has passed review and is ready for implementation

Step 5: Wrap Up

After the iteration is complete, report the following to the user:

  • How many review rounds were completed
  • Which major areas were improved
  • The final plan file path
  • The review log file path

File Convention

  • One review file per plan: reviews/{topic}-review.md
  • {topic} is the plan file name without .md
  • Append all rounds to the same file and separate them with ---
  • Example: plans/auth-refactor.md -> reviews/auth-refactor-review.md

Download now (ZIP)

  • Other versions43 projects use a version of this.

    Word for word · 0

    None found.

    Edited · 0

    None found.

    Wrote their own version · 43

    1. ahmadrosid/nakama★ 746same name
    2. igerber/diff-diff★ 412same name
    3. Mathews-Tom/armory★ 340same name
    4. sd0xdev/sd0x-dev-flow★ 192same name
    5. sd0xdev/sd0x-harness★ 192same name
    6. YougLin-dev/Aha-Loop★ 181same name
    7. ConnorGriffin/skills★ 21same name
    8. liewcf/agent-skills★ 16same name
    9. kopp0510/claude-dd★ 12same name
    10. aws-solutions/konductor★ 10same name

    33 more not listed

    How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.

  • Used alongsideProjects with it also use pr-comment, spec-review and 9 more.

    Other files people use alongside this one.

    Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
    • BenjaminGSkill

      pr-comment

      This skill should be used when reviewing someone else's pull request and you want drafted review comments posted to GitHub — either gate / gate-wf findings (tier-marked) or pr-challenge's reviewer questions (unmarked) — each drafted through humanizer and posted as a standalone inline comment at its file:line, after one confirmation. Triggers on "post these as review comments", "comment the gate findings on the PR", "draft and post my review", "leave review comments", after a gate / gate-wf run or a pr-challenge pass on a PR you're reviewing.

      Also in 3 projects that use this

    • MicrosoftSkill

      spec-review

      Independent, multi-model review of a design or spec **before** any code is written, for the microsoft/winappcli repo. Activate when a contributor asks to "review this spec", "review my design", "review this design doc", "validate this approach", "should we build this", "spec review", "design review", or "feature review". Fans out parallel sub-agents — each doing its OWN research against the real codebase and ecosystem rather than trusting the spec — covering necessity & scope, approach & alternatives, feasibility vs reality, risks & unknowns, DX & user impact, and a different-model-family cross-check. Emits a decision-oriented recommendation (proceed / proceed-with-changes / reconsider) to stdout. This is the PRE-CODE companion to the pr-review skill (which reviews code already written); use spec-review at the design/spec stage, not on an implemented diff. Does NOT write code or edit the spec.

      Also in 3 projects that use this

    • ramybarsoumSkill

      office-hours

      YC Office Hours -- two modes. Startup mode: six forcing questions that expose demand reality, status quo, desperate specificity, narrowest wedge, observation, and future-fit. Builder mode: design thinking brainstorming for side projects, hackathons, learning, and open source. Saves a design doc. Use when asked to "brainstorm this", "I have an idea", "help me think through this", "office hours", or "is this worth building". Proactively suggest when the user describes a new product idea or is exploring whether something is worth building -- before any code is written.

      Also in 3 projects that use this

    • AWSSkill

      retro

      Conduct a retrospective on a coding session.

      Also in 5 projects that use this

    • asterkinSkill

      adr

      Create Architecture Decision Records (ADRs) following project standards. Guides template usage, process, and best practices for documenting architecturally significant decisions.

      Also in 3 projects that use this

    • BlockSkill

      plan

      Draft a TDD, PRD, or lightweight plan in the conversation without committing it.

      Also in 5 projects that use this

  • In this repository2 other files it gives its agents.

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

Check your setup, free