| name | write-plans |
| description | Write and update durable project, implementation, migration, and architecture plans. Use when creating a new plan document, revising an existing plan, choosing where a plan belongs in a repository, or splitting a large plan into an indexed set of documents. |
Write Plans
Write plans as current instructions for future work, not as narratives of how the plan evolved.
Preserve the Current State
- State the plan as it is now. When facts or decisions change, replace the outdated text instead of annotating the old text inline.
- Avoid historical comparisons such as “previously,” “now,” “changed from,” or “unlike the original plan” unless that history is necessary to execute or understand the work.
- Rely on version control for history. If essential context would otherwise be lost, add a very brief changelog at the bottom of the plan.
- Keep one clearly controlling plan. Remove or update stale guidance and references that could send an agent to an obsolete plan.
Follow Repository Conventions
Inspect the repository before choosing a location or structure. Follow its existing plan directories, indexes, naming patterns, and status conventions.
If the repository has no convention, use:
docs/plans/
├── planning/
├── active/
├── implemented/
└── deprecated/
Choose the directory that describes the plan's current state. Add another status directory when none of these categories fits. When moving a plan between states, update indexes and inbound references so its canonical location remains discoverable.
Keep Plans Usable
- Make scope, intended outcome, important decisions, work sequence, dependencies, and acceptance evidence explicit when they matter.
- Distinguish settled decisions from unresolved questions. Do not present assumptions or proposals as established facts.
- Prefer a concise, navigable plan over an exhaustive narrative.
- If a plan would flood an agent's context, turn it into a directory with a concise index and focused supporting documents. Make the index identify the controlling document, recommended reading order, and purpose of each file.
- Do not include developer-time estimates unless the user explicitly requests them.
- Optionally include rough story or epic sizing when it helps communicate relative scope; sizing is not required.
Update Existing Plans
Read the whole affected plan and its index before editing. Rewrite impacted sections into a coherent current-state document, then check for contradictions, stale links, duplicate authorities, and status mismatches across the plan set.
