- **Recommended:** 3-5 parallel agents - **Maximum:** 8 (OpenAI rate limits unknown for ChatGPT auth) - **If rate limited:** Reduce to 2-3 and add 5s delay between spawns

Before spawning parallel agents, verify no overlap: ```bash # Extract file lists from all prompts, check for duplicates echo "${ALL_FILES[@]}" | sort | uniq -d # If any output → files appear in multiple agents → SERIALIZE those tasks ```

``` THIS IS PRODUCTION. Include in EVERY agent prompt: - DO NOT run migrate:fresh, migrate:reset, db:wipe - DO NOT delete files outside your SCOPE - DO NOT modify .env or config files unless explicitly instructed - Verify syntax before finishing: php -l {files} ```

| Task Complexity | Model | Effort | Est. Cost | |----------------|-------|--------|-----------| | Simple rename/move | gpt-5.4 | low | ~1-2k tokens | | Extract method/class | gpt-5.4 | medium | ~3-8k tokens | | Complex refactor | gpt-5.4 | high | ~10-20k tokens | | Architecture decisions | gpt-5.4 | xhigh | ~20-50k tokens | | Budget bulk ops | gpt-5-codex-mini | medium | ~1-3k tokens | ---

``` TASK: Apply transformation to all files matching pattern FILES TO PROCESS: {file_list} TRANSFORMATION: For each file: 1. {transformation step} 2. {transformation step} DO NOT: - Change file structure beyond the transformation - Add new dependencies - Modify files not in the list WHEN DONE (MANDATORY): 1. php -l on each modified file 2. git add {all modified files} 3. git commit -m "fix: {transformation description} [codex-agent-{N}]" ``` ---

**Include this block in EVERY Codex agent prompt to prevent premature stopping:** ``` AUTONOMY RULES (CRITICAL — follow these exactly): - Complete the ENTIRE task in full. Do NOT stop early. - Do NOT suggest breaking the task into stages or batches. - Do NOT ask the user to confirm, clarify, or choose between options. - Do NOT say "too large", "unmanageable", or "please narrow scope". - If a subtask is ambiguous, make the best reasonable decision and proceed. - If you encounter an error,...

**Include this block in EVERY Codex agent prompt:** ``` CODE QUALITY RULES (ReportMaker enforces these — do not violate): PHP: - Max file size: 400 lines target, 800 lines hard limit — if refactoring creates files over 800L, split further - No new PHPStan errors at Level 7 — avoid untyped returns, missing @param, mixed types - Follow PSR-12 / Laravel code style (Pint-compatible) - No generic class basenames: use domain-specific names (e.g. CrawlAnalysisService, NOT AnalysisService) -...

``` TASK: Extract {method/logic} from {source_file} into {target_file} SCOPE: - {source_file} (modify: remove extracted code, add import/use) - {target_file} (create or modify: add extracted code) RULES: - Preserve all existing method signatures in {source_file} - New class/trait in {target_file} must follow PSR-4: namespace {namespace} - Add proper use/import statements - Do NOT change any logic, only move code WHEN DONE (MANDATORY): 1. php -l {source_file} && php -l {target_file} 2. git...

``` TASK: {one-line description} SCOPE (only edit these files): - {file1.php} - {file2.php} DO NOT EDIT: - {protected-file.php} - Any file not listed in SCOPE INSTRUCTIONS: 1. {step 1} 2. {step 2} CONVENTIONS: - {coding convention relevant to task} WHEN DONE (MANDATORY — do ALL steps): 1. Verify syntax: php -l {files} 2. Stage your changes: git add {files} 3. Commit: git commit -m "fix: {description} [codex-agent-{N}]" 4. Report what you changed ``` > **CRITICAL: Self-commit is...

If an agent failed or produced incomplete output: ```bash codex exec resume "{SESSION_ID}" "The previous step failed. Error: {error}. Please retry." \ -m "gpt-5.4" -c model_reasoning_effort=high --full-auto 2>&1 ``` Bump reasoning effort for retries (low→medium, medium→high). ---

```bash # Syntax check all changed files git diff --name-only | grep '\.php$' | xargs -I{} php -l {} # Check for merge markers or corruption git diff --name-only | xargs grep -l '<<<<<<' 2>/dev/null # Code quality spot-checks (run after all agents complete) # PHPStan delta (only new errors, not baseline): vendor/bin/phpstan analyse $(git diff --name-only | grep '\.php$' | tr '\n' ' ') 2>/dev/null | tail -5 # ESLint on changed JS/TS files: git diff --name-only | grep -E '\.(js|ts)$' | xargs...

