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), clear description, or vague/fuzzy (needs clarification)

• Clarify if vague — Ask questions ONE at a time

• Detect depth — Auto-detect quick/standard/deep

• Runtime context (Tidewave) — Gather live schemas, routes, and warnings before spawning agents (see planning-orchestrator)

• Spawn research agents — Selective, parallel, based on need. Create a Claude Code task per agent for progress visibility: 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

• Generate plan — Checkboxes, phased tasks, code patterns

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

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

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 the plan"

• "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)

• references/planning-workflow.md — Detailed step-by-step

• references/plan-template.md

• references/complexity-detail.md

• references/example-plan.md

• references/agent-selection.md

• references/breadboarding.md