🤖 feat: improve plan tool to scale with complexity

[ammario]

Summary

Updates the plan tool description to encourage proportional planning that scales with task complexity, making plans more concise for simple tasks while still allowing detailed plans for complex work.

Problem

The current plan tool description prescribes a fixed, comprehensive structure regardless of task complexity:

• Requires: problem/context, chosen approach with rationale, alternatives considered, step-by-step implementation, edge cases and risks, scope/impact, testing strategy
• Results in over-planning for simple tasks
• Creates unnecessarily long plans that slow down review
• Wastes tokens on ceremonial sections

Changes

Tool Description (before):

"Propose a detailed plan for implementation. The plan will be reviewed by the user 
before execution. Use this to outline the approach, steps, and considerations 
before making changes."

Tool Description (after):

"Propose a plan before taking action. The plan should be complete but minimal - 
cover what needs to be decided or understood, nothing more. Use this tool to get 
approval before proceeding with implementation."

Plan Parameter Description (before):

"Implementation plan in markdown (start at h2 level). Cover: problem/context, 
chosen approach with rationale, alternatives considered, step-by-step implementation, 
edge cases and risks, scope/impact on existing code, testing strategy. Break complex 
work into phases."

Plan Parameter Description (after):

"Implementation plan in markdown (start at h2 level). Scale the detail to match the 
task complexity: for straightforward changes, briefly state what and why; for complex 
changes, explain approach, key decisions, risks/tradeoffs; for uncertain changes, 
clarify options and what needs user input. Cover what's necessary to understand and 
approve the approach. Omit obvious details or ceremony."

Key Improvements

1. Mandatory planning in plan mode - "Propose a plan before taking action" (imperative, not conditional)
2. Complete but minimal - Guides toward sufficiency without excess
3. Scales with complexity - Provides examples for simple vs complex vs uncertain tasks
4. Removes prescriptive requirements - No longer requires "alternatives considered", "testing strategy", etc.
5. Avoids ceremony - "Omit obvious details or ceremony"

Expected Behavior

Simple task: "Add parameter X"
→ Brief plan (what/why/how)

Complex task: "Redesign auth system"
→ Detailed plan (architecture, phases, risks)

Uncertain task: "Not sure which approach"
→ Decision-focused plan (options with pros/cons)

Benefits

• ⚡ Faster review cycles - Users can quickly scan simpler plans
• 💰 Lower token costs - Shorter plans for simple tasks
• 🎯 Better focus - Agent concentrates on actual decisions, not ceremony
• 📏 Proportional detail - Complex tasks still get detailed plans when needed

Generated with cmux