Codex Workflows

codex-workflows

Codex is already good at one-shot changes. The gap shows up when a task touches multiple files — you start doing the planning, scoping, and verification yourself, which is exactly the work agents should handle.

codex-workflows fills that gap. It sets up specialized subagents that take a request through requirements, design, task decomposition, TDD implementation, and quality checks — each step in its own context, each task landing as one commit.

What happens when you run a recipe

$recipe-implement Add user authentication with JWT

The framework picks the right level of structure based on scope:

• 1-2 files: simplified plan, direct implementation
• 3-5 files: Design Doc, work plan, task execution
• 6+ files: PRD, ADR, Design Doc, test skeletons, phased execution

For larger work, the pipeline looks like this:

User Request
    ↓
requirement-analyzer  →  scope + scale
    ↓
technical-designer    →  ADR + Design Doc with acceptance criteria
    ↓
task-decomposer       →  atomic tasks (1 task = 1 commit)
    ↓
task-executor         →  TDD implementation per task
    ↓
quality-fixer         →  lint, test, build — all green
    ↓
Verified and ready to commit

Each subagent runs in a fresh context. The task-executor doesn't inherit assumptions from the designer. The quality-fixer rejects incomplete work before anything gets committed. By the time you look at the result, verification is already done.

Recipes

$recipe-implement    Full feature lifecycle with layer routing
$recipe-task         Single task with rule selection
$recipe-design       Requirements → ADR / Design Doc
$recipe-diagnose     Problem investigation → verified solution
$recipe-reverse-engineer  Generate docs from existing code

Frontend and fullstack recipes are included for React/TypeScript projects.

Context separation

Generation and verification happen in separate agent contexts. The document-reviewer doesn't know what the technical-designer was thinking — it reviews the output cold. The investigator collects evidence without confirmation bias from whoever reported the bug. This is context engineering, not prompt engineering.

Setup

cd your-project
npx codex-workflows install

Works with GPT-5.4, GPT-5.3-Codex, and GPT-5.3-Codex-Spark. Agents are configured via TOML files — model, sandbox mode, skills, and instructions are all editable per agent.

Codex-native counterpart of claude-code-workflows.