From d32052eff6c3386267147e3297719672a5ef72ff Mon Sep 17 00:00:00 2001
From: Florian BRUNIAUX <florian@bruniaux.com>
Date: Mon, 12 Jan 2026 13:38:02 +0100
Subject: [PATCH] feat(examples): add Learning Mode template with SuperClaude
 reference

- Create examples/modes/ folder with MODE_Learning.md ready to copy
- Add modes/README.md with installation guide and SuperClaude link
- Update examples/README.md with modes section
- Bump version to 2.9.4 across all files

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
---
 CHANGELOG.md                          |  13 +++
 README.md                             |   2 +-
 claude-code-reference.yaml            |   2 +-
 english-ultimate-claude-code-guide.md |   4 +-
 examples/README.md                    |  15 +++-
 examples/modes/MODE_Learning.md       | 121 ++++++++++++++++++++++++++
 examples/modes/README.md              |  76 ++++++++++++++++
 7 files changed, 227 insertions(+), 6 deletions(-)
 create mode 100644 examples/modes/MODE_Learning.md
 create mode 100644 examples/modes/README.md

diff --git a/CHANGELOG.md b/CHANGELOG.md
index e56a13e..b3693b2 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -6,6 +6,19 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 
 ## [Unreleased]
 
+## [2.9.4] - 2026-01-12
+
+### Added
+- **examples/modes/** - New folder for behavioral modes
+  - `MODE_Learning.md` - Complete Learning Mode ready to copy to `~/.claude/`
+  - `README.md` - Installation guide with SuperClaude framework reference
+- **examples/README.md** - Updated with modes folder and templates
+
+### Stats
+- 2 new files created (MODE_Learning.md, modes/README.md)
+- 1 file modified (examples/README.md)
+- Focus on making SuperClaude Learning Mode plug-and-play
+
 ## [2.9.3] - 2026-01-12
 
 ### Added
diff --git a/README.md b/README.md
index 79edea5..3c1bb77 100644
--- a/README.md
+++ b/README.md
@@ -329,7 +329,7 @@ If this guide saved you time, helped you master Claude Code, or inspired your wo
 
 ---
 
-*Version 2.9.3 | January 2026 | Crafted with Claude*
+*Version 2.9.4 | January 2026 | Crafted with Claude*
 
 <!-- SEO Keywords -->
 <!-- claude code, claude code tutorial, anthropic cli, ai coding assistant, claude code mcp,
diff --git a/claude-code-reference.yaml b/claude-code-reference.yaml
index 2c897c7..55e4998 100644
--- a/claude-code-reference.yaml
+++ b/claude-code-reference.yaml
@@ -3,7 +3,7 @@
 # Source: english-ultimate-claude-code-guide.md
 # Purpose: Condensed index for LLMs to quickly answer user questions about Claude Code
 
-version: "2.9.3"
+version: "2.9.4"
 updated: "2026-01"
 
 # ════════════════════════════════════════════════════════════════
diff --git a/english-ultimate-claude-code-guide.md b/english-ultimate-claude-code-guide.md
index a4fbeb1..3aab8d7 100644
--- a/english-ultimate-claude-code-guide.md
+++ b/english-ultimate-claude-code-guide.md
@@ -10,7 +10,7 @@
 
 **Last updated**: January 2026
 
-**Version**: 2.8
+**Version**: 2.9.4
 
 ---
 
@@ -9009,4 +9009,4 @@ Thumbs.db
 
 **Contributions**: Issues and PRs welcome.
 
-**Last updated**: January 2026 | **Version**: 2.8
+**Last updated**: January 2026 | **Version**: 2.9.4
diff --git a/examples/README.md b/examples/README.md
index fbf52e4..05d9781 100644
--- a/examples/README.md
+++ b/examples/README.md
@@ -15,6 +15,7 @@ Ready-to-use templates for Claude Code configuration.
 | [`scripts/`](./scripts/) | Utility scripts for setup and diagnostics |
 | [`github-actions/`](./github-actions/) | CI/CD workflows for GitHub Actions |
 | [`workflows/`](./workflows/) | Advanced development workflow guides |
+| [`modes/`](./modes/) | Behavioral modes for Claude (SuperClaude) |
 
 ## Quick Start
 
@@ -32,6 +33,7 @@ Ready-to-use templates for Claude Code configuration.
 | Hooks | `.claude/hooks/` | `~/.claude/hooks/` |
 | Config | `.claude/` | `~/.claude/` |
 | Memory | `./CLAUDE.md` or `.claude/CLAUDE.md` | `~/.claude/CLAUDE.md` |
+| Modes | — | `~/.claude/MODE_*.md` |
 
 > **Windows**: Replace `~/.claude/` with `%USERPROFILE%\.claude\`
 
@@ -89,8 +91,10 @@ Ready-to-use templates for Claude Code configuration.
 | File | Purpose | Output |
 |------|---------|--------|
 | [audit-scan.sh](./scripts/audit-scan.sh) | Fast setup audit scanner | JSON / Human |
-| [check-claude.sh](./scripts/check-claude.sh) | Health check diagnostics | Human |
-| [clean-reinstall-claude.sh](./scripts/clean-reinstall-claude.sh) | Clean reinstall procedure | Human |
+| [check-claude.sh](./scripts/check-claude.sh) | Health check diagnostics (macOS/Linux) | Human |
+| [check-claude.ps1](./scripts/check-claude.ps1) | Health check diagnostics (Windows) | Human |
+| [clean-reinstall-claude.sh](./scripts/clean-reinstall-claude.sh) | Clean reinstall procedure (macOS/Linux) | Human |
+| [clean-reinstall-claude.ps1](./scripts/clean-reinstall-claude.ps1) | Clean reinstall procedure (Windows) | Human |
 
 > **Usage**: `./audit-scan.sh` for human output, `./audit-scan.sh --json` for JSON output
 
@@ -108,6 +112,13 @@ Ready-to-use templates for Claude Code configuration.
 |------|---------|
 | [database-branch-setup.md](./workflows/database-branch-setup.md) | Isolated feature dev with database branches (Neon/PlanetScale) |
 
+### Modes
+| File | Purpose | Activation |
+|------|---------|------------|
+| [MODE_Learning.md](./modes/MODE_Learning.md) | Just-in-time explanations | `--learn` flag |
+
+> **See [modes/README.md](./modes/README.md) for installation and SuperClaude framework reference**
+
 ---
 
 *See the [main guide](../english-ultimate-claude-code-guide.md) for detailed explanations.*
diff --git a/examples/modes/MODE_Learning.md b/examples/modes/MODE_Learning.md
new file mode 100644
index 0000000..4d9cc8e
--- /dev/null
+++ b/examples/modes/MODE_Learning.md
@@ -0,0 +1,121 @@
+# Learning Mode
+
+**Purpose**: Just-in-time skill development with contextual explanations when techniques are first used
+
+## Activation Triggers
+- Manual flag: `--learn`, `--learn focus:[domain]`
+- User profile indicates learning preference (beginner/intermediate signals)
+- First occurrence of advanced technique in session
+- User explicitly asks "why?" or "how?" about an action
+- Complex tool chain where reasoning would aid future independence
+
+## Default Behavior
+**OFF by default** - Activates via triggers above or explicit `--learn` flag
+
+When active, tracks techniques explained this session to avoid repetition.
+
+## Behavioral Changes
+- **First-Occurrence Offers**: Offer explanation only on first use of technique per session
+- **Compressed Offers**: Single-line offer format, not paragraph prompts
+- **Depth on Demand**: Surface level unless user requests more
+- **Context-Driven**: Explanations tied to active problem, not abstract theory
+
+## Offer Format
+
+### Standard Mode
+```
+[action complete]
+-> Explain: [concept]? (y/detail/skip)
+```
+
+### Token Efficiency Mode Active
+```
+[action complete]
+-> ?[concept]
+```
+
+### Examples
+```
+git rebase -i HEAD~3
+-> Explain: rebase vs merge? (y/detail/skip)
+
+# User: "y"
+Rebase rewrites history linearly; merge preserves branches.
+Use rebase for clean history before push, merge for shared branches.
+
+# User: "detail"
+[Full explanation with trade-offs, edge cases, recovery commands]
+
+# User: "skip" or no response
+[Continue without explanation]
+```
+
+## Technique Tracking
+
+Track per session to avoid repetition:
+
+| Category | Examples |
+|----------|----------|
+| Git | rebase, cherry-pick, reflog, bisect |
+| Architecture | DI, SOLID patterns, composition |
+| Tools | Task agents, MCP servers, MultiEdit |
+| Performance | memoization, lazy loading, virtualization |
+| Security | sanitization, CORS, CSP headers |
+
+Once explained -> suppress further offers for same technique this session.
+
+## Depth Levels
+
+| Level | Tokens | Trigger |
+|-------|--------|---------|
+| Surface | 20-50 | Default "y" response |
+| Medium | 100-200 | "detail" or "more" |
+| Deep | 300-500 | "deep" or explicit request |
+
+## Mode Integration
+
+### With Token Efficiency Mode
+- Use compressed offer format: `-> ?[concept]`
+- Surface explanations only unless explicitly requested
+- Symbol-enhanced explanations when delivering
+
+### With Brutal Advisor Mode
+- Brutal on diagnosis: "This approach is wrong because X"
+- Pedagogical on explanation: Clear teaching without condescension
+- No softening of technical truth, but constructive in delivery
+
+### With Orchestration Mode
+- Explain tool selection matrix choices on first occurrence
+- Compress offers during parallel operations
+
+### With Task Management Mode
+- Batch explanations: offer summary at phase completion
+- Don't interrupt task flow with individual offers
+
+## User Control
+
+| Flag | Effect |
+|------|--------|
+| `--learn` | Activate learning mode for session |
+| `--learn focus:[domain]` | Only offer for specific domain (git/arch/perf/sec/tools) |
+| `--no-learn` | Suppress all learning offers |
+| `--learn batch` | Collect offers, summarize at task end |
+
+## Priority Rules
+
+```
+--no-learn > --uc > --learn
+Token Efficiency constraints > Learning verbosity
+Brutal truth > Pedagogical softening
+Task flow > Individual explanations
+```
+
+## Anti-Patterns
+
+| Wrong | Right |
+|-------|-------|
+| Offer on every command | First occurrence only |
+| Multi-sentence offer prompts | Single-line compressed offers |
+| Explain without asking | Offer -> User chooses |
+| Repeat explained techniques | Track and suppress |
+| Interrupt task flow | Batch or defer |
diff --git a/examples/modes/README.md b/examples/modes/README.md
new file mode 100644
index 0000000..f2a7091
--- /dev/null
+++ b/examples/modes/README.md
@@ -0,0 +1,76 @@
+# Behavioral Modes
+
+Ready-to-use behavioral mode files for Claude Code. Copy to `~/.claude/` and reference in your `CLAUDE.md`.
+
+## Available Modes
+
+| Mode | File | Purpose |
+|------|------|---------|
+| **Learning** | [MODE_Learning.md](./MODE_Learning.md) | Just-in-time explanations when techniques are first used |
+
+## Installation
+
+### 1. Copy the mode file
+
+```bash
+cp MODE_Learning.md ~/.claude/
+```
+
+### 2. Reference in your CLAUDE.md
+
+Add to `~/.claude/CLAUDE.md`:
+
+```markdown
+# Behavioral Modes
+@MODE_Learning.md
+```
+
+### 3. Add flags (optional)
+
+Add to `~/.claude/FLAGS.md` for flag-based activation:
+
+```markdown
+**--learn**
+- Trigger: User requests learning mode, "why/how" questions
+- Behavior: Enable just-in-time explanations with first-occurrence tracking
+
+**--no-learn**
+- Trigger: User wants pure execution without educational offers
+- Behavior: Suppress all learning mode offers
+```
+
+## Usage
+
+```bash
+# Activate for entire session
+claude --learn
+
+# Focus on specific domain
+claude --learn focus:git
+claude --learn focus:architecture
+
+# Batch explanations at task end
+claude --learn batch
+```
+
+## More Modes: SuperClaude Framework
+
+This guide includes only **Learning Mode**. For a complete behavioral framework with additional modes, check out [SuperClaude](https://github.com/SuperClaude-Org/SuperClaude_Framework):
+
+| Mode | Purpose |
+|------|---------|
+| **Orchestration** | Smart tool selection, parallel execution optimization |
+| **Task Management** | Hierarchical task tracking with persistent memory |
+| **Token Efficiency** | Symbol-enhanced compression (30-50% token reduction) |
+| **Learning** | Just-in-time skill development (included here) |
+
+SuperClaude also includes:
+- `FLAGS.md` — Behavioral flags (`--think`, `--ultrathink`, `--delegate`, etc.)
+- `PRINCIPLES.md` — Engineering principles (SOLID, DRY, evidence-based)
+- `RULES.md` — Actionable rules with priority system
+- MCP server documentation (Context7, Sequential, Serena)
+
+## See Also
+
+- [Guide Section 10.5: SuperClaude Framework](../../english-ultimate-claude-code-guide.md#105-superclaude-framework) — Full documentation
+- [SuperClaude Repository](https://github.com/SuperClaude-Org/SuperClaude_Framework) — Complete framework