plan-writing

Plan Writing

Instructions

When writing or reviewing a plan file:

1. Use the .plan.md extension.
2. When the user does not specify a location, default to <repo>/.agents/plans/; if the repo already has an established plans directory such as .cursor/plans/, follow that local convention.
3. Start with YAML frontmatter containing name, overview, todos, and isProject.
4. Make todos a short execution checklist with stable lowercase hyphenated id values, concrete content, and status: pending.
5. After frontmatter, write the plan body in Markdown.
6. Include enough repo-specific detail that another agent can implement without guessing.
7. Separate implementation steps from validation, rollout, and rollback when the work has operational risk.
8. Prefer exact files, commands, config keys, target hosts, acceptance criteria, and blockers over broad intent.
9. Do not hide open questions. Add an assumptions or blockers section when requirements are uncertain.
10. Date design decisions and verified claims (e.g. "verified 2026-06-09"), so a later session knows how stale they might be.

Executing a Plan

A plan file is shared state across sessions and agents: a resumed or parallel session decides what to do next by reading the todo statuses. Stale statuses cause redone or skipped work, so maintain them as part of the implementation itself, not as cleanup afterward.

• Statuses are pending, in_progress, and completed.
• Set a todo to in_progress when starting it, and to completed as soon as its work is done and verified — not in a batch at the end of the session. If the session dies mid-plan, the file should still show exactly where things stood.
• Only mark completed when the step truly finished, including its verification. A step that ended in failing tests or partial work stays in_progress.
• If a step turns out to be unnecessary or is superseded, do not leave it pending forever and do not silently delete it — mark it completed with a brief note appended to its content (e.g. "— superseded by X"), so the record stays honest.
• When implementation diverges from the plan body (a design changes, an edge case forces a different approach), update the body with a short dated note at the point of divergence. The plan should describe what was actually built; a plan that lies is worse than no plan.
• When the last todo completes, give the body a final pass: blockers that materialized, follow-ups discovered during implementation, and anything the next reader needs.