feat(ce-work-beta): add beta Codex delegation mode

[tmchow]

Summary

Adds Codex delegation as a beta-only execution path in ce:work-beta, validated through 6 iterations of evaluation comparing delegation vs standard mode across small, medium, large, and extra-large plans. The final architecture uses batched delegation, reference file extraction for token efficiency, and a <testing> prompt section that closes the test quality gap.

Credit to @mvanhorn for the original push on delegation and @huntharo for permissioning thought partnership. This branch supersedes the earlier direction from #364 and #365, now implemented as a beta rollout.

How to Test (Pre-Merge)

This is a beta skill — it requires manual invocation and does not affect the stable ce:work path.

Option A: Point at a local checkout (simplest)

git clone https://github.com/EveryInc/compound-engineering-plugin.git
cd compound-engineering-plugin
git checkout feat/codex-delegation-work

Then from any project directory:

claude --plugin-dir /path/to/compound-engineering-plugin/plugins/compound-engineering

Option B: Use the plugin-path CLI (keeps your checkout clean)

cd compound-engineering-plugin
bun install
bun run src/index.ts plugin-path compound-engineering --branch feat/codex-delegation-work

This outputs a --plugin-dir path. On re-run it pulls the latest from the remote branch.

claude --plugin-dir <path from above>

Try it out:

# Standard mode (no delegation) — should behave identically to ce:work
/ce:work-beta path/to/your-plan.md

# With Codex delegation (requires codex CLI installed)
/ce:work-beta delegate:codex path/to/your-plan.md

On first delegation, the skill prompts for one-time consent and sandbox mode selection.

Optional: --dangerously-skip-permissions reduces permission prompts during delegation (codex exec, git operations). Not required.

Prerequisites for delegation: Codex CLI installed and on PATH (npm install -g @openai/codex).

Key Findings from Evaluation

6 iterations of eval with real code implementation in isolated worktrees:

Plan size	Units	Delegate tokens	Standard tokens	Overhead	Verdict
Small	1-3	51-63k	38-42k	+34-50%	Not worth it for token savings
Medium	4	54k	53k	+2%	Marginal
Large	7	62k	62k	+1%	Break-even
Extra-large	10	54k	62k	-13%	Delegation is cheaper

Crossover point: ~5-7 units. Above that, delegation saves Claude tokens. Users may still choose delegation below the crossover for cost arbitrage (Codex tokens cheaper) or coding preference.

Architecture

Reference file extraction (the biggest optimization)

Delegation content (~250 lines) extracted from SKILL.md body to references/codex-delegation-workflow.md, loaded on demand only when delegation is active. SKILL.md shrank from 776 to 514 lines -- a 34% body reduction saving ~15k Claude tokens per non-delegation run.

Batched execution model

Replaced per-unit delegation (N codex exec calls) with batched delegation (ceil(N/5) calls). All units in one batch for plans <=5 units; split at roughly 5 for larger plans. Reduced orchestration from O(N) to O(batches).

Codex owns verify

Codex runs tests and fixes failures within the delegation -- the orchestrator does not re-verify independently. Safety net: circuit breaker (3 consecutive failures -> standard mode fallback), plus Phase 3 full test suite before shipping.

flowchart TD
  A[ce:work-beta invoked with plan] --> B{delegation_active?}
  B -- no --> C[Standard execution]
  B -- yes --> D[Read delegation workflow reference]

  D --> E[Pre-delegation checks: platform, env, CLI, consent]
  E -- any fail --> C
  E -- all pass --> F{work_delegate_decision}

  F -- auto --> G[State plan and proceed]
  F -- ask --> H[Present recommendation, wait for choice]
  H -- Claude Code --> C
  H -- Codex --> G

  G --> I{All units trivial?}
  I -- yes --> C
  I -- no --> J[Batch units]

  J --> K[Write prompt with testing + verify sections]
  K --> L[codex exec per batch]
  L --> M{Result classification}
  M -- success --> N[Commit batch]
  M -- partial --> O[Finish locally, commit]
  M -- failure --> P[Rollback, increment circuit breaker]
  P --> Q{3 failures?}
  Q -- yes --> C
  Q -- no --> K

  N --> R{More batches?}
  R -- yes --> S[Report progress, continue]
  S --> K
  R -- no --> T[Cleanup scratch, Phase 3]

Loading

What Changed

plugins/compound-engineering/
  AGENTS.md                                  # refined shell-chaining rule
  compound-engineering.local.example.md      # NEW — settings template
  skills/
    ce-work-beta/
      SKILL.md                               # slimmed body (776 -> 514 lines)
      references/
        codex-delegation-workflow.md          # NEW — full delegation workflow
        swarm-mode.md                        # NEW — extracted from body
    ce-work/
      SKILL.md                               # stable, non-delegating
    ce-plan/
      SKILL.md                               # neutral, handoffs stay on ce:work

docs/
  brainstorms/
    2026-03-31-codex-delegation-requirements.md   # NEW — 19 requirements
  plans/
    2026-03-31-001-feat-codex-delegation-plan.md  # NEW — 6 implementation units
  solutions/
    best-practices/
      codex-delegation-best-practices-2026-04-01.md  # NEW — compounded learning
    skill-design/
      ce-work-beta-promotion-checklist-2026-03-31.md # NEW — promotion steps

tests/
  pipeline-review-contract.test.ts           # delegation contract coverage

Prompt Engineering for Delegation

The Codex prompt template includes:

• <testing> section -- Test Scenario Completeness guidance (happy path, edge cases, error paths, integration). Improved Codex test output by ~35% on large plans.
• <verify> section -- requires running ALL tests in a single command (not per-file) to catch cross-file contamination. Discovered in eval when mocked globalThis.fetch leaked between test files.
• <constraints> -- no git commits, scoped changes, honest result reporting
• <output_contract> -- structured result schema for classification

User Settings

# .claude/compound-engineering.local.md
---
work_delegate: codex              # codex | false (default: false)
work_delegate_consent: true       # true | false (default: false)
work_delegate_sandbox: yolo       # yolo | full-auto (default: yolo)
work_delegate_decision: auto      # auto | ask (default: auto)
---

Promotion Follow-Up

When ready to promote beta -> stable:

• Copy validated implementation from ce:work-beta into ce:work
• Remove beta-only manual-invocation caveats
• Update planner and workflow handoffs atomically
• Move contract tests from beta surface to stable surface
• Retire or redirect ce:work-beta

See docs/solutions/skill-design/ce-work-beta-promotion-checklist-2026-03-31.md for detailed steps.

Test plan

• bun test tests/pipeline-review-contract.test.ts -- 24 pass, delegation contract verified
• bun test -- 547 pass (1 pre-existing path sanitization failure)
• 6 iterations of eval: routing correctness, code correctness, token measurement, circuit breaker fallback
• Codex delegation end-to-end: prompt generation -> codex exec -> result classification -> commit (verified with real codex CLI)

Post-Deploy Monitoring & Validation

No additional operational monitoring required. Changes are limited to skill contracts, reference files, planning docs, and test coverage in the plugin repo. The beta skill requires manual invocation (ce:work-beta) and does not affect the stable ce:work path.

---

🤖 Generated with Claude Opus 4.6 (1M context, extended thinking) via Claude Code

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 4304970c34

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[tmchow]

@codex review

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: d3f7069e77

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[tmchow]

@codex review

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: d3f7069e77

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".