plan-mode

The plan-mode workflow uses a PLAN.md file to structure exploration, clarify requirements, and document design decisions before implementation. It provides stepwise guidance from initial codebase exploration through architectural design to a finalized plan.

A structured planning workflow is needed for non-trivial tasks involving new features, architectural decisions, multi-file changes, unclear requirements, or multiple valid approaches. It ensures holistic, system-aware planning to minimize rework.

A PLAN.md file should follow a stepwise workflow from exploration through design to a finalized plan, documenting explicit decision points, clarifications, and architectural choices to guide coherent multi-file changes.

Plan-mode requires no specific dependencies or environment setup. You simply create or update a PLAN.md file at your project root and follow the structured exploration, clarification, design, and planning workflow.

The best way to ensure architectural coherence is to perform thorough codebase exploration, clarify ambiguous requirements, and document design decisions in a structured plan before implementation begins.

Starting to code immediately on tasks with multiple valid approaches risks architectural incoherence and significant rework. Explicit exploration and structured planning first ensures you choose the correct design path before implementation.