[Feature]: External Executor Pattern — orchestrator/executor split for cross-CLI agent delegation

[Jhonata-Matias]

Summary

Introduce a first-class External Executor pattern that lets an AIOX agent runtime (e.g. Claude Code acting as @aiox-master or @dev) delegate the execution phase of a development task to a different CLI agent runtime (e.g. Codex CLI in headless --full-auto background mode), while retaining ownership of orchestration, acceptance criteria validation, and story state updates.

This is complementary to the existing Codex-as-skill integration (.codex/skills/aiox-<agent-id> + npm run sync:skills:codex), not a replacement. It addresses a different use case: orchestrator/executor split across runtimes.

Problem Statement

The current AIOX integration model (per AGENTS.md) treats each supported CLI (Claude Code, Codex CLI, Gemini CLI) as a runtime that carries the full persona of an agent — Codex loads aiox-dev, becomes Dex, and does everything end-to-end (plan → implement → validate → update story).

A real use case I hit on a downstream project I work on:

• I want Claude Code as the orchestrator — strong at reading stories, validating ACs, reviewing diffs, enforcing constitutional gates (Article IV "No Invention", File List integrity).
• I want Codex CLI as the implementer — fast, sandboxed (--full-auto = workspace-write + auto-approve), parallelizable in background, doesn't consume the orchestrator's context window.

Today there is no first-class pattern for this split. Each project ends up building an ad-hoc squad (in my case a codex-delegation squad with a bash wrapper + a project-local task definition). This means:

1. Inconsistent prompt construction across projects.
2. No standardized run directory layout / log capture.
3. Constitutional gates (Article IV, File List, AC traceability) re-implemented per-project — easy to skip.
4. Locks each project into one specific external CLI without a shared abstraction.

Proposed Solution

A new task family + opt-in config + provider adapters:

1. Task definition

.aiox-core/development/tasks/delegate-to-external-executor.md — formalizes:

• Inputs: prompt, slug, optional story_id / story_path / workdir / provider.
• Outputs: run_dir, output, log, diff.
• Pre-conditions: executor on PATH, git tree clean (or intentional changes already committed), prompt explicitly cites AC + relevant file scope.
• Post-conditions: orchestrator reviewed output + git diff, validated against AC, File List/checkboxes updated only after review approved.
• Anti-patterns: marking story done without reading diff; trusting executor summary without verification; delegating non-@dev work (@po, @qa, @sm, @devops) to the executor.

2. Provider adapters

.aiox-core/development/external-executors/:

• codex.md — reference implementation: codex exec --full-auto -C <wd> -o <output> "<prompt>"
• Future: aider.md, cline.md, cursor-cli.md, gemini-cli.md (when invoked headless)

Each adapter declares: invocation command, sandbox flags, supported flags (model, image, etc.), output capture mechanism, exit-code semantics.

3. Opt-in config (core-config.yaml)

dev:
  execution_mode: native       # native (default) | delegate
  delegate_to: codex           # provider id when delegate
  auto_review: true            # enforce orchestrator review of diff before marking done
external_executors:
  enabled: true
  default_sandbox: full-auto   # full-auto | workspace-write | danger-full-access
  run_dir: .aiox/external-runs # gitignored

Backward compatible: execution_mode: native is the default — no behavior change for existing users.

4. CLI wrapper

bin/aiox-delegate (or scripts/delegate.sh):

aiox-delegate <provider> -t <slug> [-f prompt_file | -p prompt] [-d workdir] [-m model]

Manages run directory (.aiox/external-runs/<YYYYMMDD-HHMMSS>-<slug>/), launches in background via nohup, captures stdout/stderr to codex.log, last message to output.md, prints RUN_DIR / PID / LOG / OUTPUT to its own stdout for the orchestrator to consume.

5. Constitutional integration

When auto_review: true (default for the delegate mode), the orchestrator MUST execute the review checklist before any story state mutation:

• Each AC satisfied?
• Diff scope matches story scope?
• Article IV: every change traces to a requirement?
• Tests added/updated per story?
• Lint/typecheck pass?

The task delegate-to-external-executor.md declares these as post_conditions so any orchestrator (Claude Code, Gemini CLI, future runtimes) enforces them uniformly.

Code Example

# core-config.yaml — opt in once per project
dev:
  execution_mode: delegate
  delegate_to: codex
  auto_review: true

# User flow
@dev *develop story-4.3
  → orchestrator builds prompt from story (AC + file scope + constraints)
  → calls bin/aiox-delegate codex -t story-4.3 -f /tmp/prompt.md
  → returns RUN_DIR=.aiox/external-runs/20260425-220000-story-4.3
  → orchestrator monitors LOG in background, doesn't block UI
  → on completion: reads OUTPUT, runs `git diff`, applies review checklist
  → if APPROVED: updates File List, checkboxes, status InProgress→InReview
  → if REJECTED: re-prompts executor with specific feedback (max N iterations)

Alternatives Considered

1. Status quo (Codex skill aiox-dev): works for single-runtime use. Doesn't address the orchestrator/executor split where the user values the orchestrator's review capacity.
2. Project-local squad (what I'm currently doing on the downstream project): functional but per-project reinvention; missing constitutional enforcement.
3. Codex-specific task without provider abstraction: simpler PR but locks AIOX into one vendor; conflicts with the multi-runtime philosophy already evident in AGENTS.md (sync:ide:claude, sync:ide:gemini, validate:codex-sync).
4. Hardcode delegation in @dev: breaks backward compatibility; opt-in via config preserves current default.

Impact Assessment

New functionality — backward compatible. execution_mode: native remains the default.

Priority

Medium — would improve workflow for users running multi-CLI setups.

Open Questions for Maintainers

1. Provider adapter location — .aiox-core/development/external-executors/ or under .aiox-core/integrations/? Or a new packages/external-executors/?
2. CLI binary placement — bin/aiox-delegate (top-level CLI) vs scripts/delegate.sh (utility) vs subcommand of existing aiox CLI (aiox dev delegate ...)?
3. Review enforcement — block on missing review (raise error) vs warn-only? My instinct: block when auto_review: true; user can opt out via config.
4. Should this work with the inverse direction too (Codex orchestrating, Claude/Gemini as executor)? My initial scope is Claude→Codex, but the abstraction shouldn't preclude it.
5. CodeRabbit interaction — current dev-develop-story has a self-healing loop (max 2 iterations). Does the delegate mode integrate with that, replace it, or run after?

Community Contribution

I'm willing to:

• Implement the reference Codex adapter + task definition + wrapper
• Document the pattern (docs/)
• Write tests (smoke for wrapper, integration for the orchestrator review path)

If the design is approved, I can open a follow-up PR scoped narrowly (Codex provider only, no other adapters in v1).

[github-actions]

Welcome to aiox-core! Thanks for opening your first issue.

What happens next?

• A maintainer will triage this and add appropriate labels
• We'll respond as soon as possible
• Feel free to join Community Discussions

Helpful Resources:

• Contributing Guide
• Documentation

Looking to contribute? Check issues labeled community: good first issue.