writing-plans-codex

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)

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.

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:

{
  "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."