feat: add ecosystem positioning, install script & new commands

Ecosystem & Positioning: - Add README section with competitive positioning (davila7, awesome-claude-code, wesammustafa) - Add comparison table highlighting unique features (architecture, TDD/SDD, quiz, YAML index) - Add ecosystem section to reference.yaml Template Installation: - Add scripts/install-templates.sh for one-liner template installation - Support for agents, hooks, commands, skills, memory templates New Commands: - catchup, explain, optimize, refactor, security, ship New Content: - Semantic anchors catalog and documentation - Extended guide content (+470 lines) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2026-01-19 08:42:33 +01:00 · 2026-01-19 08:42:33 +01:00 · a5f441bcea
commit a5f441bcea
parent 77d6d8eeb6
16 changed files with 2333 additions and 62 deletions
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@ -6,43 +6,111 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).

 ## [Unreleased]

+## [3.9.0] - 2026-01-19
+
 ### Added

+- **6 new slash commands** (Sprint 1 + Sprint 2 implementation)
+  - `examples/commands/catchup.md` - Restore context after `/clear` (137 lines)
+    - Git history analysis (last 10 commits, recent diffs)
+    - TODO/FIXME scanning across codebase
+    - Project state summary with actionable next steps
+  - `examples/commands/security.md` - Quick OWASP security audit (149 lines)
+    - Secrets detection (API keys, tokens, passwords)
+    - Injection vulnerability scanning (SQL, XSS, command)
+    - Dependency audit integration
+    - Severity-based output (Critical/High/Medium/Low)
+  - `examples/commands/refactor.md` - SOLID-based code improvements (195 lines)
+    - SOLID violation detection with examples
+    - Risk level assessment for each suggestion
+    - Atomic commit recommendations
+  - `examples/commands/explain.md` - Code explanations with 3 depth levels (174 lines)
+    - Simple (TL;DR), Standard, Deep modes
+    - Supports files, functions, concepts, flows
+    - Example outputs at each level
+  - `examples/commands/optimize.md` - Performance analysis and roadmap (195 lines)
+    - Runtime, memory, database, bundle analysis
+    - Profiling commands per language
+    - Prioritized optimization roadmap
+  - `examples/commands/ship.md` - Pre-deploy checklist (189 lines)
+    - Blocker/High/Recommended categorization
+    - Tests, lint, build, secrets, security audit
+    - Migration and rollback verification
+
+- **Named Prompting Patterns** section in `guide/ultimate-guide.md` (Section 9.15, ~155 lines)
+  - **"As If" Pattern**: Set quality expectations ("Implement as if senior engineer at Google")
+  - **Constraint Pattern**: Force creative solutions ("Solve without new dependencies")
+  - **"Explain First" Pattern**: Force planning before implementation
+  - **"Rubber Duck" Pattern**: Collaborative debugging through questions
+  - **Incremental Pattern**: Gradual complexity building
+  - **Boundary Pattern**: Define scope and constraints explicitly
+  - Combination examples and anti-patterns
+
+- **Mermaid Diagram Generation** section in `guide/ultimate-guide.md` (Section 9.7, ~90 lines)
+  - 6 diagram types: Flowchart, Sequence, Class, ER, State, Gantt
+  - Prompt templates for each type
+  - Visualization tools reference (GitHub, mermaid.live, VS Code)
+
+- **Eight Beginner Mistakes** checklist in `guide/ultimate-guide.md` (Section 1.7, ~70 lines)
+  - Based on competitive analysis vs Jo Vinkenroye's Mastery series
+  - 8 common mistakes with symptoms and solutions
+  - Prevention patterns for each mistake
+
+- **Commands vs Skills vs Agents** enhanced comparison table (Section 5.1, ~50 lines)
+  - Detailed comparison across 8 aspects
+  - When to use each type with decision criteria
+  - Combination patterns for complex workflows
+
 - **Learning with AI guide** for junior developers (`guide/learning-with-ai.md`, ~900 lines)
  - **Quick Self-Check** (L31-81): 5 diagnostic questions to assess AI dependency
  - **Three Developer Patterns** (L82-126): Dependent, Avoidant, Augmented profiles with action paths
-  - **UVAL Protocol** (L127-352): Understand → Verify → Apply → Learn framework with Claude Code implementations
-  - **Claude Code for Learning** (L353-469): CLAUDE.md configuration, slash commands, hooks for learning mode
+  - **UVAL Protocol** (L127-352): Understand → Verify → Apply → Learn framework
+  - **Claude Code for Learning** (L353-469): CLAUDE.md configuration, slash commands, hooks
  - **Breaking Dependency** (L470-517): Recovery plan for over-reliant developers
  - **Embracing AI** (L518-709): Onboarding for AI-skeptical developers
  - **30-Day Progression Plan** (L710-769): Week-by-week AI ratio progression
  - **Red Flags Checklist** (L770-850): Warning signs and corrective actions
-  - Case study: Méthode Aristote principles (human supervision + AI assistance)

 - **Learning mode templates** (3 new files)
  - `examples/claude-md/learning-mode.md`: CLAUDE.md template for learning-focused development
-  - `examples/commands/quiz.md`: /quiz slash command for self-testing (5 difficulty levels)
+  - `examples/commands/quiz.md`: /quiz slash command for self-testing
  - `examples/hooks/bash/learning-capture.sh`: Stop event hook for daily learning capture

 - **Wireframing & Figma MCP documentation** in `guide/ultimate-guide.md` (+143 lines)
-  - **Wireframing Tools for AI Development** (L483-518): Comparison table for Excalidraw, tldraw, Frame0, Paper+Photo with MCP support indicators
-  - **Figma MCP Integration** (L520-583): Official Anthropic MCP server setup, available tools (`get_design_context`, `get_variable_defs`, `get_code_connect_map`), workflow examples
-  - **Image Optimization for Claude Vision** (L585-624): Resolution guidelines, token calculation formula, format recommendations
-  - New config template: `examples/mcp-configs/figma.json`
-  - Updated `machine-readable/reference.yaml` with new entries and shifted line numbers
+  - Wireframing tools comparison (Excalidraw, tldraw, Frame0, Paper+Photo)
+  - Figma MCP Integration with official Anthropic server
+  - Image Optimization for Claude Vision with resolution guidelines

 ### Changed

- **README.md**: Added prominent "Visit Website" badge linking to landing page
- **Templates count**: 52 → 55 in README.md badges (3 new learning templates)
- **Navigation updated**: `guide/README.md`, `examples/hooks/README.md` with new learning resources
- **Reference index expanded**: `machine-readable/reference.yaml` with 10 new deep_dive entries for learning topics
+- **README.md** updates:
+  - Lines badge: 9,800+ → 10,200+
+  - Templates badge: 56 → 62 (55 → 60+ in text)
+  - Commands table: Added 6 new commands
+  - Version: 3.8.2 → 3.9.0
+  - Added prominent "Visit Website" badge linking to landing page
+
+- **examples/README.md**: Added 6 new commands to Commands table
+
+- **scripts/install-templates.sh**: Updated commands list with new templates
+
+- **guide/ultimate-guide.md**:
+  - Table of Contents updated with sections 1.6, 1.7
+  - Section 9 Recap enhanced with Communication Patterns checklist
+  - Guide expanded by ~385 lines (9,881 → 10,266)

 - **Semantic search tools priority**: grepai now recommended over mgrep
-  - `guide/ultimate-guide.md`: Sections reordered (grepai first as "Recommended", mgrep as "Alternative")
-  - `guide/cheatsheet.md`: MCP Servers table updated (mgrep → grepai)
-  - `quiz/questions/08-mcp-servers.yaml`: Question 08-013 updated to reference grepai
-  - Rationale: grepai is fully open-source, runs locally (privacy), and offers call graph analysis
+  - Sections reordered (grepai first as "Recommended", mgrep as "Alternative")
+  - `guide/cheatsheet.md`: MCP Servers table updated
+  - Rationale: grepai is fully open-source, runs locally (privacy)
+
+### Stats
+
+- 6 new command files created (~1,039 lines total)
+- ~385 lines added to ultimate-guide.md
+- Templates count: 56 → 62
+- Focus on competitive analysis gaps vs community resources
+- Named patterns and beginner-friendly content added

 ---

--- a/README.md
+++ b/README.md
@ -6,8 +6,8 @@

 <p align="center">
  <a href="https://github.com/FlorianBruniaux/claude-code-ultimate-guide/stargazers"><img src="https://img.shields.io/github/stars/FlorianBruniaux/claude-code-ultimate-guide?style=for-the-badge" alt="Stars"/></a>
-  <a href="#"><img src="https://img.shields.io/badge/Lines-9,800+-blueviolet?style=for-the-badge" alt="Lines"/></a>
-  <a href="./examples/"><img src="https://img.shields.io/badge/Templates-56-green?style=for-the-badge" alt="Templates"/></a>
+  <a href="#"><img src="https://img.shields.io/badge/Lines-10,200+-blueviolet?style=for-the-badge" alt="Lines"/></a>
+  <a href="./examples/"><img src="https://img.shields.io/badge/Templates-62-green?style=for-the-badge" alt="Templates"/></a>
  <a href="./quiz/"><img src="https://img.shields.io/badge/Quiz-217_questions-orange?style=for-the-badge" alt="Quiz"/></a>
 </p>

@ -133,7 +133,7 @@ Claude asks 2-4 questions then guides you through personalized content based on
 - You read official docs → dense, no progression
 - You search tutorials → scattered, outdated in weeks

-**This guide:** Structured learning path with 55 copy-paste templates. Your mileage may vary—but this saves you the exploration time.
+**This guide:** Structured learning path with 60+ copy-paste templates. Your mileage may vary—but this saves you the exploration time.

 | Traditional Docs | This Guide |
 |------------------|------------|
