TKasperczyk/codex_cc_workflow_skill.md

## codex_cc_workflow_skill.md

      
    Raw
  

              codex_cc_workflow_skill.md
            
          
  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.2.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 1: IMPLEMENTATION
  → Launch Codex to implement the feature
  → 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 1: Implementation

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 find the implementation details itself

Do NOT pre-chew the work by pointing to specific files, functions, or line numbers. That constrains Codex's ability to find better solutions.
Implementation Prompt Template

Adapt based on project context:
Implement the following feature:

{TASK_DESCRIPTION - focus on WHAT and WHY, not HOW}

BEFORE WRITING CODE:

1. Read project conventions - AGENTS.md, CLAUDE.md, CONTRIBUTING.md, README
2. Explore the codebase to understand existing patterns and architecture
3. Search for existing implementations you can reuse or extend
{IF claude-context available:}
4. Use the search_code MCP tool for semantic searches across the codebase
{ENDIF}

REQUIREMENTS:

- NO DUPLICATION: Search before creating any new utility, component, or helper
- 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:

- Files created/modified with brief description
- Existing utilities you reused (prove you searched)
- 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

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. Search the codebase to check for duplication
{IF claude-context available:}
4. Use the search_code MCP tool for semantic searches against the full codebase
{ENDIF}

REVIEW CRITERIA:

1. REQUIREMENTS: Does the implementation actually do what was requested?
2. DUPLICATION: Did implementation miss existing utilities that should have been reused?
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
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 search step before creating new code
Making changes during review phase
Auto-fixing everything without filtering
Ignoring project conventions
Iterating endlessly on the same issues
Skipping verification
No results found