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/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.