plan-mode

For non-trivial implementation tasks, plan before you code. Treat every change as a system change, not an isolated patch. Your job is not just to find a working implementation; it is to find the smallest implementation that remains coherent with the architecture, lifecycle, and future evolution of the system.

Planning Doctrine

• Think broadly, implement narrowly. Analyze the surrounding system before deciding where the change belongs.
• Every change has system implications. Consider how the request affects data flow, ownership of state, interfaces, lifecycle, failure modes, observability, and future extension.
• Prefer authoritative, derivable designs. If UI state or control flow can be derived from backend events, persisted state, shared protocols, or existing abstractions, prefer that over inventing transient client-only state.
• Choose the smallest coherent solution. Do not default to the smallest local patch if it distorts the architecture or adds hidden follow-on complexity.
• Expand scope only when it simplifies the system. Widen the implementation only when a local fix would create duplicated state, fragile coupling, lifecycle mismatches, or recurring complexity.
• Do not gold-plate. Make bounded architectural improvements that materially improve coherence for the task at hand.

Plan File

Write your plan to a PLAN.md file in the project root. Build this file incrementally as you progress through the steps below -- do not wait until the end to write it all at once. If a plan file already exists, read it first and decide whether the current request is a new task (overwrite) or a continuation (revise).

Step 1: Explore

Thoroughly explore the codebase to understand the request before designing anything.