fix(ce-work-beta): document Codex exec pitfalls for delegation

docs/plans/2026-03-24-001-fix-codex-stdin-pipe-guidance-plan.md

@@ -0,0 +1,43 @@
+---
+title: "fix: add explicit stdin piping guidance for Codex delegation"
+type: fix
+status: active
+date: 2026-03-24
+---
+
+# fix: add explicit stdin piping guidance for Codex delegation
+
+## Problem
+
+When ce:work-beta delegates to Codex CLI, the skill says "piping the prompt file via stdin" but provides no concrete command example. The agent interprets this as a shell redirect:
+
+```bash
+codex --dangerously-bypass-approvals-and-sandbox < /tmp/codex_task_20980.txt 2>&1
+```
+
+This fails with:
+
+```
+Error: Exit code 1
+Error: stdin is not a terminal
+```
+
+Codex CLI checks whether stdin is a terminal (likely `isatty()`) and rejects shell redirects (`< file`). A pipe (`cat file | codex`) works because it presents data differently to the process.
+
+## Approach
+
+In step 5 ("Delegate") of the External Delegate Mode section in `ce-work-beta/SKILL.md`, add:
+
+1. A concrete command example using `cat file | codex ...`
+2. An explicit warning that `< file` (shell redirect) does NOT work -- Codex rejects it with "stdin is not a terminal"
+3. Keep the existing note about avoiding argv expansion for large prompts
+
+## Files
+
+- `plugins/compound-engineering/skills/ce-work-beta/SKILL.md` -- step 5 of External Delegate Mode
+
+## Acceptance Criteria
+
+- [ ] Step 5 contains a concrete `cat ... | codex exec ...` command example with placeholder flags from step 2
+- [ ] Explicit warning: shell redirects (`< file`) fail with "stdin is not a terminal"
+- [ ] Existing guidance about avoiding argv expansion is preserved

plugins/compound-engineering/skills/ce-work-beta/SKILL.md

@@ -472,7 +472,23 @@ When external delegation is active, follow this workflow for each tagged task. D
 
 3. **Write prompt to file** — Save the assembled prompt to a unique temporary file to avoid shell quoting issues and cross-task races. Use a unique filename per task.
 
-4. **Delegate** — Run the delegate CLI, piping the prompt file via stdin (not argv expansion, which hits `ARG_MAX` on large prompts). Omit the model flag to use the delegate's default model, which stays current without manual updates.
+4. **Delegate** — Run `codex exec` with the prompt piped via stdin. Use `exec` (not bare `codex`) for non-interactive delegation. Omit the model flag to use the delegate's default model, which stays current without manual updates.
+
+   ```bash
+   cat /tmp/codex-task-XXXXX.txt | codex exec --skip-git-repo-check - 2>&1
+   ```
+
+   **Codex exec pitfalls (all discovered during testing):**
+
+   | Pitfall | Error you get | Fix |
+   |---------|--------------|-----|
+   | Shell redirect `< file` instead of pipe | "stdin is not a terminal" | Use `cat file \| codex exec ...` |
+   | Bare `codex` instead of `codex exec` | Enters interactive mode, hangs | Use `codex exec` for non-interactive delegation |
+   | `--approval-mode` flag on `exec` | "unexpected argument" | `exec` has its own flags; `--approval-mode` is for bare `codex` only |
+   | Running outside a git repo | "Not inside a trusted directory" | Add `--skip-git-repo-check` flag |
+   | Forgetting `-` at end | Prompt not read from stdin | Trailing `-` tells `codex exec` to read the prompt from stdin |
+
+   Piping also avoids `ARG_MAX` limits that would occur if passing the prompt as a CLI argument.
 
 5. **Review diff** — After the delegate finishes, verify the diff is non-empty and in-scope. Run the project's test/lint commands. If the diff is empty or out-of-scope, fall back to standard mode for that task.