An agentic skills framework & software development methodology that works.
docs(codex-tools): add named agent dispatch mapping for Codex (#647)
Drew Ritter2b1bfe5db62e
diff --git a/skills/using-superpowers/references/codex-tools.md b/skills/using-superpowers/references/codex-tools.mdindex 86f58fa61..539b2b1c7 100644--- a/skills/using-superpowers/references/codex-tools.md+++ b/skills/using-superpowers/references/codex-tools.md@@ -4,7 +4,7 @@ Skills use Claude Code tool names. When you encounter these in a skill, use your| Skill references | Codex equivalent ||-----------------|------------------|-| `Task` tool (dispatch subagent) | `spawn_agent` |+| `Task` tool (dispatch subagent) | `spawn_agent` (see [Named agent dispatch](#named-agent-dispatch)) || Multiple `Task` calls (parallel) | Multiple `spawn_agent` calls || Task returns result | `wait` || Task completes automatically | `close_agent` to free slot |@@ -23,3 +23,78 @@ multi_agent = true```This enables `spawn_agent`, `wait`, and `close_agent` for skills like `dispatching-parallel-agents` and `subagent-driven-development`.++## Named agent dispatch++Claude Code skills reference named agent types like `superpowers:code-reviewer`.+Codex does not have a named agent registry — `spawn_agent` creates generic agents+from built-in roles (`default`, `explorer`, `worker`).++When a skill says to dispatch a named agent type:++1. Find the agent's prompt file (e.g., `agents/code-reviewer.md` or the skill's+ local prompt template like `code-quality-reviewer-prompt.md`)+2. Read the prompt content+3. Fill any template placeholders (`{BASE_SHA}`, `{WHAT_WAS_IMPLEMENTED}`, etc.)+4. Spawn a `worker` agent with the filled content as the `message`++| Skill instruction | Codex equivalent |+|-------------------|------------------|+| `Task tool (superpowers:code-reviewer)` | `spawn_agent(agent_type="worker", message=...)` with `code-reviewer.md` content |+| `Task tool (general-purpose)` with inline prompt | `spawn_agent(message=...)` with the same prompt |++### Message framing++The `message` parameter is user-level input, not a system prompt. Structure it+for maximum instruction adherence:++```+Your task is to perform the following. Follow the instructions below exactly.++<agent-instructions>+[filled prompt content from the agent's .md file]+</agent-instructions>++Execute this now. Output ONLY the structured response following the format+specified in the instructions above.+```++- Use task-delegation framing ("Your task is...") rather than persona framing ("You are...")+- Wrap instructions in XML tags — the model treats tagged blocks as authoritative+- End with an explicit execution directive to prevent summarization of the instructions++### When this workaround can be removed++This approach compensates for Codex's plugin system not yet supporting an `agents`+field in `plugin.json`. When `RawPluginManifest` gains an `agents` field, the+plugin can symlink to `agents/` (mirroring the existing `skills/` symlink) and+skills can dispatch named agent types directly.++## Environment Detection++Skills that create worktrees or finish branches should detect their+environment with read-only git commands before proceeding:++```bash+GIT_DIR=$(cd "$(git rev-parse --git-dir)" 2>/dev/null && pwd -P)+GIT_COMMON=$(cd "$(git rev-parse --git-common-dir)" 2>/dev/null && pwd -P)+BRANCH=$(git branch --show-current)+```++- `GIT_DIR != GIT_COMMON` → already in a linked worktree (skip creation)+- `BRANCH` empty → detached HEAD (cannot branch/push/PR from sandbox)++See `using-git-worktrees` Step 0 and `finishing-a-development-branch`+Step 1 for how each skill uses these signals.++## Codex App Finishing++When the sandbox blocks branch/push operations (detached HEAD in an+externally managed worktree), the agent commits all work and informs+the user to use the App's native controls:++- **"Create branch"** — names the branch, then commit/push/PR via App UI+- **"Hand off to local"** — transfers work to the user's local checkout++The agent can still run tests, stage files, and output suggested branch+names, commit messages, and PR descriptions for the user to copy.