name	description	version
codex-workflow	General-purpose Codex-powered implementation and review workflow. Use for non-trivial feature implementation with built-in code review. Emphasizes no-duplication, simplicity, and pattern consistency.	1.4.0

Codex Implementation & Review Workflow

Orchestrates feature implementation and code review using Codex MCP, with optional claude-context semantic search integration.

When to Use

Implementing a non-trivial feature (multi-file, architectural decisions)
Wanting thorough code review before committing
Making changes where duplication risk is high

Workflow Overview

Phase 0: SETUP (if claude-context available)
  → Force index the codebase
  → Wait for indexing to complete

Phase 1A: EXPLORATION
  → Launch Codex to discover codebase structure and existing utilities
  → Identify reusable code relevant to the task
  → Output: utility locations, relevant existing code, gaps

Phase 1B: IMPLEMENTATION
  → Launch Codex to implement (with exploration findings)
  → Require search before any new utility
  → Monitor until complete

Phase 2: RE-INDEX (if claude-context available)
  → Force re-index to capture new changes
  → Wait for completion

Phase 3: REVIEW
  → Launch Codex to review changes (with original task context)
  → Present findings by severity
  → Ask user: manual fix or auto-resolve?

Phase 4: AUTO-RESOLVE (if user opts in)
  → Evaluate which findings are worth fixing
  → Launch Codex to fix selected issues
  → Re-review fixes, iterate if needed (max 2 iterations)

Phase 5: VERIFICATION
  → Run tests, type checking, linting
  → Report failures to user
  → Optionally launch Codex to fix failures

Claude-Context Detection

Before starting, check if claude-context is available for this project:

mcp__claude-context__get_indexing_status({ path: "<project_root>" })

If this succeeds (returns status info) → claude-context is available
If this fails or MCP is unavailable → proceed without semantic search

Phase 0: Indexing (claude-context only)

If claude-context is available:

Force index the codebase:

mcp__claude-context__index_codebase({
  path: "<project_root>",
  force: true,
  customExtensions: [<project-specific extensions like ".svelte", ".vue", etc.>]
})

Wait for indexing to complete - poll every 60-180 seconds:
```
mcp__claude-context__get_indexing_status({ path: "<project_root>" })
```
Continue when status shows "completed".

Codex Configuration

Always include to prevent hanging:

sandbox: "danger-full-access"
approval-policy: "never"

Use danger-full-access when the project has dependencies outside its directory (monorepo, workspace packages). Use workspace-write for self-contained projects.

Phase 1A: Exploration

Purpose: Discover the codebase structure and find existing utilities BEFORE writing any code. This prevents duplication by identifying reusable code upfront.

Important: Save the threadId returned by this Codex call. You'll use it in Phase 1B to continue with full context.

Exploration Prompt Template

Explore this codebase to prepare for implementing the following feature:

{TASK_DESCRIPTION - brief summary}

DO NOT WRITE ANY CODE. This is exploration only.

EXPLORATION TASKS:

1. Read project conventions (CLAUDE.md, AGENTS.md, README, CONTRIBUTING)

2. Discover utility/helper locations:
   - Where does this project keep shared utilities?
   - Where are common helpers, parsers, formatters?
   - Where are API/HTTP helpers?
   - Where are UI component utilities (if frontend)?

3. Search for existing code relevant to this feature:
{IF claude-context available:}
   Use the search_code MCP tool for semantic searches. Search for:
{ELSE:}
   Use grep/glob to search for:
{ENDIF}
   - Patterns similar to what you'll need to implement
   - Utilities for: parsing, validation, formatting, streaming, HTTP, etc.
   - Any code that does something close to what the feature needs

4. Identify gaps:
   - What utilities exist that you can reuse?
   - What's missing that you'll need to create?

OUTPUT FORMAT:

## Utility Locations
- [path]: description of what's there

## Relevant Existing Code
- [path:function]: what it does, how it's relevant

## Reusable for This Feature
- [function/component]: how you'll use it

## Gaps (will need to create)
- [description]: why nothing existing fits

## Recommended Approach
- Brief implementation strategy based on findings

Phase 1B: Implementation

Important: Use mcp__codex__codex-reply with the threadId from Phase 1A to continue the session. This preserves all the exploration context (discovered utilities, relevant code, gaps identified) so Codex can build on what it learned.

Prompt Philosophy

Tell Codex WHAT to do, not HOW to do it.

Bad (over-prescriptive):

"Implement the feature using the handleAuth function in src/auth/handler.ts. Use the existing validateToken helper from line 45."

Good (goal-oriented):

"Implement JWT refresh token rotation. When a refresh token is used, invalidate it and issue a new one. Ensure this works with the existing auth flow."

Codex performs better when given freedom to explore and discover the right approach. Your job as the orchestrator is to:

Clearly describe the desired outcome
Specify constraints and requirements
Mention relevant domain context the user provided
Let Codex use the exploration findings it already has in context

Implementation Prompt Template

Use codex-reply with the exploration threadId:

mcp__codex__codex-reply({
  threadId: "<threadId from Phase 1A>",
  prompt: "<implementation prompt below>"
})

