mzored/superpowers-cc-to-codex/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)

<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:

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

1. 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.

1. Review the draft — Claude reviews the returned plan against the spec (see Self-Review below)
2. Fix issues — edit the plan inline to fix any gaps found in review
3. Save plan — write to docs/superpowers/plans/YYYY-MM-DD-<feature-name>.md using plan-template.md header; commit
4. 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."