After all agents complete: 1. Read each agent's `-o` output file 2. Check exit codes (0 = success) 3. **Verify commits exist**: `git log --oneline -N` (N = number of agents) - Each agent should have created exactly one commit with `[codex-agent-{N}]` tag - If a commit is MISSING → that agent's sandbox was cleaned up → re-run it 4. Check for unexpected file conflicts: `git diff --name-only` (should be empty if all committed) 5. Run syntax checks: `php -l` on changed PHP files

**Pattern for parallel background execution:** ```bash REGISTRY="/tmp/codex-registry-$$.json" echo '{"agents":[]}' > "$REGISTRY" for i in 1 2 3; do ( OUTPUT=$(codex exec -m "gpt-5.4" \ -c model_reasoning_effort=medium \ --full-auto \ -o "/tmp/codex-agent-$i-result.txt" \ "${PROMPTS[$i]}" 2>&1) SESSION=$(echo "$OUTPUT" | grep "session id:" | awk '{print $NF}') TOKENS=$(echo "$OUTPUT" | grep "tokens used" | head -1) EXIT=$? # Atomic write to...

Create a tracking structure before spawning: ```bash REGISTRY_FILE="/tmp/codex-orchestrator-$(date +%Y%m%d-%H%M%S).json" ``` Track per agent: - Agent ID (incrementing integer) - Session UUID (from codex output) - Status: spawning / running / completed / failed - Assigned files (for conflict detection) - Model + reasoning effort - Start time - Output summary

Before spawning agents, decompose the work into independent, non-overlapping units. **CRITICAL: File Conflict Prevention** Each Codex agent operates in the SAME workspace (no git worktrees). Agents MUST NOT edit the same files simultaneously. ``` SAFE: Agent A edits app/Services/Foo.php, Agent B edits app/Services/Bar.php UNSAFE: Agent A and B both edit app/Services/Shared.php ``` **Decomposition rules:** 1. Each agent gets a DISTINCT set of files 2. No file appears in more than one agent's...

| # | Task | Files | Score | Model | Effort | Est. Tokens | |---|------|-------|-------|-------|--------|-------------| | 1 | Extract FooHelper trait | 2 | 3 | gpt-5.4 | medium | ~5k | | 2 | Rename old methods | 1 | 1 | gpt-5.4 | low | ~1k | | 3 | Refactor BarService logic | 4 | 5 | gpt-5.4 | high | ~15k | Total estimated: ~21k tokens Parallel groups: [1,2] parallel → 3 sequential (shares file with 1) Godkjenn? (ja / endre agent 3 til xhigh / manuell overstyring) ``` **User can override ANY...

After auto-selection, ALWAYS show the plan: ```

``` Score 0-1 → gpt-5.4 / low (trivial: rename, simple write) Score 2-3 → gpt-5.4 / medium (standard: extract method, add feature) Score 4-6 → gpt-5.4 / high (complex: refactor, multi-file logic) Score 7+ → gpt-5.4 / xhigh (hard: architecture, cross-cutting) BUDGET MODE (user-requested): Score 0-1 → gpt-5-codex-mini / medium (cheapest possible) Score 2-3 → gpt-5.4 / low (downgrade effort) Score 4+ → gpt-5.4 / medium (cap at medium) ```

For each decomposed task, evaluate these signals: ``` SIGNAL SCORING: +0 points = baseline (low effort) File count: 1 file → +0 2-3 files → +1 4-5 files → +2 6+ files → +3 Lines of change (estimated): <30 LOC → +0 30-100 LOC → +1 100-300 LOC → +2 300+ LOC → +3 Task type: rename/move/delete → +0 add field/method → +1 extract class/trait → +2 refactor logic → +3 cross-concern change → +4 Dependency complexity: Self-contained ...

When user selects "Smart Auto-Select", analyze EACH task independently:

``` Velg reasoning effort: 1. low - Raske, enkle oppgaver (rename, flytt, enkel write) ~1-2k tokens 2. medium - Standard kodeedits (ekstraher, modifiser) ~3-8k tokens 3. high - Kompleks refaktorering (multi-fil, logikk-endring) ~10-20k tokens 4. xhigh - Maksimal reasoning (arkitektur, vanskelige problemer) ~20-50k tokens ``` ---

