From 1354d0836f12fd47caf56d38ee58d4abcd03cb80 Mon Sep 17 00:00:00 2001
From: Peter Steinberger <steipete@gmail.com>
Date: Sat, 3 Jan 2026 00:11:21 +0000
Subject: [PATCH] coding-agent: comprehensive update from Jan 2 learnings

- workdir 'little box' pattern (don't read unrelated files)
- background mode replaces tmux
- --full-auto for building, vanilla for reviewing
- parallel Codex processes supported
- PR review tips (fetch refs, use git diff, don't checkout)
- patience rules (don't kill slow sessions!)
---
 skills/coding-agent/SKILL.md | 43 ++++++++++++++++++++++++++++--------
 1 file changed, 34 insertions(+), 9 deletions(-)

diff --git a/skills/coding-agent/SKILL.md b/skills/coding-agent/SKILL.md
index 077a4b0d9..9a8a75f2c 100644
--- a/skills/coding-agent/SKILL.md
+++ b/skills/coding-agent/SKILL.md
@@ -1,12 +1,12 @@
 ---
 name: coding-agent
-description: Run Claude Code, Codex CLI, or OpenCode via background process for programmatic control.
+description: Run Codex CLI, Claude Code, or OpenCode via background process for programmatic control.
 metadata: {"clawdis":{"emoji":"🧩","requires":{"anyBins":["claude","codex","opencode"]}}}
 ---
 
 # Coding Agent (background-first)
 
-Use **bash background mode** for all coding-agent CLIs. Full programmatic control, no tmux needed.
+Use **bash background mode** for coding agents. Full programmatic control, no tmux needed.
 
 ## The Pattern: workdir + background
 
@@ -18,7 +18,7 @@ bash workdir:~/project/folder background:true command:"<agent command>"
 # Monitor progress
 process action:log sessionId:XXX
 
-# Check if done
+# Check if done  
 process action:poll sessionId:XXX
 
 # Send input (if agent asks a question)
@@ -28,21 +28,44 @@ process action:write sessionId:XXX data:"y"
 process action:kill sessionId:XXX
 ```
 
-Why workdir matters: Agent wakes up in a focused directory, doesn't wander off reading unrelated files.
+**Why workdir matters:** Agent wakes up in a focused directory, doesn't wander off reading unrelated files (like your soul.md 😅).
 
 ---
 
 ## Codex CLI
 
-**Model:** `gpt-5.2-codex` — choose reasoning effort based on task:
-- `medium` — most tasks
+**Model:** `gpt-5.2-codex` is the default (set in ~/.codex/config.toml)
+
+**Reasoning effort:** Choose based on task complexity:
+- `medium` — most tasks (default)
 - `high` — complex/architectural tasks
 
+### Building/Creating (use --full-auto)
 ```bash
-bash workdir:~/project background:true command:"codex exec --model gpt-5.2-codex -c reasoning_effort=\"medium\" -s workspace-write \"Your task\""
+bash workdir:~/project background:true command:"codex exec --full-auto \"Build a snake game with dark theme\""
 ```
 
-**Flags:** `-s workspace-write`, `--full-auto`, `--skip-git-repo-check`
+### Reviewing (vanilla, no flags needed)
+```bash
+bash workdir:~/project background:true command:"codex exec \"Review PR #115. Run git diff origin/main...origin/pr/115 to see changes.\""
+```
+
+### Running Multiple Codex Processes
+You can run many Codex processes in parallel! Each gets its own session:
+```bash
+# Start multiple reviews
+bash workdir:~/project background:true command:"codex exec \"Review PR #1\""
+bash workdir:~/project background:true command:"codex exec \"Review PR #2\""
+bash workdir:~/project background:true command:"codex exec \"Review PR #3\""
+
+# Check all running
+process action:list
+```
+
+### PR Review Tips
+- Fetch PR refs first: `git fetch origin '+refs/pull/*/head:refs/remotes/origin/pr/*'`
+- Tell Codex to use: `git diff origin/main...origin/pr/XX`
+- Don't let it checkout branches (conflicts with parallel reviews)
 
 ---
 
@@ -64,6 +87,8 @@ bash workdir:~/project background:true command:"opencode run \"Your task\""
 
 ## ⚠️ Rules
 
-1. **Respect tool choice** — if user asks for Codex, use Codex. Don't offer to build it yourself!
+1. **Respect tool choice** — if user asks for Codex, use Codex. NEVER offer to build it yourself!
 2. **Be patient** — don't kill sessions because they're "slow"
 3. **Monitor with process:log** — check progress without interfering
+4. **--full-auto for building** — auto-approves changes
+5. **vanilla for reviewing** — no special flags needed