Add best practices, hooks, memory files, and scripts from recent sessions

Includes: spec-driven and test-driven development best practices,
reproduce-before-fixing debugging workflow, require-plan-file hook,
find-project-root script, session logs, memory files for decisions/
gotchas/process-lessons, and updates to existing best practice topics.

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

CLAUDE.md

@@ -2,7 +2,7 @@
 
 ## Session Start
 
-1. **Immediately** (without waiting for user input) list the project directories under `~/dev/claude/` (excluding `secrets/`) and present a numbered menu like:
+1. **Immediately** (without waiting for user input) use the directory tree already provided by `context-load` (the `TREE` section in your context) to identify project directories under `~/dev/claude/` (excluding `secrets/`). Present a numbered menu like:
 
    > What are we working on today?
    >
@@ -12,7 +12,7 @@
    > N-1. **No project right now** — just chat
    > N. **New project!** — start something new
 
-   Scan the directories at runtime so the list is always current. Include a brief description if the project has a CLAUDE.md or README.md you can glean one from.
+   Do **not** run shell commands to list directories — the tree is already in your context. Include a brief description if the project has a CLAUDE.md or README.md you can glean one from.
 
 2. Based on the user's choice:
    - **Existing project**: `cd` into the directory, read all `.md` files, and read `~/dev/claude/secrets/` (read-only reference — review every file to refresh context). Then read `BESTPRACTICES.md` (loaded automatically by `context-load`) and load any topic files relevant to the selected project's technology stack. Ask clarifying questions if anything is unclear or incomplete, and note context in MEMORY.md.
@@ -74,7 +74,7 @@ The primary reference for Claude sessions. Should contain:
 ### MEMORY.md (Tiered Memory System)
 Long-running projects accumulate significant context. To keep MEMORY.md useful rather than bloated, use a **tiered memory** structure:
 
-**MEMORY.md** is a **thin index only** — one-line descriptions with links to topic files in `memory/`. No content lives in MEMORY.md itself. Think of it as a card catalog. Keep it under ~50 lines.
+**MEMORY.md** is a **thin index only** — one-line descriptions with links to topic files in `memory/`. No content lives in MEMORY.md itself. Think of it as a card catalog. 
 
 **memory/** contains the actual content, split by topic:
 - `memory/project-status.md` — Current milestone, what's next, blockers
@@ -165,6 +165,28 @@ Session logs use structured markdown with parseable section headers: Summary, De
 - Unreflected logs older than `log.warn_unreflected_days` (default: 14) trigger a warning instead of deletion
 - `/reflect-logs` flags stale memory entries (version-specific bugs that have been fixed, manual processes that have been automated)
 
+## Plan Mode
+
+When working in plan mode (`permission_mode: plan`):
+
+**Before calling `ExitPlanMode`**, always write the complete plan to a file in the project root:
+
+- **Filename:** `[MILESTONE]-[PURPOSE]-PLAN.md` — e.g. `M2-auth-PLAN.md`, `M3-monitoring-PLAN.md`
+  - MILESTONE: the milestone identifier (e.g. `M2`) or a short label if not milestone-scoped (e.g. `initial`)
+  - PURPOSE: a short kebab-case description of what the plan covers
+- **Contents:** the full plan as developed in the planning conversation — steps, decisions, rationale, open questions
+- **Location:** project root (same directory as CLAUDE.md)
+
+This file becomes the implementation reference for the session that follows plan mode.
+
+**Keep the plan updated during implementation.** After completing each phase or significant step, update the PLAN.md file:
+- Mark the phase/step status as **Complete**
+- Add key commits, references, or artifacts produced
+- Document deviations from the original plan (what changed and why)
+- Note verification results
+
+This ensures the plan stays accurate as a living document — useful for resuming across sessions, reflecting on the milestone, and understanding what actually happened vs. what was planned.
+
 ## Milestones
 
 Break projects into numbered milestones (M1, M2, ...). Every milestone completion MUST include:
@@ -201,6 +223,7 @@ Break projects into numbered milestones (M1, M2, ...). Every milestone completio
 - Use colour output for pass/fail indicators in verification scripts
 - Verification scripts should check for default/insecure credentials and print remediation instructions on failure
 - Scripts should exit non-zero on failure so `&&` chains work naturally
+- **Never hardcode secrets, tokens, or access keys in scripts.** Accept them via environment variables, stdin, or `@file` references. If a script needs a secret at runtime, read it from `~/dev/claude/secrets/` or accept it as a parameter — never embed it.
 
 ## Process Principles