``` Velg Codex-modell: 1. gpt-5.4 (anbefalt - nyeste, best kvalitet) 2. gpt-5.2-codex (stabil, god kvalitet) 3. gpt-5.1-codex-max (utvidet kontekst) 4. gpt-5-codex-mini (budget, enkle oppgaver) ```

``` Codex Agent Configuration: Velg agent-tilordning: 1. Smart Auto-Select (anbefalt) - Analyserer oppgavekompleksitet og velger modell+effort automatisk 2. Uniform - Samme modell/effort for alle agenter (du velger) 3. Manual per agent - Du spesifiserer modell og effort per oppgave ```

Before ANY agent spawning, present the user with configuration choices using AskUserQuestion:

Even without sandbox overlay, agents MUST `git add + git commit` as a mandatory final step. This ensures work is tracked and visible to other agents/sessions. **Every agent prompt MUST include `git add + git commit` as a mandatory final step.** Without this, work is silently lost. See "Effective Prompt Structure" for the correct WHEN DONE block. ---

```bash codex exec resume "{SESSION_ID}" "{next_prompt}" -m "{model}" -c model_reasoning_effort={effort} --dangerously-bypass-approvals-and-sandbox 2>&1 ```

`--full-auto` uses `bwrap` (bubblewrap) sandbox which requires network namespace creation. This server (KVM VM on laravelserver-v11) lacks permission for `RTM_NEWADDR` on loopback, causing every command to fail with: `bwrap: loopback: Failed RTM_NEWADDR: Operation not permitted`. `--dangerously-bypass-approvals-and-sandbox` skips bwrap entirely — safe because this server IS the execution environment.

- `--dangerously-bypass-approvals-and-sandbox` - No sandbox, no approval prompts (REQUIRED on this server — bwrap fails) - `--full-auto` - Workspace-write sandbox + auto-approve (BROKEN on this server — bwrap loopback fails) - `--json` - JSONL event stream (for programmatic parsing) - `-o {file}` - Write last agent message to file - `-C {dir}` - Set working directory - `--ephemeral` - Don't persist session (no resume possible)

```bash codex exec -m "{model}" -c model_reasoning_effort={effort} --dangerously-bypass-approvals-and-sandbox "{prompt}" 2>&1 ```

| Model | Reasoning | Best For | |-------|-----------|----------| | gpt-5.4 | low/medium/high/xhigh | Default, best quality (latest) | | gpt-5.3-codex | low/medium/high/xhigh | Fallback | | gpt-5.2-codex | low/medium/high/xhigh | Legacy fallback | | gpt-5.1-codex-max | low/medium/high/xhigh | Extended tasks | | gpt-5.2 | low/medium/high/xhigh | Non-codex variant | | gpt-5.1-codex | low/medium/high | Stable, lighter | | gpt-5-codex-mini | medium/high | Budget, simple tasks | **NOT available via...

| Scenario | Use Codex | Use Claude Task | |----------|-----------|-----------------| | Autonomous file edits across many files | ✅ | | | Refactoring with clear instructions | ✅ | | | Bulk migrations/transformations | ✅ | | | Tasks needing inherited context | | ✅ | | Tasks needing tool restrictions | | ✅ | | Coordinated multi-agent with shared state | | ✅ | | Cost-sensitive (ChatGPT plan = free) | ✅ | | ---

All MCP servers are active (deferred loading — 0 cost until first use). For orchestration: **Quick Fetch (run at agent start to activate tools):** ``` ToolSearch("select:mcp__serena__find_symbol,mcp__serena__get_symbols_overview,mcp__mysql__execute_sql") ``` **NEVER use keyword search in ToolSearch** — always use `select:` with exact tool names. - **Serena** — Understand codebase structure for task delegation - **MySQL** — Check data state when coordinating data-related tasks ---

**Purpose:** Spawn, track, and coordinate multiple parallel OpenAI Codex CLI agents for autonomous code tasks. **Expert file:** `coordination/experts/_claude/agent-system/CURRENT-codex-cli.md` ---

After detecting workspace, **immediately read the full variant file** and follow its instructions completely. Do NOT use this router file for actual cleanup work. This file is ONLY for routing.

