Move best-practices index to BESTPRACTICES.md and document CONTEXT.md pattern

Aligns index files with context-load discovery: BESTPRACTICES.md and CONTEXT.md
now follow the same thin-index pattern as MEMORY.md, auto-loaded at session start.
Adds documentation for both new index types to CLAUDE.md Documentation Standards.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

BESTPRACTICES.md

@@ -0,0 +1,18 @@
+# Best Practices Index
+
+Generalised best practices extracted from real project work. Each topic file is self-contained — read only the files relevant to the current project.
+
+## Topics
+
+- [Validation & Deployment](best-practices/validation.md) — Validate locally, deploy once; full-chain testing; pre-flight checks
+- [Secrets Management](best-practices/secrets-management.md) — SOPS + age, credential handling, file naming, encryption gotchas
+- [Git & Source Control](best-practices/git-source-control.md) — Commit practices, GitOps workflows, remote conventions
+- [Kubernetes Patterns](best-practices/kubernetes.md) — Volume mounts, deployment strategies, naming, bootstrap ordering
+- [Helm Charts](best-practices/helm.md) — Schema validation, version verification, values structure
+- [Ansible](best-practices/ansible.md) — Inventory, templates, idempotency, credential safety
+- [Scripting](best-practices/scripting.md) — Shell conventions, verification scripts, idempotency, colour output
+- [Documentation Standards](best-practices/documentation.md) — CLAUDE.md, MEMORY.md, FUTURE.md, README.md structure and tiered memory
+- [Milestones & Reflections](best-practices/milestones.md) — Milestone workflow, verification, reflection process
+- [Debugging Methodology](best-practices/debugging.md) — Systematic diagnosis, full-chain testing, common pitfalls
+- [Claude Code Skills](best-practices/skills-development.md) — Skill authoring, context injection, tool restrictions
+- [Linting & Formatting](best-practices/linting.md) — Tool choices per language, PostToolUse hook, pre-commit integration, formatter contract

CLAUDE.md

@@ -15,9 +15,9 @@
    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.
 
 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 the [Best Practices Index](best-practices/INDEX.md) in the `claude-foundations` repo 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.
+   - **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.
    - **No project right now**: Do nothing further — just respond normally.
-   - **New project!**: Follow the "New Projects" section below. Also read `~/dev/claude/secrets/` as above. Read the [Best Practices Index](best-practices/INDEX.md) in the `claude-foundations` repo and load topic files relevant to the new project's technology stack.
+   - **New project!**: Follow the "New Projects" section below. Also read `~/dev/claude/secrets/` as above. Read `BESTPRACTICES.md` (loaded automatically by `context-load`) and load topic files relevant to the new project's technology stack.
 
 ## Secrets (`~/dev/claude/secrets/`)
 
@@ -60,7 +60,7 @@ If this is a new project:
 
 ## Documentation Standards
 
-Every project maintains four core markdown files:
+Every project maintains up to six standard markdown files. All root-level `.md` files are automatically loaded by `context-load` at session start, so they should be **thin indexes** pointing to detail files in subdirectories — not large documents themselves.
 
 ### CLAUDE.md (per-project)
 The primary reference for Claude sessions. Should contain:
@@ -96,6 +96,29 @@ Long-running projects accumulate significant context. To keep MEMORY.md useful r
 
 **When writing memory after a milestone:** Create the reflection file, update any affected topic files (new gotchas, updated status), and update the index.
 
