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>

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/