Ever run parallel tasks with Codex and Superpowers?
You’re watching it run, and suddenly a sub-agent just freezes. Logs show nothing, Codex is still “working”, but no output. You check AGENTS.md and see wait. Wrong. The correct command is wait_agent.
That was the pitfall in V2. V3 fixes this and streamlines the entire workflow.
Why V3 Isn’t Just Another Update
V1 and V2 of AGENTS.md were experimental. V1 focused on task routing. V2 added auto-judgment on top, but the documentation was repetitive, logic was verbose, context bloated, and real-world results were underwhelming.
V3 does three things: streamlines routing logic (flattens the winding conditionals), fixes sub-agent wait bug (replaces wait with wait_agent, PR submitted to Superpowers), adds parallel-first prioritization (auto-research parallel feasibility after writeplan).
The result: shorter context, but more complete scenario coverage.
AGENTS.md Priority Logic: Four Layers
AGENTS.md isn’t written casually. It takes effect by priority, from highest to lowest:
1. User's explicit request in current session
2. Repository rules, docs, and conventions
3. This AGENTS.md
4. Related Superpowers / skill flow definitions
Codex reads ~/.codex/AGENTS.md (global) and project root AGENTS.md (project-level) on startup. Project-level overrides global, same logic as .gitignore.
The benefit: use company rules at work, personal rules for side projects, neither interferes with the other.
Task Routing: Teaching AI to Be Lazy
V3’s core principle in one sentence: parallel-first when suitable, serial when not.
“Lazy” here is a compliment. If AI encounters a small task like changing one config line or fixing a single-file bug, making it go through the full brainstorming, writing-plans, implementation, review chain is like asking a chef to write a design document for fried rice.
V3 splits tasks into two categories:
- Read-only tasks: analysis, explanation, architecture docs, code reading—process directly, skip implementation flow.
- Lightweight tasks: single-file changes, clear bug fixes, config tweaks—skip brainstorming and heavy review, implement directly.
Everything else is heavyweight. New features, public APIs, concurrency logic, large refactors—these go through the full flow.
The key isn’t “when to downgrade” but “when to upgrade”. When scope expands beyond initial judgment, involves shared contracts, or requirements become unclear—upgrade immediately, don’t force the lightweight path.
Parallel Development Done Right
V3 goes hard on parallelism.
Sub-agent dispatch has hard requirements: model and reasoning_effort must be explicitly set. Only gpt-5.4 and gpt-5.3-codex allowed, defaulting to gpt-5.4. Reasoning effort only high or xhigh, bump up when in doubt.
This constraint seems rigid at first. Pick a mismatched model casually, sub-agent quality fluctuates, and the whole parallel strategy falls apart.
The dispatch loop is locked down:
spawn_agent → log agent_id → wait_agent → collect results → close_agent
Can’t use regular command wait to replace sub-agent wait semantics. This rule is non-negotiable for parallelism to actually work.
Parallel admission is strict: tasks must split into 2-4 cleanly bounded subtasks, with clear scope_write/scope_read, independently verifiable, no obvious file write conflicts.
If changes concentrate in 1-2 core files, involve shared contracts or shared types, or rework integration risk is high—stick to serial, don’t force the split.
Ownership rules are direct: no two subtasks can simultaneously modify the same file, config source, or contract. package.json, lockfile, root build/lint/test configs, CI, schema, migration, shared adapters—serial by default or unified finalization.
The Sub-Agent Wait Pitfall: wait vs wait_agent
This was the bug discovered between V2 and V3.
Many wrote wait in AGENTS.md, and sub-agents froze. The reason: wait doesn’t mean what you think—it doesn’t wait for sub-agent results, it just waits a duration then continues.
wait_agent is the correct choice: it waits for sub-agent completion or actual blocking, then returns control.
This bug is fixed in Superpowers code. V3’s AGENTS.md uses the corrected semantics.
Codex Test Levels: Not Every Task Needs TDD
V3 provides five test levels, choose by scenario:
Level 0: Targeted verification — local, low-risk, small changes
Level 1: Regression testing — medium-small fixes or local behavior changes
Level 2: TDD — new features, explicit behavior changes, shared logic
Level 3: Code Review — follow review rules
Level 4: Completion Verification — final check before done
TDD isn’t default. Explicitly decide based on “behavior impact, shared scope, regression risk, test value”.
Many teams hear “AI coding assistant” and think “TDD everything”. Result: AI generates piles of tests while core logic stays uncovered. V3’s advice: targeted verification first, cover key paths, don’t force tests for low-value scenarios.
Commit Convention: Keep It Simple
Format: <type>(scope): <summary>, scope optional, summary starts with verb, max 50 chars, no period.
Common types: feat / fix / refactor / docs / test / chore
Example: fix(auth): handle token refresh on expiry
Complete AGENTS.md Config
This AGENTS.md integrates all rules above. Copy to ~/.codex/AGENTS.md or project root, adjust as needed.
# Global Agent Rules
## Priority
1. User's explicit request in current session
2. Repository rules, docs, and conventions
3. This AGENTS.md
4. Related Superpowers / skill flow definitions
## Default Principles
### Shortest Path & Parallel Routing
- Default to "shortest path that meets quality requirements"
- Judge if task suits parallel first; parallel if suitable, serial if not
- Don't upgrade to heavier flow if directly completable and verifiable
- Don't upgrade to heavy doc flow if lightweight planning suffices
- Don't expand to full Superpowers if single skill suffices
### Lightweight Task Strategy
- Lightweight: single-file changes, clear bug fixes, config tweaks, small test additions
- Skip full brainstorming, writing-plans, using-git-worktrees and heavy review chain by default
- Questions: max 1 key question for lightweight tasks; give 2-3 options at once for medium tasks
- Default authorization: modify directly related app code, tests, local docs in current branch
- Must confirm: file deletion, large refactors, shared contracts, root configs, CI, database changes
### Flow Upgrade / Downgrade
- Upgrade: scope exceeds initial judgment, involves public API / schema / persistence / concurrency, unclear requirements
- Downgrade: local changes with clear boundaries, no shared core logic, direct verification
## Task Routing Model
### Read-only Tasks
- Analysis, explanation, architecture docs, code reading—process directly
- Issue investigation prefers systematic-debugging
### Implementation Tasks
- Default flow: brainstorming -> writing-plans -> implementation
- Lightweight planning minimum: objective, boundaries, risks, verification method
- Review via requesting-code-review / receiving-code-review
- Run verification-before-completion before done
## Parallel Development Control
### Sub-agent Dispatch
- spawn_agent must explicitly set model and reasoning_effort
- Models: gpt-5.4 (default) and gpt-5.3-codex only
- reasoning_effort: high or xhigh only
### Dispatch Loop
- spawn_agent → log agent_id → wait_agent → collect results → close_agent
- Don't use regular command wait for sub-agent semantics
### Parallel Admission
- Suitable: 2-4 cleanly bounded, independently verifiable subtasks
- Not suitable: changes in 1-2 core files, shared contracts, needs branch isolation
### Final Integration
- Must integrate after all subtasks complete
- Minimum: summarize changes, check conflicts, run final verification, output merge plan
## Test Strategy
- Level 0: Targeted verification (local, low-risk)
- Level 1: Regression testing (medium-small fixes)
- Level 2: TDD (new features, shared logic, high-risk changes)
- Level 3: Code Review
- Level 4: Completion Verification
## Commit Convention
- Format: <type>(scope): <summary>
- Common types: feat / fix / refactor / docs / test / chore
- Summary: verb-first, ≤50 chars, no period
## Safety Rules
- No destructive commands (git reset, etc.) unless user explicitly requests
- Don't use non-Git tools on .git
- Don't hardcode secrets, API keys in source
- Use parameterized queries for database access
- Don't concatenate untrusted input into shell commands or SQL
## Skill Invocation
Main integration:
- Before implementation: brainstorming -> writing-plans
- Debug: systematic-debugging
- Review: requesting-code-review / receiving-code-review
- Before completion: verification-before-completion
- Frontend design: ui-ux-pro-max
Getting Started Tips
Don’t deploy this AGENTS.md everywhere at once. Pick a medium-sized project first, observe if Codex behaves as expected.
Watch for these signals: are parallel tasks actually running simultaneously, any sub-agent “fake death” (appears running but no output), are commit messages following the format correctly.
If these check out, migrate to other projects.
FAQ
Q: Which AGENTS.md takes effect when both global and project-level exist?
Project-level overrides global. Codex merges both files, project-level rules have higher priority.
Q: What if sub-agent freezes?
First check if you’re still using wait instead of wait_agent. V3 config uses wait_agent uniformly. If issue persists, check if the task truly suits parallelism—some scenarios have higher integration cost after splitting.
Q: Can I skip brainstorm for lightweight tasks?
Yes. AGENTS.md is default rules. When user makes explicit request in current session, that takes priority over AGENTS.md.