Writing Plans

Save a drafted plan to the repository unless the user requests chat-only output. Default to docs/plans/YYYY-MM-DD_<topic>-plan.md with a concise lowercase kebab-case topic and update it in place during authorized execution.

Plan Content

Ground the plan in relevant repository evidence and state assumptions or unknowns only when they affect execution or validation. Always include Goal, Plan, and Completion Checklist. Add only useful optional sections: Context; Architecture for system boundaries, ownership, data flow, APIs, state, permissions, storage, or deployment; Tech Stack for tool, runtime, or package choices; Non-Goals; Assumptions; Unknowns; and Risks. Include Rollback / Recovery for production data, migrations, infrastructure, releases, or public APIs.

Tasks

Use dependency-ordered Markdown checkboxes that each name one action, its object, expected result, and acceptance evidence. Limit tasks and finite completion checks to work the agent can perform with available tools, safely prepared dependencies, and granted authorization. Keep checks in scope when the agent can safely prepare their environment; do not classify work by test type alone. Turn material unknowns into early discovery tasks. Keep dependent tasks blocked when a missing external prerequisite prevents safe implementation.