Codex advisor

Codex Advisor

Use this skill to consult Codex as a senior engineering advisor through two specialized collaboration modes: Chat for peer brainstorming and Consensus for structured evaluation. Invoke Codex strictly for advisory consultation—it provides analysis and recommendations while Claude handles all code implementation.

Collaboration Modes

Chat Mode — Peer brainstorming for exploring solutions, trade-offs, and validation. Use for iterative problem-solving and technical discussions. See references/chat-pattern.md for detailed guidance.

Consensus Mode — Structured evaluation for major decisions. Provides 7-dimension assessment with verdict and confidence scoring. Use for high-stakes architectural or technology decisions. See references/consensus-pattern.md for detailed guidance.

When to Use This Skill

Invoke Codex for advisory consultation on architecture, design decisions, code review, technology selection, and strategic planning. Codex provides analysis and recommendations only—all code implementation uses Claude's tools directly.

Do not use for: Simple questions, actual code writing, or file modifications.

Collaboration Workflow

Step 1: Load Project Context (Always Do This First)

Before consulting Codex, gather project-specific context to ensure recommendations align with established constraints:

Required:

1. Read ~/.claude/CLAUDE.md for global project principles and constraints
2. Extract key information:
   • Core principles (e.g., "INVESTIGATE BEFORE CHANGING", "MINIMAL SURGICAL CHANGES")
   • Forbidden patterns or practices
   • Architecture constraints
   • Code style requirements
   • Security/quality standards

Optional:

• If project-specific ./AGENTS.md exists in current directory, read it for additional context

Usage:

• Include extracted constraints in your prompt to Codex, OR
• Add them as context in the developer-instructions parameter

Example context to include:

Project constraints from CLAUDE.md:
- INVESTIGATE BEFORE CHANGING: debug systematically first
- MINIMAL SURGICAL CHANGES: change only what's requested
- FOLLOW EXISTING PATTERNS: match codebase conventions
- No placeholders or fallback implementations

If CLAUDE.md is missing or unreadable:

• Note this limitation to the user
• Proceed with consultation but warn recommendations may not align with project standards
• Ask user if they want to provide key constraints manually

Step 2: Choose Mode and Load System Prompt

Determine which collaboration mode fits the user's request:

• Chat Mode: Brainstorming, trade-offs, validation, iterative discussion
• Consensus Mode: Formal evaluation, structured assessment, high-stakes decisions

For Chat Mode (Brainstorming):

2a. Load system prompt:

• Read the file prompts/chat-mode-system-prompt.md
• Use the complete contents as developer-instructions parameter

2b. Invoke Codex: Use mcp__codex__codex tool with these parameters:

• prompt: Your question/problem (include context from Step 1 here)
• developer-instructions: Contents from step 2a
• sandbox: "read-only" (REQUIRED - prevents file modifications)
• approval-policy: "never" (safe for read-only consultations)
• cwd: Current project directory path (optional)

Note: Chat mode uses optimized GPT-5 prompt (~158 tokens). See references/chat-pattern.md for detailed usage patterns.

For Consensus Mode (Evaluation):

2a. Load system prompt template:

• Read the file prompts/consensus-mode-system-prompt.md
• This file contains a {stance_prompt} placeholder that must be replaced

2b. Select and apply stance:

1. Choose stance based on evaluation needs (default: neutral):

   • neutral: Balanced, objective analysis
   • skeptical: Risk-focused scrutiny
   • supportive: Opportunity-focused
   • security-focused: Security-first lens
   • performance-focused: Performance-first lens
   • pragmatic: Resource-constrained practicality

2. Get stance text from references/consensus-pattern.md section "Stance Options"

3. Replace {stance_prompt} placeholder with chosen stance text

2c. Invoke Codex: Use mcp__codex__codex tool with these parameters:

• prompt: Your proposal with context (include constraints from Step 1)
• developer-instructions: Modified template from step 2b
• sandbox: "read-only" (REQUIRED)
• approval-policy: "never"
• cwd: Current project directory path (optional)
• model: "gpt-5.2" (recommended for architecture/code evaluation)

Note: Consensus mode uses optimized GPT-5 prompt (~420 tokens). See references/consensus-pattern.md for detailed evaluation framework.

Step 3: Continue Collaboration (Optional)

For multi-turn consultation, use mcp__codex__codex-reply:

3a. Store conversation ID:

• Save the conversationId returned from initial mcp__codex__codex call

3b. Invoke follow-up: Use mcp__codex__codex-reply tool with these parameters:

• conversationId: ID from step 3a
• prompt: Your follow-up question or clarification request

Note: No need to re-specify developer-instructions, sandbox, or other settings - they carry over from initial call.

When to follow up:

• User asks for deeper exploration of Codex's recommendation
• You need clarification on specific points
• Alternative approaches should be discussed
• Implementation details need elaboration

Step 4: Synthesize and Present

After receiving Codex's input:

1. Summarize key findings and recommendations
2. Present trade-offs and alternatives to user
3. Let user decide which approach to pursue
4. Implement the chosen solution using Claude's own tools

Verification Checklist

Before presenting Codex's response to the user, verify you completed these steps correctly:

Pre-Consultation Checks

• ✅ Read ~/.claude/CLAUDE.md for project constraints
• ✅ Extracted key principles and included them in consultation context
• ✅ Loaded correct system prompt file for chosen mode
• ✅ For Consensus: selected stance and replaced {stance_prompt} placeholder

Safety Checks

• ✅ Set sandbox: "read-only" (Codex must never modify files)
• ✅ Set approval-policy: "never" (safe for read-only advisory mode)
• ✅ Codex's role is ADVISORY ONLY - no file modifications requested

