/codex-workflows

Use this skill for headless parallel Codex dispatch or when cmux is unavailable. Healthy cmux panes remain the default for visible, reachable single-worker tasks; headless mode is a fan-out engine and degraded fallback, not a cmux replacement.

Run the harness through scripts/codex-workflows.sh. Detailed interfaces are in workflows/agent.md, workflows/parallel.md, and workflows/pipeline.md.

Primitives

• agent creates one isolated worktree, launches one worker, verifies startup, and records it in an explicit manifest.
• parallel validates a JSON fan-out spec, launches every worker before watching, and keeps every outcome in one manifest.
• pipeline runs ordered stages, parallel within a stage, and stops on failure before the next stage unless continue_on_failure is explicitly enabled.
• watch observes process exit first, then parses the finished log once.
• status, harvest, and cleanup make inspection and retirement mechanical.

Non-Negotiable Guards

1. Discover the real default branch with git remote show origin. Never assume main or master.
2. Launch /Users/etanheyman/.local/bin/codex through /usr/bin/nohup. Never invoke bare codex; a captured PID is not a worker.
3. Use one worktree, branch, and log per worker. Grant workspace-write access to the repository Git directory and explicit reporting paths with --add-dir.
4. Verify startup after a grace period. Report FAILED_LAUNCH loudly when the process died or launcher diagnostics show an executable, command, or fetch failure.
5. Never live-grep a worker stream. Wait for process exit, then extract exact TASK_DONE, PR URLs, and failures from structured finished-log events.
6. Pin the bounded-work default to gpt-5.6-luna with explicit xhigh or max reasoning effort. Record the effective model/effort, output tokens, and wall-clock duration in the manifest and run log.
7. Treat TASK_DONE as a signal, not artifact proof. Harvest only declared worktree-relative, non-symlink artifacts; do not clean up before harvest.

Degraded-Mode Contract

Every headless run and worker record must state the same four facts:

• lead-reachable-only
• no-pane
• no-listen-name
• no-self-monitor

Name the dispatching lead. ARM-MONITORS registration must describe the worker as lead-reachable-only; do not invent a pane, listen-name, or monitor.

Completion Interpretation

parallel without --watch proves launch only, records completion_proven: false, prints LAUNCH_ONLY, and exits 75 so it cannot be mistaken for completed work. With --watch, success requires every worker to reach completed. failed_launch, failed, watch_timeout, parser_failed, and incomplete all return nonzero. A watch timeout preserves the live process and log so another watch can resume.

See references/manifest.md for states and references/composition.schema.json for the fan-out/pipeline input contract.