Pipeline Orchestrator for Codex

Full-depth, prompt-driven multi-agent pipeline for OpenAI Codex CLI and Kimi Code CLI. Ported toward parity with the local canonical Claude Code Pipeline Orchestrator v5.2.0, with runtime-native constraints made explicit for each platform.

A single /pipeline-orchestrator-for-codex:pipeline command classifies any task, confirms a proposal with you, then orchestrates 45 agent prompts across 4 structured phases when a real spawn_agent adapter is available. Without that adapter, operational pipeline execution blocks as blocked-no-agent-runtime rather than simulating multi-agent parity. The runtime now includes HMAC-backed sentinel and ledger integrity, v5.2 protocol events, brainstorm run directories, Spec lifecycle gates, TRACE.md validation, TDD gates, adversarial review loops, confidence scoring, and Go/No-Go validation.

New: Kimi Code CLI port — the same 4-phase pipeline is now available as a Kimi skill (.kimi/skills/pipeline/), with 13 agent prompts adapted for Kimi's coder/explore subagent types, deterministic exec-window scripts, and a parent handler loop that processes GATE_REQUEST, DISPATCH_REQUEST, and PLAN_MODE_REQUEST blocks.

# ~/.codex/config.toml
multi_agent = true
model_reasoning_effort = "high"

Option 1: From Codex Plugin Registry (if published)

codex install fx-studio-ai/pipeline-orchestrator-for-codex

Option 2: From GitHub (recommended for portable use)

# Clone the repo
git clone https://github.com/fernandoxavier02/Pipeline-Orchestrator-for-Codex.git

# Install into Codex plugins cache
mkdir -p ~/.codex/plugins/cache/fx-studio-ai/pipeline-orchestrator-for-codex/0.5.3
cp -r Pipeline-Orchestrator-for-Codex/* ~/.codex/plugins/cache/fx-studio-ai/pipeline-orchestrator-for-codex/0.5.3/

Option 3: Symlink for development

git clone https://github.com/fernandoxavier02/Pipeline-Orchestrator-for-Codex.git
cd Pipeline-Orchestrator-for-Codex

# Create a symlink in the plugins cache
mkdir -p ~/.codex/plugins/cache/fx-studio-ai/pipeline-orchestrator-for-codex
ln -sf "$(pwd)" ~/.codex/plugins/cache/fx-studio-ai/pipeline-orchestrator-for-codex/0.5.3

# Check the plugin is detected
ls ~/.codex/plugins/cache/fx-studio-ai/pipeline-orchestrator-for-codex/*/skills/pipeline/SKILL.md

# Should output: SKILL.md path with version number

/pipeline-orchestrator-for-codex:pipeline <your task description>

The first assistant action is visible planning: the orchestrator calls update_plan so Codex opens the plan panel before it dispatches agents, edits files, or writes a report. The first user decision is then WORKFLOW_METHOD_GATE from references/workflow-method-gate.md: it names the workflow it selected, for example Bug Fix, Audit, Implement, UX, Spec, Brainstorm, Review, or Verify Completion, and asks whether you want to keep it. Reply yes to keep it, adjust to revise it manually, no to stop, or reply with audit, bugfix, feature, ux, spec, brainstorm, review, or verify-completion to switch workflow before any execution. For /pipeline-orchestrator-for-codex:pipeline, both the visible plan and this gate happen before Phase 0 agent dispatch.

For complex work or --plan, the proposal also emits PLAN_MODE_REQUEST v1. Hosts that support native Codex Plan Mode should surface the planning checkpoint there; otherwise the generated implementation plan is shown and must be approved before edits.

Every public workflow also follows the VISIBLE_PLAN contract in references/visible-plan-contract.md: the parent Codex context must call update_plan as the first assistant action, keep one step in progress, execute in batches, run adversarial review after every batch, and preserve PDD, DDD, ATDD, and TDD or the report-only evidence-first equivalent.

