plan-mode.md

title	Plan Mode

Use wavemill plan when work is still too large or ambiguous for wavemill mill. It decomposes a broad epic or initiative into well-scoped sub-issues that can be milled later.

What It Does

1. Selects an epic from your Linear backlog.
2. Optionally researches comparable products and patterns.
3. Decomposes the epic into 3–10 independently executable sub-issues.
4. Creates a milestone and all sub-issues in Linear with priority, estimates, and dependency links.

Run It

# interactive epic selection + decomposition
wavemill plan

# or use the tool directly
npx tsx tools/plan-initiative.ts list        # rank initiatives by size
npx tsx tools/plan-initiative.ts decompose   # decompose + create issues

Workflow Phases

1) Epic Selection

Pick an initiative or large issue from your Linear backlog. Context is saved to epics/<epic-name>/selected-task.json.

2) Research (optional)

Pass --research to have Claude study 2–3 comparable products and extract patterns and anti-patterns before planning. Output goes to epics/<epic-name>/research-summary.md.

3) Decomposition

Claude breaks the epic into sub-issues organized by milestone:

• Proof of Concept — validate core assumptions
• MVP — minimum shippable feature set
• V1 Launch — polish, edge cases, observability
• Long-term — extensions, optimizations

Each sub-issue includes a title, user story, description, priority (P0–P3), and dependency references.

4) Linear Issue Creation

The decomposition plan is pushed to Linear:

• A milestone is created (or matched to an existing one).
• Sub-issues are created with enhanced descriptions that reference the parent epic and relevant files.
• Dependency relations (blocks) are created between issues so the backlog reflects execution order.

Key Files

File	Purpose
tools/plan-initiative.ts	List and decompose initiatives
shared/lib/wavemill-plan.sh	Plan workflow orchestrator called by wavemill plan
tools/prompts/initiative-planner.md	System prompt for decomposition
tools/prompts/research-phase.md	Research phase prompt template
shared/lib/linear.js	Linear API helpers (create issues, milestones, relations)

See Also

• Feature Workflow — guided single-issue execution with plan → implement → validate gates
• Mill Mode — autonomous parallel backlog processing
• Expand Mode — batch expand issues into task packets
• Eval Mode — evaluate LLM performance on workflows
• Labels — how labels control parallel task scheduling
• Troubleshooting — common issues and fixes