Codex-Claude Engineering Loop Skill

When to use

Recommended after the following (plan validation runs only on request/approval):

• After building a non-trivial plan (3+ steps, architecture impact, multi-file changes) -> run plan validation only if user requests/approves
• After implementation completes (new feature, refactor, API change)
• Final validation before build/deploy
• Quality gate check after major work

Do not use for:

• Simple config changes (env vars, formatter settings)
• Documentation-only updates
• 1-2 line trivial edits (typos, minor styling)

Role

• Base role follows CLAUDE.md. Codex is a reviewer for plan/implementation.
• The last agent that summarized continues the work.

Constraint-based guardrails (Gemini prompt strategy)

• Specify context scope: do not guess/assume/edit beyond target files/folders. Cite evidence by file/line.
• Fix output format: keep requested output format (Plan/Implementation/Review) and length constraints.
• Declare allowed/forbidden actions: no external resources, no new deps, no large refactors without approval.
• Handle uncertainty: ask briefly when info is missing; mark as "needs confirmation" instead of guessing.
• Checklist self-check: before sending, verify key constraints (file scope, format, forbidden items, risks).

Response template

User context

• Target files/folders:
• Current behavior:
• Additional context:
• (If needed) constraints/priorities: allowed/forbidden actions, output length/format, whether questions needed

Example

• Target files/folders:
  • src/app/page.tsx
  • src/store/dashboardStore.ts
• Current behavior: fetch data from server and store in local state
• Additional context: can use Suspense / useOptimistic for React 19 support

Task

• Summarize the user request as bullets.
• Example:
  • Split dashboard state management into Zustand + Immer
  • Minimize potential breakage in existing code
  • Consider type safety (narrowing, ReturnType, etc.)
• Re-summarize constraints (allowed/forbidden actions, format, length, confirm needs).

Output format

1. Plan: summarize key steps, assumptions, risks.
2. Implementation: summarize file-by-file changes and evidence.
3. Review: summarize edge cases, test approach, remaining risks.

Final instruction

• Always respond in Plan -> Implementation -> Review order.

Codex-Claude Loop Procedure

1. Plan (Claude): build a detailed plan and record it in {tasksRoot}/context.md.
2. Plan validation (Codex) (optional): when requested/approved, ask MCP to validate in background.
   • Use mcp__codex__spawn_agent
   • Prompt example:

   Review this implementation plan and find issues:
   [Claude's plan]
   
   Focus on:
   - Logic errors and missing edge cases
   - Data/flow consistency and API contract violations
   - Type safety (narrowing, null/undefined) and error handling
   - Performance/resource waste
   - Security/auth/input validation
   - Framework/language best practices
   - Project code conventions and repo rules (CLAUDE.md, etc.)
   
   Constraints:
   - Keep Plan/Implementation/Review format, summary only
   - Do not mention files/deps not in context; mark "needs confirmation" if unknown
   - Cite evidence near file/line
   

   • Summarize results: extract only key issues from Codex response for the user (full logs only if needed)
3. Feedback loop: summarize Codex issues, update the plan, and ask the user whether to re-validate or proceed.
4. Implementation (Claude): implement step-by-step following the validated plan and record errors/changes explicitly.
5. Cross review (Codex): request background review after implementation.
   • Use mcp__codex__spawn_agent
   • Prompt example:

   Review the implementation and check:
   
   - Logic/flow errors, missing edge cases
   - Type safety and null/undefined guards, error/exception handling
   - API contract and data model consistency
   - Performance/resource waste
   - Security/auth/input validation
   - Framework/language best practices
   - Project code conventions and repo rules (CLAUDE.md, etc.)
   - Code complexity and maintainability
   
   Constraints:
   - Summarize response in Plan/Implementation/Review format
   - Do not suggest deps/files outside context; mark "needs confirmation" if required
   - Cite file/line evidence for each issue
   

   • Summarize results: classify as critical issues, warnings, suggestions
6. Re-validate and continue: fix critical issues immediately; confirm large changes with the user; re-validate if needed.
7. Error handling: on Codex or implementation errors, analyze cause -> adjust strategy -> confirm before large-impact changes.

Codex Result Summary Guide

Summary principles

• Only the essentials: critical issues > warnings > suggestions
• Brevity: deliver only 3-5 key points
• Context savings: do not dump full Codex logs
• Action-oriented: include a fix approach for each issue

Summary template

Codex validation complete:

Critical issues (fix immediately):
- [Issue 1]: [short description] -> [action]

Warnings (improve if possible):
- [Issue 2]: [short description] -> [action]

Suggestions:
- [Issue 3]: [short description]

Example

Codex validation complete:

Critical issues:
- Type safety: PagingResponse<T> missing -> apply PagingResponse type to API response

Warnings:
- Error handling: Either Left case missing -> add fold handling

Suggestions:
- Performance: consider useMemo for list filtering

Notes

• Plan validation: run plan validation via mcp__codex__spawn_agent
• Implementation: use Claude Edit/Write/Read tools
• Review: run review prompt via mcp__codex__spawn_agent
• Parallel validation: use mcp__codex__spawn_agents_parallel for multi-angle checks