@ -432,7 +432,7 @@ Weak Areas (< 75%):
 ```
 claude-code-ultimate-guide/
 ├── guide/                    # 📖 Core documentation
-│   ├── ultimate-guide.md     # Complete reference (~9800 lines)
+│   ├── ultimate-guide.md     # Complete reference (~10200 lines)
 │   ├── cheatsheet.md         # 1-page printable reference
 │   ├── architecture.md       # How Claude Code works internally
 │   ├── adoption-approaches.md # Team implementation strategies
@ -499,6 +499,12 @@ Copy-paste templates from [`examples/`](./examples/) for immediate use:
 | [/review-pr](./examples/commands/review-pr.md) | Review pull requests | Code quality analysis |
 | [/git-worktree](./examples/commands/git-worktree.md) | Manage git worktrees | Parallel development |
 | [/validate-changes](./examples/commands/validate-changes.md) | Validate code changes | Pre-commit checks |
+| [/catchup](./examples/commands/catchup.md) | Restore context after /clear | Git history, TODOs, project state |
+| [/security](./examples/commands/security.md) | Quick OWASP security audit | Secrets, injection, dependencies |
+| [/refactor](./examples/commands/refactor.md) | SOLID-based improvements | Violation detection, risk levels |
+| [/explain](./examples/commands/explain.md) | Code explanations (3 depths) | Files, functions, concepts |
+| [/optimize](./examples/commands/optimize.md) | Performance analysis | Runtime, memory, bundle |
+| [/ship](./examples/commands/ship.md) | Pre-deploy checklist | Tests, security, migrations |

 ### Utility Scripts

@ -649,6 +655,67 @@ Found an error? Have a suggestion? See [CONTRIBUTING.md](./CONTRIBUTING.md) for

 ---

+## 🌐 Ecosystem & Positioning
+
+### Quick Start vs Deep Understanding
+
+| I need... | Best Resource |
+|-----------|---------------|
+| Install templates NOW | → [claude-code-templates](https://github.com/davila7/claude-code-templates) (CLI, 17k⭐) |
+| Discover community tools | → [awesome-claude-code](https://github.com/hesreallyhim/awesome-claude-code) |
+| Visual walkthrough | → [Claude-Code-Everything](https://github.com/wesammustafa/Claude-Code-Everything) (screenshots, BMAD) |
+| Understand & master | → **This guide** |
+| Debug issues | → **This guide** → [Troubleshooting](./guide/ultimate-guide.md#troubleshooting) |
+
+### What Makes This Guide Different
+
+| Feature | claude-code-templates | awesome-claude-code | This Guide |
+|---------|----------------------|---------------------|------------|
+| **Focus** | Distribution | Curation | Education |
+| **Approach** | Install & use | Discover & link | Learn & master |
+| **Content** | Aggregated | Aggregated | Original |
+| **Architecture docs** | ❌ | ❌ | ✅ Unique |
+| **Methodologies (TDD/SDD)** | ❌ | ❌ | ✅ Unique |
+| **Interactive quiz** | ❌ | ❌ | ✅ 217 questions |
+| **Machine-readable index** | ❌ | ❌ | ✅ YAML with line numbers |
+
+**Recommended path**:
+1. Read this guide (2-3h) → Understand the concepts
+2. Use CLI tools for installation → Faster setup
+3. Return here for debugging/advanced patterns
+
+### Quick Template Install
+
+Install templates from this guide directly into your project:
+
+```bash
+# Base URL for convenience
+URL="https://raw.githubusercontent.com/FlorianBruniaux/claude-code-ultimate-guide/main/scripts/install-templates.sh"
+
+# List all available templates
+curl -fsSL "$URL" | bash -s -- list
+
+# Install specific templates
+curl -fsSL "$URL" | bash -s -- command pr
+curl -fsSL "$URL" | bash -s -- hook dangerous-actions-blocker
+curl -fsSL "$URL" | bash -s -- agent security-reviewer
+```
+
+<details>
+<summary><strong>All template types</strong></summary>
+
+| Type | Install | Examples |
+|------|---------|----------|
+| **agent** | `bash -s -- agent <name>` | security-reviewer, code-reviewer |
+| **hook** | `bash -s -- hook <name>` | dangerous-actions-blocker, auto-format |
+| **command** | `bash -s -- command <name>` | pr, release-notes, commit |
+| **skill** | `bash -s -- skill <name>` | TDD, pdf-generator |
+| **memory** | `bash -s -- memory <name>` | minimal, comprehensive, nextjs |
+
+</details>
+
+---
+
 ## 📄 License

 Licensed under [CC BY-SA 4.0](https://creativecommons.org/licenses/by-sa/4.0/). Free to share and adapt with attribution and same-license distribution.
@ -674,7 +741,7 @@ Get notified about major updates, new templates, and Claude Code best practices:

 ---

-*Version 3.8.2 | January 2026 | Crafted with Claude*
+*Version 3.9.0 | January 2026 | Crafted with Claude*

 <!-- SEO Keywords -->
 <!-- claude code, claude code tutorial, anthropic cli, ai coding assistant, claude code mcp,
--- a/2
+++ b/2
@ -1 +1 @@
-3.8.2
+3.9.0
--- a/examples/README.md
+++ b/examples/README.md
@ -19,6 +19,7 @@ Ready-to-use templates for Claude Code configuration.
 | [`github-actions/`](./github-actions/) | CI/CD workflows for GitHub Actions |
 | [`workflows/`](./workflows/) | Advanced development workflow guides |
 | [`modes/`](./modes/) | Behavioral modes for Claude (SuperClaude) |
+| [`semantic-anchors/`](./semantic-anchors/) | Precise vocabulary for better LLM outputs |

 ## Quick Start

@ -71,6 +72,12 @@ Ready-to-use templates for Claude Code configuration.
 | [diagnose.md](./commands/diagnose.md) | `/diagnose` | Interactive troubleshooting assistant (FR/EN) |
 | [validate-changes.md](./commands/validate-changes.md) | `/validate-changes` | LLM-as-a-Judge pre-commit validation |
 | [quiz.md](./commands/quiz.md) | `/quiz` | Self-testing for learning concepts |
+| [catchup.md](./commands/catchup.md) | `/catchup` | Restore context after /clear |
+| [security.md](./commands/security.md) | `/security` | Quick OWASP security audit |
+| [refactor.md](./commands/refactor.md) | `/refactor` | SOLID-based code improvements |
+| [explain.md](./commands/explain.md) | `/explain` | Code explanations (3 depth levels) |
+| [optimize.md](./commands/optimize.md) | `/optimize` | Performance analysis and roadmap |
+| [ship.md](./commands/ship.md) | `/ship` | Pre-deploy checklist |

 ### Hooks
 | File | Event | Purpose |
@ -147,6 +154,13 @@ Ready-to-use templates for Claude Code configuration.

 > **See [modes/README.md](./modes/README.md) for installation and SuperClaude framework reference**

+### Semantic Anchors
+| File | Purpose |
+|------|---------|
+| [anchor-catalog.md](./semantic-anchors/anchor-catalog.md) | Comprehensive catalog of precise technical terms for prompting |
+
+> **See [Section 2.7](../guide/ultimate-guide.md#27-semantic-anchors) in the guide for how to use semantic anchors**
+
 ---

 *See the [main guide](../guide/ultimate-guide.md) for detailed explanations, or the [architecture guide](../guide/architecture.md) for how Claude Code works internally.*
--- a/examples/commands/catchup.md
+++ b/examples/commands/catchup.md
@ -0,0 +1,122 @@
+# Context Catchup
+
+Restore context after `/clear` - summarize recent work and project state.
+
+## Purpose
+
+After clearing context with `/clear`, use this command to quickly rebuild understanding of:
+- What was recently modified
+- Current project state
+- Outstanding TODOs and issues
+- Where to resume work
+
+## Instructions
+
+### Step 1: Git History Analysis
+
+```bash
+# Recent commits (last 10)
+git log --oneline -10
+
+# Files modified in last 5 commits
+git diff --stat HEAD~5 2>/dev/null || git diff --stat $(git rev-list --max-parents=0 HEAD)
+
+# Current branch and status
+git branch --show-current
+git status --short
+```
+
+### Step 2: Recent Changes Summary
+
+```bash
+# What changed today
+git log --oneline --since="midnight" --author="$(git config user.name)" 2>/dev/null
+
+# Uncommitted work
+git diff --name-only
+git diff --cached --name-only
+```
+
+### Step 3: TODO/FIXME Scan
+
+```bash
+# Find outstanding work markers in recently modified files
+git diff --name-only HEAD~5 2>/dev/null | head -20 | xargs grep -n "TODO\|FIXME\|XXX\|HACK" 2>/dev/null | head -30
+```
+
+### Step 4: Project State Check
+
+```bash
+# Check for common state indicators
+[ -f "package.json" ] && echo "📦 Node project: $(jq -r '.name // "unnamed"' package.json)"
+[ -f "Cargo.toml" ] && echo "🦀 Rust project: $(grep '^name' Cargo.toml | head -1)"
+[ -f "pyproject.toml" ] && echo "🐍 Python project"
+[ -f "go.mod" ] && echo "🐹 Go project: $(head -1 go.mod | cut -d' ' -f2)"
+
+# Active branch purpose (from branch name)
+BRANCH=$(git branch --show-current)
+echo "🌿 Branch: $BRANCH"
+```
+
+## Output Format
+
+Provide a structured summary:
+
+---
+
+### 📍 Context Restored
+
+**Project**: [name from package.json/Cargo.toml/etc]
+**Branch**: [current branch]
+**Last Activity**: [time of last commit]
+
+### 🔄 Recent Work (Last 5 Commits)
+
+1. [commit message 1] - [files affected]
+2. [commit message 2] - [files affected]
+...
+
+### 📝 Uncommitted Changes
+
+- [list of modified files with brief description of changes]
+
+### ⚠️ Outstanding TODOs
+
+- [file:line] TODO: [description]
+- [file:line] FIXME: [description]
+
+### 🎯 Suggested Next Steps
+
+Based on recent activity:
+1. [Most likely next action based on patterns]
+2. [Alternative focus area]
+
+---
+
+## Usage Examples
+
+**After a long break:**
+```
+/catchup
+```
+→ Full context restoration
+
+**Quick status check:**
+```
+/catchup --brief
+```
+→ Just commits and uncommitted changes
+
+**Focus on specific area:**
+```
+/catchup auth
+```
+→ Filter to auth-related changes
+
+## Pro Tips
+
+1. **Document before `/clear`**: Write a brief note in a commit message or CLAUDE.md before clearing context
+2. **Use with Memory Bank**: Combine with `.claude/memory/` files for persistent state
+3. **Branch naming**: Use descriptive branch names (e.g., `feat/user-auth`) to aid context restoration
+
+$ARGUMENTS
--- a/examples/commands/explain.md
+++ b/examples/commands/explain.md
@ -0,0 +1,166 @@
+# Code Explainer
+
+Explain code, concepts, or system behavior with adjustable depth levels.
+
+## Purpose
+
+Get clear explanations of:
+- How specific code works
+- Why certain patterns are used
+- What a system/module does
+- Architectural decisions and trade-offs
+
+## Instructions
+
+### Step 1: Determine Scope
+
+Identify what needs explanation:
+- **File**: Entire file structure and purpose
+- **Function/Method**: Specific implementation details
+- **Concept**: Architectural pattern or design decision
+- **Flow**: How data/control moves through the system
+
+### Step 2: Assess Complexity
+
+```
+Simple (1-2 min read)     → Quick summary, key points only
+Standard (3-5 min read)   → Purpose, how it works, key decisions
+Deep (10+ min read)       → Full breakdown, alternatives, trade-offs
+```
+
+### Step 3: Gather Context
+
+```bash
+# For file explanations
+head -50 "$FILE"  # See imports and structure
+
+# For function explanations
+grep -A 30 "function $NAME\|def $NAME\|fn $NAME" "$FILE"
+
+# For module explanations
+ls -la "$DIR"
+cat "$DIR/index.ts" 2>/dev/null || cat "$DIR/__init__.py" 2>/dev/null
+```
+
+### Step 4: Structure the Explanation
+
+## Output Format
+
+---
+
+### 📖 Explanation: [Target]
+
+**Scope**: [file/function/concept/flow]
+**Depth**: [simple/standard/deep]
+
+### What It Does
+
+[1-3 sentences describing the purpose]
+
+### How It Works
+
+[Step-by-step breakdown appropriate to depth level]
+
+### Key Decisions
+
+| Decision | Why | Alternative |
+|----------|-----|-------------|
+| [choice made] | [reasoning] | [what else could work] |
+
+### Example Usage
+
+```typescript
+// How to use this correctly
+```
+
+### Related Code
+
+- `path/to/related.ts` - [relationship]
+- `path/to/dependency.ts` - [relationship]
+
+### 💡 Learning Notes (if --learn flag)
+
+[Additional context for understanding the broader pattern]
+
+---
+
+## Depth Levels
+
+### Simple (`/explain --simple`)
+
+```markdown
+**validateUser()** checks if the user object has required fields
+(email, password) and returns a boolean. Uses regex for email format.
+```
+
+### Standard (`/explain` - default)
+
+```markdown
+**validateUser(user: User): ValidationResult**
+
+**Purpose**: Validates user input before database operations.
+
+**Flow**:
+1. Check required fields exist (email, password)
+2. Validate email format with regex
+3. Check password meets requirements (8+ chars, special char)
+4. Return { valid: boolean, errors: string[] }
+
+**Used by**: signup(), updateProfile()
+```
+
+### Deep (`/explain --deep`)
+
+```markdown
+[All of standard, plus:]
+
+**Design Decisions**:
+- Returns ValidationResult instead of throwing to allow batch validation
+- Regex chosen over library for zero dependencies
+- Password rules configurable via config.ts
+
+**Trade-offs**:
+- Pro: Fast, no dependencies
+- Con: Regex email validation isn't RFC-compliant
+
+**Alternatives Considered**:
+- Zod schema: More powerful but adds 50KB
+- Class-validator: Better for decorators but OOP-heavy
+```
+
+## Usage Examples
+
+**Explain a file:**
+```
+/explain src/auth/middleware.ts
+```
+
+**Explain a function:**
+```
+/explain the handleWebhook function in payments.ts
+```
+
+**Explain a concept:**
+```
+/explain how our event sourcing works
+```
+
+**Explain with specific depth:**
+```
+/explain --deep the authentication flow
+/explain --simple what useCallback does
+```
+
+**Explain for learning:**
+```
+/explain --learn the repository pattern used here
+```
+
+## Tips
+
+1. **Be specific**: "Explain line 45-60" > "Explain this file"
+2. **State your level**: "I'm new to TypeScript" helps calibrate
+3. **Ask follow-ups**: "Why not use X instead?" deepens understanding
+4. **Request analogies**: "Explain like I'm familiar with Python but not TS"
+
+$ARGUMENTS
--- a/examples/commands/optimize.md
+++ b/examples/commands/optimize.md
@ -0,0 +1,217 @@
+# Performance Optimizer
+
+Analyze and suggest performance improvements for code, queries, or systems.
+
+## Purpose
+
+Identify optimization opportunities:
+- Runtime performance bottlenecks
+- Memory usage issues
+- Database query inefficiencies
+- Bundle size problems
+- Algorithm complexity
+
+## Instructions
+
+### Step 1: Scope Identification
+
+Determine optimization target:
+- **Function**: Single function performance
+- **Module**: Related functions/classes
+- **Query**: Database query optimization
+- **Bundle**: Frontend bundle analysis
+- **System**: Architecture-level optimization
+
+### Step 2: Performance Analysis
+
+#### Runtime Analysis
+
+```bash
+# Find potentially slow patterns
+grep -rn "forEach\|\.map\|\.filter\|\.reduce" --include="*.{ts,js}" . | head -20
+
+# Find nested loops (O(n²) potential)
+grep -rn "for.*for\|\.forEach.*\.forEach\|\.map.*\.map" --include="*.{ts,js}" . | head -10
+
+# Find sync operations that could be async
+grep -rn "readFileSync\|writeFileSync\|execSync" --include="*.{ts,js}" . | head -10
+```
+
+#### Memory Analysis
+
+```bash
+# Large array operations
+grep -rn "new Array\|Array\.from\|\.concat\|spread" --include="*.{ts,js}" . | head -10
+
+# Potential memory leaks (event listeners, intervals)
+grep -rn "addEventListener\|setInterval\|setTimeout" --include="*.{ts,js}" . | head -10
+```
+
+#### Database Query Analysis
+
+```bash
+# N+1 query patterns
+grep -rn "await.*find\|await.*query" --include="*.{ts,js}" . | head -15
+
+# Missing indexes hints
+grep -rn "WHERE\|ORDER BY\|GROUP BY" --include="*.{ts,js,sql}" . | head -15
+```
+
+#### Bundle Analysis
+
+```bash
+# Check bundle size (if applicable)
+[ -f "package.json" ] && npm run build 2>/dev/null && ls -lh dist/*.js 2>/dev/null
+
+# Large dependencies
+[ -f "package.json" ] && cat package.json | jq '.dependencies | keys[]' | head -20
+```
+
+### Step 3: Prioritization
+
+Rank findings by:
+1. **Impact**: How much will this improve performance?
+2. **Effort**: How hard is the fix?
+3. **Risk**: What could break?
+
+## Output Format
+
+---
+
+### ⚡ Performance Analysis
+
+**Target**: [file/module/system]
+**Analysis Date**: [timestamp]
+
+### 📊 Current Metrics (if measurable)
+
+| Metric | Current | Target | Gap |
+|--------|---------|--------|-----|
+| Response time | Xms | <Yms | -Z% needed |
+| Memory usage | XMB | <YMB | -Z% needed |
+| Bundle size | XKB | <YKB | -Z% needed |
+
+### 🔴 Critical Issues
+
+#### 1. [Issue Title] - [Location]
+
+**Problem**: [What's slow and why]
+
+**Current**:
+```typescript
+// O(n²) - nested loops
+users.forEach(user => {
+  permissions.forEach(perm => {
+    if (user.id === perm.userId) { ... }
+  });
+});
+```
+
+**Optimized**:
+```typescript
+// O(n) - Map lookup
+const permMap = new Map(permissions.map(p => [p.userId, p]));
+users.forEach(user => {
+  const perm = permMap.get(user.id);
+  if (perm) { ... }
+});
+```
+
+**Impact**: ~10x faster for 1000 users
+**Effort**: Low (5 min)
+**Risk**: Low
+
+### 🟠 High Priority
+
+| Issue | Location | Impact | Effort |
+|-------|----------|--------|--------|
+| [description] | file:line | [estimate] | [time] |
+
+### 🟡 Medium Priority
+
+| Issue | Location | Impact | Effort |
+|-------|----------|--------|--------|
+| [description] | file:line | [estimate] | [time] |
+
+### 💡 Quick Wins
+
+1. [Small change with good impact]
+2. [Another quick optimization]
+3. [Low-hanging fruit]
+
+### 📈 Optimization Roadmap
+
+```
+Week 1: Critical fixes (items 1-3)
+Week 2: High priority (items 4-6)
+Week 3: Measure and validate improvements
+```
+
+---
+
+## Common Patterns
+
+### Array Operations
+
+| Pattern | Issue | Fix |
+|---------|-------|-----|
+| `arr.filter().map()` | Two iterations | Single `reduce()` or `flatMap()` |
+| `arr.find()` in loop | O(n²) | Build Map/Set first |
+| `[...arr1, ...arr2]` | Memory allocation | `arr1.concat(arr2)` or push |
+
+### Database
+
+| Pattern | Issue | Fix |
+|---------|-------|-----|
+| Loop with await | N+1 queries | Batch query with `IN` |
+| `SELECT *` | Over-fetching | Select only needed columns |
+| Missing WHERE index | Full table scan | Add composite index |
+
+### React/Frontend
+
+| Pattern | Issue | Fix |
+|---------|-------|-----|
+| Inline functions in JSX | Re-renders | `useCallback` |
+| Large list rendering | DOM thrashing | Virtualization |
+| Unoptimized images | Slow LCP | Next/Image, lazy loading |
+
+### Node.js
+
+| Pattern | Issue | Fix |
+|---------|-------|-----|
+| Sync file operations | Blocks event loop | Async alternatives |
+| JSON.parse large files | Memory spike | Streaming parser |
+| No connection pooling | Connection overhead | Pool with pg-pool, etc. |
+
+## Usage
+
+**Analyze specific file:**
+```
+/optimize src/services/user.ts
+```
+
+**Focus on specific area:**
+```
+/optimize --queries src/repositories/
+/optimize --bundle
+/optimize --memory src/workers/
+```
+
+**With target metrics:**
+```
+/optimize --target=100ms src/api/search.ts
+```
+
+**Quick scan:**
+```
+/optimize --quick
+```
+
+## Notes
+
+- Measurements beat assumptions: profile before optimizing
+- Premature optimization is the root of all evil (Knuth)
+- Focus on hot paths: optimize what runs often
+- Consider trade-offs: speed vs readability vs maintainability
+
+$ARGUMENTS
--- a/examples/commands/refactor.md
+++ b/examples/commands/refactor.md
@ -0,0 +1,209 @@
+# SOLID Refactoring Assistant
+
+Analyze code for SOLID violations and suggest targeted improvements.
+
+## Purpose
+
+Identify refactoring opportunities based on:
+- SOLID principle violations
+- Code smells and anti-patterns
+- Complexity metrics
+- Duplication detection
+
+## Instructions
+
+### Step 1: Scope Analysis
+
+Determine the refactoring scope from user input:
+- Single file: Deep analysis
+- Directory: Pattern detection across files
+- Function/class: Focused extraction suggestions
+
+```bash
+# Get file/directory stats
+if [ -f "$TARGET" ]; then
+  wc -l "$TARGET"
+  echo "Single file analysis"
+elif [ -d "$TARGET" ]; then
+  find "$TARGET" -type f \( -name "*.ts" -o -name "*.js" -o -name "*.py" \) | wc -l
+  echo "Directory analysis"
+fi
+```
+
+### Step 2: SOLID Violations Detection
+
+#### S - Single Responsibility
+
+Look for:
+- Files > 300 lines
+- Functions > 50 lines
+- Classes with > 10 methods
+- Mixed concerns (data + UI + business logic)
+
+```bash
+# Find large files
+find . -name "*.{ts,js,py}" -exec wc -l {} + 2>/dev/null | sort -rn | head -10
+
+# Functions with high line count (approximate)
+grep -rn "function\|def \|fn " --include="*.{ts,js,py,rs}" . | head -20
+```
+
+#### O - Open/Closed Principle
+
+Look for:
+- Switch/case statements on types
+- Repeated if/else type checking
+- Direct modifications vs extensions
+
+#### L - Liskov Substitution
+
+Look for:
+- Overridden methods that throw "not implemented"
+- Type checks before method calls
+- Empty method overrides
+
+#### I - Interface Segregation
+
+Look for:
+- Large interfaces (> 10 methods)
+- Classes implementing unused interface methods
+- Fat service classes
+
+#### D - Dependency Inversion
+
+Look for:
+- Direct instantiation of dependencies (`new Service()`)
+- Hardcoded class references
+- Missing dependency injection
+
+### Step 3: Code Smells
+
+```bash
+# Duplication patterns
+grep -rn --include="*.{ts,js,py}" . 2>/dev/null | \
+  awk -F: '{print $3}' | sort | uniq -c | sort -rn | head -10
+
+# Long parameter lists (> 4 params)
+grep -rn "function.*,.*,.*,.*," --include="*.{ts,js}" . 2>/dev/null | head -10
+
+# Deep nesting (4+ levels)
+grep -rn "^\s\{16,\}" --include="*.{ts,js,py}" . 2>/dev/null | head -10
+```
+
+### Step 4: Complexity Assessment
+
+For each issue found, assess:
+- **Impact**: How much code is affected?
+- **Risk**: What could break?
+- **Effort**: Lines to change, tests needed?
+
+## Output Format
+
+---
+
+### 🔧 Refactoring Analysis
+
+**Target**: [file/directory]
+**Lines Analyzed**: [count]
+
+### 📊 SOLID Scorecard
+
+| Principle | Status | Issues Found |
+|-----------|--------|--------------|
+| Single Responsibility | 🟡 | 3 large classes |
+| Open/Closed | 🟢 | OK |
+| Liskov Substitution | 🟢 | OK |
+| Interface Segregation | 🔴 | 2 fat interfaces |
+| Dependency Inversion | 🟡 | 5 direct instantiations |
+
+### 🎯 Priority Refactorings
+
+#### 1. [Highest Impact] - Extract class from `UserService`
+
+**Violation**: Single Responsibility
+**Current**: 450 lines handling auth + profile + notifications
+**Suggested**:
+```
+UserService.ts (450 lines)
+    ↓ Extract
+AuthService.ts (~150 lines)
+ProfileService.ts (~150 lines)
+NotificationService.ts (~100 lines)
+```
+**Risk**: Medium (update imports)
+**Tests Needed**: Update dependency injection in tests
+
+#### 2. [Second Priority] - Replace switch with polymorphism
+
+**Location**: `src/handlers/payment.ts:45`
+**Current**:
+```typescript
+switch (paymentType) {
+  case 'card': // 50 lines
+  case 'bank': // 50 lines
+  case 'crypto': // 50 lines
+}
+```
+**Suggested**: Strategy pattern with `PaymentProcessor` interface
+**Risk**: Low (isolated change)
+
+### 📝 Code Smells
+
+| Smell | Location | Severity |
+|-------|----------|----------|
+| Long Method | `api.ts:calculateTotal` (120 lines) | 🟠 High |
+| Duplicate Code | `utils/*.ts` (3 similar blocks) | 🟡 Medium |
+| Deep Nesting | `parser.ts:parse` (6 levels) | 🟡 Medium |
+
+### 🚀 Quick Wins (Low Risk, High Value)
+
+1. Extract `validateEmail()` to shared utils (used in 4 places)
+2. Replace magic numbers with named constants
+3. Add early returns to reduce nesting in `processOrder()`
+
+### ⚠️ Technical Debt Notes
+
+- [Item to track for future sprints]
+
+---
+
+## Refactoring Safety Checklist
+
+Before applying suggestions:
+
+- [ ] Tests exist for affected code
+- [ ] Create feature branch
+- [ ] Commit current state
+- [ ] Apply one refactoring at a time
+- [ ] Run tests after each change
+- [ ] Review diff before committing
+
+## Usage
+
+**Analyze specific file:**
+```
+/refactor src/services/user.ts
+```
+
+**Analyze directory:**
+```
+/refactor src/api/
+```
+
+**Focus on specific principle:**
+```
+/refactor --focus=srp src/services/
+```
+
+**With complexity threshold:**
+```
+/refactor --threshold=high
+```
+
+## References
+
+- Martin Fowler's Refactoring Catalog
+- Clean Code by Robert C. Martin
+- SOLID principles by Robert C. Martin
+
+$ARGUMENTS
--- a/examples/commands/security.md
+++ b/examples/commands/security.md
@ -0,0 +1,160 @@
+# Security Quick Audit
+
+Rapid security assessment focused on OWASP Top 10 vulnerabilities.
+
+## Purpose
+
+Perform a quick security scan to identify common vulnerabilities:
+- Hardcoded secrets and credentials
+- SQL injection risks
+- XSS vulnerabilities
+- Insecure dependencies
+- Authentication/authorization issues
+
+## Instructions
+
+### Step 1: Secrets Scan
+
+```bash
+# Common secret patterns
+grep -rn --include="*.{js,ts,py,go,java,rb,php,env}" \
+  -E "(password|secret|api_key|apikey|token|auth|credential).*[=:].*['\"][^'\"]{8,}['\"]" \
+  --exclude-dir={node_modules,vendor,.git,dist,build} . 2>/dev/null | head -20
+
+# .env files that might be committed
+find . -name ".env*" -not -path "*/node_modules/*" -type f 2>/dev/null
+
+# Check if secrets are gitignored
+[ -f ".gitignore" ] && grep -q "\.env" .gitignore && echo "✅ .env in .gitignore" || echo "⚠️ .env NOT in .gitignore"
+```
+
+### Step 2: Injection Vulnerabilities
+
+```bash
+# SQL injection patterns (raw queries with string concat)
+grep -rn --include="*.{js,ts,py,go,java,php}" \
+  -E "(query|execute|raw|sql).*\+.*\$|f['\"].*SELECT|\.format\(.*SELECT" \
+  --exclude-dir={node_modules,vendor,.git} . 2>/dev/null | head -15
+
+# Command injection patterns
+grep -rn --include="*.{js,ts,py,go,rb,php}" \
+  -E "(exec|spawn|system|shell_exec|popen)\s*\(" \
+  --exclude-dir={node_modules,vendor,.git} . 2>/dev/null | head -15
+```
+
+### Step 3: XSS Patterns
+
+```bash
+# Dangerous innerHTML/dangerouslySetInnerHTML usage
+grep -rn --include="*.{js,ts,jsx,tsx,vue}" \
+  -E "(innerHTML|dangerouslySetInnerHTML|v-html)" \
+  --exclude-dir={node_modules,.git,dist} . 2>/dev/null | head -15
+
+# Unescaped template literals in HTML context
+grep -rn --include="*.{js,ts,jsx,tsx}" \
+  -E "\`.*\$\{.*\}.*<" \
+  --exclude-dir={node_modules,.git,dist} . 2>/dev/null | head -10
+```
+
+### Step 4: Dependency Check
+
+```bash
+# Check for known vulnerabilities in npm packages
+[ -f "package-lock.json" ] && npm audit --json 2>/dev/null | jq '{vulnerabilities: .metadata.vulnerabilities}' 2>/dev/null
+
+# Check for outdated packages with security issues
+[ -f "package.json" ] && npm outdated --json 2>/dev/null | jq 'to_entries | map(select(.value.current != .value.latest)) | length' 2>/dev/null
+```
+
+### Step 5: Auth & Session Issues
+
+```bash
+# Hardcoded JWT secrets
+grep -rn --include="*.{js,ts,py,go}" \
+  -E "(jwt|JWT).*secret.*[=:].*['\"].{8,}['\"]" \
+  --exclude-dir={node_modules,vendor,.git} . 2>/dev/null
+
+# Missing CSRF protection patterns
+grep -rn --include="*.{js,ts,py}" \
+  -E "(POST|PUT|DELETE|PATCH).*fetch|axios\.(post|put|delete|patch)" \
+  --exclude-dir={node_modules,vendor,.git} . 2>/dev/null | head -10
+```
+
+## Output Format
+
+---
+
+### 🛡️ Security Audit Report
+
+**Scan Date**: [timestamp]
+**Scope**: [directory scanned]
+
+### 🔴 Critical Issues
+
+| Issue | Location | Description |
+|-------|----------|-------------|
+| [type] | [file:line] | [brief description] |
+
+### 🟠 High Severity
+
+| Issue | Location | Recommendation |
+|-------|----------|----------------|
+| [type] | [file:line] | [fix suggestion] |
+
+### 🟡 Medium Severity
+
+| Issue | Location | Note |
+|-------|----------|------|
+| [type] | [file:line] | [context] |
+
+### 📊 Summary
+
+- **Critical**: X issues
+- **High**: X issues
+- **Medium**: X issues
+- **Dependencies**: X vulnerabilities
+
+### 🔧 Quick Fixes
+
+1. [Highest priority fix with command/code]
+2. [Second priority]
+3. [Third priority]
+
+---
+
+## Severity Levels
+
+| Level | Examples | Action |
+|-------|----------|--------|
+| 🔴 Critical | Hardcoded prod secrets, SQL injection | Fix immediately |
+| 🟠 High | Missing auth, XSS vectors | Fix before deploy |
+| 🟡 Medium | Outdated deps, missing CSRF | Plan remediation |
+| 🟢 Low | Best practice violations | Track for improvement |
+
+## Usage
+
+**Full audit:**
+```
+/security
+```
+
+**Focus on specific area:**
+```
+/security auth
+/security deps
+/security injection
+```
+
+**Specific file/directory:**
+```
+/security src/api/
+```
+
+## Notes
+
+- This is a quick heuristic scan, not a comprehensive security audit
+- For production systems, complement with dedicated tools (Snyk, SonarQube, OWASP ZAP)
+- False positives are possible - verify findings manually
+- See `examples/hooks/security-hooks.sh` for automated pre-commit security checks
+
+$ARGUMENTS
--- a/examples/commands/ship.md
+++ b/examples/commands/ship.md
@ -0,0 +1,232 @@
+# Ship Command - Pre-Deploy Checklist
+
+Comprehensive pre-deployment verification to ensure release readiness.
+
+## Purpose
+
+Run before every production deployment to verify:
+- Code quality gates
+- Test coverage
+- Security checks
+- Documentation updates
+- Environment readiness
+
+## Pre-Deploy Checklist
+
+### 🔴 Blockers (Must Pass)
+
+```bash
+# 1. All tests passing
+npm test 2>/dev/null || pnpm test 2>/dev/null || yarn test 2>/dev/null
+echo "Exit code: $?"
+
+# 2. No TypeScript/lint errors
+npm run typecheck 2>/dev/null || npx tsc --noEmit
+npm run lint 2>/dev/null || npx eslint .
+
+# 3. Build succeeds
+npm run build 2>/dev/null || pnpm build 2>/dev/null
+
+# 4. No secrets in code
+grep -rn "API_KEY=\|SECRET=\|PASSWORD=" --include="*.{ts,js,json}" . 2>/dev/null | grep -v node_modules | grep -v ".env.example"
+```
+
+### 🟠 High Priority (Should Pass)
+
+```bash
+# 5. Security audit
+npm audit --audit-level=high 2>/dev/null || echo "Run manually: npm audit"
+
+# 6. No console.log in production code
+grep -rn "console\.log\|console\.debug" --include="*.{ts,js,tsx,jsx}" src/ 2>/dev/null | grep -v "// allowed" | head -10
+
+# 7. No TODO/FIXME in critical paths
+grep -rn "TODO\|FIXME\|XXX\|HACK" --include="*.{ts,js}" src/ 2>/dev/null | head -10
+
+# 8. Database migrations ready
+[ -d "prisma/migrations" ] && echo "Prisma migrations: $(ls prisma/migrations | wc -l) total"
+[ -d "migrations" ] && echo "Migrations: $(ls migrations | wc -l) total"
+```
+
+### 🟡 Recommended (Nice to Have)
+
+```bash
+# 9. Documentation updated
+git diff --name-only HEAD~5 | grep -E "README|CHANGELOG|docs/" | head -10
+
+# 10. Version bumped
+cat package.json | jq -r '.version' 2>/dev/null || echo "Check version manually"
+
+# 11. Environment variables documented
+[ -f ".env.example" ] && echo "✅ .env.example exists" || echo "⚠️ Missing .env.example"
+```
+
+## Output Format
+
+---
+
+### 🚀 Ship Readiness Report
+
+**Branch**: [current branch]
+**Commit**: [HEAD short hash]
+**Target**: [production/staging]
+**Timestamp**: [date/time]
+
+### Blockers (Must Fix Before Deploy)
+
+| Check | Status | Details |
+|-------|--------|---------|
+| Tests | ✅/❌ | X passed, Y failed |
+| TypeScript | ✅/❌ | X errors |
+| Lint | ✅/❌ | X warnings, Y errors |
+| Build | ✅/❌ | Success/Failed |
+| Secrets | ✅/❌ | X potential leaks |
+
+### High Priority
+
+| Check | Status | Action |
+|-------|--------|--------|
+| Security Audit | ⚠️/✅ | X vulnerabilities |
+| Console Logs | ⚠️/✅ | X found in src/ |
+| TODOs | ⚠️/✅ | X critical TODOs |
+| Migrations | ⚠️/✅ | X pending |
+
+### Recommended
+
+| Check | Status | Note |
+|-------|--------|------|
+| Docs Updated | ⚠️/✅ | CHANGELOG updated |
+| Version Bumped | ⚠️/✅ | Current: X.Y.Z |
+| Env Documented | ⚠️/✅ | .env.example present |
+
+### 📊 Summary
+
+```
+🔴 Blockers:    X/5 passed
+🟠 High:        X/4 passed
+🟡 Recommended: X/3 passed
+─────────────────────────
+Overall:        [READY TO SHIP / NOT READY]
+```
+
+### 🎯 Action Items
+
+1. [Most critical fix needed]
+2. [Second priority]
+3. [Third priority]
+
+---
+
+## Environment-Specific Checks
+
+### Production Deploy
+
+```bash
+# Verify production env vars
+[ -f ".env.production" ] && echo "Production env exists"
+
+# Check for debug flags
+grep -rn "DEBUG=true\|NODE_ENV=development" .env* 2>/dev/null
+
+# Verify API endpoints point to production
+grep -rn "localhost\|127\.0\.0\.1" --include="*.{ts,js,json}" src/ 2>/dev/null | grep -v test | head -5
+```
+
+### Staging Deploy
+
+```bash
+# Staging-specific checks
+[ -f ".env.staging" ] && echo "Staging env exists"
+
+# Feature flags for staging
+grep -rn "FEATURE_FLAG\|ENABLE_" .env* 2>/dev/null
+```
+
+## CI/CD Integration
+
+Add to your pipeline:
+
+```yaml
+# GitHub Actions example
+ship-check:
+  runs-on: ubuntu-latest
+  steps:
+    - uses: actions/checkout@v4
+    - name: Run ship checklist
+      run: |
+        npm ci
+        npm test
+        npm run typecheck
+        npm run lint
+        npm run build
+        npm audit --audit-level=high
+```
+
+## Post-Deploy Verification
+
+After deployment, verify:
+
+```bash
+# 1. Health check
+curl -s https://your-app.com/health | jq .
+
+# 2. Version check
+curl -s https://your-app.com/version | jq .
+
+# 3. Smoke tests
+npm run test:smoke 2>/dev/null || echo "Run smoke tests manually"
+```
+
+## Rollback Preparation
+
+Before shipping, ensure you can rollback:
+
+```bash
+# Note current production tag
+git describe --tags --abbrev=0
+
+# Verify rollback procedure exists
+[ -f "docs/runbooks/rollback.md" ] && echo "✅ Rollback docs exist"
+
+# Check database migration reversibility
+# Prisma: prisma migrate diff
+# Rails: rails db:rollback (dry-run)
+```
+
+## Usage
+
+**Full checklist:**
+```
+/ship
+```
+
+**Production deploy:**
+```
+/ship --production
+```
+
+**Quick check (blockers only):**
+```
+/ship --quick
+```
+
+**With specific target:**
+```
+/ship --target=staging
+```
+
+## Tips
+
+1. **Run early, run often**: Don't wait until deploy day
+2. **Automate in CI**: Make blockers fail the pipeline
+3. **Team agreement**: Define what's a blocker vs warning
+4. **Document exceptions**: If skipping a check, note why
+5. **Monitor after deploy**: Ship is not done until monitoring confirms success
+
+## Related Commands
+
+- `/release-notes` - Generate changelog and announcements
+- `/validate-changes` - LLM-based code review
+- `/security` - Deep security audit
+
+$ARGUMENTS
--- a/examples/semantic-anchors/anchor-catalog.md
+++ b/examples/semantic-anchors/anchor-catalog.md
@ -0,0 +1,310 @@
+# Semantic Anchors Catalog
+
+> **Concept**: Alexandre Soyer
+> **Source**: [github.com/LLM-Coding/Semantic-Anchors](https://github.com/LLM-Coding/Semantic-Anchors) (Apache-2.0)
+> **Adapted for**: Claude Code workflows
+
+## What Are Semantic Anchors?
+
+LLMs are statistical pattern matchers. When you use **precise technical vocabulary**, you help Claude access the right patterns from its training data. Generic terms produce generic code; specific terms produce specific, well-structured code.
+
+**Analogy**: Technical terms are GPS coordinates into Claude's knowledge base.
+
+---
+
+## Testing & Quality Assurance
+
+### Test Methodologies
+
+| Vague | Semantic Anchor | What It Activates |
+|-------|-----------------|-------------------|
+| "write tests" | "TDD London School (mockist)" | Outside-in, mock collaborators, focus on behavior |
+| "write tests" | "TDD Chicago School (classicist)" | Bottom-up, real collaborators, state verification |
+| "test edge cases" | "Property-Based Testing (QuickCheck)" | Generative testing, shrinking, invariant discovery |
+| "thorough testing" | "Mutation Testing (Stryker/PIT)" | Kill mutants, measure test effectiveness |
+| "behavior tests" | "BDD Gherkin syntax (Given/When/Then)" | Cucumber-style, living documentation |
+
+### Test Quality
+
+| Vague | Semantic Anchor | Effect |
+|-------|-----------------|--------|
+| "good test names" | "Roy Osherove naming: MethodName_Scenario_ExpectedBehavior" | Consistent, descriptive names |
+| "isolated tests" | "Test Pyramid (Fowler): 70% unit, 20% integration, 10% E2E" | Proper test distribution |
+| "fast tests" | "Sociable unit tests with test doubles at boundaries" | Speed with realistic behavior |
+| "readable tests" | "Arrange-Act-Assert (AAA) pattern" | Clear test structure |
+| "maintainable tests" | "Object Mother / Test Data Builder pattern" | Reusable test fixtures |
+
+---
+
+## Architecture & Design
+
+### Architectural Patterns
+
+| Vague | Semantic Anchor | When to Use |
+|-------|-----------------|-------------|
+| "clean architecture" | "Hexagonal Architecture (Ports & Adapters)" | Domain isolation, testability |
+| "layered architecture" | "Onion Architecture (Palermo)" | Dependency toward center |
+| "microservices" | "Domain-Driven Design bounded contexts" | Service boundaries |
+| "event-driven" | "CQRS with Event Sourcing" | Read/write separation, audit trail |
+| "scalable" | "Event-Driven Architecture with message broker" | Async processing, decoupling |
+
+### Domain-Driven Design (Evans)
+
+| Vague | Semantic Anchor | Purpose |
+|-------|-----------------|---------|
+| "business logic" | "DDD Aggregate pattern" | Transactional consistency |
+| "data access" | "DDD Repository pattern" | Persistence abstraction |
+| "object mapping" | "DDD Value Objects" | Immutable, equality by value |
+| "complex objects" | "DDD Entity pattern" | Identity-based equality |
+| "business rules" | "DDD Domain Services" | Stateless operations |
+| "integration" | "DDD Anti-Corruption Layer (ACL)" | External system isolation |
+
+### SOLID Principles
+
+| Vague | Semantic Anchor | Specific Guidance |
+|-------|-----------------|-------------------|
+| "single purpose" | "SRP: one reason to change (Robert C. Martin)" | Cohesion focus |
+| "extensible" | "OCP: open for extension, closed for modification" | Plugin architecture |
+| "substitutable" | "LSP: subtypes must be substitutable" | Contract preservation |
+| "minimal interfaces" | "ISP: clients shouldn't depend on unused methods" | Interface segregation |
+| "decoupled" | "DIP: depend on abstractions, not concretions" | Inversion of control |
+
+---
+
+## Code Quality & Refactoring
+
+### Refactoring Catalog (Fowler)
+
+| Vague | Semantic Anchor | Trigger |
+|-------|-----------------|---------|
+| "extract logic" | "Extract Method refactoring" | Long methods |
+| "remove conditionals" | "Replace Conditional with Polymorphism" | Complex if/switch |
+| "simplify creation" | "Replace Constructor with Factory Method" | Complex instantiation |
+| "remove duplication" | "Extract Class / Extract Superclass" | Similar classes |
+| "improve naming" | "Rename Method/Variable (intention-revealing names)" | Unclear names |
+
+### Code Smells (Fowler/Beck)
+
+| Smell | Semantic Anchor | Solution |
+|-------|-----------------|----------|
+| "long method" | "Extract Method until comments become unnecessary" | Methods < 10 lines |
+| "large class" | "Extract Class following SRP" | Single responsibility |
+| "feature envy" | "Move Method to class that owns data" | Better cohesion |
+| "primitive obsession" | "Replace Primitive with Value Object" | Type safety |
+| "shotgun surgery" | "Move Field/Method to consolidate changes" | Centralize logic |
+
+### Clean Code (Martin)
+
+| Vague | Semantic Anchor | Application |
+|-------|-----------------|-------------|
+| "readable" | "Screaming Architecture: package structure reveals intent" | Folder naming |
+| "clear names" | "Intention-revealing names (Clean Code Ch. 2)" | Self-documenting |
+| "no comments" | "Code should be self-explanatory (comments lie)" | Refactor instead |
+| "small functions" | "Functions should do one thing (max 20 lines)" | Single responsibility |
+| "no side effects" | "Command-Query Separation (CQS)" | Predictable behavior |
+
+---
+
+## Error Handling
+
+### Functional Patterns
+
+| Vague | Semantic Anchor | Benefits |
+|-------|-----------------|----------|
+| "error handling" | "Railway Oriented Programming with Either<L,R>" | Composable errors |
+| "null safety" | "Option/Maybe monad (never return null)" | Explicit absence |
+| "error accumulation" | "Validation applicative functor" | Collect all errors |
+| "async errors" | "Task/Future monad with error channel" | Async error flow |
+
+### Exception Strategies
+
+| Vague | Semantic Anchor | Use Case |
+|-------|-----------------|----------|
+| "handle errors" | "Checked exceptions at boundaries only" | External integration |
+| "error recovery" | "Circuit Breaker pattern (Nygard)" | Fault tolerance |
+| "graceful degradation" | "Bulkhead pattern" | Isolation |
+| "retry logic" | "Exponential backoff with jitter" | Resilience |
+
+---
+
+## API Design
+
+### REST Maturity
+
+| Vague | Semantic Anchor | Level |
+|-------|-----------------|-------|
+| "REST API" | "REST Level 0: HTTP as tunnel" | Basic |
+| "proper REST" | "REST Level 2: HTTP verbs + status codes" | Standard |
+| "HATEOAS" | "REST Level 3: Hypermedia controls" | Full REST |
+| "API versioning" | "URL path versioning (/v1/) or header versioning" | Evolution |
+
+### API Quality
+
+| Vague | Semantic Anchor | Application |
+|-------|-----------------|-------------|
+| "consistent API" | "JSON:API specification" | Response format |
+| "documented API" | "OpenAPI 3.0 (Swagger)" | Spec-first design |
+| "secure API" | "OAuth 2.0 + PKCE flow" | Authentication |
+| "rate limiting" | "Token bucket algorithm" | Traffic control |
+
+---
+
+## Documentation
+
+### Architecture Documentation
+
+| Vague | Semantic Anchor | Output |
+|-------|-----------------|--------|
+| "document architecture" | "C4 Model (Context, Container, Component, Code)" | Diagrams |
+| "architecture docs" | "arc42 template structure" | Comprehensive docs |
+| "design decisions" | "ADR (Architecture Decision Records) - Nygard format" | Decision log |
+| "system overview" | "4+1 View Model (Kruchten)" | Multiple perspectives |
+
+### Code Documentation
+
+| Vague | Semantic Anchor | Format |
+|-------|-----------------|--------|
+| "API docs" | "JSDoc / TSDoc with @example tags" | Generated docs |
+| "README" | "README-driven development (Tom Preston-Werner)" | Project intro |
+| "changelog" | "Keep a Changelog format (semver)" | Release notes |
+| "contributing" | "CONTRIBUTING.md with PR template" | Contributor guide |
+
+---
+
+## Requirements & Specifications
+
+### Requirements Syntax
+
+| Vague | Semantic Anchor | Format |
+|-------|-----------------|--------|
+| "requirements" | "EARS syntax (Easy Approach to Requirements)" | Structured requirements |
+| "user stories" | "Connextra format: As a [role] I want [goal] so that [benefit]" | User perspective |
+| "acceptance criteria" | "BDD Gherkin: Given/When/Then" | Testable criteria |
+| "use cases" | "Cockburn's use case template (brief/casual/fully dressed)" | Interaction flows |
+
+### Discovery & Mapping
+
+| Vague | Semantic Anchor | Technique |
+|-------|-----------------|-----------|
+| "understand users" | "User Story Mapping (Jeff Patton)" | Journey visualization |
+| "prioritize features" | "MoSCoW method (Must/Should/Could/Won't)" | Priority triage |
+| "user needs" | "Jobs-to-be-Done framework (Christensen)" | Outcome focus |
+| "event modeling" | "Event Storming (Brandolini)" | Domain discovery |
+
+---
+
+## Security
+
+### OWASP & Common Vulnerabilities
+
+| Vague | Semantic Anchor | Protection |
+|-------|-----------------|------------|
+| "secure code" | "OWASP Top 10 mitigations" | Comprehensive checklist |
+| "input validation" | "Allowlist validation + parameterized queries" | Injection prevention |
+| "authentication" | "OWASP ASVS Level 2 requirements" | Auth standards |
+| "secrets management" | "HashiCorp Vault or cloud KMS" | Secret storage |
+
+### Security Patterns
+
+| Vague | Semantic Anchor | Implementation |
+|-------|-----------------|----------------|
+| "secure by default" | "Principle of least privilege" | Minimal permissions |
+| "defense in depth" | "Multiple security layers (network, app, data)" | Layered security |
+| "secure communication" | "TLS 1.3 with certificate pinning" | Transport security |
+| "audit logging" | "Immutable audit trail with tamper detection" | Compliance |
+
+---
+
+## Performance
+
+### Optimization Patterns
+
+| Vague | Semantic Anchor | Application |
+|-------|-----------------|-------------|
+| "caching" | "Cache-aside pattern with TTL" | Read performance |
+| "batch processing" | "Bulk operations with chunking" | Write performance |
+| "lazy loading" | "Virtual proxy pattern" | Resource optimization |
+| "memoization" | "Function memoization with LRU eviction" | Computation caching |
+
+### Scalability
+
+| Vague | Semantic Anchor | Technique |
+|-------|-----------------|-----------|
+| "horizontal scaling" | "Stateless services + external state store" | Scale-out |
+| "database scaling" | "Read replicas + write-through caching" | DB performance |
+| "async processing" | "Message queue with competing consumers" | Throughput |
+| "load balancing" | "Round-robin with health checks" | Distribution |
+
+---
+
+## CLAUDE.md Template with Semantic Anchors
+
+```markdown
+# Project Architecture
+
+## Principles (Semantic Anchors)
+
+### Architecture
+- **Pattern**: Hexagonal Architecture (Ports & Adapters)
+- **Domain modeling**: Domain-Driven Design tactical patterns (Aggregates, Value Objects, Domain Events)
+- **Documentation**: ADR (Architecture Decision Records) for significant decisions
+
+### Code Quality
+- **Design**: SOLID principles, especially SRP and DIP
+- **Refactoring**: Apply Fowler's catalog - Extract Method, Replace Conditional with Polymorphism
+- **Naming**: Intention-revealing names, Screaming Architecture for packages
+
+### Testing
+- **Methodology**: TDD London School - outside-in, mock collaborators
+- **Structure**: Arrange-Act-Assert (AAA) pattern
+- **Coverage**: Test Pyramid - 70% unit, 20% integration, 10% E2E
+
+### Error Handling
+- **Pattern**: Railway Oriented Programming with Result<T, E>
+- **Never**: Return null, throw for control flow
+- **Always**: Use Option/Maybe for optional values
+
+### API Design
+- **Style**: REST Level 2 with proper HTTP verbs and status codes
+- **Documentation**: OpenAPI 3.0 spec-first
+- **Security**: OAuth 2.0 + PKCE for authentication
+
+### Requirements
+- **Format**: EARS syntax for formal requirements
+- **User stories**: Connextra format with acceptance criteria
+- **Discovery**: Event Storming for domain exploration
+```
+
+---
+
+## Quick Reference
+
+### Before/After Examples
+
+| Before (Vague) | After (Anchored) |
+|----------------|------------------|
+| "Make it clean" | "Apply SRP: each class has one reason to change" |
+| "Add error handling" | "Use Railway Oriented Programming with Either monad" |
+| "Write good tests" | "Follow TDD London School with mock collaborators" |
+| "Document the API" | "Generate OpenAPI 3.0 spec from annotations" |
+| "Make it secure" | "Mitigate OWASP Top 10, specifically A03:Injection" |
+| "Refactor this" | "Apply Extract Method until comments are unnecessary" |
+| "Scale this service" | "Implement CQRS with Event Sourcing for read/write separation" |
+
+---
+
+## Usage Tips
+
+1. **Combine anchors**: "Apply Hexagonal Architecture with DDD tactical patterns and Railway Oriented error handling"
+
+2. **Specify versions/authors**: "Following Kent Beck's TDD (2003)" is more specific than "TDD"
+
+3. **Reference books**: "Clean Code Chapter 2 naming conventions" activates specific knowledge
+
+4. **Name patterns explicitly**: "Strategy pattern" > "pluggable behavior"
+
+5. **Use with XML tags**: Combine anchors with `<constraints>` and `<quality_criteria>` tags for maximum effect
+
+---
+
+> **Remember**: The goal is precision, not jargon. Use anchors that Claude has seen extensively in its training data. When in doubt, reference the authoritative source (book, paper, framework).
--- a/guide/ultimate-guide.md
+++ b/guide/ultimate-guide.md
@ -106,6 +106,8 @@ Context full → /compact or /clear
  - [1.3 Essential Commands](#13-essential-commands)
  - [1.4 Permission Modes](#14-permission-modes)
  - [1.5 Productivity Checklist](#15-productivity-checklist)
+  - [1.6 Migrating from Other AI Coding Tools](#16-migrating-from-other-ai-coding-tools)
+  - [1.7 Eight Beginner Mistakes](#17-eight-beginner-mistakes-and-how-to-avoid-them)
 - [2. Core Concepts](#2-core-concepts)
  - [2.1 The Interaction Loop](#21-the-interaction-loop)
  - [2.2 Context Management](#22-context-management)
@ -174,7 +176,7 @@ Context full → /compact or /clear

 # 1. Quick Start (Day 1)

-_Quick jump:_ [Installation](#11-installation) · [First Workflow](#12-first-workflow) · [Essential Commands](#13-essential-commands) · [Permission Modes](#14-permission-modes) · [Productivity Checklist](#15-productivity-checklist) · [Migrating from Other Tools](#16-migrating-from-other-ai-coding-tools)
+_Quick jump:_ [Installation](#11-installation) · [First Workflow](#12-first-workflow) · [Essential Commands](#13-essential-commands) · [Permission Modes](#14-permission-modes) · [Productivity Checklist](#15-productivity-checklist) · [Migrating from Other Tools](#16-migrating-from-other-ai-coding-tools) · [Beginner Mistakes](#17-eight-beginner-mistakes-and-how-to-avoid-them)

 ---

@ -1027,6 +1029,76 @@ Keep Copilot/Cursor for:
 - Catching more issues through Claude reviews
 - Better understanding of unfamiliar code

+## 1.7 Eight Beginner Mistakes (and How to Avoid Them)
+
+Common pitfalls that slow down new Claude Code users:
+
+### 1. ❌ Skipping the Plan
+
+**Mistake**: Jumping straight into "fix this bug" without explaining context.
+
+**Fix**: Use the WHAT/WHERE/HOW/VERIFY format:
+```
+WHAT: Fix login timeout error
+WHERE: src/auth/session.ts
+HOW: Increase token expiry from 1h to 24h
+VERIFY: Login persists after browser refresh
+```
+
+### 2. ❌ Ignoring Context Limits
+
+**Mistake**: Working until context hits 95% and responses degrade.
+
+**Fix**: Watch `Ctx(u):` in the status line. `/compact` at 70%, `/clear` at 90%.
+
+### 3. ❌ Using Vague Prompts
+
+**Mistake**: "Make this code better" or "Check for bugs"
+
+**Fix**: Be specific: "Refactor `calculateTotal()` to handle null prices without throwing"
+
+### 4. ❌ Accepting Changes Blindly
+
+**Mistake**: Hitting "y" without reading the diff.
+
+**Fix**: Always review diffs. Use "n" to reject, then explain what's wrong.
+
+### 5. ❌ No Version Control Safety
+
+**Mistake**: Making large changes without commits.
+
+**Fix**: Commit before big changes. Use feature branches. Claude can help: `/commit`
+
+### 6. ❌ Overly Broad Permissions
+
+**Mistake**: Setting `Bash(*)` or `--dangerously-skip-permissions`
+
+**Fix**: Start restrictive, expand as needed. Use allowlists: `Bash(npm test)`, `Bash(git *)`
+
+### 7. ❌ Mixing Unrelated Tasks
+
+**Mistake**: "Fix the auth bug AND refactor the database AND add new tests"
+
+**Fix**: One focused task per session. `/clear` between different tasks.
+
+### 8. ❌ Not Using CLAUDE.md
+
+**Mistake**: Repeating project context in every prompt.
+
+**Fix**: Create `CLAUDE.md` with your tech stack, conventions, and patterns. Claude reads it automatically.
+
+### Quick Self-Check
+
+Before your next session, verify:
+
+- [ ] I have a clear, specific goal
+- [ ] My project has a CLAUDE.md file
+- [ ] I'm on a feature branch (not main)
+- [ ] I know my context level (`/status`)
+- [ ] I'll review every diff before accepting
+
+> **Tip**: Bookmark Section 9.11 for detailed pitfall explanations and solutions.
+
 ---

 # 2. Core Concepts
@ -2589,7 +2661,100 @@ cat claudedocs/templates/code-review.xml | \

 > **Source**: [DeepTo Claude Code Guide - XML-Structured Prompts](https://cc.deeptoai.com/docs/en/best-practices/claude-code-comprehensive-guide)

-## 2.6 Data Flow & Privacy
+## 2.7 Semantic Anchors
+
+LLMs are statistical pattern matchers trained on massive text corpora. Using **precise technical vocabulary** helps Claude activate the right patterns in its training data, leading to higher-quality outputs.
+
+### Why Precision Matters
+
+When you say "clean code", Claude might generate any of dozens of interpretations. But when you say "SOLID principles with dependency injection following Clean Architecture layers", you anchor Claude to a specific, well-documented pattern from its training.
+
+**Key insight**: Technical terms act as GPS coordinates into Claude's knowledge. The more precise, the better the navigation.
+
+### Common Anchors for Claude Code
+
+| Vague Term | Semantic Anchor | Why It Helps |
+|------------|-----------------|--------------|
+| "error handling" | "Railway Oriented Programming with Either/Result monad" | Activates functional error patterns |
+| "clean code" | "SOLID principles, especially SRP and DIP" | Targets specific design principles |
+| "good tests" | "TDD London School with outside-in approach" | Specifies test methodology |
+| "good architecture" | "Hexagonal Architecture (Ports & Adapters)" | Names a concrete pattern |
+| "readable code" | "Screaming Architecture with intention-revealing names" | Triggers specific naming conventions |
+| "scalable design" | "CQRS with Event Sourcing" | Activates distributed patterns |
+| "documentation" | "arc42 template structure" | Specifies documentation framework |
+| "requirements" | "EARS syntax for requirements (Easy Approach to Requirements)" | Targets requirement format |
+| "API design" | "REST Level 3 with HATEOAS" | Specifies maturity level |
+| "security" | "OWASP Top 10 mitigations" | Activates security knowledge |
+
+### How to Use in CLAUDE.md
+
+Add semantic anchors to your project instructions:
+
+```markdown
+# Architecture Principles
+
+Follow these patterns:
+- **Architecture**: Hexagonal Architecture (Ports & Adapters) with clear domain boundaries
+- **Error handling**: Railway Oriented Programming - never throw, return Result<T, E>
+- **Testing**: TDD London School - mock collaborators, test behaviors not implementations
+- **Documentation**: ADR (Architecture Decision Records) for significant choices
+```
+
+### Combining with XML Tags
+
+Semantic anchors work powerfully with XML-structured prompts (Section 2.6):
+
+```xml
+<instruction>
+  Refactor the user service following Domain-Driven Design (Evans)
+</instruction>
+
+<constraints>
+  - Apply Hexagonal Architecture (Ports & Adapters)
+  - Use Repository pattern for persistence
+  - Implement Railway Oriented Programming for error handling
+  - Follow CQRS for read/write separation
+</constraints>
+
+<quality_criteria>
+  - Screaming Architecture: package structure reveals intent
+  - Single Responsibility Principle per class
+  - Dependency Inversion: depend on abstractions
+</quality_criteria>
+```
+
+### Semantic Anchors by Domain
+
+**Testing**:
+- TDD London School (mockist) vs Chicago School (classicist)
+- Property-Based Testing (QuickCheck-style)
+- Mutation Testing (PIT, Stryker)
+- BDD Gherkin syntax (Given/When/Then)
+
+**Architecture**:
+- Hexagonal Architecture (Ports & Adapters)
+- Clean Architecture (Onion layers)
+- CQRS + Event Sourcing
+- C4 Model (Context, Container, Component, Code)
+
+**Design Patterns**:
+- Gang of Four patterns (specify: Strategy, Factory, Observer...)
+- Domain-Driven Design tactical patterns (Aggregate, Repository, Domain Event)
+- Functional patterns (Monad, Functor, Railway)
+
+**Requirements**:
+- EARS (Easy Approach to Requirements Syntax)
+- User Story Mapping (Jeff Patton)
+- Jobs-to-be-Done framework
+- BDD scenarios
+
+> **💡 Pro tip**: When Claude produces generic code, try adding more specific anchors. "Use clean code" → "Apply Martin Fowler's Refactoring catalog, specifically Extract Method and Replace Conditional with Polymorphism."
+
+> **Full catalog**: See [examples/semantic-anchors/anchor-catalog.md](../examples/semantic-anchors/anchor-catalog.md) for a comprehensive reference organized by domain.
+
+> **Source**: Concept by Alexandre Soyer. Original catalog: [github.com/LLM-Coding/Semantic-Anchors](https://github.com/LLM-Coding/Semantic-Anchors) (Apache-2.0)
+
+## 2.8 Data Flow & Privacy

 > **Important**: Everything you share with Claude Code is sent to Anthropic servers. Understanding this data flow is critical for protecting sensitive information.

@ -2645,7 +2810,7 @@ When you use Claude Code, the following data leaves your machine:

 > **Full guide**: For complete privacy documentation including known risks, community incidents, and enterprise considerations, see [Data Privacy & Retention Guide](./data-privacy.md).

-## 2.7 Under the Hood
+## 2.9 Under the Hood

 > **Reading time**: 5 minutes
 > **Goal**: Understand the core architecture that powers Claude Code
@ -3907,6 +4072,48 @@ Skills are knowledge packages that agents can inherit.
 | **Skill** | Knowledge module | Inherited by agents |
 | **Command** | Process workflow | Slash command |

+#### Detailed Comparison
+
+| Aspect | Commands | Skills | Agents |
+|--------|----------|--------|--------|
+| **What it is** | Prompt template | Knowledge module | Specialized worker |
+| **Location** | `.claude/commands/` | `.claude/skills/` | `.claude/agents/` |
+| **Invocation** | `/command-name` | Inherited via `@skill` | Task tool delegation |
+| **Execution** | In main conversation | Loaded into context | Separate subprocess |
+| **Context** | Shares main context | Adds to agent context | Isolated context |
+| **Best for** | Repeatable workflows | Reusable knowledge | Complex multi-step tasks |
+| **Token cost** | Low (template only) | Medium (knowledge loaded) | High (full agent) |
+| **Examples** | `/commit`, `/pr`, `/ship` | TDD, security-guardian | code-reviewer, architect |
+
+#### Decision Tree: Which to Use?
+
+```
+Is this a repeatable workflow with steps?
+├─ Yes → Use a COMMAND
+│        Example: /commit, /release-notes, /ship
+│
+└─ No → Is this specialized knowledge multiple agents need?
+        ├─ Yes → Use a SKILL
+        │        Example: TDD methodology, security checklist
+        │
+        └─ No → Does this need isolated context or parallel work?
+                ├─ Yes → Use an AGENT
+                │        Example: code-reviewer, performance-auditor
+                │
+                └─ No → Just write it in CLAUDE.md as instructions
+```
+
+#### Common Patterns
+
+| Need | Solution | Example |
+|------|----------|---------|
+| Run tests before commit | Command | `/commit` with test step |
+| Security review expertise | Skill + Agent | security-guardian skill → security-reviewer agent |
+| Parallel code review | Multiple agents | Launch 3 reviewer agents in parallel |
+| Quick git workflow | Command | `/pr`, `/ship` |
+| Architecture knowledge | Skill | architecture-patterns skill |
+| Complex debugging | Agent | debugging-specialist agent |
+
 ### Why Skills?

 Without skills:
@ -6058,7 +6265,7 @@ The most powerful Claude Code pattern combines three techniques:
 Thinking tokens are billed. With thinking enabled by default:
 - **Simple tasks**: Consider Alt+T to disable → faster responses, lower cost
 - **Complex tasks**: Leave enabled → better reasoning, worth the cost
- **Sonnet/Haiku**: No extended thinking available (Opus 4.5 only)
+- **Sonnet/Haiku**: No extended thinking available (Opus 4.5 only). Note: The warning "Ultrathink no longer does anything" appears on **all models** (including Sonnet), even though the feature itself is Opus-only

 #### Migration for Existing Users

@ -7168,6 +7375,98 @@ Explain using:
 **Next Steps**: [if any]
 ```

+### Mermaid Diagram Generation
+
+Claude Code can generate Mermaid diagrams for visual documentation. This is useful for architecture documentation, flow visualization, and system understanding.
+
+#### Supported Diagram Types
+
+| Type | Use Case | Syntax Start |
+|------|----------|--------------|
+| **Flowchart** | Process flows, decision trees | `flowchart TD` |
+| **Sequence** | API calls, interactions | `sequenceDiagram` |
+| **Class** | OOP structure, relationships | `classDiagram` |
+| **ER** | Database schema | `erDiagram` |
+| **State** | State machines | `stateDiagram-v2` |
+| **Gantt** | Project timelines | `gantt` |
+
+#### Request Patterns
+
+**Architecture diagram:**
+```markdown
+Generate a Mermaid flowchart showing the authentication flow:
+1. User submits credentials
+2. Server validates
+3. JWT issued or error returned
+```
+
+**Database schema:**
+```markdown
+Create an ER diagram for our user management system
+showing User, Role, and Permission relationships.
+```
+
+**Sequence diagram:**
+```markdown
+Show me a Mermaid sequence diagram of how our
+checkout process calls payment API → inventory → notification services.
+```
+
+#### Example Outputs
+
+**Flowchart:**
+```mermaid
+flowchart TD
+    A[User Request] --> B{Authenticated?}
+    B -->|Yes| C[Process Request]
+    B -->|No| D[Return 401]
+    C --> E[Return Response]
+```
+
+**Sequence:**
+```mermaid
+sequenceDiagram
+    Client->>+API: POST /checkout
+    API->>+Payment: charge()
+    Payment-->>-API: success
+    API->>+Inventory: reserve()
+    Inventory-->>-API: confirmed
+    API-->>-Client: order_id
+```
+
+**Class:**
+```mermaid
+classDiagram
+    class User {
+        +String email
+        +String passwordHash
+        +login()
+        +logout()
+    }
+    class Role {
+        +String name
+        +Permission[] permissions
+    }
+    User "1" --> "*" Role
+```
+
+#### Where to Visualize
+
+| Platform | Support |
+|----------|---------|
+| **GitHub** | Native rendering in README, issues, PRs |
+| **VS Code** | Mermaid Preview extension |
+| **GitLab** | Native rendering |
+| **Notion** | Code block with mermaid language |
+| **mermaid.live** | Online editor with export |
+
+#### Integration Tips
+
+1. **In CLAUDE.md**: Ask Claude to document architecture decisions with diagrams
+2. **In PRs**: Include sequence diagrams for complex flows
+3. **In docs/**: Generate architecture.md with embedded diagrams
+4. **Export**: Use mermaid.live to export as PNG/SVG for presentations
+
 ## 9.8 Vibe Coding & Skeleton Projects

 **Reading time**: 5 minutes
@ -8548,6 +8847,165 @@ Time savings from effective Claude Code usage typically far outweigh API costs f

 ---

+## 9.15 Named Prompting Patterns
+
+**Reading time**: 5 minutes
+**Skill level**: Week 2+
+
+Memorable named patterns for effective Claude Code interaction. These patterns have emerged from community best practices and help you communicate more effectively.
+
+### The "As If" Pattern
+
+Set quality expectations by establishing context and standards.
+
+**Pattern**: "Implement as if you were a [role] at [high-standard company/context]"
+
+**Examples:**
+```markdown
+# High quality code
+Implement this authentication system as if you were a senior security engineer at a major bank.
+
+# Production readiness
+Review this code as if preparing for a SOC2 audit.
+
+# Performance focus
+Optimize this function as if it will handle 10,000 requests per second.
+```
+
+**Why it works**: Activates relevant knowledge patterns and raises output quality to match the stated context.
+
+### The Constraint Pattern
+
+Force creative solutions by adding explicit limitations.
+
+**Pattern**: "Solve this [with constraint X] [without using Y]"
+
+**Examples:**
+```markdown
+# Dependency constraint
+Implement this feature without adding any new dependencies.
+
+# Size constraint
+Solve this in under 50 lines of code.
+
+# Time constraint (execution)
+This must complete in under 100ms.
+
+# Simplicity constraint
+Use only standard library functions.
+```
+
+**Why it works**: Constraints prevent over-engineering and force focus on the essential solution.
+
+### The "Explain First" Pattern
+
+Force planning before implementation.
+
+**Pattern**: "Before implementing, explain your approach in [N] sentences"
+
+**Examples:**
+```markdown
+# Simple planning
+Before writing code, explain in 2-3 sentences how you'll approach this.
+
+# Detailed planning
+Before implementing, outline:
+1. What components you'll modify
+2. What edge cases you've considered
+3. What could go wrong
+
+# Trade-off analysis
+Before choosing an approach, explain 2-3 alternatives and why you'd pick one.
+```
+
+**Why it works**: Prevents premature coding and catches misunderstandings early. Especially useful for complex tasks.
+
+### The "Rubber Duck" Pattern
+
+Debug collaboratively by having Claude ask questions.
+
+**Pattern**: "I'm stuck on [X]. Ask me questions to help me figure it out."
+
+**Examples:**
+```markdown
+# Debugging
+I'm stuck on why this test is failing. Ask me questions to help diagnose the issue.
+
+# Design
+I can't decide on the right architecture. Ask me questions about my requirements.
+
+# Problem understanding
+I don't fully understand what I need to build. Ask clarifying questions.
+```
+
+**Why it works**: Often the problem is unclear requirements or assumptions. Questions surface hidden constraints.
+
+### The "Incremental" Pattern
+
+Build complex features step by step with validation.
+
+**Pattern**: "Let's build this incrementally. Start with [minimal version], then we'll add [features]."
+
+**Examples:**
+```markdown
+# Feature development
+Build the user registration incrementally:
+1. First: Basic form that saves to database
+2. Then: Email validation
+3. Then: Password strength requirements
+4. Finally: Email verification flow
+
+Show me step 1 first.
+
+# Refactoring
+Refactor this incrementally. First extract the validation logic,
+run tests, then we'll continue.
+```
+
+**Why it works**: Reduces risk, enables validation at each step, maintains working code throughout.
+
+### The "Boundary" Pattern
+
+Define explicit scope to prevent over-engineering.
+
+**Pattern**: "Only modify [X]. Don't touch [Y]."
+
+**Examples:**
+```markdown
+# File scope
+Only modify auth.ts. Don't change any other files.
+
+# Function scope
+Fix just the calculateTotal function. Don't refactor surrounding code.
+
+# Feature scope
+Add the logout button only. Don't add session management or remember-me features.
+```
+
+**Why it works**: Prevents scope creep and keeps changes focused and reviewable.
+
+### Pattern Combinations
+
+| Situation | Pattern Combination |
+|-----------|---------------------|
+| Critical feature | As If + Explain First + Incremental |
+| Quick fix | Constraint + Boundary |
+| Debugging session | Rubber Duck + Incremental |
+| Architecture decision | Explain First + As If |
+| Refactoring | Boundary + Incremental + Constraint |
+
+### Anti-Patterns to Avoid
+
+| Anti-Pattern | Problem | Better Approach |
+|--------------|---------|-----------------|
+| "Make it perfect" | Undefined standard | Use "As If" with specific context |
+| "Fix everything" | Scope explosion | Use "Boundary" pattern |
+| "Just do it" | No validation | Use "Explain First" |
+| "Make it fast" | Vague constraint | Specify: "under 100ms" |
+| Overwhelming detail | Context pollution | Focus on relevant constraints only |
+
+---
+
 ## 🎯 Section 9 Recap: Pattern Mastery Checklist

 Before moving to Section 10 (Reference), verify you understand:
@ -8570,6 +9028,10 @@ Before moving to Section 10 (Reference), verify you understand:
 - [ ] **Best Practices**: Do/Don't patterns for professional work
 - [ ] **Development Methodologies**: TDD, SDD, BDD, and other structured approaches

+**Communication Patterns**:
+- [ ] **Named Prompting Patterns**: As If, Constraint, Explain First, Rubber Duck, Incremental, Boundary
+- [ ] **Mermaid Diagrams**: Generate visual documentation for architecture and flows
+
 ### What's Next?

 **Section 10 is your command reference** — bookmark it for quick lookups during daily work.
--- a/machine-readable/llms.txt
+++ b/machine-readable/llms.txt
@ -37,7 +37,7 @@ This repository provides everything needed to go from Claude Code beginner to po
  - Context7 (library documentation lookup)
  - Sequential (structured multi-step reasoning)
  - Playwright (browser automation)
- **Trinity Pattern**: Combining Plan Mode + Think Levels + MCP for complex tasks
+- **Trinity Pattern**: Combining Plan Mode + Extended Thinking + MCP for complex tasks
 - **CI/CD Integration**: Headless mode, GitHub Actions, Verify Gate pattern

 ### Best Practices
@ -155,7 +155,7 @@ For fast LLM parsing, see `machine-readable/reference.yaml` (~2K tokens) - struc
 - Prompting formula (WHAT/WHERE/HOW/VERIFY)
 - Commands, shortcuts, CLI flags
 - Context management zones and symptoms
- MCP servers, think levels, cost optimization
+- MCP servers, extended thinking, cost optimization
 - Anti-patterns and troubleshooting

 ## Keywords
--- a/machine-readable/reference.yaml
+++ b/machine-readable/reference.yaml
@ -15,6 +15,8 @@ deep_dive:
  # Claude Code Releases
  claude_code_releases: "guide/claude-code-releases.md"
  claude_code_releases_yaml: "machine-readable/claude-code-releases.yaml"
+  # Template Installation
+  install_templates_script: "scripts/install-templates.sh"
  # Session management
  session_search: "guide/observability.md:29"
  session_search_script: "examples/scripts/session-search.sh"
@ -57,38 +59,40 @@ deep_dive:
  fresh_context_pattern: 1289
  plan_mode: 1822
  rewind: 2000
-  mental_model: 2082
-  xml_prompting: 2139
-  memory_files: 2787
-  claude_folder: 2938
-  settings: 2989
-  precedence_rules: 3211
-  agents: 3309
-  agent_template: 3382
-  agent_examples: 3520
-  skills: 3898
-  skill_template: 3976
-  skill_examples: 4044
-  commands: 4323
-  command_template: 4393
-  hooks: 4646
-  hook_templates: 4791
-  security_hooks: 5053
-  mcp_servers: 5194
-  mcp_config: 5488
-  mcp_security: 5856
-  cicd: 6157
-  ide_integration: 6846
-  feedback_loops: 6916
-  batch_operations: 7254
-  pitfalls: 7373
-  git_best_practices: 7642
-  cost_optimization: 8108
-  commands_table: 8598
-  shortcuts_table: 8631
-  troubleshooting: 8757
-  cheatsheet: 9132
-  daily_workflow: 9208
+  mental_model: 2154
+  xml_prompting: 2211
+  semantic_anchors: 2664
+  semantic_anchors_catalog: "examples/semantic-anchors/anchor-catalog.md"
+  memory_files: 2952
+  claude_folder: 3103
+  settings: 3154
+  precedence_rules: 3376
+  agents: 3474
+  agent_template: 3547
+  agent_examples: 3685
+  skills: 4063
+  skill_template: 4183
+  skill_examples: 4251
+  commands: 4530
+  command_template: 4600
+  hooks: 4853
+  hook_templates: 4998
+  security_hooks: 5260
+  mcp_servers: 5401
+  mcp_config: 5695
+  mcp_security: 6063
+  cicd: 6381
+  ide_integration: 7070
+  feedback_loops: 7140
+  batch_operations: 7570
+  pitfalls: 7689
+  git_best_practices: 7957
+  cost_optimization: 8423
+  commands_table: 9076
+  shortcuts_table: 9109
+  troubleshooting: 9235
+  cheatsheet: 9610
+  daily_workflow: 9686

 # ════════════════════════════════════════════════════════════════
 # DECISION TREE (most important - en premier)
@ -325,6 +329,26 @@ rules:
  5: "Create CLAUDE.md for every project"
  6: "Commit frequently after each task"

+# ════════════════════════════════════════════════════════════════
+# ECOSYSTEM - Related resources & positioning
+# ════════════════════════════════════════════════════════════════
+ecosystem:
+  this_guide:
+    focus: "Education - Learn & master"
+    unique: ["architecture docs", "TDD/SDD methodologies", "217-question quiz", "YAML index"]
+  complementary:
+    claude_code_templates:
+      url: "github.com/davila7/claude-code-templates"
+      focus: "Distribution - Install & use (CLI)"
+      stars: "17k+"
+    awesome_claude_code:
+      url: "github.com/hesreallyhim/awesome-claude-code"
+      focus: "Curation - Discover & link"
+    claude_code_everything:
+      url: "github.com/wesammustafa/Claude-Code-Everything"
+      focus: "Visual walkthrough - Screenshots, BMAD method"
+  install_templates: "scripts/install-templates.sh"
+
 # ════════════════════════════════════════════════════════════════
 # ONBOARDING MATRIX - Maps user profile → content sections
 # Used by tools/onboarding-prompt.md for personalized learning paths
--- a/scripts/install-templates.sh
+++ b/scripts/install-templates.sh
@ -0,0 +1,220 @@
+#!/bin/bash
+# Claude Code Ultimate Guide - Template Installer
+# Usage: curl -fsSL https://raw.githubusercontent.com/FlorianBruniaux/claude-code-ultimate-guide/main/scripts/install-templates.sh | bash -s -- [type] [name]
+#
+# Examples:
+#   ./install-templates.sh list                          # List all available templates
+#   ./install-templates.sh agent security-reviewer       # Install a specific agent
+#   ./install-templates.sh hook dangerous-actions-blocker # Install a specific hook
+#   ./install-templates.sh command pr                    # Install a specific command
+
+set -e
+
+REPO_RAW="https://raw.githubusercontent.com/FlorianBruniaux/claude-code-ultimate-guide/main"
+CLAUDE_DIR=".claude"
+
+# Colors
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+RED='\033[0;31m'
+BLUE='\033[0;34m'
+NC='\033[0m' # No Color
+
+show_help() {
+    echo -e "${BLUE}Claude Code Ultimate Guide - Template Installer${NC}"
+    echo ""
+    echo "Usage:"
+    echo "  $0 list                    List all available templates"
+    echo "  $0 agent <name>            Install an agent template"
+    echo "  $0 hook <name>             Install a hook (bash)"
+    echo "  $0 command <name>          Install a slash command"
+    echo "  $0 skill <name>            Install a skill"
+    echo "  $0 memory <name>           Install a CLAUDE.md template"
+    echo ""
+    echo "Examples:"
+    echo "  $0 list"
+    echo "  $0 agent security-reviewer"
+    echo "  $0 hook dangerous-actions-blocker"
+    echo "  $0 command pr"
+    echo "  $0 command release-notes"
+    echo ""
+    echo "Templates are installed to .claude/ directory"
+}
+
+list_templates() {
+    echo -e "${BLUE}📦 Available Templates${NC}"
+    echo ""
+
+    echo -e "${GREEN}Agents:${NC}"
+    echo "  security-reviewer, performance-auditor, migration-assistant,"
+    echo "  accessibility-auditor, documentation-writer, refactoring-specialist,"
+    echo "  test-coverage-analyst, dependency-updater, code-reviewer"
+    echo ""
+
+    echo -e "${GREEN}Hooks (bash):${NC}"
+    echo "  dangerous-actions-blocker, prompt-injection-detector, unicode-injection-scanner,"
+    echo "  repo-integrity-scanner, mcp-config-integrity, output-secrets-scanner,"
+    echo "  notification, auto-format, security-check, session-logger, claudemd-scanner"
+    echo ""
+
+    echo -e "${GREEN}Commands:${NC}"
+    echo "  pr, release-notes, sonarqube, commit, diagnose, generate-tests,"
+    echo "  review-pr, git-worktree, validate-changes, quiz,"
+    echo "  catchup, security, refactor, explain, optimize, ship"
+    echo ""
+
+    echo -e "${GREEN}Skills:${NC}"
+    echo "  pdf-generator, TDD, backend-architect, security-guardian,"
+    echo "  bilan-hebdo-tech-product, skill-creator, using-git-worktree"
+    echo ""
+
+    echo -e "${GREEN}Memory (CLAUDE.md templates):${NC}"
+    echo "  minimal, comprehensive, nextjs, python, rust, security-focused"
+    echo ""
+
+    echo -e "${YELLOW}Tip:${NC} Run '$0 <type> <name>' to install"
+}
+
+ensure_dir() {
+    local dir="$1"
+    if [ ! -d "$dir" ]; then
+        mkdir -p "$dir"
+        echo -e "${YELLOW}Created directory: $dir${NC}"
+    fi
+}
+
+install_agent() {
+    local name="$1"
+    local dest_dir="${CLAUDE_DIR}/agents"
+    local dest_file="${dest_dir}/${name}.md"
+    local url="${REPO_RAW}/examples/agents/${name}.md"
+
+    ensure_dir "$dest_dir"
+
+    echo -e "${BLUE}Downloading agent: ${name}...${NC}"
+    if curl -fsSL "$url" -o "$dest_file" 2>/dev/null; then
+        echo -e "${GREEN}✓ Installed: ${dest_file}${NC}"
+    else
+        echo -e "${RED}✗ Failed to download agent: ${name}${NC}"
+        echo "  Check available agents with: $0 list"
+        exit 1
+    fi
+}
+
+install_hook() {
+    local name="$1"
+    local dest_dir="${CLAUDE_DIR}/hooks"
+    local dest_file="${dest_dir}/${name}.sh"
+    local url="${REPO_RAW}/examples/hooks/bash/${name}.sh"
+
+    ensure_dir "$dest_dir"
+
+    echo -e "${BLUE}Downloading hook: ${name}...${NC}"
+    if curl -fsSL "$url" -o "$dest_file" 2>/dev/null; then
+        chmod +x "$dest_file"
+        echo -e "${GREEN}✓ Installed: ${dest_file}${NC}"
+        echo -e "${YELLOW}Note: Configure in settings.json to enable this hook${NC}"
+    else
+        echo -e "${RED}✗ Failed to download hook: ${name}${NC}"
+        echo "  Check available hooks with: $0 list"
+        exit 1
+    fi
+}
+
+install_command() {
+    local name="$1"
+    local dest_dir="${CLAUDE_DIR}/commands"
+    local dest_file="${dest_dir}/${name}.md"
+    local url="${REPO_RAW}/examples/commands/${name}.md"
+
+    ensure_dir "$dest_dir"
+
+    echo -e "${BLUE}Downloading command: ${name}...${NC}"
+    if curl -fsSL "$url" -o "$dest_file" 2>/dev/null; then
+        echo -e "${GREEN}✓ Installed: ${dest_file}${NC}"
+        echo -e "${YELLOW}Use with: /${name} in Claude Code${NC}"
+    else
+        echo -e "${RED}✗ Failed to download command: ${name}${NC}"
+        echo "  Check available commands with: $0 list"
+        exit 1
+    fi
+}
+
+install_skill() {
+    local name="$1"
+    local dest_dir="${CLAUDE_DIR}/skills"
+    local dest_file="${dest_dir}/${name}.md"
+    local url="${REPO_RAW}/examples/skills/${name}.md"
+
+    ensure_dir "$dest_dir"
+
+    echo -e "${BLUE}Downloading skill: ${name}...${NC}"
+    if curl -fsSL "$url" -o "$dest_file" 2>/dev/null; then
+        echo -e "${GREEN}✓ Installed: ${dest_file}${NC}"
+    else
+        echo -e "${RED}✗ Failed to download skill: ${name}${NC}"
+        echo "  Check available skills with: $0 list"
+        exit 1
+    fi
+}
+
+install_memory() {
+    local name="$1"
+    local dest_file="CLAUDE.md"
+    local url="${REPO_RAW}/examples/memory/${name}.md"
+
+    if [ -f "$dest_file" ]; then
+        echo -e "${YELLOW}Warning: CLAUDE.md already exists${NC}"
+        read -p "Overwrite? (y/N) " -n 1 -r
+        echo
+        if [[ ! $REPLY =~ ^[Yy]$ ]]; then
+            echo "Aborted."
+            exit 0
+        fi
+    fi
+
+    echo -e "${BLUE}Downloading memory template: ${name}...${NC}"
+    if curl -fsSL "$url" -o "$dest_file" 2>/dev/null; then
+        echo -e "${GREEN}✓ Installed: ${dest_file}${NC}"
+        echo -e "${YELLOW}Customize this file for your project${NC}"
+    else
+        echo -e "${RED}✗ Failed to download memory template: ${name}${NC}"
+        echo "  Check available templates with: $0 list"
+        exit 1
+    fi
+}
+
+# Main
+case "${1:-}" in
+    ""|help|--help|-h)
+        show_help
+        ;;
+    list)
+        list_templates
+        ;;
+    agent)
+        [ -z "${2:-}" ] && { echo -e "${RED}Error: Agent name required${NC}"; exit 1; }
+        install_agent "$2"
+        ;;
+    hook)
+        [ -z "${2:-}" ] && { echo -e "${RED}Error: Hook name required${NC}"; exit 1; }
+        install_hook "$2"
+        ;;
+    command)
+        [ -z "${2:-}" ] && { echo -e "${RED}Error: Command name required${NC}"; exit 1; }
+        install_command "$2"
+        ;;
+    skill)
+        [ -z "${2:-}" ] && { echo -e "${RED}Error: Skill name required${NC}"; exit 1; }
+        install_skill "$2"
+        ;;
+    memory)
+        [ -z "${2:-}" ] && { echo -e "${RED}Error: Memory template name required${NC}"; exit 1; }
+        install_memory "$2"
+        ;;
+    *)
+        echo -e "${RED}Unknown type: $1${NC}"
+        echo "Use: agent, hook, command, skill, memory"
+        exit 1
+        ;;
+esac
--- a/tools/audit-prompt.md
+++ b/tools/audit-prompt.md
@ -510,7 +510,7 @@ Here's an example of what the audit report looks like:
 | **PostToolUse** | Hook that runs AFTER Claude executes a tool - great for formatting |
 | **Plan Mode** | Read-only exploration mode for safe analysis before making changes |
 | **Thinking Mode** | Extended thinking (Opus 4.5: ON by default). Toggle with Alt+T, configure in /config |
-| **Trinity Pattern** | Combining Plan Mode + Think Levels + MCP for complex tasks |
+| **Trinity Pattern** | Combining Plan Mode + Extended Thinking + MCP for complex tasks |
 | **Verify Gate** | CI/CD pattern: build → lint → test → typecheck before merge |
 | **Context Zones** | Green (0-50%), Yellow (50-70%), Red (70%+) - context usage thresholds |
 | **Data Retention** | Anthropic stores conversations: 5 years (default), 30 days (opt-out), 0 days (Enterprise ZDR) |
 @ -1 +1 @@
 .8.2
 .9.0