Proposal: User-Defined Codex Workflows

What variant of Codex are you using?

CLI

What feature would you like to see?

Proposal: User-Defined Codex Workflows

Workflows are user-authored agent procedures that Codex can run as named, repeatable processes.

A workflow lets a user describe not just the outcome they want, but the process Codex should follow to get there. Instead of asking Codex to improvise from a single prompt, the user can invoke a predefined procedure for work such as fixing bugs, implementing features, reviewing code, preparing releases, running migrations, or coordinating multi-step production work.

For example:

/fix-bug check reported bug # GIT-123

Codex reads the workflow, uses the task details to inspect the referenced ticket or work item when available, executes the authored steps, carries context between them, follows any retry or escalation rules, and reports progress and results back to the user.

The core idea:

Users define the process.
Codex executes it.

The product value is that Codex understands a user-authored process as something it can execute consistently: binding task-specific values such as ticket IDs, project names, and output targets; running ordered steps; applying role-specific instructions; carrying context between nodes; handling verification loops; respecting stopping conditions; and producing final reports.

---

Origin of the Idea

This proposal comes from a pattern that appears after using Codex for real multi-step work: the user starts repeating the same prompt sequences.

The first workaround is straightforward: save useful prompts in files and reuse them manually.

For example:

sequential-prompts/
  understand-request.md
  inspect-project.md
  implement.md
  verify.md
  summarize.md

That works, but it leaves the user acting as the workflow engine. The user still has to remember which prompt comes next, copy the right file, pass context between steps, decide what to do when verification fails, and adapt the sequence for each project.

That workaround also creates a constant adaptation cost. Saved prompt files often contain concrete details from the last run, such as a ticket number. Before using the same sequence on a new ticket, the user has to find and replace values like GIT-123 throughout the prompt files. That manual adaptation is exactly the kind of work a workflow system should absorb.

The need becomes clearer because different projects need different prompt sequences. A software project might have prompts for bug triage, implementation, tests, static analysis, and ticket updates. A video generation project might have a completely different sequence:

video-production/
  prepare.md
  develop-story.md
  plan-scenes.md
  generate-assets.md
  produce-video.md
  review-output.md

The missing product concept is not "users can save prompts." Users can already do that. The missing concept is that Codex can treat a saved prompt sequence as a named workflow with invocation-specific inputs, execution state, ordering, handoff between nodes, failure handling, and progress reporting.

---

Workflow Shape

A workflow is a named procedure made up of one or more steps. The exact nodes depend on the user's process.

One possible bug-fix authoring shape:

fix-bug/
  WORKFLOW.md
  adapt-input.md
  read-ticket.md
  reproduce.md
  triage.md
  understand-project.md
  implement.md
  verify.md
  static-analysis.md
  loop-on-failure.md
  update-ticket.md
  summarize.md

WORKFLOW.md describes the overall flow. Each node file describes what Codex should do at that stage.

Example snippets for each file:

# WORKFLOW.md

Run these nodes in order:
adapt-input -> read-ticket -> reproduce -> triage -> understand-project
-> implement -> verify -> static-analysis -> update-ticket -> summarize

If `verify` or `static-analysis` fails, run `loop-on-failure`.
After `loop-on-failure` resolves the cause, resume at the appropriate
earlier node and continue forward.
If the ticket lacks critical details, stop and ask the user.

# adapt-input.md

Parse the workflow invocation.
Bind values such as `ticket_id = GIT-123`, requested action,
project name, branch name, or target artifact.
Use those values throughout the workflow without editing the original
node files. If a required value is missing, ask the user.

# read-ticket.md

Read the ticket or work item referenced by `ticket_id`.
Extract the user-visible problem or request, expected behavior,
actual behavior, acceptance criteria, severity, environment,
repro steps, logs, screenshots, and related links.

# reproduce.md

Try to reproduce the reported behavior using the ticket details.
If the issue cannot be reproduced, identify the closest verifiable
path and list what information is missing.

# triage.md

