codex-workflows

English | 简体中文 | 日本語 | Español | 한국어 | Português (Brasil)

On larger product work, Codex can pursue technical consistency beyond what the user needs. Handling every edge case and making each path deterministic can alter what users see even when the approved outcome does not require it.

codex-workflows keeps that work within the smallest approved outcome. It confirms which user-visible behavior may change, records what must not, and requires evidence before completion. Within those boundaries, Codex chooses reversible implementation details from the repository.

The workflows are installed as Agent Skills and custom agents for OpenAI Codex CLI. The main Codex session checks scope and rough cost before design, owns progress and review decisions, and carries approved work through implementation and independent verification.

---

Why not use Codex directly?

Direct Codex is the better fit for a well-scoped fix, disposable experiment, or one-shot script. It is faster and cheaper when the intended outcome and safe implementation boundary are already clear.

Use codex-workflows when technical choices can change the product scope, user-visible behavior, or a decision that needs to survive across contexts.

For example, a request to extend an existing authentication path can lead to a technically cleaner second mechanism, broader validation, and a new response contract. The frontend may adapt and the tests may pass, while users receive behavior that was never part of the approved change.

codex-workflows controls that expansion throughout the run:

Control	What changes
Scope	The workflow compares the request with the desired outcome, explicit exclusions, the existing code, and rough implementation cost. Work that does not earn its cost is removed before it becomes architecture, and cut back later if it got in anyway.
Phase gates	Requirements, design, and planning outputs are checked before they can authorize the next phase. Fresh agents read the approved decisions and evidence they need instead of reconstructing intent from a long conversation.
Execution	Once you authorize implementation, Codex executes the task set autonomously. Each task passes its focused verification and applicable repository checks before its implementation commit.
Completion	Independent code and security reviews check that the completed change stays within the approved scope and has no serious problems. Required corrections return through the same implementation and quality cycle.

This workflow uses more agent calls and tokens than direct execution. Use it when protecting the approved outcome is worth that cost. When a change does not need every check, lite mode runs fewer of them.

An edge case does not require work simply because Codex can handle it. Additional validation, deterministic behavior, or a new abstraction must protect an approved requirement, an observable contract, or a demonstrated failure. This cuts both ways: when a design decision turns out to carry more than the outcome needs, the workflow removes it instead of defending it because a document already named it.

A real workflow run

The BytePlus Seedream provider integration in mcp-image added a third external image provider across 18 files. Eight planned tasks kept the public MCP request, client, file-save, and file-URI contracts unchanged while the provider-specific implementation evolved.

Before merge, live evaluation established the final model routing, prompt limits, timeout, and response handling. Independent reviews also caught an unbounded file read, a validation bypass, a blocking FIFO path, and inconsistent API-key normalization. All four were fixed, and the PR passed 303 tests across 19 files plus a no-retry live provider call. Across the eight tasks and four fixes, the approved public contracts stayed unchanged.

---

Quick Start

Requires Node.js 22 or later and the latest Codex CLI.

Install and run

cd your-project
npx codex-workflows install

Then invoke a recipe in Codex CLI:

$recipe-implement Add user authentication with JWT

$ invokes a skill explicitly. Type $recipe- to see the available workflows.

Choose a path

What do you need?	Start with
Deliver a change end to end and let the workflow choose the backend, frontend, or fullstack path	$recipe-implement
Design first and implement later	$recipe-design → $recipe-plan → $recipe-build
Design and build a React / TypeScript web frontend	$recipe-front-design → $recipe-front-plan → $recipe-front-build
Start directly with separate backend and React frontend design flows	$recipe-fullstack-implement
Review an implementation against its design	$recipe-review or $recipe-front-review
Define or update repository-specific quality rules	$recipe-quality-profile
Investigate a problem without changing code	$recipe-diagnose
Run a throwaway experiment or one-shot script	Use Codex directly

---

How It Works

flowchart LR
    A[Request] --> B[Agree on the smallest useful outcome]
    B --> C{One evident implementation path?}
    C -->|Yes| S[Direct task cycle and security review]
    S --> L[Complete]
    C -->|No| D[Inspect, design, and review]
    D --> E[Plan dependent work]
    E --> F[Authorize implementation]
    F --> H[Per task: implement, verify, quality-check, commit]
    H --> K[Independent code and security review]
    K -->|Correction| H
    K -->|Requirement or major design changed| B
    K -->|Passed| L[Complete]

The number of independent product and design decisions determines the route, not file count or the number of edge cases Codex can identify