| name | delegate-with-foreman |
| description | Delegate scoped coding tasks to AI workers through Foreman. Use when a coding task can be split into independent implementation slices that should run in isolated git worktrees while Codex remains architect and QA. |
Delegate With Foreman
Use Foreman when the user explicitly wants Codex to parallelize coding work through AI coding workers, or when a repo task has independent file-scoped implementation slices.
Operating Model
- Codex is architect and QA.
- Claude Code, Emux-headed interactive Claude Code, Codex CLI, Gemini CLI, Aider, opencode, and local Gemma workers are engineers.
- Each worker gets one concrete task, one git worktree, one branch, and one verification command.
- Codex collects diffs, runs or reviews verification, then chooses merge, PR, or discard.
Tool Flow
- Split work into independent specs with acceptance criteria.
- Choose the worker engine:
claude-emux when the user may need to watch or interrupt Claude Code through Emux, or when Foreman should use the normal interactive Claude Code surface; claude only when the headless metered claude -p path is intentional; codex for hard reasoning/QA; gemini for broad alternate passes; aider for narrow patch tasks; opencode for alternate agent/model runs; gemma4 for throttled local Gemma-family runs; and smoke only for plumbing tests.
- Call
foreman_delegate once per independent task.
- Treat
foreman_delegate as fire-and-return: record the returned worker_id, run_id, worktree path, and log path.
For claude-emux, also record the returned emux.head_command, emux.capture_command, and emux.interrupt_command.
- Use
foreman_status for a cheap lifecycle check and foreman_tail for bounded recent logs while workers run.
- Use
foreman_collect to review changed files and diff.
- Run final verification yourself from the parent repo before
foreman_finalize.
Tool Discovery Guard
Foreman's MCP server exposes more tools than an initial broad tool search may load. If only foreman_delegate, foreman_list, or foreman_control_jobs are visible, do not conclude the plugin lacks lifecycle tools. Search again for the exact names:
foreman_status foreman_tail foreman_collect foreman_finalize
Then use the newly loaded tools for status, logs, diffs, and finalization. This protects the plugin from partial tool-index exposure while keeping the same fire-and-return workflow.
For Slack or other remote-adjacent callers, prefer the control-plane path when available: submit a structured job with foreman control-submit, let a local or rented-machine agent lease it with foreman agent-run --once, then report back from control-status. This keeps Foreman reusable while preserving the same isolated worktree execution model.
Worker Spec Template
Goal:
Acceptance criteria:
Files in scope:
Files out of scope:
Verification command:
Notes:
Keep worker specs narrow. Do not delegate broad architecture, secrets, deploys, money movement, destructive git actions, or human-only approvals.