Map the ticket to likely product areas.
Identify the suspected root cause, affected files, related tests,
dependencies, and whether the ticket describes a regression,
missing behavior, or ambiguous requirement.

# understand-project.md

Before changing code, inspect the project's rules, conventions,
architecture, existing patterns, and relevant documentation.
Prefer local conventions over new abstractions.
Identify constraints that should shape the implementation.

# implement.md

Make the smallest safe code change that satisfies the ticket.
Preserve existing behavior unless the ticket explicitly requires a change.
Do not modify generated files or unrelated areas.

# verify.md

Add or update focused tests for the reported behavior or acceptance criteria.
Run the narrowest relevant tests first, then any broader checks required
by the workflow.

# static-analysis.md

After verification, run static analysis such as type checks, linting,
format checks, dependency checks, or project-specific analyzers.
Treat failures as workflow failures that must be investigated.

# loop-on-failure.md

If verification or static analysis fails, determine whether the problem
is the implementation, the test, the environment, or the ticket interpretation.
Return to the correct earlier node. If the same class of failure repeats,
stop and ask the user.

# update-ticket.md

Update the referenced ticket status or draft the exact update for the user.
Include the current state, cause or implementation notes, verification
evidence, remaining risks, and any open questions.

# summarize.md

Summarize the ticket, the cause or chosen approach, the code change,
the verification evidence, static analysis result, ticket status,
and any remaining risks.

The Codex team can decide the technical execution model. The user-facing concept is that a workflow is a reusable procedure Codex can invoke by name.

The same concept applies outside ticket-based software work. A video generation workflow could have a completely different shape:

video-production/
  WORKFLOW.md
  adapt-input.md
  prepare.md
  develop-story.md
  plan-scenes.md
  generate-assets.md
  produce-video.md
  review-output.md

In that workflow, adapt-input.md might bind values such as project title, target duration, aspect ratio, visual style, and delivery format. The later nodes would use those values without requiring the user to rewrite each saved prompt.

---

Example 1: Bug Fix Workflow

A user or team defines a workflow called fix-bug.

The developer runs:

/fix-bug check reported bug # GIT-123

Codex follows the authored process:

adapt-input
  Parse the command, bind ticket_id = GIT-123, and use that value
  throughout the workflow without changing the saved node files.

read-ticket
  Read the ticket referenced by ticket_id.
  Extract the user-visible failure, expected behavior, actual behavior,
  environment, repro steps, attachments, and logs.

reproduce
  Use the ticket to reproduce the failure locally or identify the closest
  verifiable reproduction path.

triage
  Identify the likely root cause, affected files, related tests,
  and whether the ticket describes a regression or an existing gap.

understand-project
  Inspect project rules, conventions, architecture, and local patterns
  before editing. Identify constraints that should shape the fix.

implement
  Make the smallest safe code change that fixes the reported behavior.

verify
  Add or update a regression test, then run the narrowest relevant checks.

static-analysis
  Run type checks, linting, formatting checks, and project-specific analyzers
  after verification.

loop-on-failure
  If verification or static analysis fails, analyze whether the patch,
  the test, the environment, or the ticket interpretation is wrong,
  then return to the right step.

update-ticket
  Update the ticket referenced by ticket_id, or draft the exact ticket update with
  the cause, fix, verification result, and static analysis result.

summarize
  Explain what changed, what was tested, the static analysis result,
  the ticket status, and any remaining risks.

The workflow can encode the user's preferred debugging behavior once:

Treat the referenced ticket as the source of truth.
Use the workflow invocation to bind the current ticket ID.
Never require manual find-and-replace inside saved prompt files.
Extract repro steps before editing.
Always inspect tests before changing implementation code.
Understand project rules, conventions, and architecture before implementation.
Prefer minimal patches.
Do not modify generated files.
Run the narrowest regression test first, then the broader suite.
Run static analysis after verification.
Update the ticket status before the final summary.
If the ticket is missing critical repro details, stop and ask the developer.
If verification or static analysis fails twice, stop and ask the developer.

