codex-workflows

End-to-end AI coding workflows for Codex CLI — specialized subagents handle requirements, design, implementation, and quality checks so you get code with explicit design docs, test coverage, and commit-level traceability — not just raw generations.

Built on the Agent Skills specification and Codex subagents. Works with the latest GPT models.

---

Quick Start

cd your-project
npx codex-workflows install

Then in Codex CLI:

$recipe-implement Add user authentication with JWT

$ is Codex CLI's syntax for invoking a skill explicitly. Type $recipe- to see all available recipes via tab completion.

The framework runs a structured workflow — requirements → design → task decomposition → TDD implementation → quality gates — all through specialized subagents.

---

Why codex-workflows?

Without codex-workflows:

• Code generation is inconsistent across large tasks
• Requirements and design decisions are implicit — lost after the session
• Refactoring and debugging become harder as context grows

With codex-workflows:

• Every change is traceable: PRD → Design Doc → Task → Commit
• Built-in TDD and quality gates catch regressions before commit
• Large tasks stay structured and reviewable through agent context separation

---

What It Does

A single request becomes a structured development process:

1. Understand the problem (scale, constraints, affected files)
2. Analyze the existing codebase (dependencies, data layer, risk areas)
3. Design the solution (ADR, Design Doc with acceptance criteria)
4. Break it into tasks (atomic, 1 commit each)
5. Implement with tests (TDD per task)
6. Run quality checks (lint, test, build — no failing checks)

Each step is handled by a specialized subagent in its own context, preventing context pollution and reducing error accumulation in long-running tasks:

User Request
    ↓
requirement-analyzer  →  Scale determination (Small / Medium / Large)
    ↓
prd-creator           →  Product requirements (Large scale)
    ↓
codebase-analyzer     →  Existing codebase facts + focus areas
    ↓
technical-designer    →  ADR + Design Doc with acceptance criteria
    ↓
code-verifier         →  Design Doc vs existing code verification
    ↓
document-reviewer     →  Quality gate with verification evidence
    ↓
acceptance-test-gen   →  Test skeletons from ACs
    ↓
work-planner          →  Phased execution plan
    ↓
task-decomposer       →  Atomic tasks (1 task = 1 commit)
    ↓
task-executor         →  TDD implementation per task
    ↓
quality-fixer         →  Lint, test, build — no failing checks
    ↓
Ready to commit

The Diagnosis Pipeline

