# Team Pipeline Flow in oh-my-codex: 5-Phase Multi-Agent Orchestration

> Explore the 5-phase team pipeline flow in oh-my-codex: team-plan, team-prd, team-exec, team-verify, and team-fix. Understand multi-agent orchestration via declarative state management.

- Repository: [Bellman/oh-my-codex](https://github.com/Yeachan-Heo/oh-my-codex)
- Tags: internals
- Published: 2026-04-03

---

**The team pipeline flow in oh-my-codex is a five-phase cyclic workflow—team-plan → team-prd → team-exec → team-verify → team-fix—that coordinates specialized LLM agents through declarative state management defined in [`AGENTS.md`](https://github.com/Yeachan-Heo/oh-my-codex/blob/main/AGENTS.md).**

The **team pipeline** serves as the core coordination model driving multi-agent collaboration in the [oh-my-codex](https://github.com/Yeachan-Heo/oh-my-codex) repository. This structured workflow enables autonomous planning, execution, and verification loops that persist state across crashes and support iterative refinement. The entire contract governing these phases lives in the repository’s top-level **[`AGENTS.md`](https://github.com/Yeachan-Heo/oh-my-codex/blob/main/AGENTS.md)** file, which maps specific prompt roles to each stage of development.

## The Five Phases of the Team Pipeline

The pipeline progresses through five distinct sequential phases, with the final phase creating a loop back to execution when verification fails.

### team-plan: Requirements and Scoping

The **team-plan** phase initiates the workflow by gathering requirements and establishing a high-level approach to the problem. During this stage, the **team-orchestrator** prompt (defined in [`prompts/team-orchestrator.md`](https://github.com/Yeachan-Heo/oh-my-codex/blob/main/prompts/team-orchestrator.md)) analyzes the user request, scopes the work, and produces planning documents. Typical artifacts include `*.md` plan notes stored in the `.omx/plans/` directory, which serve as the foundation for subsequent phases.

### team-prd: Product Requirements Definition

Following the initial plan, the **team-prd** phase refines the strategy into concrete specifications. This phase produces a **Product Requirements Document (PRD)** containing detailed acceptance criteria, test outlines, and technical constraints. The orchestrator—or a dedicated product-manager prompt—generates `prd-*.md` files in `.omx/plans/`, transforming abstract goals into actionable implementation blueprints.

### team-exec: Implementation and Delivery

The **team-exec** phase represents the actual work execution, where code, assets, or other deliverables are generated according to the PRD specifications. The **team-executor** prompt (located in [`prompts/team-executor.md`](https://github.com/Yeachan-Heo/oh-my-codex/blob/main/prompts/team-executor.md)) takes ownership here, committing source files and interim logs to the workspace. This phase translates documented requirements into tangible technical output.

### team-verify: Compliance and Testing

Once execution completes, the **team-verify** phase validates that deliverables satisfy the PRD and associated test specifications. The **team-verifier** role runs automated checks, linting, and validation scripts, storing results in `.omx/state/` directory flags. Successful verification sets the pipeline state to `complete`, while failures trigger the corrective loop.

### team-fix: Iterative Correction Loop

The **team-fix** phase operates as a conditional loop entry point rather than a terminal state. When verification fails, this phase generates fix plans, updates the PRD, and returns the workflow to **team-exec** for another implementation attempt. Any role can propose fixes, and the cycle continues until **team-verify** reports success or the pipeline reaches an unrecoverable `failed` or `cancelled` state.

## How the Verification Loop Works

The pipeline follows a deterministic state machine that transitions through phases based on verification outcomes.

1. **Initialization**: A user or higher-level skill triggers **team-plan**, creating the initial scope documents in `.omx/plans/`.

2. **Documentation**: The orchestrator expands the plan into a detailed PRD during **team-prd**, establishing the contract for implementation.

3. **Execution**: The executor runs **team-exec**, generating code and committing changes to the workspace while adhering to the PRD specifications.

4. **Validation**: The verifier checks compliance during **team-verify**, setting a `complete` flag in `.omx/state/` upon success.

5. **Iteration**: On failure, **team-fix** rewrites requirements or patches code, returning to step 3 until verification passes.

This cyclical design ensures continuous improvement without manual intervention, making the pipeline **crash-safe and resumable** through its declarative state storage.

## Key Files and Architectural Structure

The pipeline relies on a specific directory structure and contract files that enable observable, multi-agent coordination.

| File/Directory | Pipeline Role | Location |
|---|---|---|
| [`AGENTS.md`](https://github.com/Yeachan-Heo/oh-my-codex/blob/main/AGENTS.md) | Central contract defining all phases and transitions | Repository root |
| [`prompts/team-orchestrator.md`](https://github.com/Yeachan-Heo/oh-my-codex/blob/main/prompts/team-orchestrator.md) | Implements **team-plan** and **team-prd** logic | `prompts/` |
| [`prompts/team-executor.md`](https://github.com/Yeachan-Heo/oh-my-codex/blob/main/prompts/team-executor.md) | Implements **team-exec** for code generation | `prompts/` |
| [`prompts/team-verifier.md`](https://github.com/Yeachan-Heo/oh-my-codex/blob/main/prompts/team-verifier.md) | Implements **team-verify** validation logic | `prompts/` |
| `.omx/plans/` | Stores PRDs, test specs, and planning artifacts | `.omx/plans/` |
| `.omx/state/` | Persists pipeline state flags (`complete`, `failed`, `in-progress`) | `.omx/state/` |

The **declarative state** approach stores all phase statuses under `.omx/`, allowing workflows to resume after interruptions without losing context.

## Running the Pipeline from the Command Line

The `omx` CLI provides direct access to the team pipeline, reading phase definitions from [`AGENTS.md`](https://github.com/Yeachan-Heo/oh-my-codex/blob/main/AGENTS.md) to execute commands consistently across projects.

### Triggering Individual Phases

```bash

# Initialize the planning phase

omx team plan --prompt "Create a greeting CLI that accepts a name argument"

# Execute the implementation

omx team exec

# Run verification checks

omx team verify

```

### Example PRD Structure

The **team-prd** phase generates markdown files following this structure in [`.omx/plans/prd-example.md`](https://github.com/Yeachan-Heo/oh-my-codex/blob/main/.omx/plans/prd-example.md):

```markdown

# PRD – Greeting CLI Feature

## Goal

Create a CLI that prints personalized greetings.

## Acceptance Criteria

- `greet <name>` prints "Hello, <name>!"
- Returns exit code 0 on success, non-zero on error
- Includes `--help` documentation

## Test Spec (for team-verify)

- `greet Alice` → stdout contains "Hello, Alice!"
- Missing arguments → exit code 1 with error message

```

### Verification Script Example

Verification scripts used in **team-verify** determine pipeline state through exit codes:

```bash
#!/usr/bin/env bash

# Saved as .omx/scripts/verify-greet.sh

cargo build --quiet && \
  ./target/debug/greet Alice | grep -q "Hello, Alice!" && \
  echo "Verification passed" && exit 0

echo "Verification failed" && exit 1

```

Exit code `0` transitions the pipeline to `complete`, while non-zero codes activate **team-fix**.

## Summary

- The **team pipeline flow** consists of five phases: **team-plan**, **team-prd**, **team-exec**, **team-verify**, and **team-fix**, defined in [`AGENTS.md`](https://github.com/Yeachan-Heo/oh-my-codex/blob/main/AGENTS.md).
- **team-fix** creates a cyclic loop back to **team-exec** when verification fails, enabling iterative refinement until the state reaches `complete`.
- All phase artifacts persist under `.omx/plans/` and state flags under `.omx/state/`, ensuring crash-safe, resumable workflows.
- Specialized prompt files in `prompts/` (orchestrator, executor, verifier) implement phase logic without requiring code changes to the core system.
- The `omx` CLI consumes the [`AGENTS.md`](https://github.com/Yeachan-Heo/oh-my-codex/blob/main/AGENTS.md) contract to execute phases consistently across any project following the convention.

## Frequently Asked Questions

### What triggers the team-fix phase in oh-my-codex?

The **team-fix** phase activates automatically when **team-verify** detects compliance failures. If verification scripts return non-zero exit codes or fail to find required artifacts in `.omx/state/`, the pipeline transitions from verify to fix, generating corrective instructions that return the workflow to **team-exec** for another implementation attempt.

### How does oh-my-codex persist pipeline state across interruptions?

The repository uses a **declarative state** model where each phase writes status flags and artifacts to the `.omx/` directory structure. The `.omx/state/` folder contains JSON or flag files indicating current phase status (`in-progress`, `complete`, `failed`), while `.omx/plans/` stores PRDs and specifications. This design allows the `omx` CLI to resume any interrupted pipeline by reading the existing state rather than starting from scratch.

### Can I extend the team pipeline with custom phases?

Yes. The **AGENTS.md** file acts as the central contract, containing the `<team_pipeline>` block that defines phase transitions. You can inject additional phases by modifying this contract and creating corresponding prompt files in the `prompts/` directory. The `omx` CLI reads these definitions dynamically, allowing custom phases to integrate seamlessly with the existing team-plan through team-fix workflow.

### What is the difference between team-plan and team-prd?

**team-plan** focuses on high-level scoping and requirement gathering, producing initial planning notes, while **team-prd** refines these into formal Product Requirements Documents with specific acceptance criteria and test specifications. The orchestrator typically handles both phases, but **team-prd** creates the formal contract that **team-exec** must satisfy, making it the critical bridge between abstract planning and concrete implementation.