mzored/superpowers-cc-to-codex/subagent-driven-development-codex

Subagent-Driven Development

Execute plan by calling codex_implement per task via the MCP tool, with two-stage review after each: Claude-side spec compliance first, then codex_review for code quality.

Core principle: Codex implementer per task + two-stage review (spec then quality) = high quality, fast iteration

<HARD-GATE> You MUST dispatch codex_implement for every plan task (Step 3). You cannot implement code yourself, even for simple tasks. Spec review requires seeing EXTERNAL implementation. No dispatch = no task completion. </HARD-GATE>

Checklist

You MUST create a task for each plan task and complete them in order.

Setup:

1. Read plan — read the plan file once, extract all tasks with full text and context
2. Create TodoWrite — one entry per plan task

Per task:

1. Capture task base — before dispatching the implementer, record the current revision:

TASK_BASE_SHA="$(git rev-parse HEAD)"

Substitute the captured TASK_BASE_SHA value as the structured review base for this task, so the reviewer inspects only the task's delta rather than all prior tasks.

1. Dispatch implementer — call the codex_implement MCP tool.

Pass the task description as the prompt:

{
  "tool": "codex_implement",
  "arguments": {
    "taskId": "task-17",
    "prompt": "Implement Task 3 from docs/superpowers/plans/2026-04-03-agent-forwarding.md. Keep the work scoped to agents/codex-implementer.md and tests/prompt-contracts/execution-workflows.test.mjs.",
    "workspaceRoot": "/absolute/path/to/your/repo"
  }
}

1. Handle status — see Status Handling below
2. Spec compliance review — Claude reads the actual code and verifies against spec using spec-review-template.md; if issues remain, resume the same implementer thread with codex_resume:

{
  "tool": "codex_resume",
  "arguments": {
    "taskId": "task-17",
    "sessionId": "019d4f82-58b8-72d3-9212-2e3d3fc69bcb",
    "prompt": "Fix these issues:\n- The agent still lacks tools: Bash.\n- The prompt-file override is ignored in the TDD path.",
    "workspaceRoot": "/absolute/path/to/your/repo"
  }
}

1. Code quality review — call codex_review only after spec compliance passes:

{
  "tool": "codex_review",
  "arguments": {
    "taskId": "task-17-review",
    "reviewStyle": "structured",
    "scope": { "kind": "base", "base": "<captured TASK_BASE_SHA value>" },
    "prompt": "Review the implementation of Task 4 from docs/superpowers/plans/2026-04-03-agent-forwarding.md. Focus on regressions, incorrect routing, and missing test coverage.",
    "workspaceRoot": "/absolute/path/to/your/repo"
  }
}

1. Mark complete — only after both gates pass

After all tasks:

1. Final review — call codex_review for the entire implementation with a new task ID and the final base SHA.
2. Finish branch — wrap up the development branch

Status Handling

Handle the implementer's reported status:

Never ignore an escalation or force the same agent to retry without changes.

Red Flags

Never:

• Skip reviews (spec compliance OR code quality)
• Proceed with unfixed issues
• Dispatch multiple implementer agents in parallel (conflicts)
• Make the Codex agent read the plan file (provide full text instead)
• Start code quality review before spec compliance passes (wrong order)
• Move to next task while either review has open issues

If reviewer finds issues: resume the implementer thread to fix, reviewer reviews again, repeat until approved.

Integration

• superpowers-cc-to-codex:writing-plans-codex — creates the plan this skill executes
• superpowers-cc-to-codex:requesting-code-review-codex — code review via the codex_review MCP tool