claude-foundations/TODO.md

TODO: Top 10 Improvements

Prioritised by impact and effort. Each item references its detailed topic file in improvements/.

1. Configure PostToolUse auto-formatting hook

Impact: High | Effort: Low Auto-format code after every Edit/Write. Removes all formatting rules from CLAUDE.md, saves tokens, and guarantees consistent output. Start with shfmt for shell and expand. See: hooks-and-automation.md

2. Create global ~/.claude/CLAUDE.md → DONE (parent symlink)

Impact: High | Effort: Low ✅ ~/dev/claude/CLAUDE.md symlinked to claude-foundations/CLAUDE.md. All projects under ~/dev/claude/ inherit it automatically. Used parent-directory scope (option B) rather than global ~/.claude/ scope. See: global-configuration.md

3. Configure PreToolUse security hook

Impact: High | Effort: Low Block writes to secrets files, .env, lockfiles, and destructive commands. Deterministic protection vs. hoping Claude remembers the CLAUDE.md rule. See: hooks-and-automation.md

4. Install Context7 MCP server

Impact: High | Effort: Medium Real-time, version-specific documentation for Helm charts, Kubernetes APIs, and any library. Eliminates knowledge-cutoff guesswork — particularly valuable for cluster-bootstrap. See: mcp-servers.md

5. Build /catchup skill

Impact: Medium | Effort: Low Reads git diff, changed files, and relevant memory when resuming work. Automates the manual "what changed since last session?" flow. See: skills-and-progressive-disclosure.md

6. Build /validate skill

Impact: Medium | Effort: Low Codifies the "validate before deploying" principle into a single command. Runs helm template, kustomize build, linting as appropriate. Prevents deploy-crash-fix cycles. See: skills-and-progressive-disclosure.md

7. Install Language Server plugin

Impact: High | Effort: Medium boostvolt/claude-code-lsps gives Claude real-time types, go-to-definition, and find-references. "The single biggest productivity gain" per community consensus. See: plugins-and-language-servers.md

8. Add PreCompact transcript backup hook

Impact: Medium | Effort: Low Save conversation transcript before auto-compaction. Pairs with auto-memory to ensure no context is lost during long sessions. See: hooks-and-automation.md

9. Prune and restructure project CLAUDE.md

Impact: Medium | Effort: Medium — UNBLOCKED (item 2 complete) After creating the global file (item 2), prune the project CLAUDE.md. Move discoverable info out, rewrite prohibitions as positive guidance, add verification commands section, put critical rules at the top. See: claude-md-refinements.md

10. Adopt Plan Mode as default workflow — DONE (used this session)

Impact: High | Effort: Zero Use Shift+Tab twice before any non-trivial task. Iterate on the plan before executing. Boris from Anthropic says this "easily 2-3x's results." No tooling needed — just a habit change. See: 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.
• 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.
• claude-foundations Gitea repo — Created under skynet org, pushed.