Populate best practices from claude-foundations

Migrates 20 topic files from claude-foundations/best-practices/ to this
standalone repo. Adds BESTPRACTICES.md index, CLAUDE.md conventions, and
updated README.md. Container agents clone this repo to /best-practices.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

milestones.md

@@ -0,0 +1,52 @@
+# Milestones & Reflections
+
+## Milestone Structure
+
+Break projects into numbered milestones (M1, M2, ...). This provides clear checkpoints, measurable progress, and natural reflection points.
+
+## Milestone Completion Checklist
+
+Every milestone MUST include:
+
+### 1. Verification Script
+
+`scripts/verify-m<N>.sh` — automated checks confirming all milestone outcomes.
+- Idempotent, non-destructive, returns non-zero on failure
+- Colour output (green/red) for pass/fail
+- Environment-resilient (no sudo, test from accessible side)
+- Check for default/insecure credentials
+
+### 2. Milestone Reflection
+
+Write `memory/m<N>-reflection.md` by reviewing the **entire conversation** from milestone start. Cover:
+
+- **Process improvements:** What slowed us down? Wrong assumptions? Where did we go in circles? What would make this faster if redone from scratch?
+- **Key knowledge for reproduction:** Critical facts, gotchas, non-obvious config details, version-specific quirks, debugging detours
+- **Scripts and automation:** Existing tools that proved valuable, new scripts to build, patterns to extract into reusable automation
+- **Future improvements:** Ideas that surfaced but don't belong in current scope — add to FUTURE.md
+
+### 3. Updated README.md
+
+Ensure the scripts section, milestone table, and setup steps are current.
+
+### 4. Updated CLAUDE.md
+
+Reflect new repo structure, conventions, and patterns discovered during the milestone.
+
+## Reflection Quality
+
+Good reflections capture:
+- Commit stats (total commits, fix percentage) to measure validation discipline
+- Longest detour and root cause
+- Most avoidable waste and what would have prevented it
+- Concrete checklist items for future similar work
+
+## Evaluate Content Placement Before Building
+
+Before creating a new document, system, or catalog, discuss where it belongs conceptually. Different content types have different lifecycles:
+- **Accumulated learnings** → memory files (gotchas, process lessons)
+- **Authoritative maintained maps** → CLAUDE.md or dedicated reference docs
+- **Behavioral contracts** → spec files
+- **Active work state** → CONTEXT.md
+
+Picking the wrong home creates maintenance friction later. A five-minute placement discussion saves a future migration.