Problem → investigator → verifier (ACH + Devil's Advocate) → solver → Actionable solutions

Reverse Engineering

Existing code → scope-discoverer (discoveredUnits + prdUnits) → prd-creator → code-verifier → document-reviewer → Design Docs

---

Installation

Requirements

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

Install

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

Update

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

# Apply updates
npx codex-workflows update

Files you've modified locally are preserved — the updater compares each file against its hash at install time and skips any file you've changed. New files from the update are added automatically.

# Check installed version
npx codex-workflows status

---

Recipe Workflows

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

Backend & General

Recipe	What it does	When to use
$recipe-implement	Full lifecycle with layer routing (backend/frontend/fullstack)	New features — universal entry point
$recipe-task	Single task with rule selection	Bug fixes, small changes
$recipe-design	Requirements → ADR/Design Doc	Architecture planning
$recipe-plan	Design Doc → test skeletons → work plan	Planning phase
$recipe-build	Execute backend tasks autonomously	Resume backend implementation
$recipe-review	Design Doc compliance and security validation with auto-fixes	Post-implementation check
$recipe-diagnose	Problem investigation → verification → solution	Bug investigation
$recipe-reverse-engineer	Generate PRD + Design Docs from existing code	Legacy system documentation
$recipe-add-integration-tests	Add integration/E2E tests from Design Doc	Test coverage for existing code
$recipe-update-doc	Update existing Design Doc / PRD / ADR with review	Spec changes, document maintenance

Frontend (React/TypeScript)

Recipe	What it does	When to use
$recipe-front-design	Requirements → UI Spec → frontend Design Doc	Frontend architecture planning
$recipe-front-plan	Frontend Design Doc → test skeletons → work plan	Frontend planning phase
$recipe-front-build	Execute frontend tasks with RTL + quality checks	Resume frontend implementation
$recipe-front-review	Frontend compliance and security validation with React-specific fixes	Frontend post-implementation check

Fullstack (Cross-Layer)

Recipe	What it does	When to use
$recipe-fullstack-implement	Full lifecycle with separate Design Docs per layer	Cross-layer features
$recipe-fullstack-build	Execute tasks with layer-aware agent routing	Resume cross-layer implementation

Examples

Full feature development:

$recipe-implement Add user authentication with JWT and role-based access control

Quick fix with proper rule selection:

$recipe-task Fix validation error message in checkout form

Investigate a bug:

$recipe-diagnose API returns 500 error on user login after deployment

Document undocumented legacy code:

$recipe-reverse-engineer src/auth module

---

Foundational Skills

These load automatically when the conversation context matches — no explicit invocation needed:

Skill	What it provides
coding-rules	Code quality, function design, error handling, refactoring
testing	TDD Red-Green-Refactor, test types, AAA pattern, mocking
ai-development-guide	Anti-patterns, debugging (5 Whys), quality check workflow
documentation-criteria	Document creation rules and templates (PRD, ADR, Design Doc, Work Plan)
implementation-approach	Strategy selection: vertical / horizontal / hybrid slicing
integration-e2e-testing	Integration/E2E test design, ROI calculation, review criteria
task-analyzer	Task analysis, scale estimation, skill selection
subagents-orchestration-guide	Multi-agent coordination, workflow flows, autonomous execution

Language-specific references are included for TypeScript/React projects (coding-rules/references/typescript.md, testing/references/typescript.md).

---

Subagents

Codex spawns these as needed during recipe execution. Each agent runs in its own context with specialized instructions and skill configurations.

Document Creation Agents

Agent	Role
requirement-analyzer	Requirements analysis and work scale determination
prd-creator	PRD creation and structuring
technical-designer	ADR and Design Doc creation (backend)
technical-designer-frontend	Frontend ADR and Design Doc creation (React)
ui-spec-designer	UI Specification from PRD and optional prototype code
codebase-analyzer	Existing codebase analysis before Design Doc creation
work-planner	Work plan creation from Design Docs
document-reviewer	Document consistency and approval
design-sync	Cross-document consistency verification

Implementation Agents

Agent	Role
task-decomposer	Work plan → atomic task files
task-executor	TDD implementation following task files (backend)
task-executor-frontend	React implementation with Testing Library
quality-fixer	Quality checks and fixes until all pass (backend)
quality-fixer-frontend	React-specific quality checks (TypeScript, RTL, bundle)
acceptance-test-generator	Test skeleton generation from acceptance criteria
integration-test-reviewer	Test quality review

Analysis Agents

Agent	Role
code-reviewer	Design Doc compliance validation
code-verifier	Document-code consistency verification
security-reviewer	Security compliance review after implementation
rule-advisor	Skill selection via metacognitive analysis
scope-discoverer	Codebase scope discovery for reverse docs, including PRD unit grouping

Diagnosis Agents

Agent	Role
investigator	Evidence collection and hypothesis enumeration
verifier	Hypothesis validation (ACH + Devil's Advocate)
solver	Solution derivation with tradeoff analysis

---

How It Works

Scale-Based Workflow Selection

The framework automatically determines the right level of ceremony:

Scale	File Count	What Happens
Small	1-2	Simplified plan → direct implementation
Medium	3-5	Design Doc → work plan → task execution
Large	6+	PRD → ADR → Design Doc → test skeletons → work plan → autonomous execution

Autonomous Execution Mode

After work plan approval, the framework enters guided autonomous execution with escalation points:

1. task-executor implements each task with TDD
2. quality-fixer runs all checks (lint, tests, build) before every commit
3. Escalation pauses execution when design deviation or ambiguity is detected
4. Each task produces one commit — rollback-friendly granularity

Context Separation

Each subagent runs in a fresh context. This matters because:

• document-reviewer reviews without the author's bias
• investigator collects evidence without confirmation bias
• code-reviewer validates compliance without implementation context

---

Project Structure

After installation, your project gets:

your-project/
├── .agents/skills/           # Codex skills
│   ├── coding-rules/         # Foundational (auto-loaded)
│   ├── testing/
│   ├── ai-development-guide/
│   ├── documentation-criteria/
│   ├── implementation-approach/
│   ├── integration-e2e-testing/
│   ├── task-analyzer/
│   ├── subagents-orchestration-guide/
│   ├── recipe-implement/     # Recipes ($recipe-*)
│   ├── recipe-design/
│   ├── recipe-build/
│   ├── recipe-plan/
│   ├── recipe-review/
│   ├── recipe-diagnose/
│   ├── recipe-task/
│   ├── recipe-update-doc/
│   ├── recipe-reverse-engineer/
│   └── recipe-add-integration-tests/
├── .codex/agents/            # Subagent TOML definitions
│   ├── requirement-analyzer.toml
│   ├── technical-designer.toml
│   ├── task-executor.toml
│   └── ... (23 agents total)
└── docs/                     # Created as you use the recipes
    ├── prd/
    ├── design/
    ├── adr/
    ├── ui-spec/
    └── plans/
        └── tasks/

---

FAQ

Q: What models does this work with?

A: Designed for the latest GPT models. Lightweight subagents (e.g. rule-advisor) can use smaller models for faster analysis. Models are configurable per agent in the TOML files.

Q: Can I customize the agents?

A: Yes. Edit the TOML files in .codex/agents/ — change model, sandbox_mode, developer_instructions, or skills.config. Files you modify locally are preserved during npx codex-workflows update.

Q: What's the difference between $recipe-implement and $recipe-fullstack-implement?

A: $recipe-implement is the universal entry point. It runs requirement-analyzer first, detects affected layers from the codebase, and automatically routes to backend, frontend, or fullstack flow. $recipe-fullstack-implement skips the detection and goes straight into the fullstack flow (separate Design Docs per layer, design-sync, layer-aware task execution). Use $recipe-implement when you're not sure; use $recipe-fullstack-implement when you know upfront that the feature spans both layers.

Q: How does this relate to Claude Code Workflows?

A: codex-workflows is the Codex-native counterpart of Claude Code Workflows. Same development philosophy, adapted for Codex CLI's subagent architecture and GPT model family.

Q: Does this work with MCP servers?

A: Yes. Codex skills and subagents work alongside MCP — skills operate at the instruction layer while MCP operates at the tool transport layer. You can add MCP servers to any agent's TOML configuration.

Q: What if a subagent gets stuck?

A: Subagents escalate to the user when they encounter design deviations, ambiguous requirements, or specification conflicts. The framework stops autonomous execution and presents the issue with options.

---

License

MIT License — free to use, modify, and distribute.

---

Built and maintained by @shinpr