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

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.

The team pipeline serves as the core coordination model driving multi-agent collaboration in the 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 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) 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) 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	Central contract defining all phases and transitions	Repository root
prompts/team-orchestrator.md	Implements team-plan and team-prd logic	prompts/
prompts/team-executor.md	Implements team-exec for code generation	prompts/
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 to execute commands consistently across projects.

Triggering Individual Phases

# 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:

# 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:

#!/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.
• 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 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}