+### CONTEXT.md (Active Work Focus)
+Tells Claude (and independent agents) what the project is currently working on. Follows the same index pattern as MEMORY.md.
+
+**CONTEXT.md** is a **thin index** — one-line descriptions with links to detail files in `context/`. It answers "what should I focus on right now?"
+
+**context/** contains the detail files, one per active work stream:
+- `context/<topic>.md` — Background, status, what to test, future direction for that work stream
+
+**Principles:**
+- **Keep it current.** Remove entries when work is complete. CONTEXT.md should reflect what's actively in progress, not a history of past work.
+- **Link, don't inline.** The index stays small so `context-load` doesn't bloat the system prompt. Detail files can be as long as needed.
+- **Orient agents.** CONTEXT.md is the primary mechanism for pointing independent agents (including those in Docker containers) at the right work. Each agent gets the full context load, with its starting prompt referencing the relevant CONTEXT.md entry.
+- **Complement, don't duplicate.** CLAUDE.md has stable conventions. MEMORY.md has accumulated learnings. CONTEXT.md has the *current* focus and active tasks.
+
+### BESTPRACTICES.md (Best Practices Index)
+Index of generalised best practices extracted from real project work via the `/distill-best-practices` skill. Only exists in `claude-foundations` — other projects inherit it via `context-load` walking up the directory hierarchy.
+
+**BESTPRACTICES.md** is a **thin index** — one-line descriptions with links to topic files in `best-practices/`.
+
+**best-practices/** contains self-contained topic files (e.g., `kubernetes.md`, `helm.md`, `secrets-management.md`). Read only the files relevant to the current project's technology stack.
+
+The `/distill-best-practices` skill maintains both the topic files and the index.
+
 ### FUTURE.md
 Backlog of improvement ideas, each with:
 - **Problem:** What's painful or manual today

README.md

@@ -23,9 +23,12 @@ claude-foundations/
     install-hooks.sh       # Symlink hooks into ~/.claude/hooks/
     setup-formatters.sh    # Set up formatters for a project
   best-practices/          # Generalised best practices (one file per topic)
+  context/                 # Active work focus detail files
   memory/                  # Session logs and reflections
   settings.yaml            # Knowledge pipeline configuration
+  BESTPRACTICES.md         # Best practices index (loaded by context-load)
   CLAUDE.md                # Global project guidelines (symlinked to ~/dev/claude/)
+  CONTEXT.md               # Active work focus index (loaded by context-load)
   HOOKS.md                 # Hook documentation
   TODO.md                  # Improvement backlog
 ```

TODO.md

@@ -56,7 +56,7 @@ See: [planning-and-workflow.md](improvements/planning-and-workflow.md)
 
 ## Completed This Session (2026-03-12)
 
-- **Best-practices library** — 11 topic files + INDEX.md extracted from cluster-bootstrap and custom-claude-skills. Referenced in CLAUDE.md for auto-loading per project.
+- **Best-practices library** — 11 topic files + BESTPRACTICES.md index extracted from cluster-bootstrap and custom-claude-skills. Auto-loaded by `context-load` per project.
 - **Knowledge distillation pipeline** — Three new skills (`/log`, `/reflect-logs`, `/distill-best-practices`) with settings.yaml, state tracking, log pruning, and staleness detection.
 - **Parent CLAUDE.md symlink** — `~/dev/claude/CLAUDE.md` → claude-foundations, all projects inherit automatically.
 - **PreCompact transcript backup hook** — `~/.claude/hooks/pre-compact-backup.sh` with auto+manual matchers.

best-practices/INDEX.md

@@ -1,18 +0,0 @@
-# Best Practices Index
-
-Generalised best practices extracted from real project work. Each topic file is self-contained — read only the files relevant to the current project.
-
-## Topics
-
-- [Validation & Deployment](validation.md) — Validate locally, deploy once; full-chain testing; pre-flight checks
-- [Secrets Management](secrets-management.md) — SOPS + age, credential handling, file naming, encryption gotchas
-- [Git & Source Control](git-source-control.md) — Commit practices, GitOps workflows, remote conventions
-- [Kubernetes Patterns](kubernetes.md) — Volume mounts, deployment strategies, naming, bootstrap ordering
-- [Helm Charts](helm.md) — Schema validation, version verification, values structure
-- [Ansible](ansible.md) — Inventory, templates, idempotency, credential safety
-- [Scripting](scripting.md) — Shell conventions, verification scripts, idempotency, colour output
-- [Documentation Standards](documentation.md) — CLAUDE.md, MEMORY.md, FUTURE.md, README.md structure and tiered memory
-- [Milestones & Reflections](milestones.md) — Milestone workflow, verification, reflection process
-- [Debugging Methodology](debugging.md) — Systematic diagnosis, full-chain testing, common pitfalls
-- [Claude Code Skills](skills-development.md) — Skill authoring, context injection, tool restrictions
-- [Linting & Formatting](linting.md) — Tool choices per language, PostToolUse hook, pre-commit integration, formatter contract