Writing Plans Codex

---
name: writing-plans-codex
description: Use when you have a spec or requirements for a multi-step task, before touching code. Codex-backed variant.
disable-model-invocation: true
---
<!--
Upstream source: obra/superpowers skills/writing-plans/SKILL.md
Last synced: 2026-04-03
Divergence: Codex-backed plan drafter for first pass; Claude reviews and finalizes; plugin-local template refs
-->

# Writing Plans

**Announce at start:** "I'm using the writing-plans skill to create the implementation plan."

**Save plans to:** `docs/superpowers/plans/YYYY-MM-DD-<feature-name>.md`
- (User preferences for plan location override this default)

<HARD-GATE>
You MUST call codex_plan in Step 2. You cannot write the plan yourself.
The plan drafter produces the first draft; Claude reviews and refines.
No codex_plan call = cannot proceed to review or saving.
</HARD-GATE>

## Checklist

You MUST create a task for each of these items and complete them in order:

1. **Scope check** — if the spec covers multiple independent subsystems, suggest breaking into separate plans (one per subsystem, each producing working testable software)
2. **Dispatch Codex plan drafter** — call the `codex_plan` MCP tool.
   Pass the approved spec verbatim as the `prompt` body; do not summarize it.
   Start the prompt with:

```json
{
  "tool": "codex_plan",
  "arguments": {
    "prompt": "Turn this approved spec into a detailed implementation plan.\n\nPaste the full approved spec below this line with no omissions or paraphrasing.\n\n<spec goes here>",
    "workspaceRoot": "/absolute/path/to/your/repo"
  }
}
```
3. **Handle the response:**

   - **Success (`result` populated):** the draft conforms to `schemas/plan-draft.schema.json` (`plan_markdown`, `files`, `tasks`, `test_commands`, `commit_boundaries`). Proceed to review (Step 4).
   - **Partial / missing fields:** treat as a draft to refine — re-dispatch `codex_plan` with a sharper prompt naming the missing pieces, or address the gaps inline during review.
   - **Error (no `result`):** inspect `stderrTail` and the resume hint in the error message; resume with `codex_resume(taskId="…")` once the cause is resolved.

4. **Review the draft** — Claude reviews the returned plan against the spec (see Self-Review below)
5. **Fix issues** — edit the plan inline to fix any gaps found in review
6. **Save plan** — write to `docs/superpowers/plans/YYYY-MM-DD-<feature-name>.md` using `plan-template.md` header; commit
7. **Offer execution** — present the plan to the user and offer to execute via superpowers-cc-to-codex:subagent-driven-development-codex

## Self-Review (Claude's Job)

After receiving the Codex draft, review with fresh eyes:

**1. Spec coverage:** Skim each section/requirement in the spec. Can you point to a task that implements it? List any gaps.

**2. Placeholder scan:** Search the plan for red flags:
- "TBD", "TODO", "implement later"
- "Add appropriate error handling" / "handle edge cases"
- "Write tests for the above" (without actual test code)
- "Similar to Task N" (code must be repeated)
- Steps without code blocks where code is needed

**3. Type consistency:** Do types, method signatures, and property names used in later tasks match what was defined in earlier tasks?

If you find issues, fix them inline. If you find a spec requirement with no task, add the task.

## Execution Handoff

After saving the plan:

> "Plan complete and saved to `<path>`. Execute using superpowers-cc-to-codex:subagent-driven-development-codex — dispatches Codex implementer per task with two-stage review."