codex-validate-plan

munlucky's avatarfrom munlucky

Validate architecture/plan quality via Codex MCP. Use after writing context.md for complex feature/refactor work.

⭐0stars🔀0forks📁View on GitHub🕐Updated Jan 10, 2026
[Architecture Design]

When & Why to Use This Skill

This Claude skill automates the validation of software architecture and implementation plans using the Codex MCP. It is specifically designed to ensure high-quality technical designs for complex features and refactoring tasks by evaluating plans against four critical criteria: Clarity, Verifiability, Completeness, and Big Picture alignment. By acting as a 'Plan Reviewer' expert, it helps developers identify potential gaps and architectural flaws before a single line of code is written, significantly reducing technical debt and implementation errors.

Use Cases

  • Complex Feature Planning: Validating a detailed implementation plan (context.md) for a new system component to ensure all edge cases and constraints are addressed.
  • Refactoring Risk Assessment: Reviewing architectural changes during large-scale code refactors to prevent regressions and ensure the new design meets project standards.
  • Automated Quality Gates: Serving as a mandatory review step in the development lifecycle where an AI 'Plan Reviewer' provides an objective Approve/Reject verdict on technical proposals.
  • Gap Analysis: Simulating the execution of a proposed plan to uncover missing requirements or logical inconsistencies in the early design phase.
namecodex-validate-plan
descriptionValidate architecture/plan quality via claude-delegator (Plan Reviewer expert). Use after writing context.md for complex feature/refactor work.
contextfork

Codex Plan Validation (via claude-delegator)

When to use

  • complexity: complex
  • taskType: feature or refactor
  • context.md exists or was updated

Procedure

  1. Collect the path to context.md (default: {tasksRoot}/{feature-name}/context.md) and read its content
  2. Build delegation prompt using the 7-section format below
  3. Try Codex first:
    • Call mcp__codex__codex (include Plan Reviewer instructions in developer-instructions)
    • If successful, proceed to step 5
  4. Fallback to Claude (if Codex unavailable):
    • Error conditions: "quota exceeded", "rate limit", "API error", "unavailable"
    • Claude directly performs the plan review following the Plan Reviewer guidelines below
    • Add note: "codex-fallback: Claude performed review directly"
  5. Summarize critical/warning/suggestion items and decide pass/fail
  6. Per .claude/docs/guidelines/document-memory-policy.md: Store full review in archives/review-v{n}.md, keep only short summary in context.md

Delegation Format

Use the 7-section format:

TASK: Review implementation plan at [context.md path] for completeness and clarity.

EXPECTED OUTCOME: APPROVE/REJECT verdict with specific feedback.

CONTEXT:
- Plan to review: [content of context.md]
- Goals: [what the plan is trying to achieve]
- Constraints: [project constraints]

MUST DO:
- Evaluate all 4 criteria (Clarity, Verifiability, Completeness, Big Picture)
- Simulate actually doing the work to find gaps
- Provide specific improvements if rejecting

MUST NOT DO:
- Rubber-stamp without real analysis
- Provide vague feedback
- Approve plans with critical gaps

OUTPUT FORMAT:
[APPROVE / REJECT]
Justification: [explanation]
Summary: [4-criteria assessment]
[If REJECT: Top 3-5 improvements needed]

Tool Call

mcp__codex__codex({
  prompt: "[7-section delegation prompt with full context]",
  "developer-instructions": "[contents of plan-reviewer.md]",
  sandbox: "read-only",  // Advisory mode
  cwd: "[current working directory]"
})

Output (patch)

notes:
  - "codex-plan: [APPROVE/REJECT], warnings=[count]"