Plan

Plan Elixir/Phoenix Feature

Plan a feature by spawning Elixir specialist agents, then output

structured plan with checkboxes.

What Makes /phx:plan Different from /plan

• Spawns Elixir specialist agents for research
• Plans with [ecto], [liveview], [oban] task routing
• Checks for Iron Law compliance in the plan
• Includes mix compile/format/credo/test verification
• Understands Phoenix context boundaries

Usage

/phx:plan Add user avatars with S3 upload
/phx:plan .claude/plans/notifications/reviews/notifications-review.md
/phx:plan Implement notifications --depth deep
/phx:plan .claude/plans/auth/plan.md --existing

Arguments

• $ARGUMENTS = Feature description, review file, or existing plan
• --depth quick|standard|deep = Planning depth (auto-detected)
• --existing = Enhance an existing plan with deeper research

Workflow

• Gather context — File path (skip to agents), brainstorm

interview.md (skip clarification), clear description, or vague

• Clarify if vague — Ask questions ONE at a time (skip if

brainstorm interview.md exists with Status: COMPLETE)

• Detect depth — Auto-detect quick/standard/deep
• Runtime context (Tidewave) — Gather live schemas, routes,

and warnings before spawning agents (direct path only — the

research orchestrator gathers its own)

• Spawn research — Selective, based on need. 0–2 agents:

spawn directly in parallel. 3+ agents (broad multi-context feature):

determine the effective maximum nesting depth. Use an explicit positive-integer

CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH value first; when it is unset, inspect

claude --version (the default is 1 in 2.1.217–2.1.218 and 3 in 2.1.219+).

If the version is unavailable, conservatively use 1. At depth 3+, spawn ONE

planning-orchestrator to run and compress the fan-out. At depth 1 or 2,

keep orchestration in this

main session: spawn the selected specialist agents directly, wait for them, then spawn

phx:context-supervisor directly if compression is needed. Never spawn an

orchestrator that cannot delegate. Read only the resulting digest and

summaries/consolidated.md. Create a Claude Code task per spawn:

TaskCreate({subject: "{Agent} research", activeForm: "Researching..."}),

mark in_progress on spawn, completed when done

• Wait for ALL agents — Do NOT proceed until all return

"completed". NEVER write plan while any agent is still running

• Breadboard (LiveView) — System map for multi-page features
• Completeness check — MANDATORY when planning from review
• Split decision — One plan or multiple, concrete options

10. Generate plan — Checkboxes, phased tasks, code patterns.

Also create plans/{slug}/scratchpad.md for decisions and dead-ends

11. Self-check (deep only) — Three questions in Risks section

12. Present and ask — STOP, show summary, let user decide

When planning from review: Every finding must appear in the

plan — either as a task OR explicitly deferred by the user.

See ${CLAUDE_SKILL_DIR}/references/planning-workflow.md for detailed step-by-step.

--existing Mode (Deepening)

Enhances an existing plan instead of creating a new one:

• Load plan, search .claude/solutions/ for known risks
• Spawn SPECIALIST agents (not Explore) for thin sections.

Each agent writes to .claude/plans/{slug}/research/ and

returns only a 500-word summary. Same agent selection rules

• Wait for ALL agents (mark tasks completed as each finishes)
• Add implementation detail, resolve spikes, add verification
• Present diff summary — NEVER delete existing tasks

Iron Laws

• NEVER auto-start /phx:work — Always present plan and ask
• Research before assuming — Web-search unfamiliar tech
• Spawn agents selectively — Only relevant, not all
• NEVER write plan while agents still running
• NEVER skip input findings — Every finding MUST have a task
• Do NOT spawn hex-library-researcher for existing deps
• Skip research when planning from review/investigation — When

input is a review file or /phx:investigate output, the findings

ARE the research. Do NOT spawn agents to re-discover what the

review already found. Convert findings directly to plan tasks.

(Confirmed: 56-session analysis showed same findings discovered

3-4x across review→investigate→plan phases, wasting ~96K tokens)

Integration with Workflow

/phx:plan {feature}  <-- YOU ARE HERE
       |
   /phx:plan --existing (optional enhancement)
       |
   ASK USER -> /phx:work .claude/plans/{feature}/plan.md
       |
/phx:review → /phx:compound

Notes

• Plans saved to .claude/plans/{slug}/plan.md
• Research reports in .claude/plans/{slug}/research/ can be deleted after

CRITICAL: After Writing the Plan

STOP. Do NOT proceed to implementation.

After writing .claude/plans/{slug}/plan.md:

• Summarize: task count, phases, key decisions
• Use AskUserQuestion with options:
• "Start in fresh session" (recommended for 5+ tasks)
• "Get a briefing" (/phx:brief — interactive walkthrough)
• "Start here"
• "Review or adjust the plan"
• Wait for user response. Never auto-start work.

When user selects "Start in fresh session", print:

1. Run `/new` to start a fresh session
2. Then run one of:
   /phx:work .claude/plans/{slug}/plan.md
   /phx:full .claude/plans/{slug}/plan.md  (includes review + compound)

This is Iron Law #1. Violating it wastes user context.

References (DO NOT read — for human reference only)

• ${CLAUDE_SKILL_DIR}/references/planning-workflow.md — Detailed step-by-step
• ${CLAUDE_SKILL_DIR}/references/plan-template.md
• ${CLAUDE_SKILL_DIR}/references/complexity-detail.md
• ${CLAUDE_SKILL_DIR}/references/example-plan.md
• ${CLAUDE_SKILL_DIR}/references/agent-selection.md
• ${CLAUDE_SKILL_DIR}/references/breadboarding.md