| Variant | File | Workspace | Key Differences | |---------|------|-----------|-----------------| | `codebase-janitor-reportmaker` | `codebase-janitor-reportmaker.md` | `/var/www/reportmaker/` | Laravel structure, app/resources/routes dirs, artisan/composer/vite configs | | `codebase-janitor-ops` | `codebase-janitor-ops.md` | `/var/www/magitek-ops/` | Expert file structure, CURRENT symlinks, coordination/ layout, location-based dirs |

```bash # Quick check if [ -f artisan ]; then basename "$(pwd)" # reportmaker, skymirror, etc. else echo "ops-workspace" fi ```

**Detect workspace from current working directory:** ``` IF cwd = /var/www/reportmaker (or contains artisan + "reportmaker" in path): -> Read and follow ALL instructions from .claude/agents/codebase-janitor-reportmaker.md ELSE IF cwd = /var/www/skymirror (or contains artisan + "skymirror" in path): -> Read and follow ALL instructions from .claude/agents/codebase-janitor-reportmaker.md (SkyMirror uses same Laravel project structure as ReportMaker) ELSE IF cwd =...

All MCP servers are active (deferred loading — 0 cost until first use). For codebase cleanup: **Quick Fetch (run at agent start to activate tools):** ``` ToolSearch("select:mcp__serena__find_symbol,mcp__serena__get_symbols_overview,mcp__serena__find_referencing_symbols") ``` **NEVER use keyword search in ToolSearch** — always use `select:` with exact tool names. - **Serena** — Understand file relationships before cleanup decisions ---

This agent detects your workspace and delegates to the correct specialized cleanup variant.

``` cleanup(janitor): [action] [count] [category] files # Examples: cleanup(janitor): remove 7 HANDOFF-*.md from project root cleanup(janitor): remove 12 phpstan variant configs cleanup(janitor): remove 5 one-off PHP test scripts from root cleanup(janitor): remove orphan filedump/ directory ```

- Can be run standalone via `/cleanup` command - Orchestrator can delegate after `/implement-masterplan` or `/audit-masterplan` completes - Solo modes can suggest running when they notice junk during work - Post-merge hook could trigger a lightweight scan (future enhancement)

**Default: DELETE** for obvious junk (HANDOFF-*, test_*, benchmark_*, modal_output*, tool output) **ASK USER** for borderline files: - `CHANGELOG.md` — might be wanted, might be agent-generated - `backup-site.sh` — might be intentional ops script - `deployment/` — might have useful configs - Any file > 50KB — flag for review before deletion - Any `.sh` that looks like it might be in active use **MOVE to coordination/archive/** for: - Masterplan-related files found in wrong location - Expert...

```bash # Verify clean state ls *.md *.txt *.sh *.py *.php *.html 2>/dev/null # Show revert commands git log --oneline -N # Show the N cleanup commits echo "To revert any category: git revert <commit-hash>" ``` ---

For each category with approved files: ```bash # For tracked files git rm file1.md file2.md file3.md git commit -m "cleanup(janitor): remove N root-level [category] files Files removed: - file1.md - file2.md - file3.md Revert: git revert $(git rev-parse HEAD)" # For untracked files — stage first for history git add file1.txt file2.txt git rm file1.txt file2.txt git commit -m "cleanup(janitor): remove N untracked [category] files Files removed: - file1.txt - file2.txt Revert: git revert...

I will create NN commits, one per category, for easy selective revert. Each commit message: `cleanup(janitor): remove [category] — [count] files` Approve? [Wait for user] ```

- Total junk files: NN - Total size: NN KB - Tracked (safe git rm): NN files - Untracked (needs staging first): NN files

...

| File | Size | Git Status | Recommendation | |------|------|-----------|----------------| | HANDOFF-FORMAT-TAB-FIXES.md | 4.2K | tracked | DELETE | | QUICK-WINS-INDEX.md | 2.1K | tracked | DELETE |

Present findings as a clear table: ```

```bash # Root-level files (not in subdirs, not hidden except specific ones) ls -la *.md *.txt *.sh *.py *.php *.html *.neon *.xml *.json 2>/dev/null # Known junk patterns find . -maxdepth 1 -name "HANDOFF-*" -o -name "TASK-*" -o -name "IMPLEMENTATION-*" \ -o -name "AUDIT-*" -o -name "REVIEW-*" -o -name "COMPLETION-*" \ -o -name "QUICK-WINS-*" -o -name "WAVE*-*" -o -name "SECURITY_AUDIT_*" \ -o -name "test_*" -o -name "test-*" -o -name "benchmark_*" \ -o -name "modal_output*" -o -name...