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:

This workflow uses more agent calls and tokens than direct execution. Use it when protecting the approved outcome is worth that cost.

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.

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

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[Approve implementation scope]
    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.

An ADR is created only for a durable current-scope choice with at least two materially distinct options. When several choices qualify, their ADRs are reviewed together. An integration or E2E test is selected only when a cheaper test cannot prove the required interaction. Some changes need neither.

Only decisions that affect the product or repository implementation are carried forward in durable project documents. Third-party approval, production access, release execution, and unrelated operational work do not become implementation gates.

After the implementation scope is approved, the orchestrator runs the tasks, focused verification, applicable repository checks, and one implementation commit per task. It resolves problems from the approved documents and repository evidence first. User-visible behavior remains a product boundary rather than something the implementation may adjust for internal consistency. The orchestrator asks you only when progress requires a new product requirement, a change to a major approved design decision, authority only you hold, or an irreversible action you did not authorize.

Each specialist gets a bounded job, the relevant documents and paths, and a clear result to return. The specialist carries that job through completion while the main session keeps product and workflow decisions, steps in only for a decision or concrete blocker, and checks the result before the next phase. This gives specialists room to work without giving them authority to widen the approved outcome.

How decisions survive fresh contexts

Fresh contexts keep exploration, design, implementation, and review from silently sharing assumptions. The included Work Plan template ties each implementation task to its Design Doc section and acceptance criteria:

### P1-T1: Preserve the error response contract

- **Source**: `docs/design/example-design.md`, API contract, AC-2
- **Scope**: Update the repository implementation and its focused tests
- **Depends on**: none
- **Verification**: Run the contract test and observe the documented response shape

The Task File Contract carries the source, intended result, target files, and executable verification into implementation. It adds a Verification Focus only when a test could pass without proving one important behavior. After execution, the applicable repository checks run against the complete task change before commit. Final reviewers compare the completed code with the approved documents. They also look for work outside the approved scope and serious code-quality problems. When a correction is accepted, the next review focuses on the checks that correction could affect. Run $recipe-quality-profile to define repository-specific quality rules in docs/project-context/quality.yaml for implementation and review.

Installation

Requirements

• Codex CLI (latest)
• Node.js >= 22

Install

Install into the current project:

cd your-project
npx codex-workflows install

This copies into your project:

• .agents/skills/: Codex skills (foundational + recipes)
• .codex/agents/: Subagent TOML definitions
• Manifest file for tracking managed files

To make the workflows available to Codex across all projects, install them into your user-level CODEX_HOME instead:

npx codex-workflows install --user

This installs skills into $CODEX_HOME/skills/ and agents into $CODEX_HOME/agents/. When CODEX_HOME is not set, it defaults to ~/.codex.

Customize agents

Agent definitions are regular TOML files. For a project installation, edit files in .codex/agents/; for a user-level installation, edit files in $CODEX_HOME/agents/. You can change the model, sandbox_mode, or developer_instructions. Updates preserve files you have edited, as described below.

Update

# Preview what will change
npx codex-workflows update --dry-run

# Apply updates
npx codex-workflows update

# Update a user-level installation
npx codex-workflows update --user

The updater preserves files you have modified locally. It compares each file against its hash at install time and skips changed files. Versioned update history applies file moves and deletions in order, so local changes follow a moved file to its current path. Modified files retired without a replacement are moved to .codex-workflows-preserved/<version>/. New files from the update are added automatically.

# Check installed version
npx codex-workflows status

# Check a user-level installation
npx codex-workflows status --user

Workflow Recipe Reference

Invoke recipes with $recipe-name in Codex. Type $recipe- and use tab completion to see all available recipes.

Working State

Recipes use docs/plans/ as ephemeral working state for Work Plans, implementation Task Files, and temporary review-fix or test-addition Task Files. Task and phase progress is updated there after each quality-approved implementation commit, while those progress files stay outside that commit. Add the directory to your project's .gitignore unless your team intentionally wants to review those transient files:

docs/plans/

PRDs, ADRs, UI Specs, and Design Docs are durable project documents and are intended to be committed.

Included Guidance

Recipes load the repository-aware guidance required for the current task. You rarely need to select these skills directly.

Specialized Agents

Codex spawns these as needed during recipe execution. You do not need to learn them first; recipes route domain work to the relevant agents while the orchestrator retains workflow control. Each agent runs in its own context with specialized instructions and explicitly named required skills.

Project Structure

After installation, your project gets:

your-project/
├── .agents/skills/           # Codex skills
│   ├── coding-rules/         # Foundational guidance
│   ├── testing/
│   ├── ai-development-guide/
│   ├── reviewee-judgment/
│   ├── documentation-criteria/
│   ├── requirement-convergence/
│   ├── implementation-approach/
│   ├── integration-e2e-testing/
│   ├── external-resource-context/
│   ├── llm-friendly-context/
│   ├── task-analyzer/
│   ├── subagent-delegation/
│   ├── subagents-orchestration-guide/
│   └── recipe-*/             # Workflow entry points ($recipe-*)
├── .codex/agents/            # Subagent TOML definitions
│   ├── requirement-analyzer.toml
│   ├── technical-designer.toml
│   ├── ui-analyzer.toml
│   ├── task-executor.toml
│   └── ... (26 agents total)
└── docs/                     # Created as you use the recipes
    ├── prd/
    ├── design/
    ├── adr/
    ├── ui-spec/
    └── plans/
        └── tasks/

Ecosystem

Nautilus validates product ideas and produces PRDs, while linear-prism turns approved requirements into implementation-ready Linear issues. claude-code-workflows brings the same approach to Claude Code and can be installed alongside codex-workflows.

Design Rationale

License

MIT License. Free to use, modify, and distribute.

Built and maintained by @shinpr