From the user's point of view, they are not asking Codex to "try to fix a bug." They are asking Codex to follow a known bug-fixing process.

---

Example 2: Feature Implementation Workflow

A user or team defines a workflow called ship-feature.

The developer runs:

/ship-feature implement product request # GIT-456

Codex follows the authored workflow:

adapt-input
  Parse the command, bind ticket_id = GIT-456, and use that value
  throughout the workflow without changing the saved node files.

read-request
  Read the request referenced by ticket_id.
  Extract the requested user behavior, acceptance criteria, product constraints,
  designs, and rollout notes.

clarify-requirements
  Restate the request, identify assumptions, and flag any missing acceptance criteria.

design-plan
  Propose the implementation approach, affected product areas,
  data changes, permissions, and files likely to change.

understand-project
  Inspect project rules, conventions, architecture, and local patterns
  before implementation. Adjust the plan to fit the existing system.

implement
  Add the feature according to the request and approved plan.

add-tests
  Add or update tests that cover the acceptance criteria from the request
  referenced by ticket_id.

verify
  Run tests and any workflow-specific acceptance checks.

static-analysis
  Run type checks, linting, formatting checks, and project-specific analyzers
  after verification. Resolve any failures.

update-ticket
  Update the ticket referenced by ticket_id, or draft the exact ticket update with
  implementation notes, verification evidence, static analysis result,
  and unresolved decisions.

prepare-pr
  Produce a PR-style summary with user-visible behavior,
  implementation notes, validation, and linked request context.

Feature-specific node files might contain:

# read-request.md

Read the product request referenced by `ticket_id`.
Extract the requested user behavior, acceptance criteria,
constraints, designs, rollout notes, and related tickets.

# clarify-requirements.md

Restate the request in implementation terms.
Identify assumptions, missing acceptance criteria, product questions,
and decisions that need user confirmation before coding.

# design-plan.md

Propose the implementation approach.
Name affected product areas, data model changes, permissions,
API changes, UI states, migration needs, and files likely to change.

# add-tests.md

Add or update tests that prove the acceptance criteria.
Cover expected behavior, important edge cases, and any regression risk
introduced by the implementation.

# prepare-pr.md

Prepare a PR-style summary.
Include user-visible behavior, implementation notes, verification evidence,
static analysis result, ticket status, and remaining risks.

Shared nodes such as adapt-input.md, understand-project.md, verify.md, static-analysis.md, and update-ticket.md use the same snippets shown above.

The workflow becomes a reusable playbook.

One user might require tests before implementation. Another might require a design note before code changes. Another might require accessibility checks, security review, migration notes, or release documentation.

The feature does not force one methodology. It lets users encode their own methodology.

---

Why This Matters

Today, a developer can give Codex instructions in chat or rely on persistent guidance for broad rules: setup commands, code style, testing conventions, and general operating preferences.

But many real development tasks are not single-step instructions. They are repeatable processes:

adapt input -> read ticket -> understand project -> implement -> verify -> static analysis -> update ticket -> summarize
adapt input -> develop story -> plan scenes -> generate assets -> produce video -> review output
review -> classify findings -> suggest fixes -> verify -> summarize
migrate -> understand architecture -> update call sites -> run compatibility checks -> static analysis

Workflows give users a structured way to define, invoke, and reuse those processes.

---

High-Level Feature Request

Add support for user-defined Codex Workflows.

A workflow is a named, user-authored procedure that describes a multi-step agent process. Users trigger a workflow from chat using:

/workflow-name [task details]

Codex reads the workflow, binds the invocation details to workflow inputs, executes the authored steps, carries context between them, follows the workflow's control rules, and reports progress and results back to the user.

---

Product Principle

Codex should own the execution engine. Users should own the workflow content.

Users define what their process looks like. Codex handles how that process is executed safely, reliably, and consistently.

The result is that repeated prompt sequences become reusable playbooks that Codex can adapt to the current task and run end to end.

Additional information

_No response_