A common repository pattern is a top-level plan.md. It captures intent, steps, timelines, and acceptance criteria in one diff-friendly file. Keep it brief, scannable, and actionable.
- Purpose: one page of truth for the work at hand. - Structure: goals, constraints, milestones, risks, open questions. - Conventions: use headings; keep lists flat; prefer links over long quotes. - Portability: GFM checkboxes are useful but degrade gracefully as `- [ ]` elsewhere.
plan.md works because it is searchable, reviewable in PRs, and easy to merge.
# Prompts in agentic coding
Markdown is also a good container for AI/agent prompts and scaffolding: - Use code fences for system or tool directives. - Keep examples as fenced blocks for deterministic copy/paste. - Separate *instruction*, *context*, and *constraints* with headings. - Store prompts alongside code so they travel with version history.
Example layout: - `# Instruction` - `# Context` - `# Tools` - `# Examples` - `# Output contract`