This repository also includes a local Eval Gate around the orchestrator. It lives in .codex/**, .agents/skills/workflow-eval-gate/**, and evals/**, and checks whether changes to workflows, skills, hooks, commands, telemetry, gates, traces, batches, reviews, and policy surfaces have enough local evidence before they are reported as passing.

The Eval Gate is intentionally local. It does not rewrite the TypeScript runtime, does not replace /pipeline-orchestrator-for-codex:pipeline, and is not proof that plugin hooks are globally active. Codex hook activation still requires the manual /hooks trust step for .codex/hooks.json.

See evals/README.md for how the hooks, telemetry, deterministic runner, validation commands, and trust boundary work. The implementation contract for this layer is documented in docs/pipeline-orchestrator-codex/11-eval-gate-plan.md.

PASS evidence is accepted only when the runtime and hooks agree on the same integrity chain. Ledger entries use PIPELINE_INTEGRITY_HMAC_KEY when configured. Sentinel state uses PIPELINE_SENTINEL_HMAC_KEY when present and otherwise falls back to PIPELINE_INTEGRITY_HMAC_KEY, so one operational secret can sign both surfaces without creating runtime/Stop-hook drift.

# Clone the repo
git clone https://github.com/fernandoxavier02/Pipeline-Orchestrator-for-Codex.git

# Option A: User-level (available in all projects)
cp -r Pipeline-Orchestrator-for-Codex/.kimi/skills/* ~/.kimi/skills/

# Option B: Project-level (only current project)
cp -r Pipeline-Orchestrator-for-Codex/.kimi/skills/* ./.agents/skills/

Type the skill name in the Kimi chat:

pipeline <your task description>

Or use one of the shortcut skills:

bugfix <bug description>
feature <feature description>
audit <scope>
spec <feature description>
review

Kimi does not support nested Agent dispatches or AskUserQuestion from subagents. The pipeline skill uses a parent handler loop:

1. SKILL.md spawns the pipeline-controller as a coder subagent
2. The controller emits structured blocks (GATE_REQUEST, DISPATCH_REQUEST, PLAN_MODE_REQUEST)
3. The parent (main LLM) parses each block, invokes the appropriate Kimi tool, and feeds results back
4. Repeat until the controller emits PIPELINE COMPLETE

See .kimi/skills/pipeline/references/parent-handler-protocol.md for the full protocol specification.

                          /pipeline-orchestrator-for-codex:pipeline "fix auth bug"
                                    |
                    ╔═══════════════╧═══════════════╗
                    ║     PHASE 0 — TRIAGE          ║
                    ║  task-orchestrator             ║
                    ║  information-gate              ║
                    ║  design-interrogator (COMPLEXA)║
                    ╚═══════════════╤═══════════════╝
                                    |
                    ╔═══════════════╧═══════════════╗
                    ║     PHASE 1 — PROPOSAL        ║
                    ║  Classification + Confirmation ║
                    ║  plan-architect (COMPLEXA)     ║
                    ╚═══════════════╤═══════════════╝
                                    |
                         user confirms (yes/no/adjust)
                                    |
                    ╔═══════════════╧═══════════════╗
                    ║     PHASE 2 — EXECUTION       ║
                    ║  quality-gate-router → TDD     ║
                    ║  pre-tester (RED phase)        ║
                    ║  executor-controller (batches) ║
                    ║  checkpoint-validator           ║
                    ║  review-orchestrator (advers.) ║
                    ║  executor-fix (if needed)      ║
                    ╚═══════════════╤═══════════════╝
                                    |
                    ╔═══════════════╧═══════════════╗
                    ║     PHASE 3 — VALIDATION      ║
                    ║  sanity-checker                ║
                    ║  final-adversarial (3 parallel)║
                    ║  final-validator (Go/No-Go)    ║
                    ║  finishing-branch              ║
                    ╚═══════════════════════════════╝

Type-Specific Agents (dispatched based on task type):

SIMPLES = direct execution (no pipeline phases, just do the task).

Hooks append audit events to .codex/pipeline/hook-events.jsonl using JSON.stringify. Each line records hook, event, decision, attempted, expected, timestamp, cwd, reason, and execution_identity.

Use execution_identity.trace_id to correlate one workflow across .codex/pipeline/gate-decisions.jsonl, session.json, hook logs, real-agent dispatch requests, child reviewer outputs, and dispatcher output. Use execution_identity.event_id to identify the specific surface event that produced a line.

A critical adaptation for GPT-based execution. Unlike Claude, GPT treats markdown instructions as documentation rather than executable commands. This plugin uses three reinforcement layers:

Layer 1: Hook (force-pipeline-agents.cjs)
  → Injects imperative "YOUR FIRST ACTION must be..." message

Layer 2: SKILL.md top (MANDATORY-SUBAGENT-RULE block)
  → "YOU MUST ALWAYS SPAWN SUBAGENTS. THIS IS NOT OPTIONAL."

Layer 3: SKILL.md bottom (self-check + anti-patterns)
  → "Did you call spawn_agent at least once? If no, you violated the contract."

pipeline-orchestrator-for-codex/
├── .codex-plugin/
│   └── plugin.json              # Plugin manifest (v0.5.3)
├── .kimi/                       # Kimi Code CLI skill tree
│   └── skills/                  #   Skills for Kimi (pipeline, bugfix, feature, audit, review, spec)
│       ├── pipeline/
│       │   ├── SKILL.md         #     Parent handler loop (390+ lines)
│       │   ├── agents/          #     13 Kimi-adapted agent prompts
│       │   ├── references/      #     Protocol specs + gate taxonomy
│       │   └── scripts/         #     Deterministic exec-window scripts (Node.js)
│       ├── bugfix/
│       ├── feature/
│       ├── audit/
│       ├── review/
│       └── spec/
├── agents/                      # 45 agent prompt files plus inventory README (Codex/Claude)
│   ├── core/                    #   8 core agents
│   ├── executor/                #   5 executor agents
│   │   └── type-specific/       #  16 domain-specific agents
│   └── quality/                 #  12 quality/spec lifecycle agents
├── commands/
│   └── pipeline.md              # Full pipeline reference (1,058 lines)
├── hooks/
│   ├── hooks.json               # Hook registry
│   ├── force-pipeline-agents.cjs  # Agent spawn enforcement
│   ├── sentinel-hook.cjs        # Phase sequence guardian
│   └── completion-checklist.cjs # Post-completion verification
├── references/                  # 25 reference documents
│   ├── checklists/              #   Security & quality checklists
│   ├── gates/                   #   Macro/micro gate definitions
│   └── pipelines/               #  12 pipeline variant specs
├── skills/
│   └── pipeline/
│       └── SKILL.md             # Imperative execution script (315 lines)
├── src/                         # TypeScript runtime (51 files)
├── tests/                       # Unit + integration tests (44 files) + Kimi tests (6 files)
└── docs/                        # Architecture & planning docs

Create .codex/pipeline.local.md in your project root (optional):

build_command: "make build"
test_command: "make test"

If absent, the orchestrator auto-detects from package.json, Makefile, or common conventions.

• Node.js >= 20 (for hooks — they use CommonJS .cjs format)
• Codex CLI with multi_agent = true enabled
• model_reasoning_effort = "high" recommended in ~/.codex/config.toml

The plugin does NOT require a build step for normal use. The runtime components are:

The src/, dist/, and tests/ directories are for development only and are NOT required for the plugin to function.

This plugin is a Codex port targeting the local Pipeline Orchestrator for Claude Code v5.2.0 by FX Studio AI. The intelligence of the pipeline is split between markdown prompts and the TypeScript runtime: prompts define the operating contract, while runtime code enforces strict real-agent dispatch, protocol event persistence, run directories, gates, and TRACE.md validation.

Key adaptation: Claude naturally converts spawn instructions into tool calls. GPT does not. The port includes imperative enforcement layers (hook + SKILL.md + self-check) to ensure deterministic agent dispatch in the Codex runtime.

MIT

FX Studio AI
_{Built by Fernando Xavier}