Initial commit: Claude Code foundations and improvements research

Conventions, community best practices research (Sept 2025 - March 2026), and prioritized improvement backlog for Claude Code workflows. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-03-12 23:02:54 +13:00
commit a4967df815
14 changed files with 765 additions and 0 deletions
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -0,0 +1,187 @@
+# CLAUDE.md — General Project Guidelines
+
+## Session Start
+
+1. **Immediately** (without waiting for user input) list the project directories under `~/dev/claude/` (excluding `secrets/`) and present a numbered menu like:
+
+   > What are we working on today?
+   >
+   > 1. **cluster-bootstrap** — Kubernetes homelab cluster
+   > 2. **custom-claude-skills** — Reusable Claude Code skills
+   > ...
+   > 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.
+
+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). 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.
+
+## Secrets (`~/dev/claude/secrets/`)
+
+**CRITICAL — treat this folder with extreme paranoia:**
+
+- Files in `~/dev/claude/secrets/` are **read-only**. Never edit them.
+- **Never** copy, echo, write, or reproduce secret values into any other file — not MEMORY.md, not CLAUDE.md, not commit messages, not scripts, not tool output, nowhere.
+- **Never** include secret values in git commits, diffs, or changelogs of any project.
+- **Never** pass secret values as command-line arguments (visible in `ps` output). Use `@file` references, environment variables sourced at runtime, or stdin.
+- When a task requires a secret, read it at execution time from the secrets folder and use it ephemerally. Do not cache or persist the value.
+- It is acceptable to reference the **existence** of a secret file (e.g., "credentials are in `~/dev/claude/secrets/gitea/ai_enablement`") but never its contents.
+
+## New Projects
+
+If this is a new project:
+
+1. Create a new directory under `~/dev/claude/<project-name>/`
+2. **Ask the user** which Gitea user/org the repo should be created under (e.g., `homelab`, a personal user, etc.) before setting up the remote
+3. Create the initial standard files:
+   - **CLAUDE.md** — Project-specific architecture, conventions, repo structure, and working instructions for Claude
+   - **MEMORY.md** — Persistent learnings, gotchas, reflections, and process improvements
+   - **FUTURE.md** — Ideas and improvements not on the active roadmap (Problem/Idea/Open questions/Depends on format)
+   - **README.md** — Human-readable overview, quick start, milestones, and scripts reference
+4. Parse the other CLAUDE.md files from sibling project folders in `~/dev/claude/`, and based on the type of project being considered, bring over related practices, guidelines, and learnings
+
+## Source Control
+
+- All projects are hosted on **Gitea** (`gitea.oreillyit.nz`) as the primary remote — prefer this hostname over `gitea.homelab.internal` (same instance, but the public name enables external access)
+- Migrate existing remotes from `gitea.homelab.internal` to `gitea.oreillyit.nz` when convenient
+- AI-focused projects go under the **`skynet`** org; infrastructure projects under **`homelab`**
+- SSH workflows preferred. SSH config uses host aliases per Gitea user:
+  - `gitea.oreillyit.nz-homelab` → authenticates as `cluster-administrator` (key: `~/.ssh/gitea-cluster-admin`)
+  - `gitea.oreillyit.nz-ai-enablement` → authenticates as `ai_enablement` (key: `~/.ssh/gitea.ai-enablement`)
+- Git remote URLs use the alias: `git@gitea.oreillyit.nz-<user>:<org>/<repo>.git`
+  - Example: `git@gitea.oreillyit.nz-ai-enablement:skynet/custom-claude-skills.git`
+- Optionally push-mirror to GitHub for public visibility
+- Use meaningful commit messages; prefer small, focused commits over large batches
+- Enable pre-commit hooks where appropriate (secret detection, linting, formatting)
+- Never commit secrets in plaintext — use SOPS + age or equivalent encryption
+
+## Documentation Standards
+
+Every project maintains four core markdown files:
+
+### CLAUDE.md (per-project)
+The primary reference for Claude sessions. Should contain:
+- Project overview and architecture
+- Repository structure (keep updated as the project evolves)
+- Key design decisions with rationale
+- Conventions and coding standards
+- Environment details (IPs, URLs, credentials references)
+- Common operations / how-to recipes
+
+### 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/** contains the actual content, split by topic:
+- `memory/project-status.md` — Current milestone, what's next, blockers
+- `memory/network.md` — IPs, VIPs, subnets, topology
+- `memory/gotchas-<topic>.md` — Gotchas grouped by technology (e.g., `gotchas-cilium.md`, `gotchas-authelia.md`)
+- `memory/process-lessons.md` — How-to-work-with-this-repo lessons for Claude
+- `memory/m<N>-reflection.md` — One file per milestone reflection (these are time-bound, so per-file is natural)
+- `memory/decisions.md` — Architecture and design decisions made during planning
+
+**Principles:**
+- **Split by topic, not by time.** A Cilium gotcha belongs in `gotchas-cilium.md` whether discovered in M5 or M8.
+- **Milestone reflections are the exception** — inherently time-bound, one file per milestone.
+- **Index descriptions matter.** They're used to decide what to read. "Cilium L2/LB gotchas and externalTrafficPolicy quirks" beats "cluster stuff".
+- **Prune aggressively.** If a gotcha was fixed (e.g., chart version upgraded past the bug), delete it. Stale memory is worse than no memory.
+- **Each memory file should be self-contained and greppable.** Include enough context that the file makes sense on its own.
+- **Deduplicate with CLAUDE.md.** Conventions and patterns that are stable should live in CLAUDE.md. Memory files are for learnings, gotchas, and reflections that accumulate over time. If something in memory has graduated to a stable convention, move it to CLAUDE.md and remove it from memory.
+
+**When reading memory at session start:** Read MEMORY.md (the index), then selectively read topic files relevant to the current task. Don't read all memory files unless doing a broad review.
+
+**When writing memory after a milestone:** Create the reflection file, update any affected topic files (new gotchas, updated status), and update the index.
+
+### FUTURE.md
+Backlog of improvement ideas, each with:
+- **Problem:** What's painful or manual today
+- **Idea:** What the improvement looks like
+- **Open questions:** Unknowns to research before starting
+- **Depends on:** Other items or milestones that should come first
+
+### README.md
+Human-readable project documentation:
+- Architecture summary
+- Quick start / setup instructions
+- Milestone table with status
+- Scripts section listing every script with purpose and usage
+
+## Milestones
+
+Break projects into numbered milestones (M1, M2, ...). Every milestone completion MUST include:
+
+1. **Verification script** (`scripts/verify-m<N>.sh`) — automated checks confirming all milestone outcomes. Scripts should be idempotent, non-destructive, and return non-zero on failure. Use colour output (green/red) for pass/fail.
+2. **Milestone reflection** in `memory/m<N>-reflection.md` — review the entire conversation and capture:
+   - Process improvements (what slowed us down, wrong assumptions, backtracking)
+   - Key knowledge for reproduction (gotchas, version quirks, debugging detours)
+   - Scripts and automation opportunities (repeated command sequences → scripts)
+   - Future improvement ideas (add to FUTURE.md)
+   - Update affected topic files in `memory/` (new gotchas, updated status) and the MEMORY.md index
+3. **Updated README.md** — scripts section, milestone table, any new setup steps
+4. **Updated CLAUDE.md** — repo structure, conventions, new patterns discovered
+
+## Validate Before Deploying
+
+Every new config, manifest, or template should be validated locally before deploying. The target environment is not a test environment — each deploy-crash-fix cycle wastes time and clutters Git history. Batch fixes locally, push once.
+
+Examples:
+- `helm template` for Helm values
+- `kustomize build` for Kustomize apps
+- `docker run <app> validate-configuration` for app configs
+- `docker inspect` for unfamiliar container images
+- Lint/typecheck/test for application code
+- `curl --resolve` for the full request chain after deployment
+
+## Version Management
+
+- Use the latest stable version of dependencies unless pinned for a reason
+- Verify versions from live sources (`helm search repo`, upstream docs, package registries) — don't rely on memory
+- Document the reason in a comment if a version is intentionally pinned below latest
+- Check compatibility matrices before upgrading (e.g., Talos ↔ Kubernetes, framework ↔ runtime)
+
+## Secrets Management
+
+- SOPS + age is the standard encryption tool across all projects
+- The `.sops.yaml` at the repo root defines path-based encryption rules
+- Filenames containing `secret` trigger SOPS encryption via pre-commit hooks
+- Non-secret files must NOT contain `secret` in their name
+- Never pass secrets via command-line arguments (visible in `ps` output) — use `@file` references or environment variables
+- Keep unencrypted secrets in `local_secrets/` (gitignored)
+
+## Scripting Conventions
+
+- All scripts live in `scripts/` and run from the repository root
+- Scripts should be idempotent and safe to re-run
+- 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
+
+## Process Principles
+
+These are hard-won lessons from real project work:
+
+- **Validate locally, deploy once.** Don't use the live environment as a test bed. Catch errors with local validation tools before pushing.
+- **Check before you act.** Before writing firewall/network rules, check actual routing (`ip route get`). Before running config management with variables, ensure values are real, not placeholders. Before assuming a container has a shell, `docker inspect` it.
+- **Test the full chain immediately.** After wiring up a new service or endpoint, test end-to-end from the user's perspective right away. Don't assume intermediate steps working means the whole chain works.
+- **Verify scripts should be environment-resilient.** Avoid needing sudo or special access. Test from the accessible side of a connection. Use `curl --resolve` to bypass DNS/proxy layers when testing direct connectivity.
+- **Automate repeated sequences.** If you run the same 3+ commands in sequence more than once, it should become a script.
+- **Reflect after milestones.** Don't just finish — review what happened, what went wrong, what can be improved. Write it down so future sessions benefit.
+
+## Ansible Conventions (where applicable)
+
+- Roles follow standard structure: `tasks/main.yml`, `templates/*.j2`, `handlers/main.yml`
+- Jinja2 templates have `.j2` extension and include a "managed by Ansible" header comment
+- Variables that need customisation go in `inventory.yml`, not scattered across role defaults
+- Always pass `-i inventory.yml` explicitly or run from the directory containing `ansible.cfg`
+- Never use placeholder values with `-e` for vars that template config files
+
+## Helm Chart Conventions (where applicable)
+
+- Always validate values against the chart schema before committing
+- Run `helm show values <repo>/<chart> --version <ver>` to check actual structure
+- Schemas change between versions — field names and nesting can differ from docs or online examples
+- A quick `helm template` test locally catches schema errors before deployment
--- a/IMPROVEMENTS.md
+++ b/IMPROVEMENTS.md
@@ -0,0 +1,22 @@
+# Improvements Index
+
+Research from Claude community (Reddit, HN, blogs, GitHub) — Sept 2025 to March 2026.
+Each topic file contains context, community consensus, and actionable suggestions.
+
+## Topics
+
+- [Hooks & Automation](improvements/hooks-and-automation.md) — PreToolUse/PostToolUse hooks, auto-formatting, security gates, commit validation
+- [MCP Servers](improvements/mcp-servers.md) — Context7, Sequential Thinking, and other high-value MCP integrations
+- [Skills & Progressive Disclosure](improvements/skills-and-progressive-disclosure.md) — Building skills for context-on-demand, reducing token waste, recommended community skills
+- [CLAUDE.md Refinements](improvements/claude-md-refinements.md) — What to add, remove, and restructure based on community best practices
+- [Global Configuration](improvements/global-configuration.md) — Cross-project defaults via ~/.claude/CLAUDE.md and settings.json
+- [Plugins & Language Servers](improvements/plugins-and-language-servers.md) — LSP integration, superpowers, commit-commands, pr-review-toolkit
+- [Session & Context Management](improvements/session-and-context-management.md) — Context hygiene, compaction strategies, token budgeting, ultrathink
+- [Planning & Workflow](improvements/planning-and-workflow.md) — Plan Mode, TDD loops, verification-driven development
+- [Multi-Agent Patterns](improvements/multi-agent-patterns.md) — Subagents, git worktrees, orchestration tools, when (not) to use them
+- [CI/CD Integration](improvements/ci-cd-integration.md) — Headless mode, GitHub Actions, automated PR review, cross-model validation
+- [Community Resources](improvements/community-resources.md) — Curated repos, guides, and references worth bookmarking
+
+## Prioritised Actions
+
+See [TODO.md](TODO.md) for the top 10 items to implement, ranked by impact and effort.
--- a/TODO.md
+++ b/TODO.md
@@ -0,0 +1,53 @@
+# 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](improvements/hooks-and-automation.md)
+
+## 2. Create global `~/.claude/CLAUDE.md`
+**Impact: High | Effort: Low**
+Move cross-project conventions (Gitea, secrets, SSH, commit format, response style) out of the project-level CLAUDE.md. Reduces duplication and frees ~40 lines from every project file.
+See: [global-configuration.md](improvements/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](improvements/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](improvements/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](improvements/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](improvements/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](improvements/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](improvements/hooks-and-automation.md)
+
+## 9. Prune and restructure project CLAUDE.md
+**Impact: Medium | Effort: Medium**
+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](improvements/claude-md-refinements.md)
+
+## 10. Adopt Plan Mode as default workflow
+**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](improvements/planning-and-workflow.md)
--- a/improvements/ci-cd-integration.md
+++ b/improvements/ci-cd-integration.md
@@ -0,0 +1,34 @@
+# CI/CD Integration
+
+## Why This Matters
+
+60%+ of teams adopting Claude Code now use headless mode (`claude -p`) for automation. The most productive pattern is interactive Claude for architecture/design while delegating routine reviews and migrations to headless CI.
+
+## Current State
+
+- No CI/CD integration with Claude Code
+- Projects hosted on Gitea (not GitHub, so GitHub Actions patterns need adaptation)
+
+## Patterns
+
+### Headless Mode (`claude -p`)
+Run Claude non-interactively in scripts or CI pipelines:
+- `claude -p "Generate changelog from recent commits" --output-format json`
+- `claude -p "Review this diff for security issues" < diff.txt`
+- Useful for automated PR review, changelog generation, migration scripts
+
+### Automated PR Review
+Claude reviews PRs automatically on open/update (15-45 seconds per review). Would need a Gitea webhook + runner setup rather than GitHub Actions.
+
+### Cross-Model Validation
+Advanced pattern: global CLAUDE.md tells Claude to send diffs to Gemini/Codex for independent validation before committing. "High catch rate" reported by users.
+
+### Compounding Engineering
+Autonomous CI where Claude handles routine tasks (dependency updates, code style fixes, doc generation) with manual review before merging. Creates a self-improving flywheel.
+
+## Gitea Considerations
+
+Most community examples use GitHub Actions with `@claude` mentions. For Gitea:
+- Gitea Actions (compatible with GitHub Actions syntax) could run headless Claude
+- Webhook-based triggers for PR review
+- Would need to evaluate Gitea MCP compatibility or build a simple API wrapper skill
--- a/improvements/claude-md-refinements.md
+++ b/improvements/claude-md-refinements.md
@@ -0,0 +1,65 @@
+# CLAUDE.md Refinements
+
+## Why This Matters
+
+CLAUDE.md is the agent's "constitution." Community consensus is clear: bloated files cause Claude to ignore instructions. The sweet spot is under 200 lines / 1,000 tokens. Your current file is 187 lines — right at the boundary.
+
+## Current State
+
+- 187 lines in `~/dev/claude/CLAUDE.md`
+- Contains project conventions, secrets rules, scripting standards, process principles
+- Well-structured but could benefit from pruning and restructuring
+
+## What To Keep (High Value)
+
+These earn their place because Claude cannot infer them:
+
+- Bash commands with specific flags (build, test, deploy recipes)
+- Code style rules that **differ from defaults** (only deviations)
+- Architectural decisions specific to your project
+- Common gotchas and non-obvious behaviours
+- Testing instructions and preferred test runners
+- Repository etiquette (branch naming, commit format)
+- Lessons from past mistakes
+
+## What To Remove or Move
+
+These can be pruned because Claude discovers them automatically or they belong elsewhere:
+
+| Item | Why Remove | Where It Goes |
+|---|---|---|
+| Folder structure descriptions | Claude reads directories | Nowhere — discoverable |
+| Technology stack | Visible in package.json/imports | Nowhere — discoverable |
+| Generic advice ("write clean code") | No actionable signal | Delete |
+| Formatting/linting rules | Deterministic tools do this better | Hooks |
+| Detailed process that's project-specific | Only relevant in that project | Project-level CLAUDE.md or skills |
+| Secrets rules (repeated across projects) | Cross-project concern | Global `~/.claude/CLAUDE.md` |
+| Gitea/SSH conventions | Cross-project concern | Global `~/.claude/CLAUDE.md` |
+
+## Structural Improvements
+
+### Guidance Over Prohibition
+Change "Never do X" to "Prefer Y instead of X." Claude follows positive guidance better than negative constraints.
+
+Before: "Never use placeholder values with `-e` for vars that template config files"
+After: "Always source template variables from `inventory.yml`, not ad-hoc `-e` flags"
+
+### Add Verification Commands
+Boris from the Claude Code team says giving Claude explicit ways to check its own work "2-3x's output quality." Add a section listing verification commands per project type:
+- `helm template` for Helm values
+- `kustomize build` for overlays
+- `curl --resolve` for endpoint testing
+- Test commands, lint commands
+
+### Use Emphasis for Critical Rules
+Adding "IMPORTANT" or "YOU MUST" measurably improves adherence for rules that matter most. Use sparingly — if everything is critical, nothing is.
+
+### Attention Distribution
+Claude focuses most on the beginning and end of CLAUDE.md. Middle sections get less attention. Put your most critical rules at the top.
+
+## Maintenance Cadence
+
+- Review every 2-3 weeks (ask Claude to audit and suggest improvements)
+- Growth pattern: catch mistake -> add rule -> promote frequent rules to permanent status
+- Prune aggressively: if a rule hasn't prevented an issue in a month, remove it
+- Each model release, review and remove rules the new model handles natively
--- a/improvements/community-resources.md
+++ b/improvements/community-resources.md
@@ -0,0 +1,41 @@
+# Community Resources
+
+## Curated Repositories
+
+| Repository | Description |
+|---|---|
+| [awesome-claude-code](https://github.com/hesreallyhim/awesome-claude-code) | The most comprehensive curated list of skills, hooks, commands, orchestrators, and tools |
+| [awesome-claude-skills](https://github.com/travisvn/awesome-claude-skills) | Curated skills catalogue |
+| [ykdojo/claude-code-tips](https://github.com/ykdojo/claude-code-tips) | 45 practical tips from basics to advanced, including custom skills |
+| [claude-code-best-practice](https://github.com/shanraisshan/claude-code-best-practice) | Community best practices guide |
+| [claude-code-showcase](https://github.com/ChrisWiles/claude-code-showcase) | Reference project with hooks, skills, agents, commands, and GitHub Actions |
+| [VoltAgent/awesome-claude-code-subagents](https://github.com/VoltAgent/awesome-claude-code-subagents) | 100+ specialised subagent definitions |
+| [solatis/claude-config](https://github.com/solatis/claude-config) | The Claude Code creator's personal setup and philosophy |
+
+## Guides and Articles
+
+| Resource | Key Insight |
+|---|---|
+| [Official Best Practices](https://code.claude.com/docs/en/best-practices) | Authoritative source, keep CLAUDE.md under 1,000 tokens |
+| [HumanLayer Blog](https://www.humanlayer.dev/blog/writing-a-good-claude-md) | Under 60 lines ideal, 300 lines max |
+| [alexop.dev Progressive Disclosure](https://alexop.dev/posts/stop-bloating-your-claude-md-progressive-disclosure-ai-coding-tools/) | Skills as context-on-demand, 82% token savings |
+| [builder.io Claude MD Guide](https://www.builder.io/blog/claude-md-guide) | Layered configuration strategy |
+| [okhlopkov.com Claude Code Setup](https://okhlopkov.com/claude-code-setup-mcp-hooks-skills-2026/) | MCP, hooks, and skills setup walkthrough |
+| [blog.sshh.io Claude Code Features](https://blog.sshh.io/p/how-i-use-every-claude-code-feature) | Comprehensive feature walkthrough |
+| [Boris (Anthropic) HN Tips](https://news.ycombinator.com/item?id=46256606) | Plan Mode 2-3x's results, verification 2-3x's quality |
+| [24 Claude Code Tips Advent Calendar](https://dev.to/oikon/24-claude-code-tips-claudecodeadventcalendar-52b5) | Daily tips covering breadth of features |
+
+## Community Scale
+
+- **r/ClaudeCode**: 96K members, 4,200+ weekly contributors (3x r/Codex)
+- **r/ClaudeAI**: Broader Claude discussion, usage limits are the dominant topic
+- **r/vibecoding**: 89K members, rapid prototyping with Claude Code
+- Claude Code generates 4x more Reddit discussion than competing tools
+
+## Plugins and Hook Repos
+
+| Resource | Description |
+|---|---|
+| [ryanlewis/claude-format-hook](https://github.com/ryanlewis/claude-format-hook) | Multi-language auto-formatting hook |
+| [boostvolt/claude-code-lsps](https://github.com/boostvolt/claude-code-lsps) | Language Server integration for Python, TS, Rust, Go |
+| [obra/superpowers](https://github.com/obra/superpowers) | 20+ production-proven workflow skills |
--- a/improvements/global-configuration.md
+++ b/improvements/global-configuration.md
@@ -0,0 +1,42 @@
+# Global Configuration
+
+## Why This Matters
+
+A global `~/.claude/CLAUDE.md` provides cross-project defaults, eliminating duplication across project-level files. The community has converged on a layered configuration strategy.
+
+## Current State
+
+- No global `~/.claude/CLAUDE.md` exists
+- Cross-project conventions (Gitea, secrets, SSH) are in the project-level `~/dev/claude/CLAUDE.md`
+- `~/.claude/settings.json` contains only `{"model": "opus"}`
+
+## Layered Configuration Model
+
+| Layer | File | Scope | Checked In |
+|---|---|---|---|
+| Personal defaults | `~/.claude/CLAUDE.md` | All projects | No |
+| Project shared | `./CLAUDE.md` | Team, per-project | Yes |
+| Directory-specific | `./subdir/CLAUDE.md` | Loaded when working in subdir | Yes |
+| Local overrides | `CLAUDE.local.md` | Machine-specific, gitignored | No |
+| Path-scoped rules | `.claude/rules/*.md` | Conditional on file patterns | Yes |
+| On-demand knowledge | `.claude/skills/*/SKILL.md` | Loaded only when relevant | Optional |
+
+## Suggested Global CLAUDE.md Content
+
+Move these from the project-level file to global:
+
+- **Gitea conventions** — SSH aliases, remote URL format, org structure
+- **Secrets folder rules** — read-only, never copy values, never pass as CLI args
+- **Commit message format** — meaningful messages, small focused commits
+- **Session behaviour** — "Do not allow implicit decisions — confirm with the user"
+- **Response style** — concise, no trailing summaries, no unnecessary emojis
+- **SOPS + age** as the standard encryption tool
+- **Documentation standards** that apply across all projects (CLAUDE.md, MEMORY.md, FUTURE.md, README.md)
+
+## Settings.json Improvements
+
+Beyond `model`, consider:
+
+- Hook definitions (see hooks-and-automation.md)
+- MCP server registrations (see mcp-servers.md)
+- Permission preferences for common tool calls
--- a/improvements/hooks-and-automation.md
+++ b/improvements/hooks-and-automation.md
@@ -0,0 +1,58 @@
+# Hooks & Automation
+
+## Why This Matters
+
+Hooks are the #1 "why didn't I do this sooner" recommendation across the community. Unlike CLAUDE.md rules (which Claude can forget mid-session), hooks **always execute**. They provide deterministic guardrails around non-deterministic AI behaviour.
+
+Key principle: "Never send an LLM to do a linter's job. LLMs are expensive and slow compared to traditional linters."
+
+## Current State
+
+- No hooks configured in `~/.claude/settings.json`
+- Formatting/linting rules live in CLAUDE.md as prose instructions
+
+## Community Recommendations
+
+### PostToolUse: Auto-Formatting
+
+Run formatters automatically after every `Edit`/`Write` tool call. Eliminates all formatting rules from CLAUDE.md.
+
+- `prettier --write` for JS/TS/JSON/YAML/MD
+- `shfmt -w` for shell scripts
+- `ruff format` for Python
+- Plugin: `ryanlewis/claude-format-hook` supports multi-language detection
+
+Configuration goes in `~/.claude/settings.json` under `hooks.PostToolUse`.
+
+### PreToolUse: Security Gates
+
+Block dangerous operations before they execute:
+
+- Block writes to `.env`, `.key`, `.pem`, `secrets/`, lockfiles
+- Block destructive commands (`rm -rf /`, `dd`, `mkfs`)
+- Scan for API keys/credentials in file content before writes
+- Block commits that include sensitive file patterns
+
+### PreToolUse: Commit Validation
+
+Wrap `Bash(git commit)` with test/lint validation. Only allow commits if checks pass. Forces Claude into "test-and-fix" loops until the build is green. This is considered the single most effective quality gate.
+
+Important: **Don't block at write time** — blocking on `Edit`/`Write` confuses Claude mid-plan. Validate at commit time instead.
+
+### PreCompact: Transcript Backup
+
+Save conversation transcript before auto-compaction so context is never lost. Creates a timestamped backup in a known location. Pairs well with the auto-memory system.
+
+Reference: https://yuanchang.org/en/posts/claude-code-auto-memory-and-hooks/
+
+### Notification Hook
+
+Desktop notifications when Claude finishes a long task or needs input. Useful when running background agents.
+
+Plugin: `CC Notify` from awesome-claude-code.
+
+## Anti-Patterns
+
+- Don't add too many hooks — each one adds latency to every tool call
+- Don't block on `Edit`/`Write` for linting — do it on `PostToolUse` (non-blocking) or at commit time
+- Don't duplicate hook logic in CLAUDE.md — if a hook handles it, remove the prose rule
--- a/improvements/mcp-servers.md
+++ b/improvements/mcp-servers.md
@@ -0,0 +1,42 @@
+# MCP Servers
+
+## Why This Matters
+
+MCP (Model Context Protocol) servers extend Claude Code with external tool integrations. Community consensus: "If you're not using MCPs, you're driving a Ferrari in first gear." However, each registered MCP consumes context tokens even when unused, so be selective.
+
+## Current State
+
+- No MCP servers configured
+
+## Must-Have (Community Consensus)
+
+### Context7
+
+The single most-recommended MCP server. Provides real-time, version-specific documentation for any library/framework. Solves the knowledge-cutoff problem — Claude gets accurate docs for the exact version you're using.
+
+Particularly valuable for:
+- Helm chart values schemas (change between versions)
+- Kubernetes API changes
+- Any rapidly-evolving ecosystem
+
+### Sequential Thinking
+
+Structured problem-solving for complex architectural decisions. Described as "like having a senior architect who thinks before coding." Useful for planning phases.
+
+## Worth Considering
+
+| MCP Server | Purpose | Relevance |
+|---|---|---|
+| **Playwright** | Browser automation, UI testing, screenshot capture | Useful if doing web projects |
+| **GitHub/Gitea** | PR/issue management from terminal | Would need a Gitea-compatible MCP |
+| **Supabase** | Database ops, migrations, SQL queries | If using Supabase |
+
+## Key Insights
+
+- **Start with 2-3 MCPs, not all of them.** Each one adds to context overhead.
+- **MCP Tool Search (lazy loading)** reduces context usage by up to 95% — register many, only load what's needed.
+- **Prefer Skills over MCPs for stateless tools.** MCPs are best for stateful environments (browser sessions, database connections, auth boundaries). Stateless CLI wrappers are better as Skills.
+
+## Migration Pattern
+
+The community is trending toward moving stateless tools from MCPs to simple CLIs documented in SKILL.md files. The "wrapper pattern" uses commands as thin entry points (~93 tokens) + skills as full implementations loaded on-demand, reducing startup context by ~64%.
--- a/improvements/multi-agent-patterns.md
+++ b/improvements/multi-agent-patterns.md
@@ -0,0 +1,46 @@
+# Multi-Agent Patterns
+
+## Why This Matters
+
+Subagents are the most powerful tool for managing context — they explore in a separate context window, keeping the main conversation clean. However, multi-agent workflows are overkill for 95% of tasks and currently expensive.
+
+## Current State
+
+- Built-in subagent support available (Explore, Plan, general-purpose)
+- No custom orchestration
+- No multi-terminal patterns
+
+## Patterns (Simplest to Most Complex)
+
+### 1. Built-in Subagents (Already Available)
+Delegate research, exploration, and file searches to subagents. They run in separate context windows and return summaries. This is the easiest win — just use the Agent tool more deliberately.
+
+### 2. Git Worktrees for Parallel Work
+Use `git worktree` to let multiple Claude instances work on separate branches without conflicts. Each instance has its own working directory but shares the git history.
+
+### 3. The 4-Terminal Pattern
+Simple but effective: 4 specialised Claude Code agents in separate VS Code / tmux terminals with distinct roles (e.g., planner, implementer, tester, reviewer). Often beats complex orchestrators.
+
+### 4. Master-Clone Architecture
+Rather than custom subagents with rigid workflows, use Claude's built-in `Task(...)` to spawn general-agent clones. Put key context in CLAUDE.md and let the agent orchestrate delegation dynamically.
+
+### 5. Container Isolation
+Local Claude Code controls another instance inside a Docker container via tmux — sandboxed autonomous worker for risky/destructive operations.
+
+## Orchestration Tools
+
+| Tool | Description |
+|---|---|
+| **Claude Squad** | Terminal app managing multiple Claude Code agents in separate workspaces |
+| **Happy Coder** | Spawn and control multiple Claude Codes with push notifications |
+| **Claude Swarm** | Launch a Claude Code session connected to a swarm of other agents |
+| **Claude MPM** | 47+ specialised agents with PM orchestration and automatic task routing |
+
+## When NOT to Use Multi-Agent
+
+- Simple, single-file changes
+- Tasks that take less than a few minutes
+- When context window is not a constraint
+- When the coordination overhead exceeds the work itself
+
+The community consensus: master the single-agent workflow first. Multi-agent adds complexity and cost that only pays off for genuinely parallel, independent workstreams.
--- a/improvements/planning-and-workflow.md
+++ b/improvements/planning-and-workflow.md
@@ -0,0 +1,44 @@
+# Planning & Workflow
+
+## Why This Matters
+
+Boris from the Claude Code team: "Go back and forth with Claude until you like the plan before you let Claude execute. This easily 2-3x's results for harder tasks." The community-recommended paradigm is **PLAN -> TASK CREATION -> EXECUTE**.
+
+## Current State
+
+- CLAUDE.md mentions milestones and verification scripts (good)
+- No explicit planning workflow documented
+- Plan Mode available but not emphasised in workflow
+
+## Recommended Workflow
+
+### 1. Plan Mode (Shift+Tab twice)
+Enter Plan Mode before any non-trivial task. Iterate on the plan until you're satisfied. Plans save to `~/.claude/plans/` for historical review. This is the single highest-ROI workflow change according to the Claude Code team.
+
+### 2. Verification-Driven Development
+Give Claude explicit ways to check its own work. Boris says this alone "2-3x's output quality."
+
+- For Helm: `helm template` to validate values
+- For Kubernetes: `kustomize build`, `kubectl --dry-run`
+- For web: Playwright MCP or `curl --resolve`
+- For code: test commands, lint commands, type-checking
+- For infra: `scripts/verify-m<N>.sh` (you already do this well)
+
+### 3. Test-Driven Development Loops
+Let Claude write tests alongside code, then run them autonomously. The "write-test cycle" creates a self-healing loop:
+1. Claude writes/modifies code
+2. Runs tests
+3. If tests fail, fixes code
+4. Repeats until green
+
+This is especially powerful with commit-gate hooks that prevent commits until tests pass.
+
+### 4. The Stingraycharles Approach
+The creator of Claude Code's personal workflow:
+- "Do not allow the LLM to make any implicit decisions — confirm with the user"
+- Planning phase takes 1+ hours for complex tasks, but catches issues early
+- Structure code so AI can easily understand it ("LLM-friendly code")
+- Document invisible knowledge that's difficult to infer from code alone
+- Uses sub-agents plus reusable skills, with most skills invoking Python scripts
+
+Reference: https://github.com/solatis/claude-config/
--- a/improvements/plugins-and-language-servers.md
+++ b/improvements/plugins-and-language-servers.md
@@ -0,0 +1,34 @@
+# Plugins & Language Servers
+
+## Why This Matters
+
+The community calls Language Server integration "the single biggest productivity gain" for Claude Code. LSPs give Claude real-time type information, go-to-definition, and find-references — dramatically improving code understanding over raw text analysis.
+
+## Current State
+
+- No LSP plugins installed
+- No third-party plugins
+
+## Language Server Plugin
+
+**boostvolt/claude-code-lsps** — provides LSP integration for:
+- Python (pyright)
+- TypeScript (vtsls)
+- Rust (rust-analyzer)
+- Go (gopls)
+
+This gives Claude access to the same intelligence your IDE uses: types, definitions, references, diagnostics. Particularly valuable for large codebases and unfamiliar code.
+
+## Other Recommended Plugins
+
+| Plugin | Purpose | Value |
+|---|---|---|
+| **obra/superpowers** | 20+ structured workflow skills (TDD, debugging, root cause tracing) | "Transforms Claude from reactive helper to proactive senior developer" |
+| **commit-commands** | Intelligent commit messages generated from diffs | Consistent, meaningful commit history |
+| **pr-review-toolkit** | Multi-agent code reviews with confidence scoring | Automated quality gates on PRs |
+
+## Installation Considerations
+
+- Plugins add to context overhead — evaluate each one's token cost vs. value
+- Start with the LSP plugin alone and measure the improvement before adding more
+- `obra/superpowers` overlaps with custom skills — evaluate which skills you'd use before installing the full set
--- a/improvements/session-and-context-management.md
+++ b/improvements/session-and-context-management.md
@@ -0,0 +1,38 @@
+# Session & Context Management
+
+## Why This Matters
+
+Context is the most precious resource in a Claude Code session. The 200k token window seems large but fills fast — especially with MCP tools, long files, and multi-step tasks. Community consensus: managing context deliberately is a 2-3x productivity multiplier.
+
+## Current State
+
+- No explicit context management practices documented
+- Auto-memory system is configured (built-in)
+- No compaction hooks
+
+## Key Practices
+
+### Session Hygiene
+- **Use `/clear` between unrelated tasks.** A fresh session costs ~20k tokens (10% of budget), leaving ~180k for work. Polluted context from failed approaches actively degrades output quality.
+- **After two failed corrections, `/clear` and start fresh.** Context is now polluted with failed approaches. Write a better initial prompt instead.
+- **One task per session.** The "kitchen sink session" (start task A, ask about B, return to A) is a documented anti-pattern.
+
+### Context Budgeting
+- **Use `/context` to audit token usage.** MCP tools consume context even when unused. Browser automation tools alone can eat 8-30% of available context.
+- **Remove unused MCP servers** from settings when not actively needed.
+- **Compact proactively at 60-70% usage** — don't wait for auto-compact.
+
+### Extended Thinking
+- **Only `ultrathink` activates extended thinking** as of Claude Code v2.0.0. Previous keywords like "think" or "think hard" no longer work.
+- Use `ultrathink` for complex reasoning tasks, architectural decisions, and debugging subtle issues.
+
+### Compaction Strategy
+- Default reserves 32k tokens (22.5% of 200k) for auto-compact buffer.
+- Setting `CLAUDE_CODE_MAX_OUTPUT_TOKENS` to 64k increases the buffer to ~40%.
+- **PreCompact hook** (see hooks-and-automation.md) saves transcript before compaction.
+- Pair with auto-memory: gradual learning via memory, emergency snapshots via PreCompact hooks.
+
+### Handoff Between Sessions
+- Before ending a long session, create a handoff document: goals, progress, blockers, next steps.
+- A `/handoff` or `/catchup` skill (see skills-and-progressive-disclosure.md) automates this.
+- "Context is like milk — keep it fresh and condensed."
--- a/improvements/skills-and-progressive-disclosure.md
+++ b/improvements/skills-and-progressive-disclosure.md
@@ -0,0 +1,59 @@
+# Skills & Progressive Disclosure
+
+## Why This Matters
+
+Progressive disclosure is the single most powerful technique for managing context. Instead of putting everything in CLAUDE.md (which competes with Claude's ~50 built-in system instructions for attention), skills load domain knowledge **on demand** — only when relevant.
+
+Token savings: ~15,000 tokens per session recovered vs. loading everything upfront (82% improvement in one benchmark).
+
+## Current State
+
+- One custom skill: `reflect`
+- Skills symlinked from `~/dev/claude/custom-claude-skills/skills/` into `~/.claude/skills/`
+
+## Architecture
+
+```
+CLAUDE.md              # <200 lines, universal rules only
+.claude/skills/        # Domain knowledge loaded on demand
+.claude/rules/         # Path-scoped rules (YAML frontmatter for file pattern matching)
+```
+
+Skills use a three-stage loading: metadata (~100 tokens) -> full instructions (<5k tokens) -> bundled resources only as needed.
+
+## Suggested Skills to Build
+
+### /catchup
+Reads all changed files in your git branch when resuming work. Shows what changed since last session, reads relevant memory files, and summarises the current state.
+
+### /validate
+Codifies the "validate before deploying" principle. Runs helm template, kustomize build, linting, and type-checking as appropriate for the current project. Catches errors before they hit the cluster.
+
+### /deploy
+Standardised deploy workflow for cluster-bootstrap. Validates first, applies, then runs the appropriate verify script.
+
+### /security-audit
+Checks for secrets in code, insecure configurations, default credentials. Trail of Bits has 12+ open-source security skills that could be adapted.
+
+### /tdd
+Test-driven development workflow. Write tests first, then implement until tests pass. From `obra/superpowers` — 20+ production-proven skills.
+
+### /handoff
+Creates a structured handoff document (goals, progress, blockers, next steps) for session transitions. Useful before `/clear` or when hitting context limits.
+
+## Community Skills Worth Evaluating
+
+| Skill/Resource | Description |
+|---|---|
+| **obra/superpowers** | 20+ skills: TDD, systematic debugging, root cause tracing, brainstorming |
+| **Trail of Bits security skills** | 12+ security-focused skills for code auditing and vulnerability detection |
+| **cc-devops-skills** | IaC validation, shell script generation, DevOps workflows |
+| **Context Engineering Kit** | Advanced context engineering techniques with minimal token footprint |
+| **reddit-fetch** | Workaround for Claude's inability to fetch Reddit — uses Gemini CLI as fallback |
+
+## Best Practices
+
+- Limit to 20-30 high-quality skills. More than that degrades performance (Claude wastes tokens parsing descriptions).
+- Each skill should have one clear purpose and be self-contained.
+- Skills should be <200 lines / <5k tokens for the full instruction set.
+- Use YAML frontmatter in `.claude/rules/` for path-scoped conditional loading (e.g., rules that only apply to `*.yaml` files).