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 → DONE

Impact: High | Effort: Low ✅ Composable multi-language linting system implemented. Canonical formatters in formatters/ (py, sh, ts, sql, json + symlinks for js, yaml, md). PostToolUse dispatcher hook with checkpoint/revert. Pre-commit hook. Setup scripts. /linter skill for auditing. 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 → DONE

Impact: Medium | Effort: Low ✅ Implemented in ~/.claude/hooks/pre-compact-backup.sh. Fires on both auto and manual compaction. Reads transcript_path from stdin JSON, copies to ~/.claude/transcript-backups/ with timestamp, prunes backups older than 30 days. 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.
• PreCompact transcript backup hook — ~/.claude/hooks/pre-compact-backup.sh with auto+manual matchers.
• claude-foundations Gitea repo — Created under skynet org, pushed.

Completed (2026-03-13)

• PostToolUse auto-formatting hook — Composable multi-language linting system: 5 formatter scripts + 3 symlinks, PostToolUse dispatcher with git-blob checkpoints, pre-commit hook, setup scripts, /linter skill, best-practices/linting.md.