Codex: update parallel-execution skills for collab agents + FD hygiene

[deinspanjer]

Summary

Refactors several SKILL.md files to better align with Codex collab multi-agents when enabled, while providing a clean sequential fallback when collab is disabled.

Motivation

Codex supports an experimental /experimental feature called “Multi-agents” (aka “collab”). When enabled, Codex can spawn subagents (spawn_agent + wait). The current skills were written with Claude’s subagent tooling
assumptions and can mislead Codex users.

This PR updates the instructions to:

• Use collab agents when available.
• Fall back cleanly when collab is disabled.
• Avoid claiming agents were spawned without tool calls.
• Reduce risk of FD exhaustion by batching and closing agents explicitly.

Changes

Updated SKILL.md files:

• skills/dispatching-parallel-agents/SKILL.md
• skills/subagent-driven-development/SKILL.md
• skills/executing-plans/SKILL.md
• skills/writing-skills/SKILL.md

Key changes include:

• Explicit collab tool usage (spawn_agent, wait, close_agent)
• Sequential fallback when collab is disabled
• FD hygiene guidance for large agent fan-out
• Explicit warnings against claiming tool use without calls
• Reminders to enable /experimental if users want subagents

Compatibility / Risk

These edits are Codex-specific. They may not be appropriate for Claude users until the project supports agent-specific SKILL.md variants (e.g., per-agent skill overlays).

This PR is meant as a reference implementation to discuss whether agent-specific skill definitions should be introduced.

Testing

Tested in Codex with collab enabled and disabled to verify correct behavior in both scenarios. Added FD guidance because the default ulimit -n 256 can cause “too many open files” errors if Codex does not clean up old sessions
and agent handles.

Summary by CodeRabbit

Documentation

• Updated guidance on parallel agent execution workflows – Enhanced documentation for dispatching multiple agents simultaneously with improved resource management and safety checks.
• Streamlined agent collaboration patterns – Refined skill guidance to clarify proper agent spawning, waiting for results, and fallback behavior when collaboration is unavailable.
• Restructured skill documentation – Consolidated skill guides with clearer step-by-step processes, common pitfalls, and practical examples for multi-agent task execution.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

[coderabbitai]

📝 Walkthrough

Walkthrough

Documentation updates across Codex skill files restructure guidance for agent spawning, parallel execution, and resource management. Changes emphasize explicit Codex collab tool usage, sequential fallbacks when collab is disabled, and introduce lifecycle management patterns with failure handling for multi-agent workflows.

Changes

Cohort / File(s)	Summary
Bootstrap & Configuration .codex/superpowers-bootstrap.md, docs/README.codex.md	Updated tool-mapping semantics to direct Task and Subagent/Agent mentions toward spawn_agent (collab) with sequential fallback when collab is disabled; ensured proper file formatting.
Dispatching & Parallel Agents skills/dispatching-parallel-agents/SKILL.md	Complete rewrite from failure-centric pattern to prescriptive parallel-dispatch methodology; added explicit spawn_agent usage, concurrency limits, collab tool checklist, common mistakes, and real-world examples.
Plan Execution skills/executing-plans/SKILL.md	Restructured from checkpoint-based batch execution to FD-safe parallelization with agent lifecycle management; introduced per-step tagging (independent vs. coupled), concurrency caps, resource closure rules, and comprehensive failure handling.
Subagent-Driven Development skills/subagent-driven-development/SKILL.md	Converted from diagram-heavy multi-section format to concise, procedural task-centric workflow; emphasizes per-task implementer and reviewer agents, explicit spawn mechanics, fallback behavior, and structured review stages.
Skill Writing skills/writing-skills/SKILL.md	Streamlined from extensive TDD/documentation guidance to RED/GREEN/REFACTOR lifecycle with Codex Collab integration; condensed sections into action-oriented format with example-driven layout and tool usage patterns.

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~45 minutes

Poem

🐰 With collab spawns and agents in flight,
Sequential fallbacks when collab's not right,
Resource lifecycles, no FDs to fret,
Each skill reimagined—our best patterns yet!

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately and specifically summarizes the main changes: updating parallel-execution skills to support collab agents and FD hygiene.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}