Now implement the feature based on your exploration findings.

BEFORE WRITING ANY NEW FUNCTION:

Check if you're about to write a "utility" - a small, generic, reusable function:
- Parses, validates, coerces, or transforms data
- Formats strings or numbers
- Handles streaming, events, or async patterns
- Makes HTTP/API calls
- Could reasonably live in a "utils" or "helpers" file

If YES → you MUST search first:
{IF claude-context available:}
- Use the search_code MCP tool with relevant terms
{ELSE:}
- Use grep/glob to search for similar functions
{ENDIF}
- Document: "Searched for [X]" → found [Y] / found nothing suitable

REQUIREMENTS:

- NO DUPLICATION: Search before creating any new utility (document your searches)
- REUSE FIRST: Use existing utilities from exploration findings
- SIMPLICITY: Implement exactly what's needed, no speculative features
- FOLLOW PATTERNS: Match existing architectural patterns, naming, error handling
- MINIMAL CHANGES: Don't refactor unrelated code

AFTER IMPLEMENTATION, REPORT:

1. Files created/modified with brief description

2. Utilities reused (from exploration findings):
   - [function]: used for [purpose]

3. New utilities created (with search justification):
   - [function]: searched for [X], found nothing suitable because [reason]

4. Any constraints or decisions you made

Phase 2: Re-Index (claude-context only)

If claude-context is available, re-index before review to capture new changes:

mcp__claude-context__index_codebase({
  path: "<project_root>",
  force: true
})

Wait for completion before proceeding to review.

Phase 3: Review

Note: Start a fresh Codex session for review (use mcp__codex__codex, not codex-reply). Review has a different purpose and benefits from a clean slate without implementation bias.

Include the original task description so Codex can verify requirements are met.

Review Prompt Template

Review the uncommitted changes in this project.

ORIGINAL TASK:
{TASK_DESCRIPTION}

REVIEW PROCESS:

1. Run `git diff HEAD` to see all uncommitted changes

2. Read project conventions (AGENTS.md, CLAUDE.md, etc.)

3. For EACH new function/utility in the diff:
{IF claude-context available:}
   - Use search_code MCP tool to search for similar existing functions
{ELSE:}
   - Use grep to search for similar existing functions
{ENDIF}
   - Check if it duplicates something that already existed

4. Verify the implementation report's search claims:
   - Did they actually search before creating new utilities?
   - Are there existing utilities they missed?

REVIEW CRITERIA:

1. REQUIREMENTS: Does the implementation actually do what was requested?
2. DUPLICATION: For each new utility, search the codebase - does similar code exist?
3. CODE QUALITY: Types, error handling, edge cases
4. SIMPLICITY: Over-engineering? Unnecessary abstractions?
5. CONVENTIONS: Consistent with existing patterns?

OUTPUT FORMAT:

For each finding:

**[SEVERITY]** File: path/to/file:LINE
Issue: Brief description
{IF duplication:}
Existing code: path/to/existing:LINE - description
{ENDIF}
Recommendation: Specific fix

Severity levels:
- CRITICAL: Must fix before merge (bugs, security, major duplication)
- IMPORTANT: Should fix (code quality, minor duplication)
- MINOR: Nice to fix (style, small improvements)
- SUGGESTION: Consider for future (not blocking)

DO NOT MAKE CHANGES. Report findings only.

Phase 4: Auto-Resolve

If user opts for auto-resolution:

Filter findings:

Keep:

CRITICAL issues (bugs, security, major duplication)
IMPORTANT issues that affect correctness or maintainability
Reasonable stylistic improvements

Discard:

Nitpicks that add churn without real benefit
Over-engineering recommendations
Issues outside scope of original task
Suggestions that contradict project conventions

Iteration loop (max 2 iterations):

Launch Codex to fix selected issues
Re-review the fixes (brief review, focused on the changes)
If new significant issues found → iterate
If clean or max iterations reached → proceed to verification

Stop iterating if:

No CRITICAL or IMPORTANT issues remain
Same issues keep reappearing (indicates deeper problem - escalate to user)
Max iterations (2) reached

Phase 5: Verification

Run project's verification commands (as the orchestrating agent, not Codex):

Tests - Run test suite if it exists
Type checking - TypeScript, mypy, etc. if applicable
Linting - If configured in project
Build - Verify it compiles/builds

If failures:

Report to user with summary
Ask: attempt auto-fix or handle manually?
If auto-fix → launch Codex with failure context, then re-verify

Anti-Patterns

Over-prescribing to Codex - Telling it which files/functions to use instead of describing the goal. Let Codex discover the codebase itself.
Pre-exploring then constraining - If you explored to understand the task, don't pass those specific findings to Codex. Pass the understanding, not the file paths.
Skipping exploration phase - Going straight to implementation without discovering existing utilities first.
Not requiring search documentation - Letting Codex create utilities without proving they searched first.
Making changes during review phase
Auto-fixing everything without filtering
Ignoring project conventions
Iterating endlessly on the same issues
Skipping verification

TKasperczyk/codex_cc_workflow_skill.md

Select an option

No results found