Quality Checks

• ✅ Prompt includes sufficient context (scale, tech stack, constraints, timeline)
• ✅ Prompt is specific and focused (not vague like "should we use microservices?")
• ✅ For Consensus: proposal format with context and evaluation dimensions

If any check fails:

1. Identify which step was missed
2. Re-do the consultation with corrections
3. Do not present incomplete or incorrectly configured results

Error Handling

If CLAUDE.md is Missing or Unreadable

1. Note limitation to user: "CLAUDE.md not found - proceeding without project-specific constraints"
2. Ask user: "Would you like to provide key project constraints manually?"
3. Continue consultation with available context

If System Prompt File Not Found

1. Report error to user: "System prompt file missing at [path]"
2. Suggest checking skill installation
3. Do not proceed with consultation

If Codex Returns Error

1. Show full error message to user
2. Check if parameters were correct (especially stance replacement)
3. Suggest simpler prompt or different mode
4. Offer to retry with corrections

If Stance Replacement Fails (Consensus Mode)

1. Fall back to neutral stance
2. Notify user: "Using neutral stance (default)"
3. Continue with consultation

Quick Reference Examples

Chat Mode — Architecture Brainstorming

User request: "Brainstorm with Codex about our caching strategy"

Invocation:

mcp__codex__codex(
  prompt: "We're experiencing slow dashboard load times (2-3 seconds) with 50K daily users. Current stack: Node.js + Express + PostgreSQL. Considering Redis for caching. What are the key trade-offs and potential pitfalls? What caching patterns work best for dashboards with user-specific data?",
  developer-instructions: "[Load from prompts/chat-mode-system-prompt.md]",
  sandbox: "read-only",
  approval-policy: "never"
)

Consensus Mode — Technology Decision

User request: "Have Codex evaluate our GraphQL vs REST decision"

Invocation:

mcp__codex__codex(
  prompt: "Proposal: Migrate our REST API to GraphQL for the new mobile app.

Context:
- 10-person team, mostly backend experience with Node.js/Express
- 100K users, mobile and web clients
- Current API has 50+ REST endpoints
- Mobile team wants flexible data fetching
- Timeline: 6 months

Evaluate this proposal across technical feasibility, implementation complexity, and long-term implications.",
  developer-instructions: "[Load from prompts/consensus-mode-system-prompt.md, replace {stance_prompt} with neutral stance]",
  sandbox: "read-only",
  approval-policy: "never",
  model: "gpt-5.2"
)

For comprehensive examples covering refactoring discussions, security audits, performance optimization, network research, multi-turn conversations, and various stances, see:

• Chat Mode: references/chat-pattern.md — Complete invocation examples with follow-up patterns
• Consensus Mode: references/consensus-pattern.md — Examples with different stances and evaluation scenarios

Presenting Codex Collaboration to User

Chat Mode Results

Structure as conversational synthesis:

## Codex Discussion: [Topic]

**Key Insights:**

- [Insight with supporting reasoning]
- [Trade-off identified]
- [Pitfall or edge case surfaced]

**Recommendations:**
[Codex's suggested approach with rationale]

**Alternatives Discussed:**

- Option A: [Brief description with trade-offs]
- Option B: [Brief description with trade-offs]

**Next Steps:**
[2-3 actionable options for the user]

Would you like to explore any of these further, or shall I implement the recommended approach?

Consensus Mode Results

Structure as formal evaluation:

## Codex Consensus Evaluation: [Proposal]

**Verdict:**
[Single-sentence summary from consensus]

**Analysis Highlights:**

- **Technical Feasibility:** [Key finding]
- **Implementation Complexity:** [Key finding]
- **Long-term Implications:** [Key finding]

**Confidence:** [Score/10 with justification]

**Critical Takeaways:**

1. [Most important insight]
2. [Significant risk or consideration]
3. [Actionable recommendation]

**Recommendation:**
[Claude's synthesis of whether to proceed, modify, or reconsider]

What would you like to do?

Common Anti-Patterns to Avoid

Wrong mode choice — Using Consensus for quick questions or Chat for formal reviews wastes effort. Match mode to decision stakes.

Vague requests without context — Provide specific focus areas, constraints, and expected deliverable formats. Include scale, tech stack, timeline, and team expertise.

Implementation requests to Codex — Request strategy and recommendations only. Codex advises in read-only mode; Claude implements using its own tools.

Missing project constraints — Always read CLAUDE.md first and include extracted principles in consultation context to ensure alignment.

Simple questions — Reserve Codex consultation for complex analysis requiring specialized expertise, not straightforward lookups.

Resources

references/chat-pattern.md

Complete chat mode system prompt and usage guidelines for peer brainstorming:

• Interactive collaboration principles
• Practical problem-solving focus
• Edge case and trade-off exploration
• Example prompts for various scenarios

references/consensus-pattern.md

Complete consensus mode system prompt and evaluation framework:

• 7-dimension assessment structure
• Verdict and confidence scoring format
• Stance configuration options
• Example proposals and evaluations

references/mcp-parameters.md

Complete reference for Codex MCP tool parameters:

• Required vs optional parameters
• Advisory mode configuration (sandbox, approval-policy)
• Developer instructions formatting
• Model selection guidance

Philosophy

Two Modes, One Purpose: Advisory Excellence

Chat and Consensus modes provide complementary collaboration styles while maintaining strict advisory boundaries:

• Safety: Read-only mode prevents unintended modifications in both modes
• Control: User reviews recommendations before implementation
• Efficiency: Claude uses optimal tools for code editing
• Expertise: Codex provides deep technical analysis through appropriate collaboration style
• Flexibility: Choose interaction mode based on decision complexity and stakes