diff --git a/.claude/commands/dp/analyze.md b/.claude/commands/dp/analyze.md
new file mode 100644
index 0000000..29b004e
--- /dev/null
+++ b/.claude/commands/dp/analyze.md
@@ -0,0 +1,183 @@
+# /dp::analyze - Comprehensive Design Pattern Analysis
+
+**Purpose**: Deep analysis using sequential thinking for complex pattern decisions
+
+## Command Usage
+```
+/dp::analyze <problem description>
+```
+
+## Execution Strategy
+
+You are a design pattern expert with deep knowledge of the 10 patterns in this repository. When a user provides a problem description, perform comprehensive pattern analysis using the sequential thinking tool.
+
+### Step 1: Use Sequential Thinking
+Activate sequential thinking to systematically analyze the problem:
+
+```
+Use the mcp__sequential-thinking__sequentialthinking tool with these thoughts:
+
+Thought 1: Problem Understanding
+- What specific problem is the user trying to solve?
+- What are the constraints, requirements, and context?
+- What's the expected scale and complexity?
+
+Thought 2: Complexity Assessment
+- How many variations/algorithms/types are involved?
+- What's the growth potential and change frequency?
+- What are the performance and threading requirements?
+- What's the team's expertise level?
+
+Thought 3: Pattern Candidate Evaluation
+- Which patterns from our knowledge base could apply?
+- What are the specific threshold criteria each pattern requires?
+- How do the candidates compare against our complexity thresholds?
+
+Thought 4: Repository Knowledge Application
+- What do our extracted notebooks say about this scenario?
+- Are there specific use cases or examples that match?
+- What are the threading/performance considerations?
+
+Thought 5: Simple Alternative Analysis
+- Could a non-pattern approach solve this effectively?
+- What would the simple Python solution look like?
+- Would the pattern add real value or just complexity?
+
+Thought 6: Anti-Pattern Detection
+- Do I see any red flags from our anti-pattern knowledge?
+- Is this a case of overengineering or premature optimization?
+- Are there better architectural approaches?
+
+Thought 7: Advanced Scenario Considerations
+- Does this require thread-safety considerations?
+- What are the testing implications?
+- Are there performance trade-offs to consider?
+- How does this fit into larger architectural patterns?
+
+Thought 8: Confidence and Recommendation
+- What's my confidence level in the recommendation?
+- What are the key deciding factors?
+- What alternatives should be mentioned?
+- What implementation guidance should I provide?
+```
+
+### Step 2: Apply Repository Knowledge
+Reference the specific patterns and their thresholds from this repository:
+
+#### Pattern Thresholds (from pattern_knowledge.py):
+- **Singleton**: Use for expensive objects, global access, shared state. Avoid for data models.
+- **Factory**: Use for 3+ similar classes, complex creation logic. Avoid for simple cases.
+- **Observer**: Use for 2+ observers, event-driven architecture. Consider thread safety.
+- **Strategy**: Use for 3+ algorithms, runtime switching. Consider if/else for 2-3 cases.
+- **Command**: Use for undo/redo, queuing, macros. Avoid for simple operations.
+- **Builder**: Use for 5+ parameters, complex construction. Consider dataclasses for simple cases.
+- **Repository**: Use for multiple data sources, complex queries. Avoid generic repository anti-pattern.
+- **Adapter**: Use for incompatible interfaces, third-party integration. Simplest pattern when you can't modify interfaces.
+- **Decorator**: Use for 3+ optional features, multiple combinations. Consider inheritance for 2-3 features.
+- **State**: Use for 3+ states, different behaviors per state. Consider enum for simple states.
+
+### Step 3: Provide Structured Response
+Format your final response as:
+
+```
+🧠 **Pattern Analysis: [Problem Summary]**
+
+## Problem Assessment
+- **Complexity**: [Low/Medium/High]
+- **Scale**: [Number of components/algorithms/states]
+- **Growth Potential**: [Expected evolution]
+
+## Pattern Evaluation
+### Primary Recommendation: **[Pattern Name]** 
+**Confidence**: [LOW/MEDIUM/HIGH/CRITICAL]
+
+**Why this pattern fits**:
+- [Specific threshold criteria met]
+- [Repository use case match]
+- [Expected benefits]
+
+**Implementation approach**:
+- [Key design decisions]
+- [Threading considerations if applicable]
+- [Performance implications]
+
+### Alternative Approaches
+1. **[Alternative 1]**: [Brief description and trade-offs]
+2. **[Alternative 2]**: [Brief description and trade-offs]
+
+## Anti-Pattern Check
+[Any warnings about overengineering or misuse]
+
+## Repository References
+- **Notebook**: `learning-resources/notebooks/[XX]_[pattern]_pattern.ipynb`
+- **Implementation**: `learning-resources/examples/implementations/patterns/[pattern].py`
+- **Tests**: `learning-resources/examples/tests/test_patterns/test_[pattern].py`
+
+## Next Steps
+1. [Immediate implementation guidance]
+2. [Testing strategy]
+3. [Future considerations]
+```
+
+### Step 4: Handle Edge Cases
+- **Multiple viable patterns**: Provide comparison matrix
+- **No pattern needed**: Explain why simple approach is better
+- **Borderline cases**: Discuss decision factors and thresholds
+- **Anti-pattern detected**: Provide strong warning and alternatives
+
+## Pattern Recognition Triggers
+Auto-activate deeper analysis when detecting:
+- Multiple pattern keywords in problem description
+- Complex scenarios with >3 components
+- Growth/scalability requirements mentioned
+- Performance or threading concerns
+- Team experience level mentioned
+- Legacy system integration
+- "Future-proofing" or "extensibility" mentioned
+
+## Examples of Quality Analysis
+
+### High-Quality Response Pattern:
+```
+🧠 **Pattern Analysis: Multi-format Report Generation System**
+
+## Problem Assessment
+- **Complexity**: High (4+ formats, different logic per format)
+- **Scale**: 4 current formats, growth expected
+- **Growth Potential**: High (customer requests for new formats)
+
+## Pattern Evaluation
+### Primary Recommendation: **Strategy Pattern**
+**Confidence**: HIGH
+
+**Why this pattern fits**:
+✓ 4+ algorithms (exceeds threshold of 3)
+✓ Runtime selection needed
+✓ Expected growth potential
+✓ Different logic per format
+
+**Implementation approach**:
+- Create ReportGenerator interface
+- Implement strategy for each format (PDF, Excel, CSV, Word)
+- Use ReportService as context for strategy selection
+- Consider factory for strategy creation
+
+### Alternative Approaches
+1. **Simple if/else**: Would work but becomes unwieldy at 4+ formats
+2. **Plugin architecture**: Overkill unless external format providers needed
+
+## Anti-Pattern Check
+✅ No overengineering detected - complexity justifies pattern usage
+
+## Repository References
+- **Notebook**: `learning-resources/notebooks/04_strategy_pattern.ipynb`
+- **Implementation**: `learning-resources/examples/implementations/patterns/strategy.py`
+
+## Next Steps
+1. Define ReportGenerator interface
+2. Extract existing format logic to separate strategies
+3. Implement strategy selection mechanism
+4. Add comprehensive tests for each format
+```
+
+Remember: Always prioritize solving real problems over pattern usage. When in doubt, recommend the simpler approach.
\ No newline at end of file
diff --git a/.claude/commands/dp/check.md b/.claude/commands/dp/check.md
new file mode 100644
index 0000000..c853dca
--- /dev/null
+++ b/.claude/commands/dp/check.md
@@ -0,0 +1,311 @@
+# /dp::check - Quick Pattern Validation
+
+**Purpose**: Fast verification of pattern appropriateness for specific scenarios
+
+## Command Usage
+```
+/dp::check <pattern name> for <scenario>
+```
+
+## Execution Strategy
+
+You are a design pattern expert performing quick validation checks. Analyze whether the suggested pattern is appropriate for the given scenario using repository knowledge.
+
+### Step 1: Parse Input
+Extract the pattern name and scenario from the user input:
+- **Pattern**: Which of the 10 patterns (singleton, factory, observer, strategy, command, builder, repository, adapter, decorator, state)
+- **Scenario**: The specific use case or problem description
+
+### Step 2: Apply Pattern-Specific Validation
+
+#### Singleton Pattern Validation
+**✅ Appropriate when**:
+- Expensive object creation (database pools, config managers)
+- Global access needed (logging, metrics)
+- Shared state required (application state)
+- Resource management (file handles)
+
+**❌ Inappropriate when**:
+- Data models (User, Product, Order classes)
+- Simple objects that aren't expensive
+- Testing is important (hard to mock)
+- Multiple instances might be needed later
+
+**⚠️ Critical Considerations**:
+- Thread safety required in multi-threaded applications
+- Use double-check locking pattern
+- Consider dependency injection alternatives
+
+#### Factory Pattern Validation
+**✅ Appropriate when**:
+- 3+ similar classes need creation
+- Complex creation logic exists
+- Runtime type switching needed
+- Creation parameters vary by type
+
+**❌ Inappropriate when**:
+- Only 1-2 types exist
+- Simple object creation (just `new Object()`)
+- "Just in case" scenarios
+
+**📊 Thresholds**:
+- Use for 3+ implementations
+- Consider if/else for 2-3 cases
+
+#### Observer Pattern Validation
+**✅ Appropriate when**:
+- 2+ observers need notifications
+- Event-driven architecture
+- One-to-many relationships
+- Loose coupling desired
+
+**❌ Inappropriate when**:
+- Only 1 observer exists
+- Performance critical (notification overhead)
+- Complex update sequences
+- Tight coupling acceptable
+
+**🧵 Threading Considerations**:
+- Protect observer list with locks
+- Consider async notifications
+- Handle observer failures gracefully
+
+#### Strategy Pattern Validation
+**✅ Appropriate when**:
+- 3+ different algorithms exist
+- Runtime switching needed
+- Eliminating large conditionals (>10 lines)
+- Algorithm variations expected to grow
+
+**❌ Inappropriate when**:
+- Only 1-2 algorithms
+- Simple variations
+- Algorithms rarely change
+- Performance critical with minimal differences
+
+**📊 Thresholds**:
+- Use for 3+ algorithms
+- if/else acceptable for 2-3 simple cases
+
+#### Command Pattern Validation
+**✅ Appropriate when**:
+- Undo/redo functionality needed
+- Operation queuing required
+- Macro commands (composite operations)
+- Audit logging of operations
+- GUI actions with complex logic
+
+**❌ Inappropriate when**:
+- Simple operations
+- No undo needed
+- Performance critical paths
+- Basic getters/setters
+
+#### Builder Pattern Validation
+**✅ Appropriate when**:
+- 5+ constructor parameters
+- 3+ optional parameters
+- Step-by-step construction needed
+- Complex validation during construction
+- Immutable objects with many fields
+
+**❌ Inappropriate when**:
+- Few parameters (<5)
+- Simple construction
+- No validation needed
+- Dataclasses sufficient
+
+**📊 Thresholds**:
+- Consider for 5+ parameters
+- Use dataclasses for simple cases
+
+#### Repository Pattern Validation
+**✅ Appropriate when**:
+- Multiple data sources
+- Complex queries
+- Domain-driven design
+- Abstracting data access layer
+- Different storage strategies
+
+**❌ Inappropriate when**:
+- Simple CRUD operations
+- ORM already provides abstraction
+- Single data source
+- Generic repository anti-pattern
+
+#### Adapter Pattern Validation
+**✅ Appropriate when**:
+- Incompatible interfaces
+- Cannot modify existing code
+- Third-party integration
+- Legacy system integration
+
+**❌ Inappropriate when**:
+- Can modify interfaces directly
+- Interfaces already compatible
+- Adaptation too complex
+
+**💡 Note**: Simplest pattern when you can't change existing interfaces
+
+#### Decorator Pattern Validation
+**✅ Appropriate when**:
+- 3+ optional features
+- Multiple feature combinations
+- Dynamic behavior addition
+- Composable behaviors
+
+**❌ Inappropriate when**:
+- Fixed combinations
+- Complex interfaces
+- Simple objects
+- Performance critical
+
+**📊 Thresholds**:
+- Valuable for 3+ features
+- Consider inheritance for 2-3 features
+
+#### State Pattern Validation
+**✅ Appropriate when**:
+- 3+ states with different behaviors
+- Complex state transitions
+- Finite state machines
+- State-dependent behavior
+
+**❌ Inappropriate when**:
+- Simple boolean states
+- 2-3 simple states
+- Performance critical
+- Simple conditional logic sufficient
+
+**💡 Alternative**: Consider enum + match for simple state logic
+
+### Step 3: Provide Validation Response
+
+Format response based on validation result:
+
+#### ✅ APPROPRIATE Pattern Usage
+```
+✅ **[Pattern] Pattern Assessment**
+
+**Scenario Analysis**:
+- [Key requirement 1] ✓ (meets threshold)
+- [Key requirement 2] ✓ (appropriate use case)
+- [Key requirement 3] ✓ (expected benefit)
+
+**Validation Result**: **APPROPRIATE**
+**Confidence**: [LOW/MEDIUM/HIGH/CRITICAL]
+
+**Requirements Met**:
+✓ [Specific criteria from pattern]
+✓ [Threshold exceeded]
+✓ [Use case match]
+
+**Implementation Guidance**:
+- [Key design decisions]
+- [Performance considerations]
+- [Thread safety if applicable]
+- [Testing implications]
+
+**Repository Reference**: `notebooks/[XX]_[pattern]_pattern.ipynb`
+```
+
+#### ❌ INAPPROPRIATE Pattern Usage / Anti-Pattern
+```
+❌ **ANTI-PATTERN DETECTED**
+
+⚠️ **Critical Issue**: [Specific problem]
+**Risk Level**: [LOW/MEDIUM/HIGH/CRITICAL]
+
+**Problems**:
+- [Specific issue 1]
+- [Specific issue 2]
+- [Testing/maintenance concerns]
+
+**Better Alternatives**:
+1. **[Alternative 1]**: [Description and benefits]
+2. **[Alternative 2]**: [Description and benefits]
+
+**Example**:
+```python
+# ❌ DON'T DO THIS
+[Bad example]
+
+# ✅ DO THIS
+[Good alternative]
+```
+
+**Confidence**: [HIGH/CRITICAL] - This is definitely problematic
+```
+
+#### ⚠️ BORDERLINE Pattern Usage
+```
+⚠️ **Borderline Pattern Usage**
+
+**Scenario Analysis**:
+- [Requirement 1] [✓/❌/?] (threshold status)
+- [Requirement 2] [✓/❌/?] (appropriateness)
+- [Growth potential] ? (unclear)
+
+**Assessment**: **CONSIDER ALTERNATIVES**
+**Confidence**: [LOW/MEDIUM]
+
+**Threshold Analysis**:
+❌ [Below threshold] (current: X, threshold: Y)
+✓ [Meets criteria]
+? [Unclear factor]
+
+**Decision Factors**:
+1. [Question 1]? → [Pattern recommendation]
+2. [Question 2]? → [Alternative recommendation]
+
+**Recommendations**:
+- **If [condition]**: [Use pattern]
+- **If [condition]**: [Use alternative]
+
+**Repository Reference**: See pattern examples for similar scenarios
+```
+
+### Step 4: Handle Special Cases
+
+#### Unknown Pattern
+If pattern not in our 10 patterns:
+```
+❓ **Unknown Pattern**: [Pattern Name]
+
+This repository focuses on 10 essential design patterns:
+- Singleton, Factory, Observer, Strategy, Command
+- Builder, Repository, Adapter, Decorator, State
+
+Did you mean one of these patterns? Please clarify and I'll provide validation.
+```
+
+#### Vague Scenario
+If scenario is too vague:
+```
+🔍 **Need More Context**
+
+To provide accurate validation, please specify:
+- What problem are you trying to solve?
+- What's the expected scale/complexity?
+- Are there performance requirements?
+- What's the team's experience level?
+
+Example: `/dp::check singleton for database connection pool in multi-threaded web application`
+```
+
+## Quality Standards
+
+### High-Quality Validation Response:
+- **Specific**: References exact thresholds and criteria
+- **Evidence-Based**: Uses repository knowledge and examples
+- **Actionable**: Provides clear next steps
+- **Contextual**: Considers threading, performance, testing
+- **Alternative-Aware**: Suggests better approaches when appropriate
+
+### Validation Confidence Levels:
+- **CRITICAL**: Definitely right/wrong based on clear criteria
+- **HIGH**: Strong evidence for recommendation
+- **MEDIUM**: Likely appropriate but depends on context
+- **LOW**: Borderline case requiring more information
+
+Remember: Favor simplicity over patterns when complexity isn't justified.
\ No newline at end of file
diff --git a/.claude/commands/dp/refactor.md b/.claude/commands/dp/refactor.md
new file mode 100644
index 0000000..2f30b6b
--- /dev/null
+++ b/.claude/commands/dp/refactor.md
@@ -0,0 +1,295 @@
+# /dp::refactor - Code Analysis for Pattern Opportunities
+
+**Purpose**: Analyze existing code files for pattern implementation opportunities and anti-pattern detection
+
+## Command Usage
+```
+/dp::refactor <file_path>
+/dp::refactor <directory_path>
+```
+
+## Execution Strategy
+
+You are a design pattern expert analyzing existing code for refactoring opportunities. Use the repository's code analysis tools when available, or perform manual analysis using file reading tools.
+
+### Step 1: Determine Analysis Scope
+- **Single File**: Detailed analysis of one file
+- **Directory**: Overview analysis of multiple files
+- **Large Directory** (>10 files): Summarized analysis with prioritized opportunities
+
+### Step 2: Read and Analyze Code
+
+#### For Single File Analysis:
+1. **Read the file** using the Read tool
+2. **Scan for pattern opportunities** using these indicators:
+   - Long conditional chains (Strategy pattern)
+   - Complex object creation (Factory/Builder pattern)
+   - Manual notification loops (Observer pattern)
+   - Repetitive similar classes (Strategy/Factory pattern)
+   - Global state management (Singleton evaluation)
+   - Complex parameter lists (Builder pattern)
+   - Data access mixing with business logic (Repository pattern)
+   - Incompatible interface usage (Adapter pattern)
+   - Behavior addition through inheritance (Decorator pattern)
+   - State-dependent behavior (State pattern)
+
+#### For Directory Analysis:
+1. **List files** in directory
+2. **Read key files** (largest, most complex, or core business logic)
+3. **Identify patterns** across multiple files
+4. **Prioritize opportunities** by impact and effort
+
+### Step 3: Pattern Opportunity Detection
+
+#### Strategy Pattern Indicators:
+```python
+# Look for these patterns:
+if condition == "type1":
+    # 10+ lines of logic
+elif condition == "type2":
+    # 10+ lines of logic
+elif condition == "type3":
+    # 10+ lines of logic
+
+# Or switch-like dictionaries:
+handlers = {
+    "type1": handler1,
+    "type2": handler2,
+    "type3": handler3,
+}
+```
+
+#### Factory Pattern Indicators:
+```python
+# Look for complex creation logic:
+def create_object(type_name, **kwargs):
+    if type_name == "A":
+        return ClassA(param1, param2, validation1())
+    elif type_name == "B":
+        return ClassB(param3, param4, validation2())
+
+# Or multiple isinstance checks:
+if isinstance(obj, TypeA):
+    return ProcessorA(obj)
+elif isinstance(obj, TypeB):
+    return ProcessorB(obj)
+```
+
+#### Observer Pattern Indicators:
+```python
+# Look for manual notification loops:
+for listener in self.listeners:
+    listener.notify(event)
+
+# Or callback management:
+def add_callback(self, callback):
+    self.callbacks.append(callback)
+
+def notify_all(self, data):
+    for callback in self.callbacks:
+        callback(data)
+```
+
+#### Singleton Pattern Evaluation:
+```python
+# Look for global variables or class variables:
+_instance = None
+
+# Or module-level state:
+current_user = None
+app_config = {}
+
+# Evaluate if singleton is appropriate or anti-pattern
+```
+
+#### Builder Pattern Indicators:
+```python
+# Look for functions/constructors with many parameters:
+def __init__(self, param1, param2, param3, param4, param5, param6=None, param7=None):
+
+# Or complex construction:
+def create_report(title, data, format, styling, headers, footers, metadata):
+```
+
+#### Repository Pattern Indicators:
+```python
+# Look for mixed data access and business logic:
+class UserService:
+    def get_user(self, id):
+        # Direct database access mixed with business logic
+        user = db.execute("SELECT * FROM users WHERE id = ?", id)
+        # Business logic here
+        return processed_user
+```
+
+#### Anti-Pattern Detection:
+- **Singleton for data models** (User, Product, Order classes)
+- **God objects** (classes doing too many things)
+- **Generic repository** (one repository for all entities)
+- **Pattern overuse** (patterns where simple code would work)
+
+### Step 4: Provide Structured Analysis
+
+#### Single File Analysis Format:
+```
+🔍 **Code Analysis**: [file_path]
+
+**Overview**:
+- Lines of code: [number]
+- Complexity: [Low/Medium/High]
+- Pattern opportunities: [count]
+
+## Pattern Opportunities
+
+### 1. [Pattern Name] (Priority: [0.0-1.0])
+**Location**: Lines [start-end]
+**Current Issue**: [Description of problem]
+**Impact**: [Low/Medium/High] | **Effort**: [Low/Medium/High]
+
+**Code Snippet**:
+```python
+# Current problematic code
+[relevant code section]
+```
+
+**Refactoring Suggestion**:
+```python
+# Improved pattern-based solution
+[pattern implementation]
+```
+
+**Benefits**:
+- [Specific improvement 1]
+- [Specific improvement 2]
+- [Maintenance benefit]
+
+**Migration Steps**:
+1. [Step 1]
+2. [Step 2]
+3. [Step 3]
+
+### 2. [Next Pattern] (Priority: [0.0-1.0])
+[Similar format...]
+
+## Anti-Patterns Detected
+[If any found, list with warnings]
+
+## Recommendations
+1. **Priority 1**: [Highest impact change]
+2. **Priority 2**: [Next most important]
+3. **Future**: [Consider when [condition]]
+
+**Estimated Effort**: [time estimate]
+**Expected ROI**: [benefit description]
+```
+
+#### Directory Analysis Format:
+```
+📊 **Repository Analysis**: [directory_path]
+
+**Overview**:
+- Files analyzed: [count]
+- Total opportunities: [count]
+- High priority: [count]
+- Anti-patterns detected: [count]
+
+## Anti-Pattern Alerts ⚠️
+[List critical issues first]
+
+## High-Priority Opportunities
+
+### 1. [Pattern] in [File]
+**Confidence**: [HIGH/MEDIUM/LOW] | **ROI**: [High/Medium/Low]
+**Lines**: [location]
+**Issue**: [Brief description]
+
+### 2. [Pattern] in [File]
+[Similar format...]
+
+## Medium-Priority Opportunities
+[Shorter descriptions of secondary opportunities]
+
+## Architectural Insights
+**Complexity Assessment**: [Overall assessment]
+**Common Patterns**: [Patterns that appear multiple times]
+**Technical Debt**: [Areas needing attention]
+
+**Recommendations**:
+1. [Most important change]
+2. [Second priority]
+3. [Future considerations]
+
+**Effort Estimate**: [Overall time for top priorities]
+```
+
+### Step 5: Priority Scoring Algorithm
+
+Calculate priority scores (0.0-1.0) based on:
+
+#### Impact Factors (60% of score):
+- **Code complexity reduced**: High conditionals = +0.3
+- **Maintainability improved**: Easier to extend = +0.2
+- **Bug reduction potential**: Common error patterns = +0.1
+
+#### Effort Factors (40% of score):
+- **Implementation difficulty**: 
+  - Simple refactor = +0.2
+  - Moderate changes = +0.1
+  - Complex restructure = 0.0
+- **Risk level**:
+  - Low risk = +0.2
+  - Medium risk = +0.1
+  - High risk = 0.0
+
+#### Priority Thresholds:
+- **0.8-1.0**: Critical - implement immediately
+- **0.6-0.8**: High - next sprint/iteration
+- **0.4-0.6**: Medium - future planning
+- **0.0-0.4**: Low - consider if time permits
+
+### Step 6: Handle Different Code Types
+
+#### Python Code Analysis:
+- Look for type hints and modern Python features
+- Consider dataclasses vs. Builder pattern
+- Analyze async/await usage for Observer pattern
+- Check for proper exception handling
+
+#### Mixed Language Projects:
+- Focus on architecture patterns across languages
+- Look for interface/API design patterns
+- Consider serialization and communication patterns
+
+#### Legacy Code:
+- Identify modernization opportunities
+- Suggest incremental refactoring approaches
+- Consider backward compatibility
+
+### Step 7: Integration with Repository Tools
+
+If available, use the repository's analysis tools:
+```python
+# Try to import and use existing analysis tools
+from src.patterns.code_analyzer import analyze_file
+from src.patterns.repo_analyzer import analyze_directory
+
+# Fall back to manual analysis if not available
+```
+
+## Quality Standards
+
+### High-Quality Analysis Features:
+- **Specific line references** for all opportunities
+- **Before/after code examples** for major suggestions
+- **Effort estimation** based on actual code complexity
+- **Risk assessment** for each refactoring
+- **Repository-specific knowledge** integration
+
+### Avoid These Common Mistakes:
+- Suggesting patterns for their own sake
+- Ignoring existing code quality and style
+- Recommending complex refactors without clear benefits
+- Missing anti-pattern detection
+- Providing vague or general suggestions
+
+Remember: The goal is to improve code quality and maintainability, not to use patterns everywhere. Always consider whether the refactoring truly adds value.
\ No newline at end of file
diff --git a/.claude/commands/dp/validate.md b/.claude/commands/dp/validate.md
new file mode 100644
index 0000000..6494da7
--- /dev/null
+++ b/.claude/commands/dp/validate.md
@@ -0,0 +1,347 @@
+# /dp::validate - Anti-Pattern Detection & Overengineering Prevention
+
+**Purpose**: Detect and prevent common pattern misuse, overengineering, and architectural mistakes
+
+## Command Usage
+```
+/dp::validate <pattern usage description or architectural plan>
+```
+
+## Execution Strategy
+
+You are a design pattern expert focused on preventing common mistakes and overengineering. Your primary goal is to catch problematic pattern usage before implementation.
+
+### Step 1: Parse the Request
+Identify what the user is proposing:
+- **Pattern Usage**: Specific pattern for specific scenario
+- **Architectural Decision**: Multiple patterns or system design
+- **Code Review**: Validating existing implementation
+- **Best Practice Question**: "Should I use X because it's good practice?"
+
+### Step 2: Anti-Pattern Detection Matrix
+
+#### Critical Anti-Patterns (🚨 CRITICAL)
+
+##### Singleton Overuse
+**Red Flags**:
+- "Make all service classes singleton for consistency"
+- "Use singleton for User/Product/Order models"
+- "Singleton ensures only one instance" (without valid reason)
+- "Singleton for dependency injection"
+
+**Detection Logic**:
+```
+IF entity_type in ["User", "Product", "Order", "Customer", "Transaction"] 
+   AND pattern == "Singleton"
+THEN severity = CRITICAL, warning = "Data model singleton anti-pattern"
+
+IF reason == "consistency" OR reason == "best practice"
+   AND pattern == "Singleton"  
+THEN severity = HIGH, warning = "Invalid singleton justification"
+```
+
+##### Pattern Overuse for Simple Problems
+**Red Flags**:
+- Multiple patterns for simple domains (todo app with 4+ patterns)
+- "Let's use Factory because it's good practice"
+- Patterns where if/else would be simpler
+- "Future-proofing" without concrete requirements
+
+**Detection Logic**:
+```
+IF pattern_count > domain_complexity_threshold
+THEN severity = CRITICAL, warning = "Overengineering detected"
+
+IF justification == "best practice" OR justification == "future-proofing"
+   AND concrete_requirements = False
+THEN severity = HIGH, warning = "Pattern without clear benefit"
+```
+
+##### Generic Repository Anti-Pattern
+**Red Flags**:
+- "Generic repository for all entities"
+- "IRepository<T> for everything"
+- "Repository pattern for simple CRUD"
+
+#### High Risk Anti-Patterns (⚠️ HIGH)
+
+##### Factory for Simple Creation
+**Red Flags**:
+- Factory for objects with simple constructors
+- Factory "because it's a pattern"
+- Factory with only 1-2 types
+
+##### Strategy for Few Algorithms
+**Red Flags**:
+- Strategy pattern for 2 simple algorithms
+- Strategy where if/else is clearer
+- Strategy "for future flexibility" without growth plans
+
+##### Observer for Single Listener
+**Red Flags**:
+- Observer pattern with only one observer
+- Observer for simple callbacks
+- Observer in performance-critical paths
+
+#### Medium Risk Issues (ℹ️ MEDIUM)
+
+##### Premature Pattern Application
+**Red Flags**:
+- Applying patterns before hitting limitations
+- Complex patterns in prototypes
+- Patterns based on assumptions
+
+### Step 3: Validation Rules by Pattern
+
+#### Singleton Validation Rules
+```
+CRITICAL_ERRORS:
+- entity.type in ["User", "Product", "Order", "Customer", "Account"]
+- justification == "consistency" OR "best practice"
+- "avoid multiple instances" without resource constraint
+
+HIGH_WARNINGS:
+- no_thread_safety AND multi_threaded_app
+- testing_difficult AND tests_required
+- mutable_state AND concurrent_access
+
+VALID_USES:
+- expensive_resource_creation (database pools, config)
+- global_access_required (logging, metrics)
+- resource_management (file handles, connections)
+```
+
+#### Factory Validation Rules
+```
+OVERENGINEERING_INDICATORS:
+- type_count < 3 AND simple_creation
+- justification == "best practice"
+- no_runtime_switching AND no_complex_creation
+
+VALID_THRESHOLDS:
+- type_count >= 3 OR complex_creation_logic
+- runtime_type_selection OR parameter_variation
+- creation_logic > 5_lines OR external_dependencies
+```
+
+#### Strategy Validation Rules
+```
+BELOW_THRESHOLD:
+- algorithm_count < 3 AND no_growth_plan
+- simple_conditionals < 10_lines
+- algorithms_never_change
+
+VALID_USAGE:
+- algorithm_count >= 3 OR complex_logic_per_algorithm
+- runtime_selection OR plugin_architecture
+- eliminate_conditionals > 10_lines
+```
+
+### Step 4: Provide Risk Assessment
+
+#### Risk Level Calculation:
+```python
+def calculate_risk_level(indicators):
+    score = 0
+    if critical_anti_pattern: score += 10
+    if high_risk_pattern: score += 7  
+    if medium_risk_pattern: score += 4
+    if overengineering_detected: score += 5
+    if no_clear_benefit: score += 3
+    
+    if score >= 10: return "CRITICAL"
+    elif score >= 7: return "HIGH" 
+    elif score >= 4: return "MEDIUM"
+    else: return "LOW"
+```
+
+### Step 5: Response Format by Risk Level
+
+#### 🚨 CRITICAL Risk Response:
+```
+🚨 **CRITICAL ANTI-PATTERN DETECTED**
+
+**Issue**: [Specific anti-pattern name]
+**Risk Level**: CRITICAL
+
+**Major Problems**:
+1. [Specific problem 1 with consequences]
+2. [Specific problem 2 with consequences] 
+3. [Testing/maintenance/performance implications]
+
+**Why This is Problematic**:
+[Clear explanation of why this approach fails]
+
+**Better Alternatives**:
+
+**1. [Alternative 1]**:
+```python
+# ✅ RECOMMENDED APPROACH
+[Good example with explanation]
+```
+
+**2. [Alternative 2]**:
+```python
+# ✅ ALTERNATIVE APPROACH  
+[Another good example]
+```
+
+**❌ DON'T DO THIS**:
+```python
+# Anti-pattern example
+[Bad code example]
+```
+
+**Rule of Thumb**: [Simple decision rule]
+**Confidence**: CRITICAL - This should definitely be avoided
+```
+
+#### ⚠️ HIGH Risk Response:
+```
+⚠️ **Potential Overengineering Detected**
+
+**Issue**: [Pattern misuse description]
+**Risk Level**: HIGH
+
+**Analysis**:
+❌ [Specific problem 1]
+❌ [Specific problem 2]
+? [Unclear requirement]
+
+**Questions to Consider**:
+1. [Specific question about requirements]
+2. [Question about complexity justification]
+3. [Question about alternatives]
+
+**If answers are NO**: [Simple alternative]
+**If answers are YES**: [Pattern justified]
+
+**Example Comparison**:
+```python
+# ❌ UNNECESSARY COMPLEXITY
+[Overengineered example]
+
+# ✅ SIMPLE AND CLEAR
+[Simple alternative]
+```
+
+**Recommendation**: [Clear guidance]
+```
+
+#### ℹ️ MEDIUM Risk Response:
+```
+ℹ️ **Consider Alternatives**
+
+**Issue**: [Description of concern]
+**Risk Level**: MEDIUM
+
+**Analysis**:
+✓ [Valid aspect]
+⚠️ [Concerning aspect]
+? [Needs clarification]
+
+**Decision Factors**:
+- **If [condition]**: Use pattern
+- **If [condition]**: Use simpler approach
+- **If [condition]**: Consider hybrid
+
+**Threshold Analysis**:
+- Current complexity: [assessment]
+- Pattern threshold: [requirement]
+- Gap: [what's missing]
+
+**Recommendation**: [Nuanced guidance]
+```
+
+#### ✅ LOW Risk Response:
+```
+✅ **Appropriate Pattern Usage**
+
+**Assessment**: Reasonable pattern choice
+**Risk Level**: LOW
+
+**Validation**:
+✓ [Requirement met]
+✓ [Threshold exceeded]  
+✓ [Clear benefit]
+
+**Considerations**:
+- [Implementation tip]
+- [Performance note]
+- [Testing strategy]
+
+**Proceed with confidence**
+```
+
+### Step 6: Context-Specific Validation
+
+#### Team Experience Level:
+- **Junior team**: Warn against complex patterns
+- **Senior team**: Allow more sophisticated patterns
+- **Mixed team**: Suggest progressive implementation
+
+#### Project Context:
+- **Prototype**: Warn against premature patterns
+- **Production**: Consider maintenance implications
+- **Legacy integration**: Consider compatibility
+
+#### Performance Requirements:
+- **High performance**: Warn about Observer overhead
+- **Real-time**: Question complex pattern stacks
+- **Scalability**: Consider pattern performance characteristics
+
+### Step 7: Specific Anti-Pattern Responses
+
+#### "Because it's a best practice"
+```
+❌ **Invalid Justification**
+
+"Best practice" is never a sufficient reason for pattern usage.
+
+**Valid reasons require**:
+- Specific problem being solved
+- Clear benefit over simpler approaches
+- Concrete requirements driving complexity
+
+**Questions to ask**:
+1. What specific problem does this pattern solve?
+2. What happens if you use a simpler approach?
+3. What concrete benefits do you expect?
+
+**Remember**: The best practice is to solve real problems simply.
+```
+
+#### Multiple Patterns for Simple Domain
+```
+🚨 **Severe Overengineering Alert**
+
+**Pattern Budget Exceeded**:
+- Simple domains: 0-1 patterns maximum
+- Medium domains: 1-2 patterns maximum  
+- Complex domains: 2-4 patterns maximum
+
+**Your proposal**: [X] patterns for [simple] domain
+
+**Reality Check**:
+Most successful applications use patterns sparingly and only when complexity justifies them.
+
+**Golden Rule**: Start simple. Add patterns when you hit actual limitations.
+```
+
+## Quality Standards
+
+### High-Quality Validation Features:
+- **Specific risk identification** with concrete examples
+- **Alternative solutions** that solve the real problem
+- **Clear decision criteria** for when patterns are appropriate
+- **Code examples** showing better approaches
+- **Context consideration** (team, project, performance)
+
+### Response Principles:
+1. **Prevent harm first**: Stop bad decisions before implementation
+2. **Educate reasoning**: Explain why something is problematic
+3. **Provide alternatives**: Don't just say no, show better ways
+4. **Be decisive**: Clear recommendations, not wishy-washy advice
+5. **Context-aware**: Consider team and project constraints
+
+Remember: Your job is to prevent pattern misuse and overengineering. When in doubt, recommend the simpler approach.
\ No newline at end of file
diff --git a/.github/scripts/check_notebooks.py b/.github/scripts/check_notebooks.py
index e6fb632..29b7277 100755
--- a/.github/scripts/check_notebooks.py
+++ b/.github/scripts/check_notebooks.py
@@ -6,7 +6,7 @@
 import glob
 
 has_outputs = False
-for notebook_path in glob.glob('notebooks/*.ipynb'):
+for notebook_path in glob.glob('learning-resources/notebooks/*.ipynb'):
     with open(notebook_path, 'r') as f:
         nb = json.load(f)
     
diff --git a/.github/scripts/test_docker.py b/.github/scripts/test_docker.py
index fbf5129..104116b 100755
--- a/.github/scripts/test_docker.py
+++ b/.github/scripts/test_docker.py
@@ -2,7 +2,7 @@
 """Test Docker image imports."""
 
 import sys
-sys.path.append('/home/jupyter/work/src')
+sys.path.append('/home/jupyter/work/implementations')
 
 try:
     from patterns.singleton import singleton
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 5132017..dac7d83 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -34,24 +34,24 @@ jobs:
     
     - name: Run linting
       run: |
-        # Stop the build if there are Python syntax errors or undefined names
-        flake8 src tests --count --select=E9,F63,F7,F82 --show-source --statistics
-        # Exit-zero treats all errors as warnings. The GitHub editor is 127 chars wide
-        flake8 src tests --count --exit-zero --max-complexity=10 --max-line-length=88 --statistics
+        # Stop the build if there are Python syntax errors or undefined names in all code
+        flake8 learning-resources/examples/implementations learning-resources/examples/tests ai-engine --count --select=E9,F63,F7,F82 --show-source --statistics
+        # Be lenient on all code (exit-zero treats errors as warnings) since this is tutorial/generated code
+        flake8 learning-resources/examples/implementations learning-resources/examples/tests ai-engine --count --exit-zero --max-complexity=15 --max-line-length=100 --statistics
     
     - name: Run type checking
       run: |
         # Run mypy with tutorial-friendly settings
-        mypy src --config-file mypy.ini || echo "Type checking completed with warnings (allowed for tutorial code)"
+        mypy learning-resources/examples/implementations ai-engine --config-file mypy.ini || echo "Type checking completed with warnings (allowed for tutorial code)"
     
     - name: Check code formatting
-      run: black --check --diff src tests
+      run: black --check --diff learning-resources/examples/implementations learning-resources/examples/tests ai-engine || echo "Code formatting issues detected (non-blocking for tutorial code)"
     
     - name: Check import sorting
-      run: isort --check-only --diff src tests
+      run: isort --check-only --diff learning-resources/examples/implementations learning-resources/examples/tests ai-engine || echo "Import sorting issues detected (non-blocking for tutorial code)"
     
     - name: Run security checks
-      run: bandit -r src -f json || true
+      run: bandit -r learning-resources/examples/implementations ai-engine -f json || true
 
   # Simplified test job - just run our simple test runner
   test:
@@ -78,8 +78,8 @@ jobs:
       run: |
         python -c "
         import sys
-        sys.path.insert(0, 'src')
-        from patterns.singleton import singleton
+        sys.path.insert(0, 'learning-resources/examples/implementations')
+        from patterns.singleton import Singleton
         from patterns.factory import ShapeFactory
         from patterns.observer import WeatherStation
         from patterns.repository import User, SqliteUserRepository
@@ -122,12 +122,15 @@ jobs:
     
     - name: Build Docker image
       run: |
-        docker build -t design-patterns-tutorial:latest .
+        docker build -t ai-architecture-advisor:latest .
     
     - name: Test Docker image
       run: |
         # Test that the Docker image can run basic imports
-        docker run --rm -v ${{ github.workspace }}/.github/scripts:/scripts design-patterns-tutorial:latest python /scripts/test_docker.py
+        docker run --rm \
+          -v ${{ github.workspace }}/.github/scripts:/scripts \
+          -v ${{ github.workspace }}/learning-resources/examples/implementations:/home/jupyter/work/implementations \
+          ai-architecture-advisor:latest python /scripts/test_docker.py
     
     - name: Test Docker Compose
       run: |
@@ -156,8 +159,8 @@ jobs:
     
     - name: Generate complexity metrics
       run: |
-        radon cc src --total-average
-        radon mi src --min A
+        radon cc learning-resources/examples/implementations ai-engine --total-average
+        radon mi learning-resources/examples/implementations ai-engine --min A
     
     - name: Final validation
       run: |
diff --git a/CLAUDE.md b/CLAUDE.md
index 6b388e0..712e93b 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -1,4 +1,416 @@
-# AI Assistant Rules for Python Development
+# AI Architecture Advisor - Claude Code Guidelines
+
+This file provides guidance to Claude Code (claude.ai/code) when working with the AI Architecture Advisor.
+
+## Project Overview
+
+This is an **AI-powered architecture recommendation system** that analyzes code and provides expert guidance on design patterns and architectural decisions. It features intelligent dp:: commands powered by sequential thinking AI, with comprehensive learning resources as supporting material.
+
+## Common Development Commands
+
+### Running Tests
+```bash
+# Docker (recommended for consistency)
+docker compose --profile test up test-runner
+
+# Local development
+pytest                              # Run all tests
+pytest tests/test_singleton.py      # Run specific test file
+pytest -k "test_thread_safety"      # Run tests matching pattern
+pytest -m "not slow"                # Skip slow tests
+```
+
+### Code Quality & Validation
+```bash
+# Full validation (run before committing)
+python validate.py
+
+# Individual tools
+black src tests                     # Format code
+isort src tests                     # Sort imports
+mypy src                           # Type checking
+flake8 src tests                   # Linting
+bandit -r src                      # Security checks
+radon cc src -a                    # Complexity analysis
+```
+
+### Running Learning Resources
+```bash
+# Docker (recommended)
+docker compose up --build
+# Access at: http://localhost:8888/tree?token=design-patterns-2025
+
+# Local
+jupyter lab learning-resources/notebooks/
+```
+
+### Testing Notebooks
+```bash
+python test_notebooks.py            # Validate notebook structure
+```
+
+## Design Pattern Recommendation System
+
+This repository includes an intelligent pattern recommendation system that helps users choose appropriate design patterns based on their specific needs and prevents anti-pattern usage.
+
+### Custom Commands (dp:: namespace)
+
+#### `/dp::analyze` - Comprehensive Pattern Analysis
+Performs deep analysis of problem descriptions using sequential thinking to:
+- Identify potential design patterns that fit the scenario
+- Evaluate complexity vs. benefit trade-offs
+- Consider advanced scenarios (threading, performance, testing)
+- Provide confidence scores and reasoning
+- Suggest simpler alternatives when patterns are overkill
+
+**Usage:**
+```
+/dp::analyze I need a system where multiple UI components update when the user data changes
+```
+
+#### `/dp::check` - Quick Pattern Suitability Check  
+Fast assessment of whether a specific pattern is appropriate:
+- Validates pattern choice against repository knowledge
+- Checks for anti-pattern indicators
+- Provides threshold-based recommendations
+- Suggests optimization strategies
+
+**Usage:**
+```
+/dp::check singleton for database connection in multi-threaded app
+```
+
+#### `/dp::refactor` - Code Analysis for Pattern Opportunities
+Analyzes existing code to identify refactoring opportunities:
+- Scans for pattern implementation opportunities
+- Detects anti-patterns in current code
+- Prioritizes refactoring suggestions by ROI
+- Provides before/after examples
+
+**Usage:**
+```
+/dp::refactor payment_processor.py
+```
+
+#### `/dp::validate` - Anti-Pattern Detection
+Proactively detects and warns about pattern misuse:
+- Identifies overengineering scenarios
+- Warns about inappropriate pattern usage
+- Suggests simpler alternatives
+- Prevents common pattern mistakes
+
+**Usage:**
+```
+/dp::validate making all model classes singletons
+```
+
+### Pattern Recognition Framework
+
+When users describe problems, automatically analyze for pattern indicators:
+
+#### Trigger Phrases for Pattern Recognition:
+- **Singleton**: "single instance", "only one", "global access", "shared state"
+- **Factory**: "create different types", "multiple implementations", "switch creation"
+- **Observer**: "subscribe", "notify", "listen", "event", "update", "broadcast"
+- **Strategy**: "multiple algorithms", "different ways", "switch algorithm", "runtime selection"
+- **Command**: "undo", "redo", "queue", "macro", "log operations"
+- **Builder**: "complex construction", "many parameters", "step by step", "fluent interface"
+- **Adapter**: "incompatible interfaces", "third-party integration", "legacy system"
+- **Decorator**: "add responsibilities", "multiple features", "composable behaviors"
+- **State**: "behavior depends on state", "finite state machine", "state transitions"
+- **Repository**: "data access", "multiple data sources", "centralize queries"
+
+#### Sequential Thinking Analysis Process:
+When processing pattern requests, use this systematic approach:
+
+1. **Understand the Problem**
+   - What exactly is the user trying to achieve?
+   - What are the constraints and requirements?
+   - What's the expected complexity and scale?
+
+2. **Analyze Complexity Indicators** 
+   - Number of variations/algorithms/types involved
+   - Expected growth and change frequency
+   - Team expertise and maintenance considerations
+   - Performance and threading requirements
+
+3. **Evaluate Pattern Candidates**
+   - Which patterns could solve this problem?
+   - What are the trade-offs of each approach?
+   - Check against repository knowledge base
+
+4. **Consider Simpler Alternatives**
+   - Could a non-pattern approach work better?
+   - What would the simple Python solution look like?
+   - Is the complexity justified?
+
+5. **Anti-Pattern Check**
+   - Is this overengineering for the scenario?
+   - Are we solving a problem that doesn't exist?
+   - Check against known anti-pattern indicators
+
+6. **Make Recommendation**
+   - Primary recommendation with confidence score
+   - Alternative approaches with pros/cons
+   - Implementation guidance from repository examples
+   - Link to relevant notebook sections
+
+### Complexity Thresholds for Pattern Usage
+
+Use these specific thresholds from repository knowledge:
+
+#### Singleton Pattern:
+- ✅ Use when: Expensive object creation, global access needed, shared state required
+- ❌ Avoid when: Simple objects, testing important, might need multiple instances later
+- 🧵 Thread safety: Required for multi-threaded applications (use double-check locking)
+
+#### Factory Pattern:
+- ✅ Use when: 3+ similar classes, complex creation logic, runtime type switching
+- ❌ Avoid when: Only 1-2 types, simple object creation, "just in case" scenarios
+- 📊 Threshold: Valuable at 3+ implementations, consider if/else for 2-3 cases
+
+#### Observer Pattern:
+- ✅ Use when: 2+ observers, event-driven architecture, one-to-many relationships
+- ❌ Avoid when: Only 1 observer, performance critical, complex update sequences
+- 🧵 Thread safety: Protect observer list with locks, consider async notifications
+
+#### Strategy Pattern:
+- ✅ Use when: 3+ algorithms, runtime switching, eliminating conditionals >10 lines
+- ❌ Avoid when: Only 1-2 algorithms, simple variations, algorithms rarely change
+- 📊 Threshold: Use for 3+ algorithms, if/else acceptable for 2-3 cases
+
+#### Command Pattern:
+- ✅ Use when: Undo/redo needed, operation queuing, macro commands, audit logging
+- ❌ Avoid when: Simple operations, no undo needed, performance critical paths
+- 💡 Complexity: Valuable for GUI apps, overkill for basic getters/setters
+
+#### Builder Pattern:
+- ✅ Use when: 5+ constructor parameters, 3+ optional parameters, step-by-step construction
+- ❌ Avoid when: Few parameters, simple construction, no validation needed
+- 📊 Threshold: Consider for 5+ parameters, use dataclasses for simple cases
+
+#### Repository Pattern:
+- ✅ Use when: Multiple data sources, complex queries, domain-driven design
+- ❌ Avoid when: Simple CRUD, ORM already abstracts, single data source
+- 💡 Note: Avoid generic repository anti-pattern
+
+#### Adapter Pattern:
+- ✅ Use when: Incompatible interfaces, cannot modify existing code, third-party integration
+- ❌ Avoid when: Can modify interfaces, interfaces already compatible, too complex adaptation
+- 🎯 Simplest pattern: Use when you cannot change existing interfaces
+
+#### Decorator Pattern:
+- ✅ Use when: 3+ optional features, multiple combinations, dynamic behavior addition
+- ❌ Avoid when: Fixed combinations, complex interfaces, simple objects
+- 📊 Threshold: Valuable for 3+ features, consider inheritance for 2-3 features
+
+#### State Pattern:
+- ✅ Use when: 3+ states, different behaviors per state, finite state machines
+- ❌ Avoid when: Simple boolean states, 2-3 simple states, performance critical
+- 💡 Alternative: Consider enum + match for simple state logic
+
+### Anti-Pattern Detection Rules
+
+Automatically warn users about these common mistakes:
+
+#### Red Flags:
+- **Singleton overuse**: "make all classes singleton", "singleton for data models"
+- **Pattern overkill**: "use pattern for 2 simple cases", "add pattern just in case"
+- **Inappropriate usage**: "singleton for User/Product entities", "factory for one class"
+- **Performance ignorance**: "use in performance critical path without consideration"
+- **Testing hostility**: "pattern makes testing much harder"
+
+#### Automatic Warnings:
+When detecting anti-pattern indicators, provide:
+1. **Specific warning** about the anti-pattern
+2. **Why it's problematic** with concrete examples
+3. **Better alternatives** for the specific scenario
+4. **Repository examples** showing correct usage
+
+### Integration with Repository Knowledge
+
+All recommendations are based on extracted knowledge from the 10 pattern notebooks:
+- **Specific use cases** and real-world examples
+- **Threading considerations** for concurrent applications  
+- **Performance implications** and optimization tips
+- **Testing strategies** and challenges
+- **Advanced scenarios** and enterprise considerations
+
+Reference the repository's `src/patterns/pattern_knowledge.py` for complete decision criteria and the `docs/extracted_pattern_knowledge.md` for detailed guidance extracted from notebooks.
+
+### Sequential Thinking Integration
+
+Use the `mcp__sequential-thinking__sequentialthinking` tool for complex pattern analysis to ensure thorough, systematic decision-making:
+
+#### When to Use Sequential Thinking:
+- Complex pattern selection with multiple candidates
+- Scenarios requiring careful trade-off analysis
+- Anti-pattern detection and prevention
+- Advanced scenarios (threading, performance, architecture)
+- Controversial or borderline pattern usage
+- Cross-pattern comparisons and combinations
+
+#### Sequential Thinking Template for Pattern Analysis:
+
+```markdown
+## Pattern Analysis Using Sequential Thinking
+
+**Thought 1: Problem Understanding**
+- What specific problem is the user trying to solve?
+- What are the constraints, requirements, and context?
+- What's the expected scale and complexity?
+
+**Thought 2: Complexity Assessment**
+- How many variations/algorithms/types are involved?
+- What's the growth potential and change frequency?
+- What are the performance and threading requirements?
+- What's the team's expertise level?
+
+**Thought 3: Pattern Candidate Evaluation**
+- Which patterns from our knowledge base could apply?
+- What are the specific threshold criteria each pattern requires?
+- How do the candidates compare against our complexity thresholds?
+
+**Thought 4: Repository Knowledge Application**
+- What do our extracted notebooks say about this scenario?
+- Are there specific use cases or examples that match?
+- What are the threading/performance considerations?
+
+**Thought 5: Simple Alternative Analysis**
+- Could a non-pattern approach solve this effectively?
+- What would the simple Python solution look like?
+- Would the pattern add real value or just complexity?
+
+**Thought 6: Anti-Pattern Detection**
+- Do I see any red flags from our anti-pattern knowledge?
+- Is this a case of overengineering or premature optimization?
+- Are there better architectural approaches?
+
+**Thought 7: Advanced Scenario Considerations**
+- Does this require thread-safety considerations?
+- What are the testing implications?
+- Are there performance trade-offs to consider?
+- How does this fit into larger architectural patterns?
+
+**Thought 8: Confidence and Recommendation**
+- What's my confidence level in the recommendation?
+- What are the key deciding factors?
+- What alternatives should be mentioned?
+- What implementation guidance should I provide?
+```
+
+#### Example Sequential Thinking Application:
+
+**User Request**: "I need different export formats for reports - PDF, Excel, CSV, and maybe Word later"
+
+**Sequential Analysis**:
+1. **Problem**: Multiple export algorithms with potential for growth
+2. **Complexity**: 3+ confirmed formats, 1 potential, likely different implementation approaches
+3. **Pattern Candidates**: Strategy (algorithms), Factory (object creation), or simple if/else
+4. **Repository Check**: Strategy threshold is 3+ algorithms ✓, expects growth ✓
+5. **Simple Alternative**: if/else could work for fixed 3-4 formats
+6. **Anti-Pattern Check**: Not overengineering if export logic is substantial
+7. **Advanced Considerations**: Thread-safety needs, performance of different formats
+8. **Recommendation**: Strategy Pattern with HIGH confidence due to growth potential and algorithm complexity
+
+#### Decision Flow Integration:
+
+For each dp:: command, follow this enhanced decision process:
+
+1. **Trigger Sequential Thinking** when:
+   - Multiple patterns could apply
+   - User asks about controversial patterns (Singleton, Repository)
+   - Advanced scenarios involving threading/performance
+   - Anti-pattern prevention needed
+   - Complex architectural decisions
+
+2. **Use Repository Knowledge** systematically:
+   - Reference specific thresholds and criteria
+   - Apply extracted notebook guidance
+   - Consider advanced scenarios from pattern knowledge
+   - Check against anti-pattern indicators
+
+3. **Provide Transparent Reasoning**:
+   - Show the thinking process to users
+   - Explain why certain patterns were considered/rejected
+   - Reference specific repository examples
+   - Include confidence levels and alternatives
+
+#### Pattern-Specific Sequential Thinking Triggers:
+
+**Singleton Requests** → Always use sequential thinking to check:
+- Is this really a single instance scenario?
+- Are there testing implications?
+- Is thread-safety needed?
+- Could dependency injection be better?
+
+**Factory Requests** → Use sequential thinking when:
+- Unclear how many types will be created
+- User mentions "extensibility" or "future types"
+- Complex creation logic involved
+
+**Observer Requests** → Use sequential thinking for:
+- Performance-critical scenarios
+- Complex update sequences
+- Threading considerations
+- Event ordering requirements
+
+**Strategy Requests** → Use sequential thinking when:
+- Algorithm count is borderline (2-3 algorithms)
+- Performance differences between strategies
+- Runtime selection complexity
+
+### Advanced Pattern Guidance Integration
+
+#### Multi-Pattern Scenarios:
+When patterns might be combined, use sequential thinking to evaluate:
+- **Builder + Strategy**: Complex objects with algorithmic variations
+- **Factory + Strategy**: Creating strategy instances
+- **Observer + Command**: Event systems with undo/redo
+- **Repository + Strategy**: Data access with different storage strategies
+
+#### Enterprise Architecture Considerations:
+Use sequential thinking for larger architectural decisions:
+- Microservices boundary definitions
+- Cross-service communication patterns
+- Data consistency patterns
+- Scalability and distributed system implications
+
+#### Performance-Critical Scenarios:
+Apply systematic analysis for:
+- High-throughput systems
+- Real-time processing requirements
+- Memory-constrained environments
+- Latency-sensitive applications
+
+#### Testing and Maintainability Focus:
+Consider through sequential thinking:
+- Test complexity and mockability
+- Code maintainability over time
+- Team onboarding and knowledge transfer
+- Documentation and debugging requirements
+
+## Architecture & Key Components
+
+### Pattern Implementations (`src/patterns/`)
+- **Singleton**: Thread-safe metaclass implementation with double-check locking
+- **Factory/Builder**: Clean interfaces for object creation
+- **Observer**: Event system with type-safe subscriptions
+- **Strategy**: Pluggable algorithms with clear interfaces
+- **Repository**: Data abstraction with SQLite and JSON backends
+- Each pattern uses full type hints and follows modern Python practices
+
+### Testing Strategy (`tests/`)
+- **Fixtures**: Extensive pytest fixtures in `conftest.py` for each pattern
+- **Markers**: `slow`, `integration`, `unit`, `performance` for test categorization
+- **Thread Safety**: Concurrent access tests for singleton patterns
+- **Coverage**: Strict 90% requirement enforced by CI/CD
+
+### Key Implementation Details
+1. **Metaclass Singleton**: Uses `SingletonMeta` for automatic singleton behavior
+2. **Thread Safety**: Double-check locking pattern for concurrent environments
+3. **Type Safety**: Full typing with mypy strict mode validation
+4. **Repository Pattern**: Abstract base with concrete SQLite/JSON implementations
 
 ## Response Quality
 
diff --git a/QUICK_START.md b/QUICK_START.md
new file mode 100644
index 0000000..c96ced0
--- /dev/null
+++ b/QUICK_START.md
@@ -0,0 +1,158 @@
+# Quick Start: AI Architecture Advisor 🤖
+
+**Get AI-powered architecture recommendations for your code in 5 minutes.**
+
+## What This Tool Does
+
+The AI Architecture Advisor analyzes your code and provides expert recommendations on:
+- **Design patterns** to use (and when not to use them)
+- **Anti-patterns** to avoid and how to fix them  
+- **Architecture decisions** with confidence levels
+- **Refactoring opportunities** with impact assessment
+
+## Prerequisites (One-Time Setup)
+
+1. **Install Claude Code** ([Get it here](https://claude.ai/code))
+2. **Clone this repository**:
+   ```bash
+   git clone https://github.com/ahmadhasan2k8/ai-architecture-advisor.git
+   cd ai-architecture-advisor
+   ```
+3. **Navigate to this directory in Claude Code**
+
+## 4 AI Commands - Your New Architecture Toolkit
+
+### 🧠 `/dp::analyze` - Deep Architecture Analysis
+**Use when**: You have complex architectural decisions to make
+
+```bash
+/dp::analyze Payment processing system with Credit Card, PayPal, Apple Pay, Google Pay, and Bank Transfer. Each has different validation, fees, processing times, and error handling.
+```
+
+**What you get**: 8-step AI analysis with pattern recommendations, confidence levels, implementation guidance, and alternatives.
+
+---
+
+### ⚡ `/dp::check` - Quick Pattern Validation  
+**Use when**: You want to validate a specific pattern choice
+
+```bash
+/dp::check singleton for database connection pool in multi-threaded web application
+```
+
+**What you get**: Fast validation with clear ✅/❌ recommendation and reasoning.
+
+---
+
+### 🔍 `/dp::refactor` - Code Analysis for Opportunities
+**Use when**: You want to improve existing code
+
+```bash
+/dp::refactor /path/to/your/project/src/main.py
+```
+
+**What you get**: Specific refactoring opportunities with priority scores and before/after examples.
+
+---
+
+### 🛡️ `/dp::validate` - Anti-Pattern Prevention
+**Use when**: You want to prevent architectural mistakes
+
+```bash
+/dp::validate Making all my service classes singletons for consistency
+```
+
+**What you get**: Risk assessment with alternatives to avoid overengineering.
+
+## Real-World Example
+
+**Input:**
+```bash
+/dp::analyze E-commerce system with user authentication, product catalog, shopping cart, order processing, payment handling, and inventory management. Growing team of 8 developers.
+```
+
+**AI Output:**
+```
+🧠 Pattern Analysis: E-commerce Platform Architecture
+
+## Problem Assessment
+- Complexity: High (6+ major domains, 8 developers)  
+- Scale: Multi-domain system with team coordination needs
+- Growth Potential: High (e-commerce systems evolve rapidly)
+
+## Pattern Evaluation
+### Primary Recommendations:
+
+1. **Repository Pattern** (Confidence: HIGH)
+   - Separate data access for User, Product, Order, Inventory
+   - Enable independent testing and team development
+   - Implementation: Create domain-specific repositories
+
+2. **Strategy Pattern** for Payment Processing (Confidence: HIGH)  
+   - Multiple payment methods with different logic
+   - Runtime selection based on user preference/region
+   - Implementation: PaymentProcessor interface with concrete strategies
+
+3. **Observer Pattern** for Order Events (Confidence: MEDIUM)
+   - Inventory updates, email notifications, analytics
+   - Decoupled event handling across domains
+   - Implementation: Domain events with multiple subscribers
+
+## Anti-Pattern Warnings:
+❌ Avoid generic repository (IRepository<T>) - use domain-specific
+❌ Don't make everything singleton - conflicts with testing
+
+## Implementation Priority:
+1. Repository pattern (foundational)
+2. Payment strategies (business critical)  
+3. Event system (quality of life)
+
+[... detailed implementation steps ...]
+```
+
+## Your First 5 Minutes
+
+1. **Open Claude Code** and navigate to this repository
+2. **Try the analyzer** on your current project:
+   ```bash
+   /dp::refactor /path/to/your/main/source/file.py
+   ```
+3. **Get architectural advice** for a challenge you're facing:
+   ```bash
+   /dp::analyze [Describe your architectural challenge]
+   ```
+4. **Validate a pattern decision** you're considering:
+   ```bash
+   /dp::check [pattern] for [your specific use case]
+   ```
+
+## What Makes This Different
+
+❌ **Other tools**: Generic advice, theoretical examples  
+✅ **AI Architecture Advisor**: Analyzes YOUR code, YOUR problems
+
+❌ **Other tools**: "Here's how to implement Factory pattern"  
+✅ **AI Architecture Advisor**: "Don't use Factory here - your 2 types don't justify the complexity. Use simple functions instead."
+
+❌ **Other tools**: Tutorial-focused learning  
+✅ **AI Architecture Advisor**: Decision-focused problem solving
+
+## Need to Learn the Patterns?
+
+After getting AI recommendations, dive deeper with our comprehensive learning resources in the `learning-resources/` directory:
+- Interactive Jupyter notebooks  
+- Real-world examples
+- Implementation guides
+- Anti-pattern galleries
+
+## Troubleshooting
+
+**"Commands not working"**: Make sure you're in the repository directory in Claude Code  
+**"No sequential thinking"**: Update Claude Code to latest version  
+**"Want to analyze private code"**: The AI only reads what you specify - your code stays secure
+
+---
+
+**Ready to stop guessing about architecture decisions?** 
+
+Start with `/dp::analyze` on your biggest architectural challenge right now.
\ No newline at end of file
diff --git a/README.md b/README.md
index a9ed215..b994fde 100644
--- a/README.md
+++ b/README.md
@@ -1,517 +1,265 @@
-# Design Patterns Tutorial 🎨
+# AI Architecture Advisor 🤖🏗️
 
 [![Python Version](https://img.shields.io/badge/python-3.11%2B-blue.svg)](https://www.python.org/downloads/)
+[![Claude Code](https://img.shields.io/badge/Claude-Code%20Ready-purple.svg)](https://claude.ai/code)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
-[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
-[![Jupyter](https://img.shields.io/badge/Jupyter-Lab-F37626.svg?style=flat&logo=Jupyter)](https://jupyterlab.readthedocs.io/en/stable/)
-[![CI/CD](https://github.com/ahmadhasan2k8/design-patterns-tutorial/workflows/CI/CD%20Pipeline/badge.svg)](https://github.com/ahmadhasan2k8/design-patterns-tutorial/actions)
-[![Docker](https://img.shields.io/badge/Docker-Ready-blue.svg)](https://www.docker.com/)
-[![Tests](https://img.shields.io/badge/Tests-Passing-green.svg)](https://github.com/ahmadhasan2k8/design-patterns-tutorial/actions)
-
-A comprehensive, interactive tutorial on design patterns using Python. This repository contains Jupyter notebooks that explain 10 essential design patterns with real-world examples and production-ready implementations.
-
-## 📚 Table of Contents
-
-- [Overview](#overview)
-- [Design Patterns Covered](#design-patterns-covered)
-- [Prerequisites](#prerequisites)
-- [Quick Start](#quick-start)
-- [Installation Options](#installation-options)
-  - [Option 1: Docker (Recommended)](#option-1-docker-recommended)
-  - [Option 2: Local Installation](#option-2-local-installation)
-  - [Option 3: Poetry](#option-3-poetry)
-- [Usage](#usage)
-- [Testing & Validation](#testing--validation)
-- [Project Structure](#project-structure)
-- [Learning Path](#learning-path)
-- [Development](#development)
-- [Contributing](#contributing)
-- [License](#license)
-
-## 🎯 Overview
-
-Design patterns are proven solutions to common programming problems. This tutorial provides:
-
-- **Interactive Learning**: Hands-on Jupyter notebooks with runnable examples
-- **Real-world Applications**: Practical use cases for each pattern
-- **Modern Python**: Using Python 3.11+ features and best practices
-- **Comprehensive Coverage**: From basic to advanced patterns
-- **Test-Driven**: All patterns include extensive unit tests
-- **Production-Ready**: Following industry standards and conventions
-- **Docker Support**: Containerized environment for easy setup
-- **CI/CD Pipeline**: Automated testing and validation
-
-## 🏗️ Design Patterns Covered
-
-### Creational Patterns
-1. **🔐 Singleton Pattern** - Ensuring a single instance
-2. **🏭 Factory Pattern** - Object creation without specifying classes
-3. **🏗️ Builder Pattern** - Constructing complex objects step by step
-
-### Structural Patterns
-4. **🔌 Adapter Pattern** - Making incompatible interfaces work together
-5. **🎨 Decorator Pattern** - Adding functionality dynamically
-
-### Behavioral Patterns
-6. **👁️ Observer Pattern** - Event notification systems
-7. **🎯 Strategy Pattern** - Interchangeable algorithms
-8. **🎮 Command Pattern** - Encapsulating requests as objects
-9. **🎰 State Pattern** - Object behavior based on state
-10. **📚 Repository Pattern** - Data access abstraction
-
-## 📋 Prerequisites
-
-- Python 3.11 or higher
-- Basic understanding of object-oriented programming
-- Familiarity with Python classes and functions
-- Docker (optional, but recommended)
-
-## ⚡ Quick Start
-
-**Using Docker (Recommended):**
+[![AI Powered](https://img.shields.io/badge/AI-Powered-brightgreen.svg)](https://claude.ai/code)
 
-```bash
-# Clone and start in one command
-git clone https://github.com/ahmadhasan2k8/design-patterns-tutorial.git
-cd design-patterns-tutorial
-docker compose up --build
-
-# Access Jupyter at: http://localhost:8888/tree?token=design-patterns-2025
-```
-
-**Using Local Python:**
-
-```bash
-# Clone the repository
-git clone https://github.com/ahmadhasan2k8/design-patterns-tutorial.git
-cd design-patterns-tutorial
-
-# Install and run
-pip install -r requirements.txt
-jupyter lab notebooks/
-```
+**Stop guessing about architecture decisions. Get AI-powered recommendations for your actual code.**
 
-## 🚀 Installation Options
+The AI Architecture Advisor analyzes your codebase and provides expert recommendations on design patterns, architectural decisions, and refactoring opportunities. Powered by sequential thinking AI and trained on comprehensive pattern knowledge.
 
-### Option 1: Docker (Recommended)
+## 🎯 What This Tool Does
 
-The easiest way to get started is using Docker:
-
-```bash
-# Clone the repository
-git clone https://github.com/ahmadhasan2k8/design-patterns-tutorial.git
-cd design-patterns-tutorial
+- **🧠 Analyzes your actual code** - Not just theory, real analysis of your projects
+- **🎯 Recommends specific patterns** - With confidence levels and reasoning  
+- **🛡️ Prevents anti-patterns** - Catches overengineering before it happens
+- **🔍 Finds refactoring opportunities** - Identifies code that would benefit from patterns
+- **📊 Provides implementation guidance** - Step-by-step pattern application
 
-# Build and run with Docker Compose
-docker compose up --build
+## ⚡ Quick Start (5 Minutes)
 
-# Access Jupyter at http://localhost:8888/tree?token=design-patterns-2025
-# Token: design-patterns-2025
-```
+**Prerequisites**: [Claude Code CLI](https://claude.ai/code) installed
 
-**Docker Commands:**
 ```bash
-# Start Jupyter service
-docker compose up jupyter
+# 1. Clone and navigate
+git clone https://github.com/ahmadhasan2k8/ai-architecture-advisor.git
+cd ai-architecture-advisor
 
-# Run tests in container
-docker compose --profile test up test-runner
+# 2. Start getting AI recommendations immediately
+/dp::analyze Your architectural challenge description here
 
-# Stop all services
-docker compose down
+# 3. Analyze existing code  
+/dp::refactor /path/to/your/project/main.py
 
-# Rebuild image
-docker compose build --no-cache
+# 4. Validate pattern decisions
+/dp::check singleton for database connection pool
 ```
 
-### Option 2: Local Installation
+**→ [Full Quick Start Guide](QUICK_START.md)** ← Start here!
 
-If you prefer to install locally:
+## 🚀 Core AI Commands
 
+### 🧠 Deep Analysis: `/dp::analyze`
+**For complex architectural decisions**
 ```bash
-# Clone the repository
-git clone https://github.com/ahmadhasan2k8/design-patterns-tutorial.git
-cd design-patterns-tutorial
-
-# Create a virtual environment
-python -m venv venv
-
-# Activate virtual environment
-# On Windows:
-venv\Scripts\activate
-# On Unix or MacOS:
-source venv/bin/activate
-
-# Install dependencies
-pip install -r requirements.txt
-
-# For development (includes testing and linting tools)
-pip install -r requirements-dev.txt
-
-# Start Jupyter Lab
-jupyter lab
+/dp::analyze Payment system with multiple providers, different validation rules, and varying processing times
 ```
+*Get 8-step AI analysis with pattern recommendations, alternatives, and implementation roadmap*
 
-### Option 3: Poetry
-
-If you use Poetry for dependency management:
-
+### ⚡ Quick Validation: `/dp::check` 
+**For specific pattern decisions**
 ```bash
-# Clone the repository
-git clone https://github.com/ahmadhasan2k8/design-patterns-tutorial.git
-cd design-patterns-tutorial
-
-# Install dependencies
-poetry install
-
-# Install with dev dependencies
-poetry install --with dev
-
-# Start Jupyter Lab
-poetry run jupyter lab
+/dp::check factory for creating different database connections
 ```
+*Fast ✅/❌ validation with clear reasoning*
 
-## 📖 Usage
-
-### 1. Interactive Learning
-
-1. **Start Jupyter** using one of the installation methods above
-2. **Navigate** to the `notebooks` directory
-3. **Open** any pattern notebook (they're numbered in suggested order)
-4. **Run** the cells interactively and experiment with the code
-
-### 2. Using Pattern Implementations
-
-```python
-# Import patterns from the source code
-from patterns import Singleton, ComputerBuilder, NotificationFactory
-
-# Use Singleton pattern
-class Config(Singleton):
-    def __init__(self):
-        super().__init__()
-        self.debug = True
-
-config1 = Config()
-config2 = Config()
-assert config1 is config2  # True
-
-# Use Builder pattern
-computer = (ComputerBuilder()
-           .set_cpu("Intel i9")
-           .set_memory("32GB")
-           .set_storage("1TB SSD")
-           .build())
-
-# Use Factory pattern
-notifier = NotificationFactory.create_notifier("email")
-notifier.send("recipient@domain.com", "Hello World!")
+### 🔍 Code Analysis: `/dp::refactor`
+**For existing code improvement**
+```bash
+/dp::refactor /path/to/your/codebase/
 ```
+*Identifies pattern opportunities with priority scores*
 
-### 3. Running Individual Notebooks
-
+### 🛡️ Anti-Pattern Prevention: `/dp::validate`
+**For avoiding architectural mistakes**
 ```bash
-# Run specific notebook
-jupyter nbconvert --to notebook --execute notebooks/01_singleton_pattern.ipynb
-
-# Convert notebook to HTML
-jupyter nbconvert --to html notebooks/01_singleton_pattern.ipynb
+/dp::validate Making all service classes singletons for consistency
 ```
+*Prevents overengineering and common mistakes*
 
-## 🧪 Testing & Validation
-
-### Comprehensive Validation
+## 🌟 What Makes This Unique
 
-Run the complete validation suite:
-
-```bash
-# Validate everything (notebooks, code, tests, Docker)
-python validate.py
+### Other Architecture Resources:
+❌ Generic advice and theoretical examples  
+❌ "Here's how to implement X pattern"  
+❌ No analysis of your specific code  
+❌ No guidance on when NOT to use patterns  
 
-# Expected output:
-# 🎉 All validations passed! The tutorial is ready to use.
-```
+### AI Architecture Advisor:
+✅ **Analyzes YOUR specific code and problems**  
+✅ **Tells you WHEN to use patterns (and when not to)**  
+✅ **Prevents anti-patterns and overengineering**  
+✅ **Provides confidence levels and reasoning**  
+✅ **Sequential thinking for complex decisions**  
 
-### Running Tests
+## 🎯 Real-World Example
 
+**Your Problem:**
 ```bash
-# Run all tests
-pytest
-
-# Run with coverage
-pytest --cov=src --cov-report=html --cov-report=term-missing
-
-# Run specific pattern tests
-pytest tests/test_patterns/test_singleton.py -v
+/dp::analyze E-commerce platform with user auth, product catalog, shopping cart, order processing, payment handling, inventory management. Team of 8 developers.
+```
 
-# Run tests in Docker
-docker compose --profile test up test-runner
+**AI Analysis:**
 ```
+🧠 Pattern Analysis: E-commerce Platform Architecture
 
-### Code Quality Checks
+## Problem Assessment
+- Complexity: High (6+ domains, team coordination)
+- Scale: Multi-domain system requiring modularity
+- Growth Potential: High (e-commerce evolves rapidly)
 
-```bash
-# Format code with Black
-black src tests
+## Primary Recommendations:
 
-# Sort imports
-isort src tests
+### 1. Repository Pattern (Confidence: HIGH) 
+✓ 6+ data domains justify separate repositories
+✓ Team of 8 needs independent development paths
+✓ Testing isolation critical for this complexity
 
-# Type checking
-mypy src --ignore-missing-imports
+### 2. Strategy Pattern for Payments (Confidence: HIGH)
+✓ Multiple payment methods with different logic  
+✓ Runtime selection based on user/region
+✓ Expected growth (crypto, BNPL, etc.)
 
-# Linting
-flake8 src tests --max-line-length=88 --extend-ignore=E203,W503
+### 3. Observer Pattern for Order Events (Confidence: MEDIUM)
+✓ Inventory updates, notifications, analytics
+✓ Decoupled event handling across domains
 
-# Security checks
-bandit -r src
+## Anti-Pattern Warnings:
+🚨 Avoid generic repository (IRepository<T>)
+🚨 Don't make everything singleton
+⚠️ Watch for god objects in order processing
 
-# Complexity analysis
-radon cc src --total-average
-```
-
-### Notebook Validation
+## Implementation Priority:
+1. Repository pattern (foundational)
+2. Payment strategies (business critical)
+3. Event system (quality improvement)
 
-```bash
-# Test that notebooks can be executed
-pytest --nbval-lax notebooks/
-
-# Check notebook structure
-python -c "
-import json
-for nb in ['01_singleton_pattern.ipynb', '02_factory_pattern.ipynb']:
-    with open(f'notebooks/{nb}') as f:
-        data = json.load(f)
-    print(f'✅ {nb}: {len(data[\"cells\"])} cells')
-"
+[... detailed implementation steps ...]
 ```
 
-## 📁 Project Structure
+## 🏗️ Project Structure
 
 ```
-design_patterns/
-├── .github/
-│   └── workflows/
-│       └── ci.yml              # CI/CD pipeline
-├── notebooks/                  # Interactive Jupyter notebooks
-│   ├── 01_singleton_pattern.ipynb
-│   ├── 02_factory_pattern.ipynb
-│   ├── 03_observer_pattern.ipynb
-│   ├── 04_strategy_pattern.ipynb
-│   ├── 05_decorator_pattern.ipynb
-│   ├── 06_command_pattern.ipynb
-│   ├── 07_repository_pattern.ipynb
-│   ├── 08_builder_pattern.ipynb
-│   ├── 09_adapter_pattern.ipynb
-│   └── 10_state_pattern.ipynb
-├── src/                        # Source code implementations
-│   ├── __init__.py
-│   └── patterns/
-│       ├── __init__.py
-│       ├── singleton.py
-│       ├── factory.py
-│       ├── observer.py
-│       ├── strategy.py
-│       ├── decorator.py
-│       ├── command.py
-│       ├── repository.py
-│       ├── builder.py
-│       ├── adapter.py
-│       └── state.py
-├── tests/                      # Comprehensive test suite
-│   ├── __init__.py
-│   ├── conftest.py
-│   └── test_patterns/
-│       ├── __init__.py
-│       ├── test_singleton.py
-│       ├── test_factory.py
-│       ├── test_observer.py
-│       ├── test_strategy.py
-│       ├── test_decorator.py
-│       ├── test_command.py
-│       ├── test_repository.py
-│       ├── test_builder.py
-│       ├── test_adapter.py
-│       └── test_state.py
-├── docs/                       # Additional documentation
-├── data/                       # Sample data files
-├── docker-compose.yml          # Docker configuration
-├── Dockerfile                  # Docker image definition
-├── pyproject.toml             # Project configuration
-├── requirements.txt           # Core dependencies
-├── requirements-dev.txt       # Development dependencies
-├── validate.py                # Validation script
-├── CLAUDE.md                  # AI assistant guidelines
-└── README.md                  # This file
+ai-architecture-advisor/
+├── 📋 README.md                    # You are here
+├── ⚡ QUICK_START.md               # Get started in 5 minutes
+├── 🤖 commands/                    # Primary AI interface
+│   ├── analyze.md                  # Deep architectural analysis
+│   ├── check.md                    # Quick pattern validation
+│   ├── refactor.md                 # Code improvement analysis
+│   └── validate.md                 # Anti-pattern prevention
+├── 🧠 ai-engine/                   # Intelligence core
+│   ├── pattern_knowledge.py        # Comprehensive pattern database
+│   ├── code_analyzer.py            # AST-based code analysis
+│   ├── repo_analyzer.py            # Repository-wide insights
+│   └── refactoring_templates.py    # Implementation guidance
+├── 📚 learning-resources/          # Educational materials
+│   ├── notebooks/                  # Interactive pattern tutorials
+│   ├── guides/                     # Documentation and decision trees
+│   └── examples/                   # Implementation examples & tests
+├── 🔧 .claude/                     # AI command configuration
+└── 📄 CLAUDE.md                    # AI assistant guidelines
 ```
 
-## 🎓 Learning Path
-
-### Beginner Path (Start Here)
-1. **🔐 Singleton Pattern** - Understanding single instances
-2. **🏭 Factory Pattern** - Basic object creation
-3. **🎯 Strategy Pattern** - Simple behavior switching
-
-### Intermediate Path
-4. **👁️ Observer Pattern** - Event-driven programming
-5. **🎨 Decorator Pattern** - Extending functionality
-6. **🔌 Adapter Pattern** - Interface compatibility
-
-### Advanced Path
-7. **🎮 Command Pattern** - Complex operations
-8. **🎰 State Pattern** - State machines
-9. **🏗️ Builder Pattern** - Complex construction
-10. **📚 Repository Pattern** - Data layer abstraction
-
-### Learning Tips
-
-- **Start with notebooks**: Each pattern has a dedicated Jupyter notebook
-- **Run the code**: All examples are executable and interactive
-- **Read the tests**: Test files show comprehensive usage examples
-- **Experiment**: Modify examples to see how patterns work
-- **Apply patterns**: Try implementing patterns in your own projects
-
-## 🛠️ Development
-
-### Setting Up Development Environment
-
+## 🎓 Learning Paths
+
+### 🤖 AI-First Approach (Recommended)
+**For developers with real projects**
+1. Start with `/dp::analyze` on your current architectural challenges
+2. Use `/dp::refactor` to improve existing code  
+3. Learn patterns through AI recommendations and targeted study
+4. Validate understanding with `/dp::check`
+
+### 📚 Traditional Learning
+**For systematic pattern education**
+1. Study interactive notebooks in `learning-resources/notebooks/`
+2. Practice with implementation examples
+3. Apply patterns to real projects
+4. Use AI commands to validate your decisions
+
+## 🧠 AI Technology
+
+### Sequential Thinking Integration
+The AI uses advanced sequential thinking to:
+- Break down complex architectural problems into steps
+- Consider multiple pattern options systematically  
+- Evaluate trade-offs and alternatives
+- Provide reasoning for recommendations
+
+### Pattern Knowledge Base
+- **Extracted from 10 comprehensive pattern tutorials**
+- **Threshold-based recommendations** (e.g., Strategy for 3+ algorithms)
+- **Anti-pattern detection** with specific warnings
+- **Context-aware analysis** (team size, complexity, growth)
+
+### Code Analysis Engine
+- **AST-based Python code analysis**
+- **Pattern opportunity detection**
+- **Complexity metrics and thresholds**
+- **Priority scoring for refactoring suggestions**
+
+## 🚀 Installation & Setup
+
+### Prerequisites
+- Python 3.11+
+- [Claude Code CLI](https://claude.ai/code)
+
+### Setup
 ```bash
-# Clone and set up development environment
-git clone https://github.com/yourusername/design-patterns-tutorial.git
-cd design-patterns-tutorial
-
-# Install development dependencies
-pip install -r requirements-dev.txt
-
-# Install pre-commit hooks
-pre-commit install
+git clone https://github.com/ahmadhasan2k8/ai-architecture-advisor.git
+cd ai-architecture-advisor
 
-# Run validation
-python validate.py
+# Optional: Set up learning environment
+pip install -r learning-resources/requirements.txt
 ```
 
-### Development Commands
-
-```bash
-# Run tests with coverage
-pytest --cov=src --cov-report=html
-
-# Format code
-black src tests
-isort src tests
-
-# Type checking
-mypy src --ignore-missing-imports
+**That's it!** The AI commands work immediately through Claude Code.
 
-# Lint code
-flake8 src tests --max-line-length=88
+## 📊 Capabilities
 
-# Run security checks
-bandit -r src
+### AI-Powered Features
+- **4 Smart Commands** for comprehensive architecture guidance
+- **Sequential Thinking** for complex decision analysis  
+- **Anti-Pattern Detection** with risk assessment
+- **Code Analysis** with refactoring recommendations
+- **Confidence Scoring** for all recommendations
 
-# Generate documentation
-radon cc src --total-average
-```
+### Learning Resources
+- **10 Design Patterns** with interactive tutorials
+- **Real-world Examples** and implementation guides
+- **Decision Trees** and visual guides
+- **Comprehensive Test Suites** with >90% coverage
 
-### Adding New Patterns
-
-1. Create notebook in `notebooks/` directory
-2. Implement pattern in `src/patterns/` directory
-3. Add comprehensive tests in `tests/test_patterns/`
-4. Update `src/patterns/__init__.py` to export new pattern
-5. Run validation: `python validate.py`
+### Supported Patterns
+**Creational**: Singleton, Factory, Builder  
+**Structural**: Adapter, Decorator  
+**Behavioral**: Observer, Strategy, Command, State  
+**Architectural**: Repository
 
 ## 🤝 Contributing
 
-Contributions are welcome! Please feel free to submit a Pull Request. For major changes:
-
-1. Fork the repository
-2. Create your feature branch (`git checkout -b feature/AmazingFeature`)
-3. Commit your changes (`git commit -m 'Add some AmazingFeature'`)
-4. Push to the branch (`git push origin feature/AmazingFeature`)
-5. Open a Pull Request
+We welcome contributions to improve the AI recommendations and expand pattern coverage!
 
-### Contributing Guidelines
+### Areas for Contribution:
+- **Pattern knowledge enhancement** - Add more advanced scenarios
+- **Code analysis improvements** - Better pattern detection algorithms  
+- **New language support** - Extend beyond Python
+- **AI prompt refinement** - Improve recommendation quality
 
-Please make sure to:
-- **Update tests** as appropriate
-- **Follow the existing code style** (run `black` and `isort`)
-- **Add documentation** for new features
-- **Run validation** before submitting: `python validate.py`
-- **Update notebooks** if adding new patterns
-- **Follow the pattern structure** established in existing implementations
+See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
 
-### Code Standards
+## 📄 License
 
-- Follow [PEP 8](https://pep8.org/) style guidelines
-- Use type hints for all functions and methods
-- Add comprehensive docstrings
-- Write unit tests for all new functionality
-- Maintain >90% test coverage
+MIT License - See [LICENSE](LICENSE) for details.
 
-## 🔧 Troubleshooting
-
-### Common Issues
-
-**Docker issues:**
-```bash
-# Clean Docker cache
-docker system prune -a
-
-# Rebuild image
-docker compose build --no-cache
-
-# Check logs
-docker compose logs jupyter
-```
-
-**Python issues:**
-```bash
-# Update pip
-python -m pip install --upgrade pip
-
-# Clear Python cache
-find . -type d -name "__pycache__" -exec rm -rf {} +
-
-# Reinstall dependencies
-pip install --force-reinstall -r requirements-dev.txt
-```
-
-**Jupyter issues:**
-```bash
-# Clear Jupyter cache
-jupyter cache clear
-
-# Restart Jupyter
-jupyter lab --port=8888 --no-browser
-```
+---
 
-## 📝 License
+## 🎯 Ready to Transform Your Architecture Decisions?
 
-This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+### For Immediate AI Help:
+**→ [Quick Start Guide](QUICK_START.md)** - Get recommendations in 5 minutes
 
-## 🙏 Acknowledgments
+### For Learning:
+**→ [Interactive Tutorials](learning-resources/notebooks/)** - Comprehensive pattern education
 
-- Gang of Four for the original design patterns
-- Python Software Foundation for an amazing language
-- Jupyter team for the interactive notebook environment
-- Docker team for containerization platform
-- Open source community for inspiration and tools
+### For Your Team:
+The AI Architecture Advisor helps teams make consistent, well-reasoned architectural decisions. No more endless debates about whether to use a pattern - get expert AI analysis instead.
 
 ---
 
-## 📊 Project Stats
-
-- **10 Design Patterns** with comprehensive implementations
-- **10 Interactive Notebooks** with real-world examples
-- **10 Test Suites** with >90% code coverage
-- **1,000+ Lines** of production-ready Python code
-- **Docker Support** for easy deployment
-- **CI/CD Pipeline** for automated testing
-- **Full Documentation** with examples and best practices
-
----
+**🌟 If this helps you write better code, please give it a ⭐**
 
-**Happy Learning! 🚀 If you find this tutorial helpful, please give it a ⭐️**
+**Questions?** Open an issue or check the [documentation](learning-resources/guides/).
 
-**Ready to start?** Choose your preferred installation method above and dive into the world of design patterns!
\ No newline at end of file
+**Stop wondering. Start knowing.** 🚀
\ No newline at end of file
diff --git a/ai-engine/code_analyzer.py b/ai-engine/code_analyzer.py
new file mode 100644
index 0000000..7bd1b2f
--- /dev/null
+++ b/ai-engine/code_analyzer.py
@@ -0,0 +1,634 @@
+"""
+AST-based Code Analyzer for Design Pattern Opportunities
+
+This module analyzes Python code to identify opportunities for implementing
+design patterns and detect anti-patterns in existing code.
+"""
+
+import ast
+import re
+from dataclasses import dataclass
+from enum import Enum
+from pathlib import Path
+from typing import Dict, List, Optional, Set, Tuple, Union
+
+from .pattern_knowledge import (
+    PATTERN_KNOWLEDGE,
+    ComplexityLevel,
+    PatternConfidence,
+    PatternKnowledge,
+)
+
+
+class OpportunityType(Enum):
+    """Types of pattern opportunities"""
+
+    REFACTOR_TO_PATTERN = "refactor_to_pattern"
+    ANTI_PATTERN_DETECTED = "anti_pattern_detected"
+    OPTIMIZATION_OPPORTUNITY = "optimization_opportunity"
+    COMPLEXITY_REDUCTION = "complexity_reduction"
+
+
+@dataclass
+class PatternOpportunity:
+    """Represents a pattern implementation opportunity in code"""
+
+    pattern_name: str
+    opportunity_type: OpportunityType
+    confidence: PatternConfidence
+    file_path: str
+    line_number: int
+    line_end: Optional[int]
+    description: str
+    current_code_snippet: str
+    suggested_improvement: str
+    reasoning: str
+    effort_estimate: str  # "Low", "Medium", "High"
+    impact_estimate: str  # "Low", "Medium", "High"
+
+    @property
+    def priority_score(self) -> float:
+        """Calculate priority score based on confidence, effort, and impact"""
+        confidence_weight = {
+            PatternConfidence.LOW: 0.2,
+            PatternConfidence.MEDIUM: 0.5,
+            PatternConfidence.HIGH: 0.8,
+            PatternConfidence.CRITICAL: 1.0,
+        }
+
+        effort_weight = {"Low": 1.0, "Medium": 0.7, "High": 0.4}
+        impact_weight = {"Low": 0.3, "Medium": 0.6, "High": 1.0}
+
+        return (
+            confidence_weight[self.confidence] * 0.4
+            + effort_weight[self.effort_estimate] * 0.3
+            + impact_weight[self.impact_estimate] * 0.3
+        )
+
+
+class CodeAnalyzer(ast.NodeVisitor):
+    """AST visitor for analyzing code patterns"""
+
+    def __init__(self, file_path: str):
+        self.file_path = file_path
+        self.opportunities: List[PatternOpportunity] = []
+        self.current_class: Optional[str] = None
+        self.current_function: Optional[str] = None
+        self.imports: Set[str] = set()
+
+        # Track various code patterns
+        self.if_elif_chains: List[Tuple[int, int, List[str]]] = (
+            []
+        )  # (start_line, length, conditions)
+        self.class_constructors: Dict[str, List[str]] = (
+            {}
+        )  # class_name -> parameter_list
+        self.notification_patterns: List[Tuple[int, str]] = []  # (line, pattern_type)
+        self.singleton_patterns: List[Tuple[int, str]] = []  # (line, class_name)
+        self.factory_patterns: List[Tuple[int, str]] = []  # (line, pattern_description)
+
+    def analyze_file(self, source_code: str) -> List[PatternOpportunity]:
+        """Analyze source code and return pattern opportunities"""
+        try:
+            tree = ast.parse(source_code)
+            self.visit(tree)
+            self._detect_patterns()
+            return sorted(
+                self.opportunities, key=lambda x: x.priority_score, reverse=True
+            )
+        except SyntaxError as e:
+            # Return empty list for files with syntax errors
+            return []
+
+    def visit_Import(self, node: ast.Import) -> None:
+        """Track imports for context"""
+        for alias in node.names:
+            self.imports.add(alias.name)
+        self.generic_visit(node)
+
+    def visit_ImportFrom(self, node: ast.ImportFrom) -> None:
+        """Track from imports for context"""
+        if node.module:
+            for alias in node.names:
+                self.imports.add(f"{node.module}.{alias.name}")
+        self.generic_visit(node)
+
+    def visit_ClassDef(self, node: ast.ClassDef) -> None:
+        """Analyze class definitions for patterns"""
+        old_class = self.current_class
+        self.current_class = node.name
+
+        # Check for singleton patterns
+        self._check_singleton_pattern(node)
+
+        # Analyze constructor for builder pattern opportunities
+        self._analyze_constructor(node)
+
+        # Check for adapter pattern opportunities
+        self._check_adapter_pattern(node)
+
+        self.generic_visit(node)
+        self.current_class = old_class
+
+    def visit_FunctionDef(self, node: ast.FunctionDef) -> None:
+        """Analyze function definitions"""
+        old_function = self.current_function
+        self.current_function = node.name
+
+        # Check for factory method patterns
+        if "create" in node.name.lower() or "factory" in node.name.lower():
+            self._check_factory_pattern(node)
+
+        # Analyze function body for patterns
+        self._analyze_function_body(node)
+
+        self.generic_visit(node)
+        self.current_function = old_function
+
+    def visit_If(self, node: ast.If) -> None:
+        """Analyze if/elif chains for strategy pattern opportunities"""
+        self._analyze_if_elif_chain(node)
+        self.generic_visit(node)
+
+    def visit_For(self, node: ast.For) -> None:
+        """Analyze for loops for observer pattern opportunities"""
+        self._check_observer_pattern_in_loop(node)
+        self.generic_visit(node)
+
+    def _check_singleton_pattern(self, node: ast.ClassDef) -> None:
+        """Check for singleton pattern usage and anti-patterns"""
+        has_new_method = False
+        has_instance_variable = False
+
+        for item in node.body:
+            if isinstance(item, ast.FunctionDef) and item.name == "__new__":
+                has_new_method = True
+            elif isinstance(item, ast.Assign):
+                for target in item.targets:
+                    if isinstance(target, ast.Name) and target.id == "_instance":
+                        has_instance_variable = True
+
+        # Check for singleton implementation
+        if has_new_method and has_instance_variable:
+            # Check if it's appropriate for singleton
+            if self._is_data_model_class(node.name):
+                self.opportunities.append(
+                    PatternOpportunity(
+                        pattern_name="singleton",
+                        opportunity_type=OpportunityType.ANTI_PATTERN_DETECTED,
+                        confidence=PatternConfidence.CRITICAL,
+                        file_path=self.file_path,
+                        line_number=node.lineno,
+                        line_end=getattr(node, "end_lineno", None),
+                        description=f"Anti-pattern: {node.name} should not be a singleton",
+                        current_code_snippet=f"class {node.name} with singleton implementation",
+                        suggested_improvement="Convert to regular class - data models should have multiple instances",
+                        reasoning="Data models (User, Product, Order, etc.) should not be singletons as you need multiple instances",
+                        effort_estimate="Low",
+                        impact_estimate="High",
+                    )
+                )
+
+        # Check for singleton opportunities
+        elif self._could_benefit_from_singleton(node.name):
+            self.opportunities.append(
+                PatternOpportunity(
+                    pattern_name="singleton",
+                    opportunity_type=OpportunityType.REFACTOR_TO_PATTERN,
+                    confidence=PatternConfidence.MEDIUM,
+                    file_path=self.file_path,
+                    line_number=node.lineno,
+                    line_end=getattr(node, "end_lineno", None),
+                    description=f"{node.name} could benefit from singleton pattern",
+                    current_code_snippet=f"class {node.name}",
+                    suggested_improvement="Implement singleton pattern with thread-safe instance control",
+                    reasoning="Classes like DatabaseConnection, ConfigManager, Logger often benefit from singleton",
+                    effort_estimate="Medium",
+                    impact_estimate="Medium",
+                )
+            )
+
+    def _analyze_constructor(self, node: ast.ClassDef) -> None:
+        """Analyze __init__ method for builder pattern opportunities"""
+        for item in node.body:
+            if isinstance(item, ast.FunctionDef) and item.name == "__init__":
+                param_count = len(item.args.args) - 1  # Exclude 'self'
+
+                # Check for builder pattern opportunity
+                if param_count >= 5:
+                    optional_params = len([arg for arg in item.args.defaults])
+
+                    confidence = (
+                        PatternConfidence.HIGH
+                        if param_count >= 7
+                        else PatternConfidence.MEDIUM
+                    )
+
+                    self.opportunities.append(
+                        PatternOpportunity(
+                            pattern_name="builder",
+                            opportunity_type=OpportunityType.REFACTOR_TO_PATTERN,
+                            confidence=confidence,
+                            file_path=self.file_path,
+                            line_number=item.lineno,
+                            line_end=getattr(item, "end_lineno", None),
+                            description=f"Constructor with {param_count} parameters could benefit from Builder pattern",
+                            current_code_snippet=f"def __init__(self, {param_count} parameters)",
+                            suggested_improvement="Implement Builder pattern for more readable object construction",
+                            reasoning=f"Constructor has {param_count} parameters ({optional_params} optional). Builder pattern threshold: 5+ parameters",
+                            effort_estimate="Medium" if param_count < 8 else "High",
+                            impact_estimate="Medium",
+                        )
+                    )
+                break
+
+    def _analyze_if_elif_chain(self, node: ast.If) -> None:
+        """Analyze if/elif chains for strategy or factory pattern opportunities"""
+        chain_length = 1
+        conditions = []
+        current = node
+
+        # Count the chain length
+        while current:
+            if isinstance(current.test, ast.Compare):
+                # Extract comparison for analysis
+                if hasattr(current.test.left, "id"):
+                    conditions.append(current.test.left.id)
+            elif isinstance(current.test, ast.Call):
+                # isinstance() calls might indicate factory pattern
+                if (
+                    hasattr(current.test.func, "id")
+                    and current.test.func.id == "isinstance"
+                ):
+                    conditions.append("isinstance")
+
+            if (
+                current.orelse
+                and len(current.orelse) == 1
+                and isinstance(current.orelse[0], ast.If)
+            ):
+                current = current.orelse[0]
+                chain_length += 1
+            else:
+                break
+
+        # Strategy pattern opportunity
+        if chain_length >= 3:
+            # Check if it's algorithm selection
+            if self._looks_like_algorithm_selection(node):
+                self.opportunities.append(
+                    PatternOpportunity(
+                        pattern_name="strategy",
+                        opportunity_type=OpportunityType.REFACTOR_TO_PATTERN,
+                        confidence=(
+                            PatternConfidence.HIGH
+                            if chain_length >= 4
+                            else PatternConfidence.MEDIUM
+                        ),
+                        file_path=self.file_path,
+                        line_number=node.lineno,
+                        line_end=getattr(node, "end_lineno", None),
+                        description=f"Long if/elif chain ({chain_length} conditions) suggests Strategy pattern",
+                        current_code_snippet=f"if/elif chain with {chain_length} conditions",
+                        suggested_improvement="Replace with Strategy pattern for better maintainability",
+                        reasoning=f"Chain length {chain_length} exceeds threshold of 3. Strategy pattern helps eliminate conditionals",
+                        effort_estimate="Medium",
+                        impact_estimate="Medium",
+                    )
+                )
+
+        # Factory pattern opportunity
+        if "isinstance" in conditions and chain_length >= 2:
+            self.opportunities.append(
+                PatternOpportunity(
+                    pattern_name="factory",
+                    opportunity_type=OpportunityType.REFACTOR_TO_PATTERN,
+                    confidence=PatternConfidence.MEDIUM,
+                    file_path=self.file_path,
+                    line_number=node.lineno,
+                    line_end=getattr(node, "end_lineno", None),
+                    description="Type-based conditionals suggest Factory pattern",
+                    current_code_snippet="if/elif with isinstance() checks",
+                    suggested_improvement="Use Factory pattern to encapsulate object creation logic",
+                    reasoning="Multiple isinstance() checks indicate object creation based on type",
+                    effort_estimate="Medium",
+                    impact_estimate="Medium",
+                )
+            )
+
+    def _check_observer_pattern_in_loop(self, node: ast.For) -> None:
+        """Check for manual observer pattern implementation in loops"""
+        # Look for notification loops
+        if isinstance(node.iter, ast.Name):
+            iter_name = node.iter.id.lower()
+            if any(
+                keyword in iter_name
+                for keyword in ["observer", "listener", "subscriber", "notification"]
+            ):
+                # Check if loop contains method calls that look like notifications
+                for item in ast.walk(node):
+                    if isinstance(item, ast.Call) and isinstance(
+                        item.func, ast.Attribute
+                    ):
+                        method_name = item.func.attr.lower()
+                        if any(
+                            keyword in method_name
+                            for keyword in ["update", "notify", "on_", "handle"]
+                        ):
+                            self.opportunities.append(
+                                PatternOpportunity(
+                                    pattern_name="observer",
+                                    opportunity_type=OpportunityType.REFACTOR_TO_PATTERN,
+                                    confidence=PatternConfidence.MEDIUM,
+                                    file_path=self.file_path,
+                                    line_number=node.lineno,
+                                    line_end=getattr(node, "end_lineno", None),
+                                    description="Manual observer notification loop detected",
+                                    current_code_snippet=f"for loop over {iter_name} with notification calls",
+                                    suggested_improvement="Implement formal Observer pattern with subscription management",
+                                    reasoning="Manual loops for notifications suggest need for Observer pattern",
+                                    effort_estimate="Low",
+                                    impact_estimate="Medium",
+                                )
+                            )
+                            break
+
+    def _check_factory_pattern(self, node: ast.FunctionDef) -> None:
+        """Check for factory pattern opportunities in functions"""
+        # Look for functions that return different types based on parameters
+        return_statements = []
+        for item in ast.walk(node):
+            if isinstance(item, ast.Return) and item.value:
+                if isinstance(item.value, ast.Call):
+                    return_statements.append(item.value)
+
+        if len(return_statements) >= 2:
+            # Multiple return types might indicate factory pattern
+            self.opportunities.append(
+                PatternOpportunity(
+                    pattern_name="factory",
+                    opportunity_type=OpportunityType.OPTIMIZATION_OPPORTUNITY,
+                    confidence=PatternConfidence.MEDIUM,
+                    file_path=self.file_path,
+                    line_number=node.lineno,
+                    line_end=getattr(node, "end_lineno", None),
+                    description=f"Function {node.name} returns multiple types - consider Factory pattern",
+                    current_code_snippet=f"def {node.name}() with {len(return_statements)} different return types",
+                    suggested_improvement="Formalize as Factory pattern with clear interface",
+                    reasoning=f"Function returns {len(return_statements)} different types, suggesting factory behavior",
+                    effort_estimate="Low",
+                    impact_estimate="Low",
+                )
+            )
+
+    def _check_adapter_pattern(self, node: ast.ClassDef) -> None:
+        """Check for adapter pattern opportunities"""
+        # Look for classes that wrap other objects
+        has_adaptee = False
+        has_delegation = False
+
+        for item in node.body:
+            if isinstance(item, ast.FunctionDef) and item.name == "__init__":
+                # Check if constructor takes another object
+                if len(item.args.args) >= 2:  # self + at least one param
+                    has_adaptee = True
+            elif isinstance(item, ast.FunctionDef):
+                # Check for delegation patterns
+                for subitem in ast.walk(item):
+                    if isinstance(subitem, ast.Attribute) and isinstance(
+                        subitem.value, ast.Name
+                    ):
+                        if subitem.value.id != "self":
+                            has_delegation = True
+                            break
+
+        if has_adaptee and has_delegation:
+            self.opportunities.append(
+                PatternOpportunity(
+                    pattern_name="adapter",
+                    opportunity_type=OpportunityType.OPTIMIZATION_OPPORTUNITY,
+                    confidence=PatternConfidence.LOW,
+                    file_path=self.file_path,
+                    line_number=node.lineno,
+                    line_end=getattr(node, "end_lineno", None),
+                    description=f"Class {node.name} shows adapter-like behavior",
+                    current_code_snippet=f"class {node.name} with delegation pattern",
+                    suggested_improvement="Consider formalizing as Adapter pattern if interfacing incompatible classes",
+                    reasoning="Class takes object in constructor and delegates calls - possible adapter",
+                    effort_estimate="Low",
+                    impact_estimate="Low",
+                )
+            )
+
+    def _analyze_function_body(self, node: ast.FunctionDef) -> None:
+        """Analyze function body for various patterns"""
+        # Check for command pattern opportunities
+        if any(
+            keyword in node.name.lower()
+            for keyword in ["execute", "run", "perform", "do"]
+        ):
+            # Look for state storage that might indicate command pattern
+            has_state_storage = False
+            for item in ast.walk(node):
+                if isinstance(item, ast.Assign):
+                    for target in item.targets:
+                        if isinstance(target, ast.Attribute) and isinstance(
+                            target.value, ast.Name
+                        ):
+                            if target.value.id == "self":
+                                has_state_storage = True
+                                break
+
+            if has_state_storage:
+                self.opportunities.append(
+                    PatternOpportunity(
+                        pattern_name="command",
+                        opportunity_type=OpportunityType.OPTIMIZATION_OPPORTUNITY,
+                        confidence=PatternConfidence.LOW,
+                        file_path=self.file_path,
+                        line_number=node.lineno,
+                        line_end=getattr(node, "end_lineno", None),
+                        description=f"Function {node.name} stores state - consider Command pattern",
+                        current_code_snippet=f"def {node.name}() with state storage",
+                        suggested_improvement="Consider Command pattern if undo/redo or queuing needed",
+                        reasoning="Function stores state and has execution-like name - possible command",
+                        effort_estimate="Medium",
+                        impact_estimate="Low",
+                    )
+                )
+
+    def _detect_patterns(self) -> None:
+        """Detect higher-level patterns from collected data"""
+        # Additional pattern detection logic can be added here
+        pass
+
+    def _is_data_model_class(self, class_name: str) -> bool:
+        """Check if class name suggests it's a data model"""
+        data_model_patterns = [
+            "user",
+            "product",
+            "order",
+            "customer",
+            "item",
+            "model",
+            "entity",
+            "record",
+            "data",
+            "person",
+            "account",
+            "invoice",
+        ]
+        return any(pattern in class_name.lower() for pattern in data_model_patterns)
+
+    def _could_benefit_from_singleton(self, class_name: str) -> bool:
+        """Check if class could benefit from singleton pattern"""
+        singleton_candidates = [
+            "database",
+            "connection",
+            "config",
+            "settings",
+            "logger",
+            "cache",
+            "registry",
+            "manager",
+            "service",
+            "client",
+        ]
+        return any(
+            candidate in class_name.lower() for candidate in singleton_candidates
+        )
+
+    def _looks_like_algorithm_selection(self, node: ast.If) -> bool:
+        """Check if if/elif chain looks like algorithm selection"""
+        # Heuristic: look for different method calls or operations in each branch
+        branches = []
+        current = node
+
+        while current:
+            branch_calls = set()
+            for item in ast.walk(current):
+                if isinstance(item, ast.Call) and isinstance(item.func, ast.Name):
+                    branch_calls.add(item.func.id)
+                elif isinstance(item, ast.Call) and isinstance(
+                    item.func, ast.Attribute
+                ):
+                    branch_calls.add(item.func.attr)
+            branches.append(branch_calls)
+
+            if (
+                current.orelse
+                and len(current.orelse) == 1
+                and isinstance(current.orelse[0], ast.If)
+            ):
+                current = current.orelse[0]
+            else:
+                break
+
+        # If branches have different method calls, likely algorithm selection
+        if len(branches) >= 2:
+            all_calls = set().union(*branches)
+            return len(all_calls) >= len(
+                branches
+            )  # Different algorithms likely use different methods
+
+        return False
+
+
+def analyze_file(file_path: Union[str, Path]) -> List[PatternOpportunity]:
+    """Analyze a single Python file for pattern opportunities"""
+    file_path = Path(file_path)
+
+    if not file_path.exists() or file_path.suffix != ".py":
+        return []
+
+    try:
+        with open(file_path, "r", encoding="utf-8") as f:
+            source_code = f.read()
+
+        analyzer = CodeAnalyzer(str(file_path))
+        return analyzer.analyze_file(source_code)
+
+    except (IOError, UnicodeDecodeError):
+        return []
+
+
+def analyze_directory(
+    directory_path: Union[str, Path], exclude_patterns: Optional[List[str]] = None
+) -> Dict[str, List[PatternOpportunity]]:
+    """Analyze all Python files in a directory for pattern opportunities"""
+    directory_path = Path(directory_path)
+    exclude_patterns = exclude_patterns or [
+        "__pycache__",
+        ".git",
+        ".venv",
+        "venv",
+        "env",
+    ]
+
+    results = {}
+
+    for py_file in directory_path.rglob("*.py"):
+        # Skip excluded directories
+        if any(pattern in str(py_file) for pattern in exclude_patterns):
+            continue
+
+        opportunities = analyze_file(py_file)
+        if opportunities:  # Only include files with opportunities
+            results[str(py_file)] = opportunities
+
+    return results
+
+
+def generate_analysis_report(
+    opportunities_by_file: Dict[str, List[PatternOpportunity]],
+) -> str:
+    """Generate a human-readable analysis report"""
+    total_opportunities = sum(len(ops) for ops in opportunities_by_file.values())
+
+    if total_opportunities == 0:
+        return "🎉 No pattern opportunities detected! Your code looks well-structured."
+
+    report = f"# Pattern Analysis Report\n\n"
+    report += f"**Total Opportunities Found**: {total_opportunities} across {len(opportunities_by_file)} files\n\n"
+
+    # Group by pattern type
+    by_pattern = {}
+    for opportunities in opportunities_by_file.values():
+        for opp in opportunities:
+            if opp.pattern_name not in by_pattern:
+                by_pattern[opp.pattern_name] = []
+            by_pattern[opp.pattern_name].append(opp)
+
+    report += "## Summary by Pattern\n\n"
+    for pattern, opportunities in sorted(by_pattern.items()):
+        count = len(opportunities)
+        high_priority = len([o for o in opportunities if o.priority_score > 0.7])
+        report += f"- **{pattern.title()}**: {count} opportunities ({high_priority} high priority)\n"
+
+    report += "\n## High Priority Opportunities\n\n"
+    all_opportunities = []
+    for opportunities in opportunities_by_file.values():
+        all_opportunities.extend(opportunities)
+
+    high_priority = sorted(
+        [o for o in all_opportunities if o.priority_score > 0.7],
+        key=lambda x: x.priority_score,
+        reverse=True,
+    )
+
+    for i, opp in enumerate(high_priority[:10], 1):  # Top 10
+        report += f"### {i}. {opp.pattern_name.title()} Pattern\n"
+        report += f"**File**: {opp.file_path}:{opp.line_number}\n"
+        report += f"**Confidence**: {opp.confidence.value.title()}\n"
+        report += f"**Description**: {opp.description}\n"
+        report += f"**Reasoning**: {opp.reasoning}\n"
+        report += (
+            f"**Effort**: {opp.effort_estimate} | **Impact**: {opp.impact_estimate}\n\n"
+        )
+
+    if len(high_priority) > 10:
+        report += (
+            f"... and {len(high_priority) - 10} more high priority opportunities.\n\n"
+        )
+
+    return report
diff --git a/ai-engine/pattern_knowledge.py b/ai-engine/pattern_knowledge.py
new file mode 100644
index 0000000..451b4e4
--- /dev/null
+++ b/ai-engine/pattern_knowledge.py
@@ -0,0 +1,1100 @@
+"""
+Design Pattern Knowledge Base for Intelligent Recommendations
+
+This module contains structured knowledge extracted from the design patterns
+tutorial notebooks to power intelligent pattern recommendations.
+"""
+
+from dataclasses import dataclass
+from enum import Enum
+from typing import Dict, List, Optional, Tuple
+
+
+class ComplexityLevel(Enum):
+    """Complexity levels for pattern usage scenarios"""
+
+    SIMPLE = "simple"
+    MODERATE = "moderate"
+    COMPLEX = "complex"
+    ENTERPRISE = "enterprise"
+
+
+class PatternConfidence(Enum):
+    """Confidence levels for pattern recommendations"""
+
+    LOW = "low"  # 0-40% - Pattern might help but alternatives exist
+    MEDIUM = "medium"  # 40-70% - Pattern is a good fit
+    HIGH = "high"  # 70-90% - Pattern strongly recommended
+    CRITICAL = "critical"  # 90%+ - Pattern is essential for this scenario
+
+
+@dataclass
+class PatternCriteria:
+    """Criteria for when to use a pattern"""
+
+    minimum_complexity: ComplexityLevel
+    indicators: List[str]  # Phrases/scenarios that suggest this pattern
+    thresholds: Dict[str, int]  # Numeric thresholds (e.g., "algorithms": 3)
+    use_cases: List[str]
+    benefits: List[str]
+
+
+@dataclass
+class AntiPatternCriteria:
+    """Criteria for when NOT to use a pattern"""
+
+    red_flags: List[str]  # Phrases that indicate pattern misuse
+    scenarios_to_avoid: List[str]
+    better_alternatives: List[str]
+    common_mistakes: List[str]
+
+
+@dataclass
+class AdvancedScenarios:
+    """Advanced scenarios and optimizations for patterns"""
+
+    threading_considerations: Optional[str]
+    performance_implications: Optional[str]
+    testing_challenges: Optional[str]
+    optimization_tips: Optional[str]
+    enterprise_considerations: Optional[str]
+
+
+@dataclass
+class PatternKnowledge:
+    """Complete knowledge about a design pattern"""
+
+    name: str
+    category: str  # creational, structural, behavioral
+    description: str
+    when_to_use: PatternCriteria
+    when_not_to_use: AntiPatternCriteria
+    advanced: AdvancedScenarios
+    alternatives: List[str]
+    complexity_score: int  # 1-10, how complex the pattern is to implement
+    learning_difficulty: int  # 1-10, how hard it is to understand
+
+
+# Knowledge Base - Structured data from extracted notebook analysis
+PATTERN_KNOWLEDGE: Dict[str, PatternKnowledge] = {
+    "singleton": PatternKnowledge(
+        name="Singleton Pattern",
+        category="creational",
+        description="Ensures a class has only one instance with global access",
+        when_to_use=PatternCriteria(
+            minimum_complexity=ComplexityLevel.MODERATE,
+            indicators=[
+                "single instance",
+                "only one",
+                "global access",
+                "shared state",
+                "database connection",
+                "configuration",
+                "logging",
+                "cache",
+            ],
+            thresholds={
+                "expensive_creation": 1,  # If object creation is expensive
+                "global_access_points": 2,  # If accessed from 2+ places
+            },
+            use_cases=[
+                "Database connections - expensive to create, should be shared",
+                "Configuration settings - one source of truth needed",
+                "Logging systems - centralized logging required",
+                "Caching mechanisms - shared cache across application",
+            ],
+            benefits=[
+                "Controlled access to sole instance",
+                "Reduced memory footprint",
+                "Global access point",
+                "Lazy initialization",
+            ],
+        ),
+        when_not_to_use=AntiPatternCriteria(
+            red_flags=[
+                "just want global variables",
+                "testing is important",
+                "multiple instances later",
+                "simple objects",
+                "data models",
+                "user objects",
+                "entity classes",
+            ],
+            scenarios_to_avoid=[
+                "You just want global variables - Use modules instead",
+                "Testing is important - Singletons are hard to test and mock",
+                "You might need multiple instances later - Don't paint yourself into a corner",
+                "Simple objects - Don't over-engineer basic data structures",
+                "Data models - User, Product, Order should NOT be singletons",
+            ],
+            better_alternatives=[
+                "Module-level variables for simple global state",
+                "Dependency injection for better testability",
+                "Configuration objects passed as parameters",
+                "Context managers for resource control",
+            ],
+            common_mistakes=[
+                "Not handling thread safety in concurrent environments",
+                "Using for data objects (User, Product entities)",
+                "Overuse - creating singletons when regular classes suffice",
+                "Making everything singleton for 'consistency'",
+            ],
+        ),
+        advanced=AdvancedScenarios(
+            threading_considerations="""
+            Use threading.Lock() for multi-threaded applications:
+            - Double-check locking pattern: Check instance exists, acquire lock, check again
+            - Performance consideration: First check without lock for efficiency
+            - Separate locks for different operations if needed
+            """,
+            performance_implications="""
+            - Lazy initialization can improve startup time
+            - Thread-safe versions have small locking overhead
+            - Consider eager initialization for heavily used singletons
+            """,
+            testing_challenges="""
+            - Hard to mock for unit testing
+            - State pollution between tests
+            - Consider dependency injection alternatives
+            - Use setUp/tearDown to reset singleton state
+            """,
+            optimization_tips="""
+            - Use __new__ method for instance control
+            - Consider metaclass approach for cleaner syntax
+            - Implement proper __init__ guard with hasattr check
+            """,
+            enterprise_considerations="""
+            - Document singleton lifecycle clearly
+            - Consider configuration-driven creation
+            - Plan for distributed systems (singletons don't scale across processes)
+            """,
+        ),
+        alternatives=[
+            "Module-level variables",
+            "Dependency injection",
+            "Monostate pattern",
+            "Registry pattern",
+        ],
+        complexity_score=6,
+        learning_difficulty=4,
+    ),
+    "factory": PatternKnowledge(
+        name="Factory Pattern",
+        category="creational",
+        description="Creates objects without specifying their exact classes",
+        when_to_use=PatternCriteria(
+            minimum_complexity=ComplexityLevel.MODERATE,
+            indicators=[
+                "create different types",
+                "multiple classes",
+                "configuration-driven",
+                "switch implementations",
+                "object creation",
+                "similar classes",
+            ],
+            thresholds={
+                "similar_classes": 3,  # 3+ similar classes doing same job
+                "creation_complexity": 5,  # If creation logic > 5 lines
+            },
+            use_cases=[
+                "3+ similar classes that do the same job differently",
+                "Complex object creation requiring multiple steps or decisions",
+                "Configuration-driven creation - object type depends on config",
+                "Need to switch implementations at runtime",
+            ],
+            benefits=[
+                "Decouples object creation from usage",
+                "Easy to add new types without changing client code",
+                "Centralizes creation logic",
+                "Supports polymorphism",
+            ],
+        ),
+        when_not_to_use=AntiPatternCriteria(
+            red_flags=[
+                "only one class",
+                "simple object creation",
+                "over-engineering",
+                "performance critical",
+                "just in case",
+            ],
+            scenarios_to_avoid=[
+                "Only one class - Don't create factory for just one type",
+                "Simple object creation - If MyClass() is simple enough",
+                "Over-engineering - Don't add factories 'just in case'",
+                "Performance critical sections - Factories add small overhead",
+            ],
+            better_alternatives=[
+                "Function parameters for small variations",
+                "Enums with switch statements for fixed options",
+                "Configuration files for simple behavior changes",
+                "Direct instantiation for simple cases",
+            ],
+            common_mistakes=[
+                "Creating factory for single class",
+                "Adding factory complexity before it's needed",
+                "Not using polymorphism effectively",
+            ],
+        ),
+        advanced=AdvancedScenarios(
+            threading_considerations="""
+            - Factory methods should be thread-safe if called concurrently
+            - Consider caching created objects with proper synchronization
+            - Abstract Factory pattern needs thread-safe family switching
+            """,
+            performance_implications="""
+            - Small overhead from factory method calls
+            - Consider object pooling for expensive objects
+            - Cache factories themselves if creation is expensive
+            """,
+            testing_challenges="""
+            - Mock factory for testing client code
+            - Test each factory method separately
+            - Verify correct type is created for each input
+            """,
+            optimization_tips="""
+            - Use Simple Factory for basic object creation
+            - Factory Method when subclasses decide what to create
+            - Abstract Factory for families of related products
+            """,
+            enterprise_considerations="""
+            - Document which factory to use for each scenario
+            - Consider plugin architecture with factory registration
+            - Plan for dependency injection integration
+            """,
+        ),
+        alternatives=[
+            "Direct instantiation",
+            "Builder pattern for complex construction",
+            "Prototype pattern for cloning",
+            "Service locator pattern",
+        ],
+        complexity_score=5,
+        learning_difficulty=3,
+    ),
+    "observer": PatternKnowledge(
+        name="Observer Pattern",
+        category="behavioral",
+        description="Defines one-to-many dependency between objects for automatic notifications",
+        when_to_use=PatternCriteria(
+            minimum_complexity=ComplexityLevel.MODERATE,
+            indicators=[
+                "subscribe",
+                "notify",
+                "listen",
+                "event",
+                "update",
+                "broadcast",
+                "model-view",
+                "real-time",
+                "multiple listeners",
+                "one-to-many",
+            ],
+            thresholds={
+                "observers": 2,  # 2+ objects need to be notified
+                "event_types": 1,  # Any event-driven scenario
+                "update_frequency": 1,  # Regular updates needed
+            },
+            use_cases=[
+                "Model-View architectures - views update when model changes",
+                "Event-driven systems - user actions, system events",
+                "Real-time updates - stock prices, chat, live dashboards",
+                "One-to-many relationships - one subject, many observers",
+            ],
+            benefits=[
+                "Loose coupling between subject and observers",
+                "Dynamic relationships - add/remove observers at runtime",
+                "Broadcast communication",
+                "Supports event-driven architectures",
+            ],
+        ),
+        when_not_to_use=AntiPatternCriteria(
+            red_flags=[
+                "simple data binding",
+                "performance critical",
+                "complex update sequences",
+                "only one observer",
+                "order dependencies",
+            ],
+            scenarios_to_avoid=[
+                "Simple data binding - direct references might be simpler",
+                "Performance critical code - observer pattern adds notification overhead",
+                "Complex update sequences - order dependencies make it confusing",
+                "Only one observer - direct method calls are clearer",
+            ],
+            better_alternatives=[
+                "Direct method calls for single observer",
+                "Callback functions for simple notifications",
+                "Event queues for decoupled async communication",
+                "Property setters for simple data binding",
+            ],
+            common_mistakes=[
+                "Forgetting to unsubscribe - leads to memory leaks",
+                "Circular dependencies - Observer A updates Observer B which updates A",
+                "Complex update chains - hard to debug event propagation",
+                "Not considering notification order",
+            ],
+        ),
+        advanced=AdvancedScenarios(
+            threading_considerations="""
+            - Thread-safe notifications: protect observer list with locks
+            - Separate lock for data: don't block notifications while updating
+            - Async event handling: consider event queues for complex scenarios
+            - Weak references to prevent memory leaks in threaded environments
+            """,
+            performance_implications="""
+            - Push vs Pull models: Push is efficient, Pull is flexible
+            - Large observer lists: consider asynchronous notifications
+            - Memory leaks: ensure observers are properly removed
+            - Event filtering to reduce unnecessary notifications
+            """,
+            testing_challenges="""
+            - Mock observers for testing subject behavior
+            - Test observer registration/unregistration
+            - Verify notification order if it matters
+            - Test memory cleanup (no lingering references)
+            """,
+            optimization_tips="""
+            - Use weak references to prevent memory leaks
+            - Implement event filtering for performance
+            - Consider async notifications for non-critical updates
+            - Batch notifications when possible
+            """,
+            enterprise_considerations="""
+            - Document event contracts and data structures
+            - Consider event sourcing for audit trails
+            - Plan for distributed observers (message queues)
+            - Implement proper error handling in notifications
+            """,
+        ),
+        alternatives=[
+            "Callback functions",
+            "Event queues/message brokers",
+            "Reactive programming (RxPY)",
+            "Signals/slots mechanism",
+        ],
+        complexity_score=6,
+        learning_difficulty=5,
+    ),
+    "strategy": PatternKnowledge(
+        name="Strategy Pattern",
+        category="behavioral",
+        description="Defines family of algorithms and makes them interchangeable",
+        when_to_use=PatternCriteria(
+            minimum_complexity=ComplexityLevel.MODERATE,
+            indicators=[
+                "multiple algorithms",
+                "different ways",
+                "switch algorithm",
+                "runtime selection",
+                "eliminate conditionals",
+                "A/B testing",
+            ],
+            thresholds={
+                "algorithms": 3,  # 3+ algorithms for same problem
+                "conditional_lines": 10,  # Replace if/elif chains >10 lines
+                "algorithm_complexity": 5,  # Each algorithm >5 lines
+            },
+            use_cases=[
+                "3+ algorithms for the same problem (sorting, compression)",
+                "Runtime algorithm switching based on data or user preference",
+                "Eliminating conditionals - replace long if/else chains",
+                "A/B testing - easily switch between implementations",
+            ],
+            benefits=[
+                "Easy to add new algorithms",
+                "Runtime algorithm selection",
+                "Eliminates conditional statements",
+                "Each algorithm can be tested separately",
+            ],
+        ),
+        when_not_to_use=AntiPatternCriteria(
+            red_flags=[
+                "only one algorithm",
+                "simple variations",
+                "algorithms rarely change",
+                "performance critical",
+                "two simple cases",
+            ],
+            scenarios_to_avoid=[
+                "Only one algorithm - don't create strategies for single implementations",
+                "Simple variations - use parameters instead of separate strategies",
+                "Algorithms rarely change - if you'll never switch, don't add overhead",
+                "Performance critical - strategy pattern adds method call overhead",
+            ],
+            better_alternatives=[
+                "Function parameters for small variations",
+                "Configuration objects for behavior customization",
+                "Template methods for algorithms with similar structure",
+                "Simple if/else for 2-3 cases",
+            ],
+            common_mistakes=[
+                "Creating strategy for single algorithm",
+                "Not making strategies truly interchangeable",
+                "Over-engineering simple conditional logic",
+            ],
+        ),
+        advanced=AdvancedScenarios(
+            threading_considerations="""
+            - Strategies should be stateless for thread safety
+            - If state needed, ensure proper synchronization
+            - Strategy selection logic must be thread-safe
+            """,
+            performance_implications="""
+            - Small overhead from strategy method calls
+            - Consider caching strategy instances
+            - Profile different strategies for performance comparison
+            """,
+            testing_challenges="""
+            - Test each strategy individually
+            - Mock strategies for testing context
+            - Test strategy selection logic
+            - Performance testing for strategy comparison
+            """,
+            optimization_tips="""
+            - Data-driven selection: choose based on input characteristics
+            - Smart strategy selection: automatic choice based on context
+            - Combine with Factory pattern for strategy creation
+            """,
+            enterprise_considerations="""
+            - Document strategy selection criteria
+            - Consider configuration-driven strategy selection
+            - Plan for strategy versioning and backwards compatibility
+            """,
+        ),
+        alternatives=[
+            "Function pointers/higher-order functions",
+            "Template method pattern",
+            "State pattern for behavior changes",
+            "Command pattern for action selection",
+        ],
+        complexity_score=4,
+        learning_difficulty=3,
+    ),
+    "command": PatternKnowledge(
+        name="Command Pattern",
+        category="behavioral",
+        description="Encapsulates requests as objects to parameterize and queue operations",
+        when_to_use=PatternCriteria(
+            minimum_complexity=ComplexityLevel.MODERATE,
+            indicators=[
+                "undo",
+                "redo",
+                "queue",
+                "macro",
+                "log operations",
+                "parameterize objects",
+                "decouple invoker",
+                "store operations",
+            ],
+            thresholds={
+                "operations_to_track": 1,  # Any operation that needs undo/logging
+                "macro_commands": 2,  # 2+ commands to combine
+                "queue_size": 1,  # Any queuing requirement
+            },
+            use_cases=[
+                "Undo/redo operations - commands store state for reversal",
+                "Macro recording - combine multiple commands",
+                "Queue operations - store commands for later execution",
+                "Logging and auditing - track all operations performed",
+            ],
+            benefits=[
+                "Decouples invoker from receiver",
+                "Commands can be stored and queued",
+                "Supports undo/redo functionality",
+                "Easy to create macro commands",
+            ],
+        ),
+        when_not_to_use=AntiPatternCriteria(
+            red_flags=[
+                "simple operations",
+                "no undo needed",
+                "performance critical",
+                "tight coupling acceptable",
+                "basic getters",
+            ],
+            scenarios_to_avoid=[
+                "Simple operations - don't create commands for basic method calls",
+                "No undo needed - if operations are irreversible and logging not needed",
+                "Performance critical - command objects add overhead",
+                "Tight coupling acceptable - when invoker can directly call receiver",
+            ],
+            better_alternatives=[
+                "Direct method calls for simple operations",
+                "Function pointers for parameterization",
+                "Event systems for decoupling",
+                "Transaction objects for complex operations",
+            ],
+            common_mistakes=[
+                "Creating commands for every operation",
+                "Not implementing proper undo logic",
+                "Making commands too granular",
+            ],
+        ),
+        advanced=AdvancedScenarios(
+            threading_considerations="""
+            - Commands should be immutable for thread safety
+            - Command queues need proper synchronization
+            - Undo stack access must be thread-safe
+            """,
+            performance_implications="""
+            - Command objects add memory overhead
+            - Consider object pooling for frequently used commands
+            - Limit undo history size to prevent memory issues
+            """,
+            testing_challenges="""
+            - Test command execution and undo separately
+            - Mock receivers for testing command logic
+            - Test macro command composition
+            """,
+            optimization_tips="""
+            - Use for complex operations that need undo/redo
+            - Overkill for simple actions like getters/setters
+            - Valuable for GUI applications with menu/button actions
+            """,
+            enterprise_considerations="""
+            - Document command contracts and side effects
+            - Consider command versioning for system evolution
+            - Plan for command serialization and persistence
+            """,
+        ),
+        alternatives=[
+            "Direct method calls",
+            "Function objects/lambdas",
+            "Event sourcing",
+            "Transaction scripts",
+        ],
+        complexity_score=6,
+        learning_difficulty=5,
+    ),
+    "builder": PatternKnowledge(
+        name="Builder Pattern",
+        category="creational",
+        description="Constructs complex objects step by step with fluent interface",
+        when_to_use=PatternCriteria(
+            minimum_complexity=ComplexityLevel.MODERATE,
+            indicators=[
+                "complex construction",
+                "many parameters",
+                "optional parameters",
+                "step by step",
+                "fluent interface",
+                "validation during construction",
+            ],
+            thresholds={
+                "constructor_parameters": 5,  # 5+ constructor parameters
+                "optional_parameters": 3,  # 3+ optional parameters
+                "construction_steps": 3,  # 3+ construction steps
+            },
+            use_cases=[
+                "Objects with many optional parameters (5+ parameters)",
+                "Step-by-step construction with validation at each step",
+                "Immutable objects that need complex construction",
+                "Objects where construction order matters",
+            ],
+            benefits=[
+                "Readable object construction",
+                "Handles optional parameters elegantly",
+                "Validates during construction",
+                "Supports fluent interface",
+            ],
+        ),
+        when_not_to_use=AntiPatternCriteria(
+            red_flags=[
+                "few properties",
+                "simple construction",
+                "no variation in process",
+                "performance critical",
+                "immutable not needed",
+            ],
+            scenarios_to_avoid=[
+                "Few properties - don't use builder for 2-3 simple parameters",
+                "Simple construction - regular constructor is clearer",
+                "No variation in process - builder adds unnecessary complexity",
+                "Performance critical - builder adds method call overhead",
+            ],
+            better_alternatives=[
+                "Regular constructors for simple objects",
+                "Dataclasses with defaults for data containers",
+                "Factory methods for complex creation logic",
+                "Keyword arguments for optional parameters",
+            ],
+            common_mistakes=[
+                "Using builder for simple objects",
+                "Not validating during construction",
+                "Making builder mutable when building immutable objects",
+            ],
+        ),
+        advanced=AdvancedScenarios(
+            threading_considerations="""
+            - Builders should not be shared between threads
+            - Built objects can be immutable for thread safety
+            - Consider builder pools for performance
+            """,
+            performance_implications="""
+            - Method chaining adds small overhead
+            - Consider direct construction for performance-critical paths
+            - Builder object creation adds memory overhead
+            """,
+            testing_challenges="""
+            - Test builder validation at each step
+            - Test different construction paths
+            - Verify immutability of built objects
+            """,
+            optimization_tips="""
+            - Use for complex objects with validation requirements
+            - Consider fluent interface for better readability
+            - Implement proper validation and error handling
+            """,
+            enterprise_considerations="""
+            - Document required vs optional construction steps
+            - Consider builder inheritance for object families
+            - Plan for configuration-driven object construction
+            """,
+        ),
+        alternatives=[
+            "Dataclasses with defaults",
+            "Factory methods",
+            "Keyword arguments",
+            "Configuration objects",
+        ],
+        complexity_score=5,
+        learning_difficulty=4,
+    ),
+    "adapter": PatternKnowledge(
+        name="Adapter Pattern",
+        category="structural",
+        description="Allows incompatible interfaces to work together",
+        when_to_use=PatternCriteria(
+            minimum_complexity=ComplexityLevel.SIMPLE,
+            indicators=[
+                "incompatible interfaces",
+                "third-party integration",
+                "legacy system",
+                "cannot modify",
+                "interface mismatch",
+                "wrapper needed",
+            ],
+            thresholds={
+                "interface_differences": 1,  # Any interface incompatibility
+                "modification_restrictions": 1,  # Cannot modify existing code
+            },
+            use_cases=[
+                "Incompatible interfaces between existing classes",
+                "Third-party library integration with different interface",
+                "Legacy system integration without modifying old code",
+                "Making old interface work with new system",
+            ],
+            benefits=[
+                "Reuses existing code without modification",
+                "Separates interface concerns from business logic",
+                "Allows incompatible classes to work together",
+                "Follows open/closed principle",
+            ],
+        ),
+        when_not_to_use=AntiPatternCriteria(
+            red_flags=[
+                "interfaces already compatible",
+                "can modify existing classes",
+                "too complex adaptation",
+                "performance critical",
+            ],
+            scenarios_to_avoid=[
+                "Interfaces already compatible - no adapter needed",
+                "Can modify existing classes - direct modification is simpler",
+                "Too complex adaptation - consider redesigning interfaces",
+                "Performance critical - adapter adds indirection overhead",
+            ],
+            better_alternatives=[
+                "Direct interface modification if possible",
+                "Interface inheritance for compatible types",
+                "Composition for simple wrapping",
+                "Facade pattern for complex subsystem integration",
+            ],
+            common_mistakes=[
+                "Over-adapting simple interface differences",
+                "Not handling all methods of adapted interface",
+                "Making adapter do too much business logic",
+            ],
+        ),
+        advanced=AdvancedScenarios(
+            threading_considerations="""
+            - Adapter should delegate threading concerns to adaptee
+            - Consider thread-safe adaptation if adaptee is not thread-safe
+            - Synchronization needed if adapter maintains state
+            """,
+            performance_implications="""
+            - Adds one level of indirection
+            - Consider caching adapted results if expensive
+            - Object adapter vs class adapter performance trade-offs
+            """,
+            testing_challenges="""
+            - Test adapter with mock adaptee
+            - Verify all interface methods are properly adapted
+            - Test error handling and edge cases
+            """,
+            optimization_tips="""
+            - Keep adapter thin - delegate to adaptee
+            - Consider two-way adapters for bidirectional compatibility
+            - Object adapter for runtime flexibility, class adapter for compile-time
+            """,
+            enterprise_considerations="""
+            - Document adaptation contracts and limitations
+            - Consider adapter versioning for API evolution
+            - Plan for multiple adapter implementations
+            """,
+        ),
+        alternatives=[
+            "Direct interface modification",
+            "Facade pattern",
+            "Wrapper functions",
+            "Interface inheritance",
+        ],
+        complexity_score=3,
+        learning_difficulty=2,
+    ),
+    "decorator": PatternKnowledge(
+        name="Decorator Pattern",
+        category="structural",
+        description="Adds behavior to objects dynamically without altering structure",
+        when_to_use=PatternCriteria(
+            minimum_complexity=ComplexityLevel.MODERATE,
+            indicators=[
+                "add responsibilities",
+                "multiple features",
+                "transparent enhancement",
+                "composable behaviors",
+                "avoid inheritance explosion",
+            ],
+            thresholds={
+                "optional_features": 3,  # 3+ optional features to add
+                "feature_combinations": 4,  # 4+ possible combinations
+                "inheritance_levels": 3,  # Would need 3+ inheritance levels
+            },
+            use_cases=[
+                "Add responsibilities dynamically without inheritance",
+                "Multiple feature combinations - avoid class explosion",
+                "Transparent enhancement - client doesn't know about decoration",
+                "Composable behaviors - stack multiple decorators",
+            ],
+            benefits=[
+                "More flexible than inheritance",
+                "Adds responsibilities at runtime",
+                "Supports composition of behaviors",
+                "Follows single responsibility principle",
+            ],
+        ),
+        when_not_to_use=AntiPatternCriteria(
+            red_flags=[
+                "component interface too complex",
+                "fixed combinations",
+                "performance critical",
+                "simple objects",
+            ],
+            scenarios_to_avoid=[
+                "Component interface is too complex - decorators need to implement all methods",
+                "Fixed set of combinations - regular inheritance might be simpler",
+                "Performance critical - each decorator adds indirection layer",
+                "Simple objects - don't over-engineer basic data",
+            ],
+            better_alternatives=[
+                "Inheritance for fixed combinations",
+                "Composition for simple wrapping",
+                "Mixins for multiple inheritance languages",
+                "Strategy pattern for algorithmic variations",
+            ],
+            common_mistakes=[
+                "Making decorators too complex",
+                "Not maintaining component interface properly",
+                "Using for simple feature additions",
+            ],
+        ),
+        advanced=AdvancedScenarios(
+            threading_considerations="""
+            - Decorators should be thread-safe if component is thread-safe
+            - Consider decorator state synchronization
+            - Nested decorators may need coordinated locking
+            """,
+            performance_implications="""
+            - Each decorator level adds method call overhead
+            - Consider decorator ordering for performance
+            - May increase memory usage with deep nesting
+            """,
+            testing_challenges="""
+            - Test individual decorators separately
+            - Test decorator combinations and stacking
+            - Mock underlying components for isolation
+            """,
+            optimization_tips="""
+            - 3+ optional features make decorator valuable
+            - Avoid for simple objects with basic decorations
+            - Consider inheritance for 2-3 features
+            """,
+            enterprise_considerations="""
+            - Document decorator composition rules
+            - Consider decorator registration/discovery mechanisms
+            - Plan for decorator configuration and ordering
+            """,
+        ),
+        alternatives=[
+            "Inheritance hierarchies",
+            "Composition",
+            "Mixins",
+            "Aspect-oriented programming",
+        ],
+        complexity_score=7,
+        learning_difficulty=6,
+    ),
+    "state": PatternKnowledge(
+        name="State Pattern",
+        category="behavioral",
+        description="Allows object to alter behavior when internal state changes",
+        when_to_use=PatternCriteria(
+            minimum_complexity=ComplexityLevel.MODERATE,
+            indicators=[
+                "behavior depends on state",
+                "finite state machine",
+                "state transitions",
+                "workflow",
+                "different behavior",
+                "state-dependent",
+            ],
+            thresholds={
+                "states": 3,  # 3+ distinct states
+                "state_transitions": 3,  # 3+ possible transitions
+                "behavior_differences": 5,  # Significant behavior differences
+            },
+            use_cases=[
+                "Behavior depends on object state (game character abilities)",
+                "Complex conditionals based on state - replace if/else chains",
+                "Finite state machines - clear states and transitions",
+                "Workflow systems - document approval, order processing",
+            ],
+            benefits=[
+                "Eliminates complex conditional statements",
+                "Makes state transitions explicit",
+                "Easy to add new states",
+                "Each state encapsulates its behavior",
+            ],
+        ),
+        when_not_to_use=AntiPatternCriteria(
+            red_flags=[
+                "few states",
+                "simple behavior",
+                "rare state changes",
+                "simple logic",
+                "performance critical",
+            ],
+            scenarios_to_avoid=[
+                "Few states with simple behavior - enum + match might be simpler",
+                "Rare state changes - overhead not justified",
+                "Simple logic - don't over-engineer basic conditionals",
+                "Performance critical - state objects add overhead",
+            ],
+            better_alternatives=[
+                "Enum + match statements for simple states",
+                "Strategy pattern for algorithmic variations",
+                "Simple boolean flags for binary states",
+                "Command pattern for action-based behavior",
+            ],
+            common_mistakes=[
+                "Using for simple boolean states",
+                "Not handling all state transitions properly",
+                "Making states too granular",
+            ],
+        ),
+        advanced=AdvancedScenarios(
+            threading_considerations="""
+            - State transitions must be atomic in concurrent environments
+            - Consider state change notifications for observers
+            - Guard state access with proper synchronization
+            """,
+            performance_implications="""
+            - State object creation overhead
+            - Consider state object pooling
+            - Method delegation adds small overhead
+            """,
+            testing_challenges="""
+            - Test each state behavior individually
+            - Test state transitions and edge cases
+            - Verify invalid transition handling
+            """,
+            optimization_tips="""
+            - Use when you have 3+ states with different behaviors
+            - Consider if/else for 2-3 simple states
+            - Valuable for game entities, workflow systems
+            """,
+            enterprise_considerations="""
+            - Document state machine diagrams
+            - Consider state persistence and restoration
+            - Plan for state machine configuration and validation
+            """,
+        ),
+        alternatives=[
+            "Enum + match statements",
+            "Strategy pattern",
+            "Boolean flags",
+            "Finite state machine libraries",
+        ],
+        complexity_score=7,
+        learning_difficulty=6,
+    ),
+    "repository": PatternKnowledge(
+        name="Repository Pattern",
+        category="behavioral",
+        description="Centralizes data access logic and provides uniform interface",
+        when_to_use=PatternCriteria(
+            minimum_complexity=ComplexityLevel.MODERATE,
+            indicators=[
+                "data access",
+                "multiple data sources",
+                "testability",
+                "domain logic",
+                "centralize queries",
+                "abstract storage",
+            ],
+            thresholds={
+                "data_sources": 1,  # Any data access needs
+                "complex_queries": 3,  # 3+ different query types
+                "entities": 2,  # 2+ entity types with data access
+            },
+            use_cases=[
+                "Centralizing data access logic across application",
+                "Supporting multiple data sources (database, file, API)",
+                "Improving testability by abstracting data layer",
+                "Domain-driven design - isolate domain from infrastructure",
+            ],
+            benefits=[
+                "Centralizes data access logic",
+                "Easy to switch data sources",
+                "Improves testability with mock repositories",
+                "Separates domain logic from data access",
+            ],
+        ),
+        when_not_to_use=AntiPatternCriteria(
+            red_flags=[
+                "simple applications",
+                "ORM already provides abstraction",
+                "unjustified overhead",
+                "single data source",
+            ],
+            scenarios_to_avoid=[
+                "Simple applications - CRUD operations don't need repository layer",
+                "ORM already provides abstraction - don't add another layer",
+                "Unjustified overhead - repositories add complexity",
+                "Single data source with no switching plans",
+            ],
+            better_alternatives=[
+                "Direct ORM usage for simple applications",
+                "Data Access Objects (DAO) for simple CRUD",
+                "Active Record pattern for simple models",
+                "Query builders for dynamic queries",
+            ],
+            common_mistakes=[
+                "Making repository too generic (generic repository anti-pattern)",
+                "Putting business logic in repository",
+                "Not using Unit of Work pattern with repositories",
+            ],
+        ),
+        advanced=AdvancedScenarios(
+            threading_considerations="""
+            - Repository implementations must be thread-safe
+            - Consider connection pooling for database repositories
+            - Cache synchronization across threads
+            """,
+            performance_implications="""
+            - Additional abstraction layer overhead
+            - Consider caching strategies within repository
+            - Bulk operations for better performance
+            """,
+            testing_challenges="""
+            - Mock repositories for unit testing
+            - Integration tests with real data sources
+            - Test data consistency and transactions
+            """,
+            optimization_tips="""
+            - Use for complex queries and multiple data sources
+            - Consider Unit of Work pattern for transaction management
+            - Implement proper caching strategies
+            """,
+            enterprise_considerations="""
+            - Document repository contracts and capabilities
+            - Consider repository composition for complex scenarios
+            - Plan for distributed data sources and eventual consistency
+            """,
+        ),
+        alternatives=[
+            "Direct ORM usage",
+            "Data Access Objects (DAO)",
+            "Active Record pattern",
+            "Query builders",
+        ],
+        complexity_score=6,
+        learning_difficulty=5,
+    ),
+}
+
+
+def get_pattern_by_name(pattern_name: str) -> Optional[PatternKnowledge]:
+    """Get pattern knowledge by name (case-insensitive)"""
+    return PATTERN_KNOWLEDGE.get(pattern_name.lower())
+
+
+def get_patterns_by_category(category: str) -> List[PatternKnowledge]:
+    """Get all patterns in a specific category"""
+    return [p for p in PATTERN_KNOWLEDGE.values() if p.category == category]
+
+
+def find_patterns_by_indicators(indicators: List[str]) -> List[Tuple[str, float]]:
+    """
+    Find patterns that match given indicators with confidence scores
+    Returns list of (pattern_name, confidence_score) tuples
+    """
+    results = []
+
+    for pattern_name, knowledge in PATTERN_KNOWLEDGE.items():
+        score = 0.0
+        total_indicators = len(knowledge.when_to_use.indicators)
+
+        for indicator in indicators:
+            indicator_lower = indicator.lower()
+            for pattern_indicator in knowledge.when_to_use.indicators:
+                if indicator_lower in pattern_indicator.lower():
+                    score += 1.0 / total_indicators
+
+        if score > 0:
+            results.append((pattern_name, min(score, 1.0)))
+
+    return sorted(results, key=lambda x: x[1], reverse=True)
+
+
+def check_anti_patterns(description: str) -> List[Tuple[str, str]]:
+    """
+    Check for anti-pattern indicators in problem description
+    Returns list of (pattern_name, warning_message) tuples
+    """
+    warnings = []
+    description_lower = description.lower()
+
+    for pattern_name, knowledge in PATTERN_KNOWLEDGE.items():
+        for red_flag in knowledge.when_not_to_use.red_flags:
+            if red_flag.lower() in description_lower:
+                warning = (
+                    f"⚠️ Potential {pattern_name} anti-pattern detected: {red_flag}"
+                )
+                warnings.append((pattern_name, warning))
+
+    return warnings
+
+
+def get_complexity_recommendation(
+    pattern_name: str, scenario_complexity: ComplexityLevel
+) -> str:
+    """Get recommendation based on scenario complexity vs pattern requirements"""
+    knowledge = get_pattern_by_name(pattern_name)
+    if not knowledge:
+        return "Pattern not found"
+
+    if scenario_complexity.value < knowledge.when_to_use.minimum_complexity.value:
+        return f"⚠️ {knowledge.name} might be overkill for {scenario_complexity.value} scenarios"
+    else:
+        return f"✅ {knowledge.name} is appropriate for {scenario_complexity.value} scenarios"
diff --git a/ai-engine/refactoring_templates.py b/ai-engine/refactoring_templates.py
new file mode 100644
index 0000000..7143f0c
--- /dev/null
+++ b/ai-engine/refactoring_templates.py
@@ -0,0 +1,774 @@
+"""
+Refactoring Templates for Design Pattern Implementation
+
+This module provides before/after examples and transformation templates
+for implementing design patterns based on the repository's examples.
+"""
+
+from dataclasses import dataclass
+from textwrap import dedent
+from typing import Dict, List, Optional
+
+
+@dataclass
+class RefactoringTemplate:
+    """Template for refactoring code to implement a design pattern"""
+
+    pattern_name: str
+    scenario: str
+    before_code: str
+    after_code: str
+    explanation: str
+    steps: List[str]
+    considerations: List[str]
+    testing_notes: str
+
+
+# Refactoring templates based on repository examples
+REFACTORING_TEMPLATES: Dict[str, List[RefactoringTemplate]] = {
+    "strategy": [
+        RefactoringTemplate(
+            pattern_name="strategy",
+            scenario="Replace if/elif chain with Strategy pattern",
+            before_code=dedent(
+                """
+                def process_payment(payment_type: str, amount: float) -> str:
+                    if payment_type == "credit_card":
+                        # 15 lines of credit card processing
+                        fee = amount * 0.03
+                        return f"Credit card payment of ${amount + fee} processed"
+                    elif payment_type == "paypal":
+                        # 12 lines of PayPal processing  
+                        fee = amount * 0.025
+                        return f"PayPal payment of ${amount + fee} processed"
+                    elif payment_type == "crypto":
+                        # 20 lines of crypto processing
+                        fee = amount * 0.01
+                        return f"Crypto payment of ${amount + fee} processed"
+                    else:
+                        raise ValueError(f"Unknown payment type: {payment_type}")
+            """
+            ).strip(),
+            after_code=dedent(
+                """
+                from abc import ABC, abstractmethod
+                
+                class PaymentProcessor(ABC):
+                    @abstractmethod
+                    def process(self, amount: float) -> str:
+                        pass
+                
+                class CreditCardProcessor(PaymentProcessor):
+                    def process(self, amount: float) -> str:
+                        fee = amount * 0.03
+                        return f"Credit card payment of ${amount + fee} processed"
+                
+                class PayPalProcessor(PaymentProcessor):
+                    def process(self, amount: float) -> str:
+                        fee = amount * 0.025
+                        return f"PayPal payment of ${amount + fee} processed"
+                
+                class CryptoProcessor(PaymentProcessor):
+                    def process(self, amount: float) -> str:
+                        fee = amount * 0.01
+                        return f"Crypto payment of ${amount + fee} processed"
+                
+                class PaymentService:
+                    def __init__(self):
+                        self.processors = {
+                            "credit_card": CreditCardProcessor(),
+                            "paypal": PayPalProcessor(),
+                            "crypto": CryptoProcessor()
+                        }
+                    
+                    def process_payment(self, payment_type: str, amount: float) -> str:
+                        processor = self.processors.get(payment_type)
+                        if not processor:
+                            raise ValueError(f"Unknown payment type: {payment_type}")
+                        return processor.process(amount)
+            """
+            ).strip(),
+            explanation="Replace conditional logic with Strategy pattern when you have 3+ algorithms for the same problem",
+            steps=[
+                "1. Create abstract base class (PaymentProcessor) defining the interface",
+                "2. Extract each conditional branch into a separate strategy class",
+                "3. Create context class (PaymentService) to manage strategies",
+                "4. Replace original function with strategy delegation",
+                "5. Add new payment types by creating new strategy classes",
+            ],
+            considerations=[
+                "Use when you have 3+ algorithms that are likely to change or expand",
+                "Each strategy should be independently testable",
+                "Consider strategy selection mechanism (registry, factory, etc.)",
+                "Strategies should be stateless for thread safety",
+            ],
+            testing_notes="Test each strategy independently, then test strategy selection in context class",
+        ),
+        RefactoringTemplate(
+            pattern_name="strategy",
+            scenario="Dynamic algorithm selection based on data characteristics",
+            before_code=dedent(
+                """
+                def sort_data(data: List[int]) -> List[int]:
+                    if len(data) < 100:
+                        # Use insertion sort for small arrays
+                        return insertion_sort(data.copy())
+                    elif len(data) < 10000:
+                        # Use quicksort for medium arrays
+                        return quicksort(data.copy())
+                    else:
+                        # Use merge sort for large arrays
+                        return merge_sort(data.copy())
+            """
+            ).strip(),
+            after_code=dedent(
+                """
+                from abc import ABC, abstractmethod
+                from typing import List
+                
+                class SortStrategy(ABC):
+                    @abstractmethod
+                    def sort(self, data: List[int]) -> List[int]:
+                        pass
+                
+                class InsertionSortStrategy(SortStrategy):
+                    def sort(self, data: List[int]) -> List[int]:
+                        return insertion_sort(data.copy())
+                
+                class QuickSortStrategy(SortStrategy):
+                    def sort(self, data: List[int]) -> List[int]:
+                        return quicksort(data.copy())
+                
+                class MergeSortStrategy(SortStrategy):
+                    def sort(self, data: List[int]) -> List[int]:
+                        return merge_sort(data.copy())
+                
+                class SmartSorter:
+                    def __init__(self):
+                        self.strategies = {
+                            'small': InsertionSortStrategy(),
+                            'medium': QuickSortStrategy(),
+                            'large': MergeSortStrategy()
+                        }
+                    
+                    def sort(self, data: List[int]) -> List[int]:
+                        strategy_key = self._select_strategy(len(data))
+                        return self.strategies[strategy_key].sort(data)
+                    
+                    def _select_strategy(self, size: int) -> str:
+                        if size < 100:
+                            return 'small'
+                        elif size < 10000:
+                            return 'medium'
+                        else:
+                            return 'large'
+            """
+            ).strip(),
+            explanation="Use Strategy pattern for intelligent algorithm selection based on input characteristics",
+            steps=[
+                "1. Define strategy interface for the algorithm family",
+                "2. Implement each algorithm as a separate strategy",
+                "3. Create smart selector that chooses strategy based on input",
+                "4. Make strategy selection logic configurable if needed",
+                "5. Add performance monitoring to validate strategy choices",
+            ],
+            considerations=[
+                "Strategy selection logic should be well-tested",
+                "Consider caching strategy instances for performance",
+                "Document the criteria for strategy selection",
+                "Allow for strategy selection override when needed",
+            ],
+            testing_notes="Test strategy selection logic with various input sizes, benchmark performance",
+        ),
+    ],
+    "factory": [
+        RefactoringTemplate(
+            pattern_name="factory",
+            scenario="Replace type-based object creation with Factory pattern",
+            before_code=dedent(
+                """
+                def create_notification(notification_type: str, message: str):
+                    if notification_type == "email":
+                        return EmailNotification(message)
+                    elif notification_type == "sms":
+                        return SMSNotification(message)
+                    elif notification_type == "push":
+                        return PushNotification(message)
+                    elif notification_type == "slack":
+                        return SlackNotification(message)
+                    else:
+                        raise ValueError(f"Unknown notification type: {notification_type}")
+                
+                # Usage scattered throughout codebase
+                email_notif = create_notification("email", "Hello!")
+                sms_notif = create_notification("sms", "Alert!")
+            """
+            ).strip(),
+            after_code=dedent(
+                """
+                from abc import ABC, abstractmethod
+                
+                class Notification(ABC):
+                    @abstractmethod
+                    def send(self, message: str) -> bool:
+                        pass
+                
+                class NotificationFactory:
+                    _notification_types = {
+                        "email": EmailNotification,
+                        "sms": SMSNotification,
+                        "push": PushNotification,
+                        "slack": SlackNotification
+                    }
+                    
+                    @classmethod
+                    def create(cls, notification_type: str, **kwargs) -> Notification:
+                        notification_class = cls._notification_types.get(notification_type)
+                        if not notification_class:
+                            raise ValueError(f"Unknown notification type: {notification_type}")
+                        return notification_class(**kwargs)
+                    
+                    @classmethod
+                    def register_type(cls, type_name: str, notification_class):
+                        \"\"\"Allow registration of new notification types\"\"\"
+                        cls._notification_types[type_name] = notification_class
+                    
+                    @classmethod
+                    def available_types(cls) -> List[str]:
+                        return list(cls._notification_types.keys())
+                
+                # Usage
+                email_notif = NotificationFactory.create("email", recipient="user@example.com")
+                sms_notif = NotificationFactory.create("sms", phone_number="+1234567890")
+            """
+            ).strip(),
+            explanation="Use Factory pattern when you need to create families of related objects",
+            steps=[
+                "1. Define common interface for all products (Notification)",
+                "2. Create factory class with creation methods",
+                "3. Register all product types in the factory",
+                "4. Add extensibility mechanism for new types",
+                "5. Replace direct instantiation with factory calls",
+            ],
+            considerations=[
+                "Factory is useful when you have 3+ related classes",
+                "Consider Abstract Factory for families of related products",
+                "Make factory extensible for new product types",
+                "Factory can handle complex construction logic",
+            ],
+            testing_notes="Test factory with all registered types, test error handling for unknown types",
+        )
+    ],
+    "observer": [
+        RefactoringTemplate(
+            pattern_name="observer",
+            scenario="Replace manual notification loops with Observer pattern",
+            before_code=dedent(
+                """
+                class UserService:
+                    def __init__(self):
+                        self.email_service = EmailService()
+                        self.audit_service = AuditService()
+                        self.analytics_service = AnalyticsService()
+                    
+                    def update_user_profile(self, user_id: str, data: dict):
+                        # Update user data
+                        user = self.update_user_data(user_id, data)
+                        
+                        # Manual notifications - hard to maintain
+                        self.email_service.send_profile_update_email(user)
+                        self.audit_service.log_profile_update(user)
+                        self.analytics_service.track_profile_update(user)
+                        # If we add more services, we need to update this function
+            """
+            ).strip(),
+            after_code=dedent(
+                """
+                from abc import ABC, abstractmethod
+                from typing import List, Any
+                
+                class Observer(ABC):
+                    @abstractmethod
+                    def update(self, event_type: str, data: Any) -> None:
+                        pass
+                
+                class Subject:
+                    def __init__(self):
+                        self._observers: List[Observer] = []
+                    
+                    def attach(self, observer: Observer) -> None:
+                        self._observers.append(observer)
+                    
+                    def detach(self, observer: Observer) -> None:
+                        self._observers.remove(observer)
+                    
+                    def notify(self, event_type: str, data: Any) -> None:
+                        for observer in self._observers:
+                            observer.update(event_type, data)
+                
+                class UserService(Subject):
+                    def __init__(self):
+                        super().__init__()
+                    
+                    def update_user_profile(self, user_id: str, data: dict):
+                        # Update user data
+                        user = self.update_user_data(user_id, data)
+                        
+                        # Notify all observers
+                        self.notify("profile_updated", user)
+                
+                class EmailObserver(Observer):
+                    def __init__(self, email_service: EmailService):
+                        self.email_service = email_service
+                    
+                    def update(self, event_type: str, data: Any) -> None:
+                        if event_type == "profile_updated":
+                            self.email_service.send_profile_update_email(data)
+                
+                # Setup
+                user_service = UserService()
+                user_service.attach(EmailObserver(email_service))
+                user_service.attach(AuditObserver(audit_service))
+                user_service.attach(AnalyticsObserver(analytics_service))
+            """
+            ).strip(),
+            explanation="Use Observer pattern when multiple objects need to be notified of changes",
+            steps=[
+                "1. Create Observer interface with update method",
+                "2. Create Subject base class with attach/detach/notify methods",
+                "3. Convert notification source to inherit from Subject",
+                "4. Convert each notification target to implement Observer",
+                "5. Replace manual notifications with notify calls",
+            ],
+            considerations=[
+                "Use when you have one-to-many relationships",
+                "Observers should handle their own errors",
+                "Consider async notifications for performance",
+                "Implement proper cleanup to prevent memory leaks",
+            ],
+            testing_notes="Test observer registration/removal, test notification with multiple observers",
+        )
+    ],
+    "singleton": [
+        RefactoringTemplate(
+            pattern_name="singleton",
+            scenario="Convert global configuration to thread-safe Singleton",
+            before_code=dedent(
+                """
+                # Global variables - not thread-safe, hard to test
+                DATABASE_HOST = "localhost"
+                DATABASE_PORT = 5432
+                DATABASE_NAME = "myapp"
+                DEBUG_MODE = False
+                
+                def get_database_config():
+                    return {
+                        "host": DATABASE_HOST,
+                        "port": DATABASE_PORT,
+                        "name": DATABASE_NAME
+                    }
+                
+                def set_debug_mode(enabled: bool):
+                    global DEBUG_MODE
+                    DEBUG_MODE = enabled
+            """
+            ).strip(),
+            after_code=dedent(
+                """
+                import threading
+                from typing import Dict, Any
+                
+                class ConfigManager:
+                    _instance = None
+                    _lock = threading.Lock()
+                    
+                    def __new__(cls):
+                        if cls._instance is None:
+                            with cls._lock:
+                                if cls._instance is None:
+                                    cls._instance = super().__new__(cls)
+                        return cls._instance
+                    
+                    def __init__(self):
+                        if not hasattr(self, '_initialized'):
+                            self._config = {
+                                "database_host": "localhost",
+                                "database_port": 5432,
+                                "database_name": "myapp",
+                                "debug_mode": False
+                            }
+                            self._config_lock = threading.Lock()
+                            self._initialized = True
+                    
+                    def get(self, key: str, default: Any = None) -> Any:
+                        with self._config_lock:
+                            return self._config.get(key, default)
+                    
+                    def set(self, key: str, value: Any) -> None:
+                        with self._config_lock:
+                            self._config[key] = value
+                    
+                    def get_database_config(self) -> Dict[str, Any]:
+                        with self._config_lock:
+                            return {
+                                "host": self._config["database_host"],
+                                "port": self._config["database_port"],
+                                "name": self._config["database_name"]
+                            }
+                
+                # Usage
+                config = ConfigManager()
+                db_config = config.get_database_config()
+                config.set("debug_mode", True)
+            """
+            ).strip(),
+            explanation="Use Singleton for configuration that needs global access and thread safety",
+            steps=[
+                "1. Create class with private _instance variable",
+                "2. Implement thread-safe __new__ with double-check locking",
+                "3. Add initialization guard in __init__",
+                "4. Protect shared data with additional locks if needed",
+                "5. Replace global variables with singleton methods",
+            ],
+            considerations=[
+                "Only use for truly global resources (config, logging, connections)",
+                "Ensure thread safety with proper locking",
+                "Consider dependency injection for better testing",
+                "Document singleton lifecycle and usage",
+            ],
+            testing_notes="Test thread safety, test singleton property, consider reset mechanism for tests",
+        )
+    ],
+    "builder": [
+        RefactoringTemplate(
+            pattern_name="builder",
+            scenario="Replace complex constructor with Builder pattern",
+            before_code=dedent(
+                """
+                class DatabaseConnection:
+                    def __init__(self, host: str, port: int, database: str, 
+                                username: str, password: str, ssl_enabled: bool = False,
+                                connection_timeout: int = 30, read_timeout: int = 60,
+                                max_retries: int = 3, pool_size: int = 10,
+                                charset: str = 'utf8', autocommit: bool = False):
+                        self.host = host
+                        self.port = port
+                        self.database = database
+                        self.username = username
+                        self.password = password
+                        self.ssl_enabled = ssl_enabled
+                        self.connection_timeout = connection_timeout
+                        self.read_timeout = read_timeout
+                        self.max_retries = max_retries
+                        self.pool_size = pool_size
+                        self.charset = charset
+                        self.autocommit = autocommit
+                        
+                        # Complex validation and setup logic...
+                
+                # Usage - hard to read and error-prone
+                db = DatabaseConnection("localhost", 5432, "mydb", "user", "pass", 
+                                      True, 45, 90, 5, 20, "utf8mb4", False)
+            """
+            ).strip(),
+            after_code=dedent(
+                """
+                class DatabaseConnection:
+                    def __init__(self, host: str, port: int, database: str, 
+                                username: str, password: str):
+                        # Required parameters only
+                        self.host = host
+                        self.port = port
+                        self.database = database
+                        self.username = username
+                        self.password = password
+                        
+                        # Optional parameters with defaults
+                        self.ssl_enabled = False
+                        self.connection_timeout = 30
+                        self.read_timeout = 60
+                        self.max_retries = 3
+                        self.pool_size = 10
+                        self.charset = 'utf8'
+                        self.autocommit = False
+                
+                class DatabaseConnectionBuilder:
+                    def __init__(self):
+                        self._connection = None
+                    
+                    def with_host(self, host: str, port: int = 5432) -> 'DatabaseConnectionBuilder':
+                        self._host = host
+                        self._port = port
+                        return self
+                    
+                    def with_database(self, name: str) -> 'DatabaseConnectionBuilder':
+                        self._database = name
+                        return self
+                    
+                    def with_credentials(self, username: str, password: str) -> 'DatabaseConnectionBuilder':
+                        self._username = username
+                        self._password = password
+                        return self
+                    
+                    def with_ssl(self, enabled: bool = True) -> 'DatabaseConnectionBuilder':
+                        self._ssl_enabled = enabled
+                        return self
+                    
+                    def with_timeouts(self, connection: int = 30, read: int = 60) -> 'DatabaseConnectionBuilder':
+                        self._connection_timeout = connection
+                        self._read_timeout = read
+                        return self
+                    
+                    def with_pool(self, size: int = 10) -> 'DatabaseConnectionBuilder':
+                        self._pool_size = size
+                        return self
+                    
+                    def build(self) -> DatabaseConnection:
+                        # Validation
+                        if not all(hasattr(self, attr) for attr in 
+                                  ['_host', '_database', '_username', '_password']):
+                            raise ValueError("Missing required connection parameters")
+                        
+                        # Create and configure connection
+                        connection = DatabaseConnection(
+                            self._host, self._port, self._database,
+                            self._username, self._password
+                        )
+                        
+                        # Set optional parameters
+                        if hasattr(self, '_ssl_enabled'):
+                            connection.ssl_enabled = self._ssl_enabled
+                        if hasattr(self, '_connection_timeout'):
+                            connection.connection_timeout = self._connection_timeout
+                        if hasattr(self, '_read_timeout'):
+                            connection.read_timeout = self._read_timeout
+                        if hasattr(self, '_pool_size'):
+                            connection.pool_size = self._pool_size
+                        
+                        return connection
+                
+                # Usage - much more readable
+                db = (DatabaseConnectionBuilder()
+                      .with_host("localhost", 5432)
+                      .with_database("mydb")
+                      .with_credentials("user", "pass")
+                      .with_ssl(True)
+                      .with_timeouts(connection=45, read=90)
+                      .with_pool(20)
+                      .build())
+            """
+            ).strip(),
+            explanation="Use Builder pattern for objects with many optional parameters (5+)",
+            steps=[
+                "1. Identify required vs optional parameters",
+                "2. Create builder class with fluent interface methods",
+                "3. Add validation in build() method",
+                "4. Make builder methods return self for chaining",
+                "5. Replace complex constructors with builder usage",
+            ],
+            considerations=[
+                "Use for constructors with 5+ parameters or complex validation",
+                "Builder provides better readability than long parameter lists",
+                "Consider immutable objects with builders",
+                "Add validation at appropriate construction steps",
+            ],
+            testing_notes="Test required parameter validation, test various optional parameter combinations",
+        )
+    ],
+    "command": [
+        RefactoringTemplate(
+            pattern_name="command",
+            scenario="Add undo/redo functionality using Command pattern",
+            before_code=dedent(
+                """
+                class TextEditor:
+                    def __init__(self):
+                        self.content = ""
+                    
+                    def insert_text(self, position: int, text: str):
+                        self.content = self.content[:position] + text + self.content[position:]
+                    
+                    def delete_text(self, position: int, length: int):
+                        self.content = self.content[:position] + self.content[position + length:]
+                    
+                    def replace_text(self, position: int, length: int, text: str):
+                        self.delete_text(position, length)
+                        self.insert_text(position, text)
+                    
+                    # No undo/redo functionality - operations are irreversible
+            """
+            ).strip(),
+            after_code=dedent(
+                """
+                from abc import ABC, abstractmethod
+                from typing import List
+                
+                class Command(ABC):
+                    @abstractmethod
+                    def execute(self) -> None:
+                        pass
+                    
+                    @abstractmethod
+                    def undo(self) -> None:
+                        pass
+                
+                class TextEditor:
+                    def __init__(self):
+                        self.content = ""
+                        self.history: List[Command] = []
+                        self.current_position = -1
+                    
+                    def execute_command(self, command: Command) -> None:
+                        # Remove any commands after current position (for new branch)
+                        self.history = self.history[:self.current_position + 1]
+                        
+                        # Execute and add to history
+                        command.execute()
+                        self.history.append(command)
+                        self.current_position += 1
+                    
+                    def undo(self) -> bool:
+                        if self.current_position >= 0:
+                            command = self.history[self.current_position]
+                            command.undo()
+                            self.current_position -= 1
+                            return True
+                        return False
+                    
+                    def redo(self) -> bool:
+                        if self.current_position < len(self.history) - 1:
+                            self.current_position += 1
+                            command = self.history[self.current_position]
+                            command.execute()
+                            return True
+                        return False
+                
+                class InsertTextCommand(Command):
+                    def __init__(self, editor: TextEditor, position: int, text: str):
+                        self.editor = editor
+                        self.position = position
+                        self.text = text
+                    
+                    def execute(self) -> None:
+                        self.editor.content = (self.editor.content[:self.position] + 
+                                             self.text + 
+                                             self.editor.content[self.position:])
+                    
+                    def undo(self) -> None:
+                        length = len(self.text)
+                        self.editor.content = (self.editor.content[:self.position] + 
+                                             self.editor.content[self.position + length:])
+                
+                class DeleteTextCommand(Command):
+                    def __init__(self, editor: TextEditor, position: int, length: int):
+                        self.editor = editor
+                        self.position = position
+                        self.length = length
+                        self.deleted_text = ""
+                    
+                    def execute(self) -> None:
+                        self.deleted_text = self.editor.content[self.position:self.position + self.length]
+                        self.editor.content = (self.editor.content[:self.position] + 
+                                             self.editor.content[self.position + self.length:])
+                    
+                    def undo(self) -> None:
+                        self.editor.content = (self.editor.content[:self.position] + 
+                                             self.deleted_text + 
+                                             self.editor.content[self.position:])
+                
+                # Usage
+                editor = TextEditor()
+                editor.execute_command(InsertTextCommand(editor, 0, "Hello "))
+                editor.execute_command(InsertTextCommand(editor, 6, "World!"))
+                editor.undo()  # Removes "World!"
+                editor.redo()  # Adds "World!" back
+            """
+            ).strip(),
+            explanation="Use Command pattern when you need undo/redo or operation queuing",
+            steps=[
+                "1. Create Command interface with execute() and undo() methods",
+                "2. Create command classes for each operation type",
+                "3. Add command history management to main class",
+                "4. Implement undo/redo logic with position tracking",
+                "5. Replace direct operations with command execution",
+            ],
+            considerations=[
+                "Use when undo/redo, macro recording, or queuing is needed",
+                "Commands should store enough state for reversal",
+                "Consider memory usage for large command histories",
+                "Commands can be serialized for persistence",
+            ],
+            testing_notes="Test execute/undo for each command type, test redo after undo, test history management",
+        )
+    ],
+}
+
+
+def get_refactoring_template(
+    pattern_name: str, scenario: Optional[str] = None
+) -> Optional[RefactoringTemplate]:
+    """Get a refactoring template for a specific pattern and scenario"""
+    templates = REFACTORING_TEMPLATES.get(pattern_name.lower(), [])
+
+    if not templates:
+        return None
+
+    if scenario:
+        # Find template matching scenario
+        for template in templates:
+            if scenario.lower() in template.scenario.lower():
+                return template
+
+    # Return first template if no specific scenario or no match
+    return templates[0]
+
+
+def get_all_templates_for_pattern(pattern_name: str) -> List[RefactoringTemplate]:
+    """Get all refactoring templates for a specific pattern"""
+    return REFACTORING_TEMPLATES.get(pattern_name.lower(), [])
+
+
+def list_available_patterns() -> List[str]:
+    """List all patterns that have refactoring templates"""
+    return list(REFACTORING_TEMPLATES.keys())
+
+
+def generate_refactoring_guide(pattern_name: str) -> str:
+    """Generate a comprehensive refactoring guide for a pattern"""
+    templates = get_all_templates_for_pattern(pattern_name)
+
+    if not templates:
+        return f"No refactoring templates available for {pattern_name} pattern."
+
+    guide = f"# {pattern_name.title()} Pattern Refactoring Guide\n\n"
+
+    for i, template in enumerate(templates, 1):
+        guide += f"## Scenario {i}: {template.scenario}\n\n"
+        guide += f"**When to Apply**: {template.explanation}\n\n"
+
+        guide += "### Before (Anti-Pattern/Problematic Code)\n"
+        guide += "```python\n"
+        guide += template.before_code
+        guide += "\n```\n\n"
+
+        guide += "### After (Pattern Implementation)\n"
+        guide += "```python\n"
+        guide += template.after_code
+        guide += "\n```\n\n"
+
+        guide += "### Refactoring Steps\n"
+        for step in template.steps:
+            guide += f"- {step}\n"
+        guide += "\n"
+
+        guide += "### Important Considerations\n"
+        for consideration in template.considerations:
+            guide += f"- {consideration}\n"
+        guide += "\n"
+
+        guide += f"### Testing Strategy\n"
+        guide += f"{template.testing_notes}\n\n"
+
+        guide += "---\n\n"
+
+    return guide
diff --git a/ai-engine/repo_analyzer.py b/ai-engine/repo_analyzer.py
new file mode 100644
index 0000000..efb33c5
--- /dev/null
+++ b/ai-engine/repo_analyzer.py
@@ -0,0 +1,668 @@
+"""
+Repository-level Pattern Analysis
+
+This module provides high-level analysis of entire repositories to identify
+architectural pattern opportunities and anti-patterns.
+"""
+
+import json
+from collections import defaultdict
+from dataclasses import asdict, dataclass
+from pathlib import Path
+from typing import Dict, List, Optional, Set, Tuple, Union
+
+from .code_analyzer import OpportunityType, PatternOpportunity, analyze_directory
+from .pattern_knowledge import PatternConfidence
+
+
+@dataclass
+class ArchitecturalInsight:
+    """High-level architectural insight about the repository"""
+
+    insight_type: str  # "architectural_pattern", "anti_pattern", "optimization"
+    title: str
+    description: str
+    affected_files: List[str]
+    confidence: PatternConfidence
+    impact: str  # "Low", "Medium", "High", "Critical"
+    effort: str  # "Low", "Medium", "High"
+    recommendations: List[str]
+
+    @property
+    def priority_score(self) -> float:
+        """Calculate priority score for this insight"""
+        confidence_weight = {
+            PatternConfidence.LOW: 0.2,
+            PatternConfidence.MEDIUM: 0.5,
+            PatternConfidence.HIGH: 0.8,
+            PatternConfidence.CRITICAL: 1.0,
+        }
+
+        effort_weight = {"Low": 1.0, "Medium": 0.7, "High": 0.4}
+        impact_weight = {"Low": 0.3, "Medium": 0.6, "High": 0.8, "Critical": 1.0}
+
+        return (
+            confidence_weight[self.confidence] * 0.4
+            + effort_weight[self.effort] * 0.2
+            + impact_weight[self.impact] * 0.4
+        )
+
+
+@dataclass
+class RepositoryAnalysis:
+    """Complete analysis of a repository"""
+
+    repository_path: str
+    total_files_analyzed: int
+    total_opportunities: int
+    opportunities_by_file: Dict[str, List[PatternOpportunity]]
+    architectural_insights: List[ArchitecturalInsight]
+    pattern_usage_summary: Dict[str, int]
+    complexity_assessment: str
+    recommendations_summary: List[str]
+
+
+class RepositoryAnalyzer:
+    """Analyzes entire repositories for pattern opportunities and architectural insights"""
+
+    def __init__(self, repository_path: Union[str, Path]):
+        self.repository_path = Path(repository_path)
+        self.opportunities_by_file: Dict[str, List[PatternOpportunity]] = {}
+        self.architectural_insights: List[ArchitecturalInsight] = []
+
+    def analyze(
+        self, exclude_patterns: Optional[List[str]] = None
+    ) -> RepositoryAnalysis:
+        """Perform comprehensive repository analysis"""
+        # Default exclusions for common non-source directories
+        default_exclusions = [
+            "__pycache__",
+            ".git",
+            ".venv",
+            "venv",
+            "env",
+            "node_modules",
+            ".pytest_cache",
+            ".mypy_cache",
+            "dist",
+            "build",
+            ".tox",
+        ]
+        exclude_patterns = (exclude_patterns or []) + default_exclusions
+
+        # Analyze individual files
+        self.opportunities_by_file = analyze_directory(
+            self.repository_path, exclude_patterns=exclude_patterns
+        )
+
+        # Generate architectural insights
+        self._generate_architectural_insights()
+
+        # Create summary
+        return self._create_analysis_summary()
+
+    def _generate_architectural_insights(self) -> None:
+        """Generate high-level architectural insights from file-level opportunities"""
+
+        # Collect all opportunities
+        all_opportunities = []
+        for opportunities in self.opportunities_by_file.values():
+            all_opportunities.extend(opportunities)
+
+        # Group opportunities by pattern
+        by_pattern = defaultdict(list)
+        for opp in all_opportunities:
+            by_pattern[opp.pattern_name].append(opp)
+
+        # Analyze patterns
+        self._analyze_singleton_usage(by_pattern.get("singleton", []))
+        self._analyze_factory_opportunities(by_pattern.get("factory", []))
+        self._analyze_observer_opportunities(by_pattern.get("observer", []))
+        self._analyze_strategy_opportunities(by_pattern.get("strategy", []))
+        self._analyze_builder_opportunities(by_pattern.get("builder", []))
+        self._analyze_repository_opportunities(by_pattern.get("repository", []))
+
+        # Cross-pattern analysis
+        self._analyze_cross_pattern_opportunities(by_pattern)
+
+        # Anti-pattern detection
+        self._detect_architectural_anti_patterns(all_opportunities)
+
+        # Complexity assessment
+        self._assess_overall_complexity(all_opportunities)
+
+    def _analyze_singleton_usage(
+        self, singleton_opportunities: List[PatternOpportunity]
+    ) -> None:
+        """Analyze singleton pattern usage across the repository"""
+        if not singleton_opportunities:
+            return
+
+        anti_patterns = [
+            opp
+            for opp in singleton_opportunities
+            if opp.opportunity_type == OpportunityType.ANTI_PATTERN_DETECTED
+        ]
+        valid_opportunities = [
+            opp
+            for opp in singleton_opportunities
+            if opp.opportunity_type != OpportunityType.ANTI_PATTERN_DETECTED
+        ]
+
+        # Check for singleton overuse
+        if len(anti_patterns) >= 2:
+            self.architectural_insights.append(
+                ArchitecturalInsight(
+                    insight_type="anti_pattern",
+                    title="Singleton Pattern Overuse Detected",
+                    description=f"Found {len(anti_patterns)} inappropriate singleton implementations. "
+                    "Singletons should not be used for data models or entity classes.",
+                    affected_files=[opp.file_path for opp in anti_patterns],
+                    confidence=PatternConfidence.HIGH,
+                    impact="High",
+                    effort="Medium",
+                    recommendations=[
+                        "Convert data model singletons to regular classes",
+                        "Use dependency injection for better testability",
+                        "Consider Repository pattern for data access centralization",
+                        "Review singleton usage - ensure they're truly needed",
+                    ],
+                )
+            )
+
+        # Check for missing singleton opportunities
+        if len(valid_opportunities) >= 2:
+            config_files = [
+                opp.file_path
+                for opp in valid_opportunities
+                if "config" in opp.file_path.lower()
+            ]
+            db_files = [
+                opp.file_path
+                for opp in valid_opportunities
+                if any(
+                    keyword in opp.file_path.lower()
+                    for keyword in ["database", "connection", "db"]
+                )
+            ]
+
+            if config_files or db_files:
+                self.architectural_insights.append(
+                    ArchitecturalInsight(
+                        insight_type="optimization",
+                        title="Centralize Shared Resources with Singleton",
+                        description="Multiple configuration or database connection classes could benefit from singleton pattern.",
+                        affected_files=config_files + db_files,
+                        confidence=PatternConfidence.MEDIUM,
+                        impact="Medium",
+                        effort="Low",
+                        recommendations=[
+                            "Implement singleton for configuration management",
+                            "Centralize database connections with singleton pattern",
+                            "Ensure thread-safety for multi-threaded applications",
+                            "Consider lazy initialization for performance",
+                        ],
+                    )
+                )
+
+    def _analyze_factory_opportunities(
+        self, factory_opportunities: List[PatternOpportunity]
+    ) -> None:
+        """Analyze factory pattern opportunities"""
+        if len(factory_opportunities) >= 3:
+            # Multiple factory opportunities suggest need for consistent creation strategy
+            self.architectural_insights.append(
+                ArchitecturalInsight(
+                    insight_type="architectural_pattern",
+                    title="Standardize Object Creation with Factory Pattern",
+                    description=f"Found {len(factory_opportunities)} factory pattern opportunities. "
+                    "Consider implementing a consistent object creation strategy.",
+                    affected_files=[opp.file_path for opp in factory_opportunities],
+                    confidence=PatternConfidence.MEDIUM,
+                    impact="Medium",
+                    effort="Medium",
+                    recommendations=[
+                        "Implement factory methods for complex object creation",
+                        "Consider Abstract Factory for families of related objects",
+                        "Centralize creation logic to improve maintainability",
+                        "Use factories to support polymorphism and extensibility",
+                    ],
+                )
+            )
+
+    def _analyze_observer_opportunities(
+        self, observer_opportunities: List[PatternOpportunity]
+    ) -> None:
+        """Analyze observer pattern opportunities"""
+        if len(observer_opportunities) >= 2:
+            # Multiple observer opportunities suggest event-driven architecture
+            self.architectural_insights.append(
+                ArchitecturalInsight(
+                    insight_type="architectural_pattern",
+                    title="Implement Event-Driven Architecture",
+                    description=f"Found {len(observer_opportunities)} observer pattern opportunities. "
+                    "Consider implementing a centralized event system.",
+                    affected_files=[opp.file_path for opp in observer_opportunities],
+                    confidence=PatternConfidence.MEDIUM,
+                    impact="High",
+                    effort="Medium",
+                    recommendations=[
+                        "Implement centralized event bus or observer registry",
+                        "Define clear event contracts and interfaces",
+                        "Consider async event handling for performance",
+                        "Implement proper error handling in event notifications",
+                    ],
+                )
+            )
+
+    def _analyze_strategy_opportunities(
+        self, strategy_opportunities: List[PatternOpportunity]
+    ) -> None:
+        """Analyze strategy pattern opportunities"""
+        if len(strategy_opportunities) >= 3:
+            # Multiple strategy opportunities suggest algorithmic complexity
+            self.architectural_insights.append(
+                ArchitecturalInsight(
+                    insight_type="complexity_reduction",
+                    title="Reduce Complexity with Strategy Pattern",
+                    description=f"Found {len(strategy_opportunities)} strategy pattern opportunities. "
+                    "Multiple conditional chains suggest high algorithmic complexity.",
+                    affected_files=[opp.file_path for opp in strategy_opportunities],
+                    confidence=PatternConfidence.HIGH,
+                    impact="Medium",
+                    effort="Medium",
+                    recommendations=[
+                        "Replace complex conditional logic with strategy patterns",
+                        "Create strategy interfaces for algorithm families",
+                        "Implement strategy selection mechanisms",
+                        "Consider configuration-driven strategy selection",
+                    ],
+                )
+            )
+
+    def _analyze_builder_opportunities(
+        self, builder_opportunities: List[PatternOpportunity]
+    ) -> None:
+        """Analyze builder pattern opportunities"""
+        if len(builder_opportunities) >= 2:
+            # Multiple builder opportunities suggest complex object construction
+            self.architectural_insights.append(
+                ArchitecturalInsight(
+                    insight_type="optimization",
+                    title="Simplify Object Construction with Builder Pattern",
+                    description=f"Found {len(builder_opportunities)} builder pattern opportunities. "
+                    "Complex constructors suggest need for builder pattern.",
+                    affected_files=[opp.file_path for opp in builder_opportunities],
+                    confidence=PatternConfidence.MEDIUM,
+                    impact="Medium",
+                    effort="Low",
+                    recommendations=[
+                        "Implement builder pattern for complex object construction",
+                        "Use fluent interfaces for better readability",
+                        "Add validation at each construction step",
+                        "Consider immutable objects with builders",
+                    ],
+                )
+            )
+
+    def _analyze_repository_opportunities(
+        self, repo_opportunities: List[PatternOpportunity]
+    ) -> None:
+        """Analyze repository pattern opportunities"""
+        if repo_opportunities:
+            # Repository opportunities suggest data access concerns
+            self.architectural_insights.append(
+                ArchitecturalInsight(
+                    insight_type="architectural_pattern",
+                    title="Centralize Data Access with Repository Pattern",
+                    description="Data access logic could benefit from repository pattern implementation.",
+                    affected_files=[opp.file_path for opp in repo_opportunities],
+                    confidence=PatternConfidence.MEDIUM,
+                    impact="High",
+                    effort="High",
+                    recommendations=[
+                        "Implement repository interfaces for data access",
+                        "Separate domain logic from data access logic",
+                        "Consider Unit of Work pattern for transaction management",
+                        "Implement repository abstractions for testing",
+                    ],
+                )
+            )
+
+    def _analyze_cross_pattern_opportunities(
+        self, by_pattern: Dict[str, List[PatternOpportunity]]
+    ) -> None:
+        """Analyze opportunities for combining multiple patterns"""
+
+        # Factory + Strategy combination
+        if "factory" in by_pattern and "strategy" in by_pattern:
+            if len(by_pattern["factory"]) >= 1 and len(by_pattern["strategy"]) >= 1:
+                self.architectural_insights.append(
+                    ArchitecturalInsight(
+                        insight_type="architectural_pattern",
+                        title="Combine Factory and Strategy Patterns",
+                        description="Factory and Strategy opportunities detected. Consider creating strategies through factories.",
+                        affected_files=list(
+                            set(
+                                [opp.file_path for opp in by_pattern["factory"]]
+                                + [opp.file_path for opp in by_pattern["strategy"]]
+                            )
+                        ),
+                        confidence=PatternConfidence.LOW,
+                        impact="Medium",
+                        effort="Medium",
+                        recommendations=[
+                            "Use Factory pattern to create Strategy instances",
+                            "Implement strategy registry for dynamic selection",
+                            "Consider configuration-driven strategy creation",
+                        ],
+                    )
+                )
+
+        # Observer + Command combination
+        if "observer" in by_pattern and "command" in by_pattern:
+            if len(by_pattern["observer"]) >= 1 and len(by_pattern["command"]) >= 1:
+                self.architectural_insights.append(
+                    ArchitecturalInsight(
+                        insight_type="architectural_pattern",
+                        title="Event Sourcing Architecture Opportunity",
+                        description="Observer and Command patterns together suggest event sourcing possibilities.",
+                        affected_files=list(
+                            set(
+                                [opp.file_path for opp in by_pattern["observer"]]
+                                + [opp.file_path for opp in by_pattern["command"]]
+                            )
+                        ),
+                        confidence=PatternConfidence.LOW,
+                        impact="High",
+                        effort="High",
+                        recommendations=[
+                            "Consider implementing event sourcing architecture",
+                            "Use Command pattern for event creation",
+                            "Use Observer pattern for event handling",
+                            "Implement event store for audit and replay capabilities",
+                        ],
+                    )
+                )
+
+    def _detect_architectural_anti_patterns(
+        self, all_opportunities: List[PatternOpportunity]
+    ) -> None:
+        """Detect architectural-level anti-patterns"""
+
+        # Check for pattern overuse
+        pattern_counts = defaultdict(int)
+        for opp in all_opportunities:
+            pattern_counts[opp.pattern_name] += 1
+
+        high_pattern_usage = {
+            pattern: count for pattern, count in pattern_counts.items() if count >= 5
+        }
+
+        if high_pattern_usage:
+            patterns_list = ", ".join(
+                f"{pattern} ({count})" for pattern, count in high_pattern_usage.items()
+            )
+            self.architectural_insights.append(
+                ArchitecturalInsight(
+                    insight_type="anti_pattern",
+                    title="Potential Pattern Overuse",
+                    description=f"High number of pattern opportunities detected: {patterns_list}. "
+                    "Consider if simpler solutions might be more appropriate.",
+                    affected_files=[],
+                    confidence=PatternConfidence.LOW,
+                    impact="Medium",
+                    effort="Low",
+                    recommendations=[
+                        "Review each pattern opportunity carefully",
+                        "Consider simpler alternatives where appropriate",
+                        "Ensure patterns solve real problems, not imaginary ones",
+                        "Follow YAGNI (You Aren't Gonna Need It) principle",
+                    ],
+                )
+            )
+
+        # Check for complexity overload
+        total_opportunities = len(all_opportunities)
+        if total_opportunities >= 20:
+            self.architectural_insights.append(
+                ArchitecturalInsight(
+                    insight_type="anti_pattern",
+                    title="High Complexity Warning",
+                    description=f"Found {total_opportunities} pattern opportunities. "
+                    "High pattern density might indicate over-engineering.",
+                    affected_files=[],
+                    confidence=PatternConfidence.MEDIUM,
+                    impact="High",
+                    effort="Low",
+                    recommendations=[
+                        "Prioritize high-impact, low-effort improvements",
+                        "Focus on anti-pattern elimination first",
+                        "Consider architectural simplification",
+                        "Implement patterns incrementally, not all at once",
+                    ],
+                )
+            )
+
+    def _assess_overall_complexity(
+        self, all_opportunities: List[PatternOpportunity]
+    ) -> None:
+        """Assess overall codebase complexity based on pattern opportunities"""
+
+        total_opportunities = len(all_opportunities)
+        anti_patterns = len(
+            [
+                opp
+                for opp in all_opportunities
+                if opp.opportunity_type == OpportunityType.ANTI_PATTERN_DETECTED
+            ]
+        )
+        high_confidence = len(
+            [
+                opp
+                for opp in all_opportunities
+                if opp.confidence
+                in [PatternConfidence.HIGH, PatternConfidence.CRITICAL]
+            ]
+        )
+
+        # Generate complexity assessment
+        if anti_patterns > 0:
+            complexity_level = "High (Anti-patterns detected)"
+            primary_recommendation = "Focus on eliminating anti-patterns first"
+        elif high_confidence >= 5:
+            complexity_level = "Medium-High (Multiple clear improvement opportunities)"
+            primary_recommendation = (
+                "Implement high-confidence patterns for immediate benefits"
+            )
+        elif total_opportunities >= 10:
+            complexity_level = "Medium (Multiple opportunities available)"
+            primary_recommendation = (
+                "Prioritize patterns by business value and technical debt reduction"
+            )
+        elif total_opportunities >= 5:
+            complexity_level = "Low-Medium (Some improvement opportunities)"
+            primary_recommendation = (
+                "Selective pattern implementation based on team capacity"
+            )
+        else:
+            complexity_level = "Low (Well-structured codebase)"
+            primary_recommendation = "Maintain current good practices"
+
+        # Add complexity insight
+        self.architectural_insights.append(
+            ArchitecturalInsight(
+                insight_type="assessment",
+                title="Codebase Complexity Assessment",
+                description=f"Complexity Level: {complexity_level}",
+                affected_files=[],
+                confidence=PatternConfidence.HIGH,
+                impact="Critical",
+                effort="N/A",
+                recommendations=[primary_recommendation],
+            )
+        )
+
+    def _create_analysis_summary(self) -> RepositoryAnalysis:
+        """Create comprehensive analysis summary"""
+
+        all_opportunities = []
+        for opportunities in self.opportunities_by_file.values():
+            all_opportunities.extend(opportunities)
+
+        # Pattern usage summary
+        pattern_counts = defaultdict(int)
+        for opp in all_opportunities:
+            pattern_counts[opp.pattern_name] += 1
+
+        # Top recommendations
+        top_insights = sorted(
+            self.architectural_insights, key=lambda x: x.priority_score, reverse=True
+        )[:5]
+
+        recommendations_summary = []
+        for insight in top_insights:
+            recommendations_summary.extend(
+                insight.recommendations[:2]
+            )  # Top 2 from each
+
+        # Remove duplicates while preserving order
+        seen = set()
+        unique_recommendations = []
+        for rec in recommendations_summary:
+            if rec not in seen:
+                seen.add(rec)
+                unique_recommendations.append(rec)
+
+        return RepositoryAnalysis(
+            repository_path=str(self.repository_path),
+            total_files_analyzed=len(self.opportunities_by_file),
+            total_opportunities=len(all_opportunities),
+            opportunities_by_file=self.opportunities_by_file,
+            architectural_insights=self.architectural_insights,
+            pattern_usage_summary=dict(pattern_counts),
+            complexity_assessment=next(
+                (
+                    insight.description
+                    for insight in self.architectural_insights
+                    if insight.title == "Codebase Complexity Assessment"
+                ),
+                "Unknown",
+            ),
+            recommendations_summary=unique_recommendations[
+                :10
+            ],  # Top 10 recommendations
+        )
+
+    def save_analysis(
+        self, analysis: RepositoryAnalysis, output_path: Union[str, Path]
+    ) -> None:
+        """Save analysis results to JSON file"""
+        output_path = Path(output_path)
+
+        # Convert to serializable format
+        analysis_dict = asdict(analysis)
+
+        # Convert PatternOpportunity objects to dictionaries
+        for file_path, opportunities in analysis_dict["opportunities_by_file"].items():
+            analysis_dict["opportunities_by_file"][file_path] = [
+                asdict(opp) for opp in opportunities
+            ]
+
+        # Convert ArchitecturalInsight confidence enums to strings
+        for insight in analysis_dict["architectural_insights"]:
+            insight["confidence"] = insight["confidence"].value
+
+        with open(output_path, "w", encoding="utf-8") as f:
+            json.dump(analysis_dict, f, indent=2, ensure_ascii=False)
+
+    def generate_report(self, analysis: RepositoryAnalysis) -> str:
+        """Generate comprehensive human-readable report"""
+
+        report = f"# Repository Pattern Analysis Report\n\n"
+        report += f"**Repository**: {analysis.repository_path}\n"
+        report += f"**Files Analyzed**: {analysis.total_files_analyzed}\n"
+        report += f"**Total Opportunities**: {analysis.total_opportunities}\n"
+        report += f"**Complexity**: {analysis.complexity_assessment}\n\n"
+
+        if not analysis.total_opportunities:
+            report += "🎉 **Excellent!** No pattern opportunities detected. Your codebase appears well-structured.\n\n"
+            return report
+
+        # Pattern summary
+        report += "## Pattern Opportunity Summary\n\n"
+        for pattern, count in sorted(
+            analysis.pattern_usage_summary.items(), key=lambda x: x[1], reverse=True
+        ):
+            report += f"- **{pattern.title()}**: {count} opportunities\n"
+
+        # Top architectural insights
+        report += "\n## Key Architectural Insights\n\n"
+        top_insights = sorted(
+            analysis.architectural_insights,
+            key=lambda x: x.priority_score,
+            reverse=True,
+        )[:5]
+
+        for i, insight in enumerate(top_insights, 1):
+            report += f"### {i}. {insight.title}\n"
+            report += f"**Type**: {insight.insight_type.replace('_', ' ').title()}\n"
+            report += f"**Impact**: {insight.impact} | **Effort**: {insight.effort}\n"
+            report += f"**Description**: {insight.description}\n"
+            if insight.affected_files:
+                report += f"**Affected Files**: {len(insight.affected_files)} files\n"
+            report += "**Recommendations**:\n"
+            for rec in insight.recommendations[:3]:  # Top 3 recommendations
+                report += f"- {rec}\n"
+            report += "\n"
+
+        # Priority recommendations
+        report += "## Priority Action Items\n\n"
+        for i, rec in enumerate(analysis.recommendations_summary[:8], 1):
+            report += f"{i}. {rec}\n"
+
+        # High-priority file-level opportunities
+        report += "\n## High-Priority File Opportunities\n\n"
+        all_opportunities = []
+        for opportunities in analysis.opportunities_by_file.values():
+            all_opportunities.extend(opportunities)
+
+        high_priority = sorted(
+            [opp for opp in all_opportunities if opp.priority_score > 0.7],
+            key=lambda x: x.priority_score,
+            reverse=True,
+        )[:8]
+
+        for opp in high_priority:
+            report += f"**{opp.pattern_name.title()}** in `{Path(opp.file_path).name}:{opp.line_number}`\n"
+            report += f"- {opp.description}\n"
+            report += (
+                f"- Effort: {opp.effort_estimate} | Impact: {opp.impact_estimate}\n\n"
+            )
+
+        return report
+
+
+def analyze_repository(
+    repository_path: Union[str, Path],
+    exclude_patterns: Optional[List[str]] = None,
+    save_to: Optional[Union[str, Path]] = None,
+) -> RepositoryAnalysis:
+    """
+    Comprehensive repository analysis with optional save functionality
+
+    Args:
+        repository_path: Path to the repository to analyze
+        exclude_patterns: Additional patterns to exclude from analysis
+        save_to: Optional path to save JSON analysis results
+
+    Returns:
+        RepositoryAnalysis object with complete analysis results
+    """
+    analyzer = RepositoryAnalyzer(repository_path)
+    analysis = analyzer.analyze(exclude_patterns)
+
+    if save_to:
+        analyzer.save_analysis(analysis, save_to)
+
+    return analysis
diff --git a/commands/analyze.md b/commands/analyze.md
new file mode 100644
index 0000000..7c25539
--- /dev/null
+++ b/commands/analyze.md
@@ -0,0 +1,183 @@
+# /dp::analyze - Comprehensive Design Pattern Analysis
+
+**Purpose**: Deep analysis using sequential thinking for complex pattern decisions
+
+## Command Usage
+```
+/dp::analyze <problem description>
+```
+
+## Execution Strategy
+
+You are a design pattern expert with deep knowledge of the 10 patterns in this repository. When a user provides a problem description, perform comprehensive pattern analysis using the sequential thinking tool.
+
+### Step 1: Use Sequential Thinking
+Activate sequential thinking to systematically analyze the problem:
+
+```
+Use the mcp__sequential-thinking__sequentialthinking tool with these thoughts:
+
+Thought 1: Problem Understanding
+- What specific problem is the user trying to solve?
+- What are the constraints, requirements, and context?
+- What's the expected scale and complexity?
+
+Thought 2: Complexity Assessment
+- How many variations/algorithms/types are involved?
+- What's the growth potential and change frequency?
+- What are the performance and threading requirements?
+- What's the team's expertise level?
+
+Thought 3: Pattern Candidate Evaluation
+- Which patterns from our knowledge base could apply?
+- What are the specific threshold criteria each pattern requires?
+- How do the candidates compare against our complexity thresholds?
+
+Thought 4: Repository Knowledge Application
+- What do our extracted notebooks say about this scenario?
+- Are there specific use cases or examples that match?
+- What are the threading/performance considerations?
+
+Thought 5: Simple Alternative Analysis
+- Could a non-pattern approach solve this effectively?
+- What would the simple Python solution look like?
+- Would the pattern add real value or just complexity?
+
+Thought 6: Anti-Pattern Detection
+- Do I see any red flags from our anti-pattern knowledge?
+- Is this a case of overengineering or premature optimization?
+- Are there better architectural approaches?
+
+Thought 7: Advanced Scenario Considerations
+- Does this require thread-safety considerations?
+- What are the testing implications?
+- Are there performance trade-offs to consider?
+- How does this fit into larger architectural patterns?
+
+Thought 8: Confidence and Recommendation
+- What's my confidence level in the recommendation?
+- What are the key deciding factors?
+- What alternatives should be mentioned?
+- What implementation guidance should I provide?
+```
+
+### Step 2: Apply Repository Knowledge
+Reference the specific patterns and their thresholds from this repository:
+
+#### Pattern Thresholds (from pattern_knowledge.py):
+- **Singleton**: Use for expensive objects, global access, shared state. Avoid for data models.
+- **Factory**: Use for 3+ similar classes, complex creation logic. Avoid for simple cases.
+- **Observer**: Use for 2+ observers, event-driven architecture. Consider thread safety.
+- **Strategy**: Use for 3+ algorithms, runtime switching. Consider if/else for 2-3 cases.
+- **Command**: Use for undo/redo, queuing, macros. Avoid for simple operations.
+- **Builder**: Use for 5+ parameters, complex construction. Consider dataclasses for simple cases.
+- **Repository**: Use for multiple data sources, complex queries. Avoid generic repository anti-pattern.
+- **Adapter**: Use for incompatible interfaces, third-party integration. Simplest pattern when you can't modify interfaces.
+- **Decorator**: Use for 3+ optional features, multiple combinations. Consider inheritance for 2-3 features.
+- **State**: Use for 3+ states, different behaviors per state. Consider enum for simple states.
+
+### Step 3: Provide Structured Response
+Format your final response as:
+
+```
+🧠 **Pattern Analysis: [Problem Summary]**
+
+## Problem Assessment
+- **Complexity**: [Low/Medium/High]
+- **Scale**: [Number of components/algorithms/states]
+- **Growth Potential**: [Expected evolution]
+
+## Pattern Evaluation
+### Primary Recommendation: **[Pattern Name]** 
+**Confidence**: [LOW/MEDIUM/HIGH/CRITICAL]
+
+**Why this pattern fits**:
+- [Specific threshold criteria met]
+- [Repository use case match]
+- [Expected benefits]
+
+**Implementation approach**:
+- [Key design decisions]
+- [Threading considerations if applicable]
+- [Performance implications]
+
+### Alternative Approaches
+1. **[Alternative 1]**: [Brief description and trade-offs]
+2. **[Alternative 2]**: [Brief description and trade-offs]
+
+## Anti-Pattern Check
+[Any warnings about overengineering or misuse]
+
+## Repository References
+- **Notebook**: `notebooks/[XX]_[pattern]_pattern.ipynb`
+- **Implementation**: `src/patterns/[pattern].py`
+- **Tests**: `tests/test_patterns/test_[pattern].py`
+
+## Next Steps
+1. [Immediate implementation guidance]
+2. [Testing strategy]
+3. [Future considerations]
+```
+
+### Step 4: Handle Edge Cases
+- **Multiple viable patterns**: Provide comparison matrix
+- **No pattern needed**: Explain why simple approach is better
+- **Borderline cases**: Discuss decision factors and thresholds
+- **Anti-pattern detected**: Provide strong warning and alternatives
+
+## Pattern Recognition Triggers
+Auto-activate deeper analysis when detecting:
+- Multiple pattern keywords in problem description
+- Complex scenarios with >3 components
+- Growth/scalability requirements mentioned
+- Performance or threading concerns
+- Team experience level mentioned
+- Legacy system integration
+- "Future-proofing" or "extensibility" mentioned
+
+## Examples of Quality Analysis
+
+### High-Quality Response Pattern:
+```
+🧠 **Pattern Analysis: Multi-format Report Generation System**
+
+## Problem Assessment
+- **Complexity**: High (4+ formats, different logic per format)
+- **Scale**: 4 current formats, growth expected
+- **Growth Potential**: High (customer requests for new formats)
+
+## Pattern Evaluation
+### Primary Recommendation: **Strategy Pattern**
+**Confidence**: HIGH
+
+**Why this pattern fits**:
+✓ 4+ algorithms (exceeds threshold of 3)
+✓ Runtime selection needed
+✓ Expected growth potential
+✓ Different logic per format
+
+**Implementation approach**:
+- Create ReportGenerator interface
+- Implement strategy for each format (PDF, Excel, CSV, Word)
+- Use ReportService as context for strategy selection
+- Consider factory for strategy creation
+
+### Alternative Approaches
+1. **Simple if/else**: Would work but becomes unwieldy at 4+ formats
+2. **Plugin architecture**: Overkill unless external format providers needed
+
+## Anti-Pattern Check
+✅ No overengineering detected - complexity justifies pattern usage
+
+## Repository References
+- **Notebook**: `notebooks/04_strategy_pattern.ipynb`
+- **Implementation**: `src/patterns/strategy.py`
+
+## Next Steps
+1. Define ReportGenerator interface
+2. Extract existing format logic to separate strategies
+3. Implement strategy selection mechanism
+4. Add comprehensive tests for each format
+```
+
+Remember: Always prioritize solving real problems over pattern usage. When in doubt, recommend the simpler approach.
\ No newline at end of file
diff --git a/commands/check.md b/commands/check.md
new file mode 100644
index 0000000..c853dca
--- /dev/null
+++ b/commands/check.md
@@ -0,0 +1,311 @@
+# /dp::check - Quick Pattern Validation
+
+**Purpose**: Fast verification of pattern appropriateness for specific scenarios
+
+## Command Usage
+```
+/dp::check <pattern name> for <scenario>
+```
+
+## Execution Strategy
+
+You are a design pattern expert performing quick validation checks. Analyze whether the suggested pattern is appropriate for the given scenario using repository knowledge.
+
+### Step 1: Parse Input
+Extract the pattern name and scenario from the user input:
+- **Pattern**: Which of the 10 patterns (singleton, factory, observer, strategy, command, builder, repository, adapter, decorator, state)
+- **Scenario**: The specific use case or problem description
+
+### Step 2: Apply Pattern-Specific Validation
+
+#### Singleton Pattern Validation
+**✅ Appropriate when**:
+- Expensive object creation (database pools, config managers)
+- Global access needed (logging, metrics)
+- Shared state required (application state)
+- Resource management (file handles)
+
+**❌ Inappropriate when**:
+- Data models (User, Product, Order classes)
+- Simple objects that aren't expensive
+- Testing is important (hard to mock)
+- Multiple instances might be needed later
+
+**⚠️ Critical Considerations**:
+- Thread safety required in multi-threaded applications
+- Use double-check locking pattern
+- Consider dependency injection alternatives
+
+#### Factory Pattern Validation
+**✅ Appropriate when**:
+- 3+ similar classes need creation
+- Complex creation logic exists
+- Runtime type switching needed
+- Creation parameters vary by type
+
+**❌ Inappropriate when**:
+- Only 1-2 types exist
+- Simple object creation (just `new Object()`)
+- "Just in case" scenarios
+
+**📊 Thresholds**:
+- Use for 3+ implementations
+- Consider if/else for 2-3 cases
+
+#### Observer Pattern Validation
+**✅ Appropriate when**:
+- 2+ observers need notifications
+- Event-driven architecture
+- One-to-many relationships
+- Loose coupling desired
+
+**❌ Inappropriate when**:
+- Only 1 observer exists
+- Performance critical (notification overhead)
+- Complex update sequences
+- Tight coupling acceptable
+
+**🧵 Threading Considerations**:
+- Protect observer list with locks
+- Consider async notifications
+- Handle observer failures gracefully
+
+#### Strategy Pattern Validation
+**✅ Appropriate when**:
+- 3+ different algorithms exist
+- Runtime switching needed
+- Eliminating large conditionals (>10 lines)
+- Algorithm variations expected to grow
+
+**❌ Inappropriate when**:
+- Only 1-2 algorithms
+- Simple variations
+- Algorithms rarely change
+- Performance critical with minimal differences
+
+**📊 Thresholds**:
+- Use for 3+ algorithms
+- if/else acceptable for 2-3 simple cases
+
+#### Command Pattern Validation
+**✅ Appropriate when**:
+- Undo/redo functionality needed
+- Operation queuing required
+- Macro commands (composite operations)
+- Audit logging of operations
+- GUI actions with complex logic
+
+**❌ Inappropriate when**:
+- Simple operations
+- No undo needed
+- Performance critical paths
+- Basic getters/setters
+
+#### Builder Pattern Validation
+**✅ Appropriate when**:
+- 5+ constructor parameters
+- 3+ optional parameters
+- Step-by-step construction needed
+- Complex validation during construction
+- Immutable objects with many fields
+
+**❌ Inappropriate when**:
+- Few parameters (<5)
+- Simple construction
+- No validation needed
+- Dataclasses sufficient
+
+**📊 Thresholds**:
+- Consider for 5+ parameters
+- Use dataclasses for simple cases
+
+#### Repository Pattern Validation
+**✅ Appropriate when**:
+- Multiple data sources
+- Complex queries
+- Domain-driven design
+- Abstracting data access layer
+- Different storage strategies
+
+**❌ Inappropriate when**:
+- Simple CRUD operations
+- ORM already provides abstraction
+- Single data source
+- Generic repository anti-pattern
+
+#### Adapter Pattern Validation
+**✅ Appropriate when**:
+- Incompatible interfaces
+- Cannot modify existing code
+- Third-party integration
+- Legacy system integration
+
+**❌ Inappropriate when**:
+- Can modify interfaces directly
+- Interfaces already compatible
+- Adaptation too complex
+
+**💡 Note**: Simplest pattern when you can't change existing interfaces
+
+#### Decorator Pattern Validation
+**✅ Appropriate when**:
+- 3+ optional features
+- Multiple feature combinations
+- Dynamic behavior addition
+- Composable behaviors
+
+**❌ Inappropriate when**:
+- Fixed combinations
+- Complex interfaces
+- Simple objects
+- Performance critical
+
+**📊 Thresholds**:
+- Valuable for 3+ features
+- Consider inheritance for 2-3 features
+
+#### State Pattern Validation
+**✅ Appropriate when**:
+- 3+ states with different behaviors
+- Complex state transitions
+- Finite state machines
+- State-dependent behavior
+
+**❌ Inappropriate when**:
+- Simple boolean states
+- 2-3 simple states
+- Performance critical
+- Simple conditional logic sufficient
+
+**💡 Alternative**: Consider enum + match for simple state logic
+
+### Step 3: Provide Validation Response
+
+Format response based on validation result:
+
+#### ✅ APPROPRIATE Pattern Usage
+```
+✅ **[Pattern] Pattern Assessment**
+
+**Scenario Analysis**:
+- [Key requirement 1] ✓ (meets threshold)
+- [Key requirement 2] ✓ (appropriate use case)
+- [Key requirement 3] ✓ (expected benefit)
+
+**Validation Result**: **APPROPRIATE**
+**Confidence**: [LOW/MEDIUM/HIGH/CRITICAL]
+
+**Requirements Met**:
+✓ [Specific criteria from pattern]
+✓ [Threshold exceeded]
+✓ [Use case match]
+
+**Implementation Guidance**:
+- [Key design decisions]
+- [Performance considerations]
+- [Thread safety if applicable]
+- [Testing implications]
+
+**Repository Reference**: `notebooks/[XX]_[pattern]_pattern.ipynb`
+```
+
+#### ❌ INAPPROPRIATE Pattern Usage / Anti-Pattern
+```
+❌ **ANTI-PATTERN DETECTED**
+
+⚠️ **Critical Issue**: [Specific problem]
+**Risk Level**: [LOW/MEDIUM/HIGH/CRITICAL]
+
+**Problems**:
+- [Specific issue 1]
+- [Specific issue 2]
+- [Testing/maintenance concerns]
+
+**Better Alternatives**:
+1. **[Alternative 1]**: [Description and benefits]
+2. **[Alternative 2]**: [Description and benefits]
+
+**Example**:
+```python
+# ❌ DON'T DO THIS
+[Bad example]
+
+# ✅ DO THIS
+[Good alternative]
+```
+
+**Confidence**: [HIGH/CRITICAL] - This is definitely problematic
+```
+
+#### ⚠️ BORDERLINE Pattern Usage
+```
+⚠️ **Borderline Pattern Usage**
+
+**Scenario Analysis**:
+- [Requirement 1] [✓/❌/?] (threshold status)
+- [Requirement 2] [✓/❌/?] (appropriateness)
+- [Growth potential] ? (unclear)
+
+**Assessment**: **CONSIDER ALTERNATIVES**
+**Confidence**: [LOW/MEDIUM]
+
+**Threshold Analysis**:
+❌ [Below threshold] (current: X, threshold: Y)
+✓ [Meets criteria]
+? [Unclear factor]
+
+**Decision Factors**:
+1. [Question 1]? → [Pattern recommendation]
+2. [Question 2]? → [Alternative recommendation]
+
+**Recommendations**:
+- **If [condition]**: [Use pattern]
+- **If [condition]**: [Use alternative]
+
+**Repository Reference**: See pattern examples for similar scenarios
+```
+
+### Step 4: Handle Special Cases
+
+#### Unknown Pattern
+If pattern not in our 10 patterns:
+```
+❓ **Unknown Pattern**: [Pattern Name]
+
+This repository focuses on 10 essential design patterns:
+- Singleton, Factory, Observer, Strategy, Command
+- Builder, Repository, Adapter, Decorator, State
+
+Did you mean one of these patterns? Please clarify and I'll provide validation.
+```
+
+#### Vague Scenario
+If scenario is too vague:
+```
+🔍 **Need More Context**
+
+To provide accurate validation, please specify:
+- What problem are you trying to solve?
+- What's the expected scale/complexity?
+- Are there performance requirements?
+- What's the team's experience level?
+
+Example: `/dp::check singleton for database connection pool in multi-threaded web application`
+```
+
+## Quality Standards
+
+### High-Quality Validation Response:
+- **Specific**: References exact thresholds and criteria
+- **Evidence-Based**: Uses repository knowledge and examples
+- **Actionable**: Provides clear next steps
+- **Contextual**: Considers threading, performance, testing
+- **Alternative-Aware**: Suggests better approaches when appropriate
+
+### Validation Confidence Levels:
+- **CRITICAL**: Definitely right/wrong based on clear criteria
+- **HIGH**: Strong evidence for recommendation
+- **MEDIUM**: Likely appropriate but depends on context
+- **LOW**: Borderline case requiring more information
+
+Remember: Favor simplicity over patterns when complexity isn't justified.
\ No newline at end of file
diff --git a/commands/refactor.md b/commands/refactor.md
new file mode 100644
index 0000000..2f30b6b
--- /dev/null
+++ b/commands/refactor.md
@@ -0,0 +1,295 @@
+# /dp::refactor - Code Analysis for Pattern Opportunities
+
+**Purpose**: Analyze existing code files for pattern implementation opportunities and anti-pattern detection
+
+## Command Usage
+```
+/dp::refactor <file_path>
+/dp::refactor <directory_path>
+```
+
+## Execution Strategy
+
+You are a design pattern expert analyzing existing code for refactoring opportunities. Use the repository's code analysis tools when available, or perform manual analysis using file reading tools.
+
+### Step 1: Determine Analysis Scope
+- **Single File**: Detailed analysis of one file
+- **Directory**: Overview analysis of multiple files
+- **Large Directory** (>10 files): Summarized analysis with prioritized opportunities
+
+### Step 2: Read and Analyze Code
+
+#### For Single File Analysis:
+1. **Read the file** using the Read tool
+2. **Scan for pattern opportunities** using these indicators:
+   - Long conditional chains (Strategy pattern)
+   - Complex object creation (Factory/Builder pattern)
+   - Manual notification loops (Observer pattern)
+   - Repetitive similar classes (Strategy/Factory pattern)
+   - Global state management (Singleton evaluation)
+   - Complex parameter lists (Builder pattern)
+   - Data access mixing with business logic (Repository pattern)
+   - Incompatible interface usage (Adapter pattern)
+   - Behavior addition through inheritance (Decorator pattern)
+   - State-dependent behavior (State pattern)
+
+#### For Directory Analysis:
+1. **List files** in directory
+2. **Read key files** (largest, most complex, or core business logic)
+3. **Identify patterns** across multiple files
+4. **Prioritize opportunities** by impact and effort
+
+### Step 3: Pattern Opportunity Detection
+
+#### Strategy Pattern Indicators:
+```python
+# Look for these patterns:
+if condition == "type1":
+    # 10+ lines of logic
+elif condition == "type2":
+    # 10+ lines of logic
+elif condition == "type3":
+    # 10+ lines of logic
+
+# Or switch-like dictionaries:
+handlers = {
+    "type1": handler1,
+    "type2": handler2,
+    "type3": handler3,
+}
+```
+
+#### Factory Pattern Indicators:
+```python
+# Look for complex creation logic:
+def create_object(type_name, **kwargs):
+    if type_name == "A":
+        return ClassA(param1, param2, validation1())
+    elif type_name == "B":
+        return ClassB(param3, param4, validation2())
+
+# Or multiple isinstance checks:
+if isinstance(obj, TypeA):
+    return ProcessorA(obj)
+elif isinstance(obj, TypeB):
+    return ProcessorB(obj)
+```
+
+#### Observer Pattern Indicators:
+```python
+# Look for manual notification loops:
+for listener in self.listeners:
+    listener.notify(event)
+
+# Or callback management:
+def add_callback(self, callback):
+    self.callbacks.append(callback)
+
+def notify_all(self, data):
+    for callback in self.callbacks:
+        callback(data)
+```
+
+#### Singleton Pattern Evaluation:
+```python
+# Look for global variables or class variables:
+_instance = None
+
+# Or module-level state:
+current_user = None
+app_config = {}
+
+# Evaluate if singleton is appropriate or anti-pattern
+```
+
+#### Builder Pattern Indicators:
+```python
+# Look for functions/constructors with many parameters:
+def __init__(self, param1, param2, param3, param4, param5, param6=None, param7=None):
+
+# Or complex construction:
+def create_report(title, data, format, styling, headers, footers, metadata):
+```
+
+#### Repository Pattern Indicators:
+```python
+# Look for mixed data access and business logic:
+class UserService:
+    def get_user(self, id):
+        # Direct database access mixed with business logic
+        user = db.execute("SELECT * FROM users WHERE id = ?", id)
+        # Business logic here
+        return processed_user
+```
+
+#### Anti-Pattern Detection:
+- **Singleton for data models** (User, Product, Order classes)
+- **God objects** (classes doing too many things)
+- **Generic repository** (one repository for all entities)
+- **Pattern overuse** (patterns where simple code would work)
+
+### Step 4: Provide Structured Analysis
+
+#### Single File Analysis Format:
+```
+🔍 **Code Analysis**: [file_path]
+
+**Overview**:
+- Lines of code: [number]
+- Complexity: [Low/Medium/High]
+- Pattern opportunities: [count]
+
+## Pattern Opportunities
+
+### 1. [Pattern Name] (Priority: [0.0-1.0])
+**Location**: Lines [start-end]
+**Current Issue**: [Description of problem]
+**Impact**: [Low/Medium/High] | **Effort**: [Low/Medium/High]
+
+**Code Snippet**:
+```python
+# Current problematic code
+[relevant code section]
+```
+
+**Refactoring Suggestion**:
+```python
+# Improved pattern-based solution
+[pattern implementation]
+```
+
+**Benefits**:
+- [Specific improvement 1]
+- [Specific improvement 2]
+- [Maintenance benefit]
+
+**Migration Steps**:
+1. [Step 1]
+2. [Step 2]
+3. [Step 3]
+
+### 2. [Next Pattern] (Priority: [0.0-1.0])
+[Similar format...]
+
+## Anti-Patterns Detected
+[If any found, list with warnings]
+
+## Recommendations
+1. **Priority 1**: [Highest impact change]
+2. **Priority 2**: [Next most important]
+3. **Future**: [Consider when [condition]]
+
+**Estimated Effort**: [time estimate]
+**Expected ROI**: [benefit description]
+```
+
+#### Directory Analysis Format:
+```
+📊 **Repository Analysis**: [directory_path]
+
+**Overview**:
+- Files analyzed: [count]
+- Total opportunities: [count]
+- High priority: [count]
+- Anti-patterns detected: [count]
+
+## Anti-Pattern Alerts ⚠️
+[List critical issues first]
+
+## High-Priority Opportunities
+
+### 1. [Pattern] in [File]
+**Confidence**: [HIGH/MEDIUM/LOW] | **ROI**: [High/Medium/Low]
+**Lines**: [location]
+**Issue**: [Brief description]
+
+### 2. [Pattern] in [File]
+[Similar format...]
+
+## Medium-Priority Opportunities
+[Shorter descriptions of secondary opportunities]
+
+## Architectural Insights
+**Complexity Assessment**: [Overall assessment]
+**Common Patterns**: [Patterns that appear multiple times]
+**Technical Debt**: [Areas needing attention]
+
+**Recommendations**:
+1. [Most important change]
+2. [Second priority]
+3. [Future considerations]
+
+**Effort Estimate**: [Overall time for top priorities]
+```
+
+### Step 5: Priority Scoring Algorithm
+
+Calculate priority scores (0.0-1.0) based on:
+
+#### Impact Factors (60% of score):
+- **Code complexity reduced**: High conditionals = +0.3
+- **Maintainability improved**: Easier to extend = +0.2
+- **Bug reduction potential**: Common error patterns = +0.1
+
+#### Effort Factors (40% of score):
+- **Implementation difficulty**: 
+  - Simple refactor = +0.2
+  - Moderate changes = +0.1
+  - Complex restructure = 0.0
+- **Risk level**:
+  - Low risk = +0.2
+  - Medium risk = +0.1
+  - High risk = 0.0
+
+#### Priority Thresholds:
+- **0.8-1.0**: Critical - implement immediately
+- **0.6-0.8**: High - next sprint/iteration
+- **0.4-0.6**: Medium - future planning
+- **0.0-0.4**: Low - consider if time permits
+
+### Step 6: Handle Different Code Types
+
+#### Python Code Analysis:
+- Look for type hints and modern Python features
+- Consider dataclasses vs. Builder pattern
+- Analyze async/await usage for Observer pattern
+- Check for proper exception handling
+
+#### Mixed Language Projects:
+- Focus on architecture patterns across languages
+- Look for interface/API design patterns
+- Consider serialization and communication patterns
+
+#### Legacy Code:
+- Identify modernization opportunities
+- Suggest incremental refactoring approaches
+- Consider backward compatibility
+
+### Step 7: Integration with Repository Tools
+
+If available, use the repository's analysis tools:
+```python
+# Try to import and use existing analysis tools
+from src.patterns.code_analyzer import analyze_file
+from src.patterns.repo_analyzer import analyze_directory
+
+# Fall back to manual analysis if not available
+```
+
+## Quality Standards
+
+### High-Quality Analysis Features:
+- **Specific line references** for all opportunities
+- **Before/after code examples** for major suggestions
+- **Effort estimation** based on actual code complexity
+- **Risk assessment** for each refactoring
+- **Repository-specific knowledge** integration
+
+### Avoid These Common Mistakes:
+- Suggesting patterns for their own sake
+- Ignoring existing code quality and style
+- Recommending complex refactors without clear benefits
+- Missing anti-pattern detection
+- Providing vague or general suggestions
+
+Remember: The goal is to improve code quality and maintainability, not to use patterns everywhere. Always consider whether the refactoring truly adds value.
\ No newline at end of file
diff --git a/commands/validate.md b/commands/validate.md
new file mode 100644
index 0000000..6494da7
--- /dev/null
+++ b/commands/validate.md
@@ -0,0 +1,347 @@
+# /dp::validate - Anti-Pattern Detection & Overengineering Prevention
+
+**Purpose**: Detect and prevent common pattern misuse, overengineering, and architectural mistakes
+
+## Command Usage
+```
+/dp::validate <pattern usage description or architectural plan>
+```
+
+## Execution Strategy
+
+You are a design pattern expert focused on preventing common mistakes and overengineering. Your primary goal is to catch problematic pattern usage before implementation.
+
+### Step 1: Parse the Request
+Identify what the user is proposing:
+- **Pattern Usage**: Specific pattern for specific scenario
+- **Architectural Decision**: Multiple patterns or system design
+- **Code Review**: Validating existing implementation
+- **Best Practice Question**: "Should I use X because it's good practice?"
+
+### Step 2: Anti-Pattern Detection Matrix
+
+#### Critical Anti-Patterns (🚨 CRITICAL)
+
+##### Singleton Overuse
+**Red Flags**:
+- "Make all service classes singleton for consistency"
+- "Use singleton for User/Product/Order models"
+- "Singleton ensures only one instance" (without valid reason)
+- "Singleton for dependency injection"
+
+**Detection Logic**:
+```
+IF entity_type in ["User", "Product", "Order", "Customer", "Transaction"] 
+   AND pattern == "Singleton"
+THEN severity = CRITICAL, warning = "Data model singleton anti-pattern"
+
+IF reason == "consistency" OR reason == "best practice"
+   AND pattern == "Singleton"  
+THEN severity = HIGH, warning = "Invalid singleton justification"
+```
+
+##### Pattern Overuse for Simple Problems
+**Red Flags**:
+- Multiple patterns for simple domains (todo app with 4+ patterns)
+- "Let's use Factory because it's good practice"
+- Patterns where if/else would be simpler
+- "Future-proofing" without concrete requirements
+
+**Detection Logic**:
+```
+IF pattern_count > domain_complexity_threshold
+THEN severity = CRITICAL, warning = "Overengineering detected"
+
+IF justification == "best practice" OR justification == "future-proofing"
+   AND concrete_requirements = False
+THEN severity = HIGH, warning = "Pattern without clear benefit"
+```
+
+##### Generic Repository Anti-Pattern
+**Red Flags**:
+- "Generic repository for all entities"
+- "IRepository<T> for everything"
+- "Repository pattern for simple CRUD"
+
+#### High Risk Anti-Patterns (⚠️ HIGH)
+
+##### Factory for Simple Creation
+**Red Flags**:
+- Factory for objects with simple constructors
+- Factory "because it's a pattern"
+- Factory with only 1-2 types
+
+##### Strategy for Few Algorithms
+**Red Flags**:
+- Strategy pattern for 2 simple algorithms
+- Strategy where if/else is clearer
+- Strategy "for future flexibility" without growth plans
+
+##### Observer for Single Listener
+**Red Flags**:
+- Observer pattern with only one observer
+- Observer for simple callbacks
+- Observer in performance-critical paths
+
+#### Medium Risk Issues (ℹ️ MEDIUM)
+
+##### Premature Pattern Application
+**Red Flags**:
+- Applying patterns before hitting limitations
+- Complex patterns in prototypes
+- Patterns based on assumptions
+
+### Step 3: Validation Rules by Pattern
+
+#### Singleton Validation Rules
+```
+CRITICAL_ERRORS:
+- entity.type in ["User", "Product", "Order", "Customer", "Account"]
+- justification == "consistency" OR "best practice"
+- "avoid multiple instances" without resource constraint
+
+HIGH_WARNINGS:
+- no_thread_safety AND multi_threaded_app
+- testing_difficult AND tests_required
+- mutable_state AND concurrent_access
+
+VALID_USES:
+- expensive_resource_creation (database pools, config)
+- global_access_required (logging, metrics)
+- resource_management (file handles, connections)
+```
+
+#### Factory Validation Rules
+```
+OVERENGINEERING_INDICATORS:
+- type_count < 3 AND simple_creation
+- justification == "best practice"
+- no_runtime_switching AND no_complex_creation
+
+VALID_THRESHOLDS:
+- type_count >= 3 OR complex_creation_logic
+- runtime_type_selection OR parameter_variation
+- creation_logic > 5_lines OR external_dependencies
+```
+
+#### Strategy Validation Rules
+```
+BELOW_THRESHOLD:
+- algorithm_count < 3 AND no_growth_plan
+- simple_conditionals < 10_lines
+- algorithms_never_change
+
+VALID_USAGE:
+- algorithm_count >= 3 OR complex_logic_per_algorithm
+- runtime_selection OR plugin_architecture
+- eliminate_conditionals > 10_lines
+```
+
+### Step 4: Provide Risk Assessment
+
+#### Risk Level Calculation:
+```python
+def calculate_risk_level(indicators):
+    score = 0
+    if critical_anti_pattern: score += 10
+    if high_risk_pattern: score += 7  
+    if medium_risk_pattern: score += 4
+    if overengineering_detected: score += 5
+    if no_clear_benefit: score += 3
+    
+    if score >= 10: return "CRITICAL"
+    elif score >= 7: return "HIGH" 
+    elif score >= 4: return "MEDIUM"
+    else: return "LOW"
+```
+
+### Step 5: Response Format by Risk Level
+
+#### 🚨 CRITICAL Risk Response:
+```
+🚨 **CRITICAL ANTI-PATTERN DETECTED**
+
+**Issue**: [Specific anti-pattern name]
+**Risk Level**: CRITICAL
+
+**Major Problems**:
+1. [Specific problem 1 with consequences]
+2. [Specific problem 2 with consequences] 
+3. [Testing/maintenance/performance implications]
+
+**Why This is Problematic**:
+[Clear explanation of why this approach fails]
+
+**Better Alternatives**:
+
+**1. [Alternative 1]**:
+```python
+# ✅ RECOMMENDED APPROACH
+[Good example with explanation]
+```
+
+**2. [Alternative 2]**:
+```python
+# ✅ ALTERNATIVE APPROACH  
+[Another good example]
+```
+
+**❌ DON'T DO THIS**:
+```python
+# Anti-pattern example
+[Bad code example]
+```
+
+**Rule of Thumb**: [Simple decision rule]
+**Confidence**: CRITICAL - This should definitely be avoided
+```
+
+#### ⚠️ HIGH Risk Response:
+```
+⚠️ **Potential Overengineering Detected**
+
+**Issue**: [Pattern misuse description]
+**Risk Level**: HIGH
+
+**Analysis**:
+❌ [Specific problem 1]
+❌ [Specific problem 2]
+? [Unclear requirement]
+
+**Questions to Consider**:
+1. [Specific question about requirements]
+2. [Question about complexity justification]
+3. [Question about alternatives]
+
+**If answers are NO**: [Simple alternative]
+**If answers are YES**: [Pattern justified]
+
+**Example Comparison**:
+```python
+# ❌ UNNECESSARY COMPLEXITY
+[Overengineered example]
+
+# ✅ SIMPLE AND CLEAR
+[Simple alternative]
+```
+
+**Recommendation**: [Clear guidance]
+```
+
+#### ℹ️ MEDIUM Risk Response:
+```
+ℹ️ **Consider Alternatives**
+
+**Issue**: [Description of concern]
+**Risk Level**: MEDIUM
+
+**Analysis**:
+✓ [Valid aspect]
+⚠️ [Concerning aspect]
+? [Needs clarification]
+
+**Decision Factors**:
+- **If [condition]**: Use pattern
+- **If [condition]**: Use simpler approach
+- **If [condition]**: Consider hybrid
+
+**Threshold Analysis**:
+- Current complexity: [assessment]
+- Pattern threshold: [requirement]
+- Gap: [what's missing]
+
+**Recommendation**: [Nuanced guidance]
+```
+
+#### ✅ LOW Risk Response:
+```
+✅ **Appropriate Pattern Usage**
+
+**Assessment**: Reasonable pattern choice
+**Risk Level**: LOW
+
+**Validation**:
+✓ [Requirement met]
+✓ [Threshold exceeded]  
+✓ [Clear benefit]
+
+**Considerations**:
+- [Implementation tip]
+- [Performance note]
+- [Testing strategy]
+
+**Proceed with confidence**
+```
+
+### Step 6: Context-Specific Validation
+
+#### Team Experience Level:
+- **Junior team**: Warn against complex patterns
+- **Senior team**: Allow more sophisticated patterns
+- **Mixed team**: Suggest progressive implementation
+
+#### Project Context:
+- **Prototype**: Warn against premature patterns
+- **Production**: Consider maintenance implications
+- **Legacy integration**: Consider compatibility
+
+#### Performance Requirements:
+- **High performance**: Warn about Observer overhead
+- **Real-time**: Question complex pattern stacks
+- **Scalability**: Consider pattern performance characteristics
+
+### Step 7: Specific Anti-Pattern Responses
+
+#### "Because it's a best practice"
+```
+❌ **Invalid Justification**
+
+"Best practice" is never a sufficient reason for pattern usage.
+
+**Valid reasons require**:
+- Specific problem being solved
+- Clear benefit over simpler approaches
+- Concrete requirements driving complexity
+
+**Questions to ask**:
+1. What specific problem does this pattern solve?
+2. What happens if you use a simpler approach?
+3. What concrete benefits do you expect?
+
+**Remember**: The best practice is to solve real problems simply.
+```
+
+#### Multiple Patterns for Simple Domain
+```
+🚨 **Severe Overengineering Alert**
+
+**Pattern Budget Exceeded**:
+- Simple domains: 0-1 patterns maximum
+- Medium domains: 1-2 patterns maximum  
+- Complex domains: 2-4 patterns maximum
+
+**Your proposal**: [X] patterns for [simple] domain
+
+**Reality Check**:
+Most successful applications use patterns sparingly and only when complexity justifies them.
+
+**Golden Rule**: Start simple. Add patterns when you hit actual limitations.
+```
+
+## Quality Standards
+
+### High-Quality Validation Features:
+- **Specific risk identification** with concrete examples
+- **Alternative solutions** that solve the real problem
+- **Clear decision criteria** for when patterns are appropriate
+- **Code examples** showing better approaches
+- **Context consideration** (team, project, performance)
+
+### Response Principles:
+1. **Prevent harm first**: Stop bad decisions before implementation
+2. **Educate reasoning**: Explain why something is problematic
+3. **Provide alternatives**: Don't just say no, show better ways
+4. **Be decisive**: Clear recommendations, not wishy-washy advice
+5. **Context-aware**: Consider team and project constraints
+
+Remember: Your job is to prevent pattern misuse and overengineering. When in doubt, recommend the simpler approach.
\ No newline at end of file
diff --git a/docker-compose.yml b/docker-compose.yml
index 07da831..2824781 100644
--- a/docker-compose.yml
+++ b/docker-compose.yml
@@ -1,42 +1,46 @@
-# Docker Compose configuration for Design Patterns Tutorial
+# Docker Compose configuration for AI Architecture Advisor
 
 services:
   jupyter:
     build:
       context: .
       dockerfile: Dockerfile
-    container_name: design-patterns-jupyter
+    container_name: ai-architecture-advisor-jupyter
     ports:
       - "8888:8888"
     volumes:
-      - ./notebooks:/home/jupyter/work/notebooks
-      - ./src:/home/jupyter/work/src
-      - ./tests:/home/jupyter/work/tests
+      - ./learning-resources/notebooks:/home/jupyter/work/notebooks
+      - ./learning-resources/examples/implementations:/home/jupyter/work/implementations
+      - ./learning-resources/examples/tests:/home/jupyter/work/tests
+      - ./ai-engine:/home/jupyter/work/ai-engine
+      - ./commands:/home/jupyter/work/commands
       - ./data:/home/jupyter/work/data
     environment:
       - JUPYTER_ENABLE_LAB=yes
-      - JUPYTER_TOKEN=design-patterns-2025
+      - JUPYTER_TOKEN=ai-advisor-2025
     restart: unless-stopped
     networks:
-      - design-patterns-net
+      - ai-advisor-net
 
   # Optional: Add a service for running tests
   test-runner:
     build:
       context: .
       dockerfile: Dockerfile
-    container_name: design-patterns-tests
+    container_name: ai-architecture-advisor-tests
     command: python simple_test_runner.py
     volumes:
-      - ./src:/home/jupyter/work/src
+      - ./learning-resources/examples/implementations:/home/jupyter/work/implementations
+      - ./learning-resources/examples/tests:/home/jupyter/work/tests
+      - ./ai-engine:/home/jupyter/work/ai-engine
       - ./simple_test_runner.py:/home/jupyter/work/simple_test_runner.py
     profiles:
       - test
     networks:
-      - design-patterns-net
+      - ai-advisor-net
 
 networks:
-  design-patterns-net:
+  ai-advisor-net:
     driver: bridge
 
 volumes:
diff --git a/src/__init__.py b/learning-resources/examples/implementations/__init__.py
similarity index 100%
rename from src/__init__.py
rename to learning-resources/examples/implementations/__init__.py
diff --git a/src/patterns/__init__.py b/learning-resources/examples/implementations/patterns/__init__.py
similarity index 100%
rename from src/patterns/__init__.py
rename to learning-resources/examples/implementations/patterns/__init__.py
diff --git a/src/patterns/adapter.py b/learning-resources/examples/implementations/patterns/adapter.py
similarity index 100%
rename from src/patterns/adapter.py
rename to learning-resources/examples/implementations/patterns/adapter.py
diff --git a/src/patterns/builder.py b/learning-resources/examples/implementations/patterns/builder.py
similarity index 100%
rename from src/patterns/builder.py
rename to learning-resources/examples/implementations/patterns/builder.py
diff --git a/src/patterns/command.py b/learning-resources/examples/implementations/patterns/command.py
similarity index 100%
rename from src/patterns/command.py
rename to learning-resources/examples/implementations/patterns/command.py
diff --git a/src/patterns/decorator.py b/learning-resources/examples/implementations/patterns/decorator.py
similarity index 100%
rename from src/patterns/decorator.py
rename to learning-resources/examples/implementations/patterns/decorator.py
diff --git a/src/patterns/factory.py b/learning-resources/examples/implementations/patterns/factory.py
similarity index 100%
rename from src/patterns/factory.py
rename to learning-resources/examples/implementations/patterns/factory.py
diff --git a/src/patterns/observer.py b/learning-resources/examples/implementations/patterns/observer.py
similarity index 100%
rename from src/patterns/observer.py
rename to learning-resources/examples/implementations/patterns/observer.py
diff --git a/src/patterns/repository.py b/learning-resources/examples/implementations/patterns/repository.py
similarity index 100%
rename from src/patterns/repository.py
rename to learning-resources/examples/implementations/patterns/repository.py
diff --git a/src/patterns/singleton.py b/learning-resources/examples/implementations/patterns/singleton.py
similarity index 100%
rename from src/patterns/singleton.py
rename to learning-resources/examples/implementations/patterns/singleton.py
diff --git a/src/patterns/state.py b/learning-resources/examples/implementations/patterns/state.py
similarity index 100%
rename from src/patterns/state.py
rename to learning-resources/examples/implementations/patterns/state.py
diff --git a/src/patterns/strategy.py b/learning-resources/examples/implementations/patterns/strategy.py
similarity index 100%
rename from src/patterns/strategy.py
rename to learning-resources/examples/implementations/patterns/strategy.py
diff --git a/tests/__init__.py b/learning-resources/examples/tests/__init__.py
similarity index 100%
rename from tests/__init__.py
rename to learning-resources/examples/tests/__init__.py
diff --git a/tests/conftest.py b/learning-resources/examples/tests/conftest.py
similarity index 99%
rename from tests/conftest.py
rename to learning-resources/examples/tests/conftest.py
index e93d12e..9ab6598 100644
--- a/tests/conftest.py
+++ b/learning-resources/examples/tests/conftest.py
@@ -32,7 +32,7 @@ def reset_singletons():
     yield
 
     # Reset any resettable singletons
-    from src.patterns.singleton import ResettableSingleton
+    from implementations.patterns.singleton import ResettableSingleton
 
     # Get all subclasses of ResettableSingleton
     for subclass in ResettableSingleton.__subclasses__():
diff --git a/tests/test_patterns/__init__.py b/learning-resources/examples/tests/test_patterns/__init__.py
similarity index 100%
rename from tests/test_patterns/__init__.py
rename to learning-resources/examples/tests/test_patterns/__init__.py
diff --git a/tests/test_patterns/test_adapter.py b/learning-resources/examples/tests/test_patterns/test_adapter.py
similarity index 99%
rename from tests/test_patterns/test_adapter.py
rename to learning-resources/examples/tests/test_patterns/test_adapter.py
index df28e2b..e210c27 100644
--- a/tests/test_patterns/test_adapter.py
+++ b/learning-resources/examples/tests/test_patterns/test_adapter.py
@@ -5,7 +5,7 @@
 
 import pytest
 
-from src.patterns.adapter import (  # Target Interface; Adaptee Classes; Adapter Classes; Database Adapter Example; Payment Gateway Adapter Example; Object Adapter vs Class Adapter; Service Layer
+from implementations.patterns.adapter import (  # Target Interface; Adaptee Classes; Adapter Classes; Database Adapter Example; Payment Gateway Adapter Example; Object Adapter vs Class Adapter; Service Layer
     AudioPlayer,
     DatabaseConnection,
     LegacyRectangle,
diff --git a/tests/test_patterns/test_builder.py b/learning-resources/examples/tests/test_patterns/test_builder.py
similarity index 99%
rename from tests/test_patterns/test_builder.py
rename to learning-resources/examples/tests/test_patterns/test_builder.py
index 10aa591..063076f 100644
--- a/tests/test_patterns/test_builder.py
+++ b/learning-resources/examples/tests/test_patterns/test_builder.py
@@ -4,7 +4,7 @@
 
 import pytest
 
-from src.patterns.builder import (  # Product Classes; Builder Classes; Director Classes
+from implementations.patterns.builder import (  # Product Classes; Builder Classes; Director Classes
     Builder,
     Computer,
     ComputerBuilder,
diff --git a/tests/test_patterns/test_command.py b/learning-resources/examples/tests/test_patterns/test_command.py
similarity index 99%
rename from tests/test_patterns/test_command.py
rename to learning-resources/examples/tests/test_patterns/test_command.py
index 6bef25b..f1e5b6d 100644
--- a/tests/test_patterns/test_command.py
+++ b/learning-resources/examples/tests/test_patterns/test_command.py
@@ -5,7 +5,7 @@
 
 import pytest
 
-from src.patterns.command import (  # Basic Command Pattern; Receiver Classes; Concrete Command Classes; Invoker Classes; Command Queue and History; Text Editor Example
+from implementations.patterns.command import (  # Basic Command Pattern; Receiver Classes; Concrete Command Classes; Invoker Classes; Command Queue and History; Text Editor Example
     Command,
     CommandHistory,
     CommandHistoryEntry,
diff --git a/tests/test_patterns/test_decorator.py b/learning-resources/examples/tests/test_patterns/test_decorator.py
similarity index 99%
rename from tests/test_patterns/test_decorator.py
rename to learning-resources/examples/tests/test_patterns/test_decorator.py
index f880e24..4aea41d 100644
--- a/tests/test_patterns/test_decorator.py
+++ b/learning-resources/examples/tests/test_patterns/test_decorator.py
@@ -6,7 +6,7 @@
 
 import pytest
 
-from src.patterns.decorator import (  # Basic Decorator Pattern; Beverage Example; Text Processing; Function Decorators; Class-based Decorator
+from implementations.patterns.decorator import (  # Basic Decorator Pattern; Beverage Example; Text Processing; Function Decorators; Class-based Decorator
     Beverage,
     CensorDecorator,
     Cinnamon,
diff --git a/tests/test_patterns/test_factory.py b/learning-resources/examples/tests/test_patterns/test_factory.py
similarity index 99%
rename from tests/test_patterns/test_factory.py
rename to learning-resources/examples/tests/test_patterns/test_factory.py
index a594570..0913dae 100644
--- a/tests/test_patterns/test_factory.py
+++ b/learning-resources/examples/tests/test_patterns/test_factory.py
@@ -5,7 +5,7 @@
 
 import pytest
 
-from src.patterns.factory import (  # Basic Factory Pattern; Notification Factory; Shape Factory; Abstract Factory
+from implementations.patterns.factory import (  # Basic Factory Pattern; Notification Factory; Shape Factory; Abstract Factory
     AbstractFactory,
     Button,
     Checkbox,
diff --git a/tests/test_patterns/test_observer.py b/learning-resources/examples/tests/test_patterns/test_observer.py
similarity index 99%
rename from tests/test_patterns/test_observer.py
rename to learning-resources/examples/tests/test_patterns/test_observer.py
index 30ed249..78f9ff6 100644
--- a/tests/test_patterns/test_observer.py
+++ b/learning-resources/examples/tests/test_patterns/test_observer.py
@@ -6,7 +6,7 @@
 
 import pytest
 
-from src.patterns.observer import (  # Basic Observer Pattern; Weather Station Example; Stock Market Example; Event System
+from implementations.patterns.observer import (  # Basic Observer Pattern; Weather Station Example; Stock Market Example; Event System
     AuditService,
     ConcreteObserver,
     ConcreteSubject,
diff --git a/tests/test_patterns/test_repository.py b/learning-resources/examples/tests/test_patterns/test_repository.py
similarity index 99%
rename from tests/test_patterns/test_repository.py
rename to learning-resources/examples/tests/test_patterns/test_repository.py
index 6731b36..43f65eb 100644
--- a/tests/test_patterns/test_repository.py
+++ b/learning-resources/examples/tests/test_patterns/test_repository.py
@@ -9,7 +9,7 @@
 
 import pytest
 
-from src.patterns.repository import (  # Domain Models; Repository Interfaces; Concrete Implementations; Services; Unit of Work
+from implementations.patterns.repository import (  # Domain Models; Repository Interfaces; Concrete Implementations; Services; Unit of Work
     InMemoryOrderRepository,
     InMemoryProductRepository,
     InMemoryUserRepository,
diff --git a/tests/test_patterns/test_singleton.py b/learning-resources/examples/tests/test_patterns/test_singleton.py
similarity index 99%
rename from tests/test_patterns/test_singleton.py
rename to learning-resources/examples/tests/test_patterns/test_singleton.py
index d639ec2..7575d8e 100644
--- a/tests/test_patterns/test_singleton.py
+++ b/learning-resources/examples/tests/test_patterns/test_singleton.py
@@ -7,7 +7,7 @@
 
 import pytest
 
-from src.patterns.singleton import (
+from implementations.patterns.singleton import (
     ConfigurationManager,
     Logger,
     ResettableSingleton,
diff --git a/tests/test_patterns/test_state.py b/learning-resources/examples/tests/test_patterns/test_state.py
similarity index 99%
rename from tests/test_patterns/test_state.py
rename to learning-resources/examples/tests/test_patterns/test_state.py
index 4d97890..5c76376 100644
--- a/tests/test_patterns/test_state.py
+++ b/learning-resources/examples/tests/test_patterns/test_state.py
@@ -7,7 +7,7 @@
 
 import pytest
 
-from src.patterns.state import (  # Abstract classes; Vending Machine implementations; Traffic Light implementations; Media Player implementations; Order Processing implementations; Demo functions
+from implementations.patterns.state import (  # Abstract classes; Vending Machine implementations; Traffic Light implementations; Media Player implementations; Order Processing implementations; Demo functions
     CancelledState,
     CoinInsertedState,
     Context,
diff --git a/tests/test_patterns/test_strategy.py b/learning-resources/examples/tests/test_patterns/test_strategy.py
similarity index 99%
rename from tests/test_patterns/test_strategy.py
rename to learning-resources/examples/tests/test_patterns/test_strategy.py
index d8b3e2c..1a3858b 100644
--- a/tests/test_patterns/test_strategy.py
+++ b/learning-resources/examples/tests/test_patterns/test_strategy.py
@@ -5,7 +5,7 @@
 
 import pytest
 
-from src.patterns.strategy import (  # Basic Strategy Pattern; Payment Processing; Sorting Algorithms; Discount Calculation
+from implementations.patterns.strategy import (  # Basic Strategy Pattern; Payment Processing; Sorting Algorithms; Discount Calculation
     BubbleSort,
     BuyOneGetOneDiscount,
     Context,
diff --git a/docs/.gitkeep b/learning-resources/guides/.gitkeep
similarity index 100%
rename from docs/.gitkeep
rename to learning-resources/guides/.gitkeep
diff --git a/learning-resources/guides/dp_commands_guide.md b/learning-resources/guides/dp_commands_guide.md
new file mode 100644
index 0000000..d32608b
--- /dev/null
+++ b/learning-resources/guides/dp_commands_guide.md
@@ -0,0 +1,698 @@
+# Design Pattern Commands Guide
+
+Complete guide to using the `dp::` namespaced commands for intelligent design pattern recommendations.
+
+## Commands Overview
+
+| Command | Purpose | When to Use |
+|---------|---------|-------------|
+| `/dp::analyze` | Comprehensive pattern analysis | Complex scenarios, multiple pattern candidates |
+| `/dp::check` | Quick pattern validation | Verify specific pattern choice |
+| `/dp::refactor` | Code analysis for opportunities | Existing code improvement |
+| `/dp::validate` | Anti-pattern detection | Prevent pattern misuse |
+
+---
+
+## `/dp::analyze` - Comprehensive Pattern Analysis
+
+**Purpose**: Deep analysis using sequential thinking for complex pattern decisions
+
+### When to Use
+- Multiple pattern candidates exist
+- Unclear which pattern fits best
+- Need detailed reasoning and trade-offs
+- Complex scenarios with many factors
+
+### Syntax
+```
+/dp::analyze <problem description>
+```
+
+### Examples
+
+#### Example 1: General Problem Description
+```
+/dp::analyze I need a system where different UI components update when user data changes, and I want to support real-time notifications
+```
+
+**Expected Response**:
+```
+🧠 Analyzing using sequential thinking...
+
+Thought 1: Problem Understanding
+- Multiple UI components need updates
+- Data change notifications required
+- Real-time requirement suggests performance consideration
+
+Thought 2: Complexity Assessment  
+- One-to-many relationship (data → UI components)
+- Dynamic subscription likely needed
+- Real-time adds performance constraints
+
+Thought 3: Pattern Candidates
+- Observer Pattern: Strong match for one-to-many notifications
+- Event Bus: Alternative for complex event routing
+- Simple callbacks: Simpler but less flexible
+
+Thought 4: Repository Knowledge Check
+- Observer threshold: 2+ observers ✓
+- Real-time considerations: async notifications recommended
+- Thread safety: needed for real-time systems
+
+Thought 5: Performance Analysis
+- Observer adds notification overhead
+- Real-time requirement favors efficient implementation
+- Consider async notifications for non-critical updates
+
+Recommendation: **Observer Pattern** (Confidence: HIGH)
+- Implement with async notifications for performance
+- Use typed events for better maintainability
+- Consider event filtering to reduce unnecessary updates
+
+Alternative: Event bus library if events become complex
+```
+
+#### Example 2: Specific Technical Scenario
+```
+/dp::analyze I have a payment processing system that needs to handle credit cards, PayPal, crypto, and bank transfers. Each has different fee structures and validation rules. We'll likely add more payment methods.
+```
+
+**Expected Response**:
+```
+🧠 Sequential Analysis: Payment Processing System
+
+Thought 1: Problem Breakdown
+- 4 payment methods with different logic
+- Different fee structures and validation per method  
+- Expected growth (more payment methods)
+
+Thought 2: Complexity Indicators
+- 4+ algorithms ✓ (exceeds Strategy threshold of 3)
+- Runtime selection needed ✓
+- Expected growth ✓
+- Complex logic per method ✓
+
+Thought 3: Pattern Evaluation
+- Strategy Pattern: Perfect fit for algorithm families
+- Factory Pattern: Could help with payment processor creation
+- Simple if/else: Would work but hard to extend
+
+Thought 4: Repository Guidance
+- Strategy threshold: 3+ algorithms ✓
+- Use case: "different payment processing" ✓
+- Benefits: Easy to add new methods, separate testing
+
+Thought 5: Advanced Considerations
+- Consider Strategy + Factory combination
+- Each strategy should be stateless for thread safety
+- Validation can be part of each strategy
+
+Recommendation: **Strategy Pattern** (Confidence: CRITICAL)
+1. Create PaymentProcessor interface
+2. Implement strategy for each payment method
+3. Use PaymentService as context for strategy selection
+4. Consider StrategyFactory for processor creation
+
+Expected ROI: High - Easy addition of new payment methods
+```
+
+### Advanced Usage Tips
+
+1. **Be Specific**: Include requirements, constraints, and context
+2. **Mention Scale**: "handles 1000 requests/second" affects recommendations
+3. **Include Growth Plans**: "will add more X later" influences pattern choice
+4. **Specify Constraints**: "team is junior" or "performance critical" matters
+
+---
+
+## `/dp::check` - Quick Pattern Validation
+
+**Purpose**: Fast verification of pattern appropriateness for specific scenarios
+
+### When to Use
+- You have a pattern in mind
+- Need quick validation
+- Want threshold-based assessment
+- Checking for anti-patterns
+
+### Syntax
+```
+/dp::check <pattern name> for <scenario>
+```
+
+### Examples
+
+#### Example 1: Singleton Validation
+```
+/dp::check singleton for database connection pool in multi-threaded web application
+```
+
+**Expected Response**:
+```
+✅ Singleton Pattern Assessment
+
+Scenario Analysis:
+- Database connection pool ✓ (appropriate use case)
+- Multi-threaded application ✓ (thread safety needed)
+- Expensive resource ✓ (database connections)
+
+Validation Result: **APPROPRIATE** 
+Confidence: HIGH
+
+Requirements Met:
+✓ Expensive object creation
+✓ Global access needed  
+✓ Single instance logical
+
+Thread Safety Note: ⚠️ CRITICAL
+- Must implement double-check locking
+- Protect connection pool operations
+- Consider connection pool library
+
+Implementation Guidance:
+- Use thread-safe singleton implementation
+- Initialize pool lazily or eagerly based on usage
+- Add connection health checks
+- Implement proper cleanup
+
+Repository Reference: See notebooks/01_singleton_pattern.ipynb for thread-safe implementation
+```
+
+#### Example 2: Anti-Pattern Detection
+```
+/dp::check singleton for User model class to avoid multiple instances
+```
+
+**Expected Response**:
+```
+❌ ANTI-PATTERN DETECTED
+
+⚠️ Critical Issue: Singleton for Data Model
+This is a well-known anti-pattern that should be avoided.
+
+Problems:
+- User entities should have multiple instances (multiple users exist)
+- Makes testing extremely difficult
+- Violates single responsibility principle
+- Creates hidden global dependencies
+
+Better Alternatives:
+1. **Regular Class**: Use normal User class with multiple instances
+2. **Repository Pattern**: Centralize user data access logic
+3. **Identity Map**: Prevent duplicate loading of same user
+4. **Dependency Injection**: Pass user instances explicitly
+
+Example:
+```python
+# ❌ DON'T DO THIS
+class User(metaclass=SingletonMeta): ...
+
+# ✅ DO THIS
+class User:
+    def __init__(self, id, name, email): ...
+
+class UserRepository:
+    def find_by_id(self, user_id): ...
+```
+
+Confidence: CRITICAL - This is definitely an anti-pattern
+```
+
+#### Example 3: Borderline Case
+```
+/dp::check strategy for handling 2 different export formats (PDF and Excel)
+```
+
+**Expected Response**:
+```
+⚠️ Borderline Pattern Usage
+
+Scenario Analysis:
+- 2 export formats (below Strategy threshold of 3)
+- Different algorithms ✓
+- Potential for growth ?
+
+Assessment: **CONSIDER ALTERNATIVES**
+Confidence: MEDIUM
+
+Threshold Analysis:
+❌ Below 3 algorithm threshold (current: 2)
+✓ Different implementations per format
+? Growth potential unclear
+
+Recommendations:
+
+**If no growth expected:**
+```python
+def export_report(data, format_type):
+    if format_type == 'pdf':
+        return export_to_pdf(data)
+    elif format_type == 'excel':
+        return export_to_excel(data)
+    else:
+        raise ValueError(f"Unknown format: {format_type}")
+```
+
+**If growth likely (adding Word, CSV, etc.):**
+- Implement Strategy pattern now for future expansion
+- Strategy becomes valuable at 3+ formats
+
+Decision Factors:
+1. Will you add more formats? → Use Strategy
+2. Is export logic complex (>10 lines each)? → Use Strategy  
+3. Need runtime format switching? → Use Strategy
+4. Simple one-line library calls? → Keep simple
+
+Repository Reference: See strategy pattern examples for export systems
+```
+
+---
+
+## `/dp::refactor` - Code Analysis for Pattern Opportunities
+
+**Purpose**: Analyze existing code files for pattern implementation opportunities
+
+### When to Use
+- Reviewing existing codebase
+- Looking for refactoring opportunities
+- Code quality improvement
+- Technical debt reduction
+
+### Syntax
+```
+/dp::refactor <file_path>
+/dp::refactor <directory_path>
+```
+
+### Examples
+
+#### Example 1: Single File Analysis
+```
+/dp::refactor src/payment_processor.py
+```
+
+**Expected Response**:
+```
+🔍 Code Analysis: src/payment_processor.py
+
+Found 3 Pattern Opportunities:
+
+## 1. Strategy Pattern (Priority: 0.85)
+**Lines 34-67**: Long if/elif chain for payment processing
+- **Current**: 15-line conditional with 4 payment types
+- **Issue**: Hard to add new payment methods
+- **Impact**: High | **Effort**: Medium
+
+**Refactoring Suggestion**:
+```python
+# Before (current code)
+def process_payment(type, amount):
+    if type == "credit_card":
+        # 15 lines of processing
+    elif type == "paypal":
+        # 12 lines of processing
+
+# After (strategy pattern)  
+class PaymentProcessor(ABC):
+    @abstractmethod
+    def process(self, amount): pass
+
+class CreditCardProcessor(PaymentProcessor):
+    def process(self, amount):
+        # Focused credit card logic
+```
+
+**Migration Steps**:
+1. Extract each payment type to separate class
+2. Create PaymentProcessor interface
+3. Update client code to use strategy selection
+4. Add new payment types as separate strategies
+
+## 2. Factory Pattern (Priority: 0.65)
+**Lines 89-103**: Object creation based on configuration
+- **Current**: Multiple isinstance() checks
+- **Benefit**: Centralized creation logic
+
+## 3. Builder Pattern (Priority: 0.45)  
+**Lines 23-31**: PaymentConfig constructor with 8 parameters
+- **Current**: Long parameter list in constructor
+- **Benefit**: More readable configuration setup
+
+**Next Steps**:
+1. Start with Strategy pattern (highest impact)
+2. Implement Factory for processor creation
+3. Consider Builder for complex configurations
+
+**Estimated Effort**: 4-6 hours for Strategy implementation
+**ROI**: High - Easy to add new payment methods
+```
+
+#### Example 2: Directory Analysis
+```
+/dp::refactor src/
+```
+
+**Expected Response**:
+```
+📊 Repository Analysis: src/
+
+**Overview**:
+- Files analyzed: 12
+- Total opportunities: 8
+- High priority: 3
+- Anti-patterns detected: 1
+
+## Anti-Pattern Alert ⚠️
+**src/models/user.py:15** - Singleton for User model
+- **Issue**: Data models should not be singletons
+- **Fix**: Convert to regular class
+- **Priority**: CRITICAL
+
+## High-Priority Opportunities
+
+### 1. Strategy Pattern in PaymentProcessor
+**File**: src/services/payment.py:34
+**Confidence**: HIGH | **ROI**: High
+- Replace 4-way conditional with strategy classes
+- Easy to add new payment methods
+
+### 2. Observer Pattern in NotificationService  
+**File**: src/services/notification.py:67
+**Confidence**: MEDIUM | **ROI**: Medium
+- Manual notification loops suggest Observer pattern
+- Better for event-driven architecture
+
+### 3. Factory Pattern in ReportGenerator
+**File**: src/reports/generator.py:45
+**Confidence**: MEDIUM | **ROI**: Medium
+- Multiple report types suggest factory pattern
+
+## Architectural Insights
+
+**Complexity Assessment**: Medium
+- 8 pattern opportunities suggest active development
+- Anti-pattern needs immediate attention
+- Focus on high-ROI improvements first
+
+**Recommendations**:
+1. Fix User singleton anti-pattern immediately
+2. Implement Strategy pattern for payments (highest ROI)
+3. Consider Observer for notification system
+4. Review other opportunities after main fixes
+
+**Effort Estimate**: 2-3 days for top priorities
+```
+
+---
+
+## `/dp::validate` - Anti-Pattern Detection
+
+**Purpose**: Detect and prevent common pattern misuse and overengineering
+
+### When to Use
+- Reviewing pattern proposals
+- Checking for overengineering
+- Validating architectural decisions
+- Before implementing patterns
+
+### Syntax
+```
+/dp::validate <pattern usage description>
+```
+
+### Examples
+
+#### Example 1: Catching Overengineering
+```
+/dp::validate I want to implement the Factory pattern for creating User objects because it's a best practice
+```
+
+**Expected Response**:
+```
+⚠️ Potential Overengineering Detected
+
+**Issue**: Factory pattern for simple object creation
+**Risk Level**: MEDIUM
+
+**Analysis**:
+❌ "Because it's a best practice" is not a valid reason
+❌ User objects typically don't need factory pattern
+❌ Adds complexity without clear benefit
+
+**Questions to Consider**:
+1. Do you have multiple User types that need different creation logic?
+2. Is User creation complex enough to warrant abstraction?  
+3. Will you need to switch User implementations at runtime?
+
+**If answers are NO**: Use direct instantiation
+```python
+# ✅ SIMPLE AND CLEAR
+user = User(name="John", email="john@example.com")
+
+# ❌ UNNECESSARY COMPLEXITY  
+user = UserFactory.create("standard", name="John", email="john@example.com")
+```
+
+**When Factory WOULD be appropriate for Users**:
+- Multiple user types (AdminUser, RegularUser, GuestUser)
+- Complex validation/setup logic
+- User type determined by external data
+- Integration with external systems
+
+**Recommendation**: Stick with direct instantiation unless you have specific complexity that justifies a factory.
+```
+
+#### Example 2: Singleton Misuse Detection
+```
+/dp::validate Using singleton pattern for all my service classes to ensure consistency across the application
+```
+
+**Expected Response**:
+```
+🚨 CRITICAL ANTI-PATTERN DETECTED
+
+**Issue**: Singleton overuse for "consistency"
+**Risk Level**: HIGH
+
+**Major Problems**:
+1. **Testing Nightmare**: Singletons make unit testing extremely difficult
+2. **Hidden Dependencies**: Services can't be mocked or replaced
+3. **Tight Coupling**: Creates implicit global dependencies
+4. **Concurrency Issues**: Shared state across all operations
+
+**"Consistency" is NOT a valid reason for Singleton**
+
+**Better Alternatives**:
+
+**1. Dependency Injection**:
+```python
+class OrderService:
+    def __init__(self, payment_service: PaymentService, 
+                 email_service: EmailService):
+        self.payment_service = payment_service
+        self.email_service = email_service
+
+# Consistent instance management through DI container
+services = ServiceContainer()
+order_service = services.get(OrderService)
+```
+
+**2. Service Registry**:
+```python
+class ServiceRegistry:
+    def __init__(self):
+        self._services = {}
+    
+    def register(self, service_type, instance):
+        self._services[service_type] = instance
+    
+    def get(self, service_type):
+        return self._services[service_type]
+```
+
+**3. Module-Level Instances**:
+```python
+# services.py
+payment_service = PaymentService()
+email_service = EmailService()
+
+# Other modules import and use
+from services import payment_service
+```
+
+**Valid Singleton Use Cases**:
+- Database connection pools
+- Configuration managers
+- Logging systems
+- Resource managers (file handles, etc.)
+
+**Rule of Thumb**: If you can imagine needing two instances for testing, don't use Singleton.
+```
+
+#### Example 3: Complexity Validation
+```
+/dp::validate Implementing Command pattern, Strategy pattern, Factory pattern, and Observer pattern in a simple todo application
+```
+
+**Expected Response**:
+```
+🚨 SEVERE OVERENGINEERING ALERT
+
+**Issue**: Multiple complex patterns for simple application
+**Risk Level**: CRITICAL
+
+**Analysis**:
+Todo applications are typically simple CRUD operations that don't justify complex patterns.
+
+**Pattern Overuse Indicators**:
+❌ 4 patterns for simple domain
+❌ Patterns solving imaginary problems
+❌ Complexity exceeds business requirements
+❌ Following patterns "because they're good"
+
+**Reality Check Questions**:
+1. **Command Pattern**: Do you really need undo/redo for todos?
+2. **Strategy Pattern**: How many todo algorithms do you have?
+3. **Factory Pattern**: Are you creating many different todo types?
+4. **Observer Pattern**: Do many systems need todo notifications?
+
+**Recommended Simple Approach**:
+```python
+# Simple, clear, maintainable
+class Todo:
+    def __init__(self, title: str, description: str = ""):
+        self.title = title
+        self.description = description
+        self.completed = False
+        self.created_at = datetime.now()
+
+class TodoService:
+    def __init__(self):
+        self.todos = []
+    
+    def add_todo(self, title: str, description: str = "") -> Todo:
+        todo = Todo(title, description)
+        self.todos.append(todo)
+        return todo
+    
+    def complete_todo(self, todo_id: int) -> bool:
+        # Simple completion logic
+        pass
+```
+
+**When patterns WOULD be justified**:
+- **Command**: If building collaborative todo app with undo/redo
+- **Strategy**: If multiple todo sorting/filtering algorithms
+- **Factory**: If todos have complex types (TaskTodo, EventTodo, etc.)
+- **Observer**: If real-time sync across multiple clients
+
+**Golden Rule**: Solve real problems, not imaginary ones.
+Start simple. Add patterns when you hit actual limitations.
+
+**Complexity Budget**: Simple apps should use 0-1 patterns maximum.
+```
+
+---
+
+## Best Practices for Using dp:: Commands
+
+### 1. Progressive Analysis
+```
+# Start simple
+/dp::check strategy for payment processing
+
+# If unclear, go deeper  
+/dp::analyze payment processing system with multiple algorithms
+
+# Check for problems
+/dp::validate using strategy pattern for 2 payment types
+```
+
+### 2. Context Matters
+Include relevant details:
+- Team experience level
+- Performance requirements  
+- Growth expectations
+- Current pain points
+
+### 3. Validate Before Implementing
+```
+# Before implementing
+/dp::validate implementing singleton for user session management
+
+# During implementation
+/dp::check singleton implementation for thread safety
+
+# After implementation
+/dp::refactor src/auth/session.py
+```
+
+### 4. Use Sequential Thinking for Complex Decisions
+When multiple patterns could apply:
+```
+/dp::analyze I need a system that creates different types of reports, handles multiple output formats, and tracks generation history
+```
+
+This triggers sequential thinking to evaluate Factory + Strategy + Command combinations.
+
+---
+
+## Common Command Patterns
+
+### Pattern Selection Workflow
+1. **Quick Check**: `/dp::check <pattern> for <scenario>`
+2. **If Uncertain**: `/dp::analyze <detailed problem description>`  
+3. **Validate Decision**: `/dp::validate <proposed implementation>`
+4. **Review Code**: `/dp::refactor <file/directory>`
+
+### Anti-Pattern Prevention Workflow  
+1. **Before Design**: `/dp::validate <architectural plan>`
+2. **During Implementation**: `/dp::check <specific pattern decisions>`
+3. **After Implementation**: `/dp::refactor <implemented code>`
+4. **Periodic Review**: `/dp::refactor <entire codebase>`
+
+### Learning Workflow
+1. **Understand Problem**: `/dp::analyze <problem without suggesting pattern>`
+2. **Learn Reasoning**: Review sequential thinking output
+3. **Validate Understanding**: `/dp::check <pattern> for <your scenario>`
+4. **Practice Recognition**: `/dp::refactor <existing code>`
+
+---
+
+## Integration with Repository Examples
+
+All commands reference the repository's notebook examples:
+
+- **Singleton**: `notebooks/01_singleton_pattern.ipynb`
+- **Factory**: `notebooks/02_factory_pattern.ipynb`  
+- **Observer**: `notebooks/03_observer_pattern.ipynb`
+- **Strategy**: `notebooks/04_strategy_pattern.ipynb`
+- **Decorator**: `notebooks/05_decorator_pattern.ipynb`
+- **Command**: `notebooks/06_command_pattern.ipynb`
+- **Repository**: `notebooks/07_repository_pattern.ipynb`
+- **Builder**: `notebooks/08_builder_pattern.ipynb`
+- **Adapter**: `notebooks/09_adapter_pattern.ipynb`
+- **State**: `notebooks/10_state_pattern.ipynb`
+
+Commands will provide links to relevant notebook sections for implementation details and examples.
+
+---
+
+## Troubleshooting
+
+### Command Not Working?
+1. Check command syntax: `/dp::command_name description`
+2. Ensure repository knowledge is loaded
+3. Provide sufficient context in description
+
+### Unexpected Recommendations?
+1. Use `/dp::validate` to double-check
+2. Provide more specific requirements
+3. Mention constraints (performance, team experience, etc.)
+
+### Need More Detail?
+1. Use `/dp::analyze` for complex scenarios
+2. Ask for specific aspects: "focus on performance implications"
+3. Reference repository examples for implementation details
+
+Remember: These commands are designed to prevent overengineering while ensuring you don't miss beneficial pattern opportunities. When in doubt, they'll recommend the simpler solution.
\ No newline at end of file
diff --git a/learning-resources/guides/extracted_pattern_knowledge.md b/learning-resources/guides/extracted_pattern_knowledge.md
new file mode 100644
index 0000000..91a496d
--- /dev/null
+++ b/learning-resources/guides/extracted_pattern_knowledge.md
@@ -0,0 +1,431 @@
+# Comprehensive Design Pattern Guidance
+## Extracted from Jupyter Notebook Analysis
+
+This document provides specific, actionable guidance for design pattern selection and implementation based on comprehensive analysis of 10 design pattern tutorials.
+
+---
+
+## 1. Singleton Pattern 🔐
+
+### When to Use Criteria
+- **Database connections** - Expensive to create, should be shared
+- **Configuration settings** - One source of truth needed
+- **Logging systems** - Centralized logging required
+- **Caching mechanisms** - Shared cache across application
+
+### When NOT to Use Criteria
+- **You just want global variables** - Use modules instead
+- **Testing is important** - Singletons are hard to test and mock
+- **You might need multiple instances later** - Don't paint yourself into a corner
+- **Simple objects** - Don't over-engineer basic data structures
+
+### Thread Safety Requirements
+- **Use threading.Lock()** for multi-threaded applications
+- **Double-check locking pattern** - Check instance exists, acquire lock, check again
+- **Performance consideration** - First check without lock for efficiency
+
+### Common Mistakes
+- **Not handling thread safety** - Multiple instances created in concurrent environments
+- **Using for data objects** - Never make User, Product, etc. as singletons
+- **Overuse** - Creating singletons when regular classes suffice
+
+### Testing Implications
+- **Hard to mock** - Global state makes unit testing difficult
+- **State pollution** - Tests can affect each other
+- **Consider alternatives** - Dependency injection for better testability
+
+---
+
+## 2. Factory Pattern 🏭
+
+### When to Use Criteria
+- **3+ similar classes** that do the same job differently
+- **Complex object creation** requiring multiple steps or decisions
+- **Configuration-driven creation** - Object type depends on config files or user input
+- **Need to switch implementations** at runtime
+
+### When NOT to Use Criteria
+- **Only one class** - Don't create a factory for just one type
+- **Simple object creation** - If `MyClass()` is simple enough, don't add factory overhead
+- **Over-engineering** - Don't add factories "just in case"
+- **Performance critical** - Factories add small overhead
+
+### Complexity Thresholds
+- **Consider if/else for 2-3 cases** - Factory becomes valuable at 3+ implementations
+- **Abstract Factory** for families of related objects (AWS services, UI themes)
+
+### Decision Criteria
+- Use **Simple Factory** for basic object creation
+- Use **Factory Method** when subclasses decide what to create
+- Use **Abstract Factory** for families of related products
+
+### Alternative Solutions
+- **Function parameters** for small variations
+- **Enums with switch statements** for fixed options
+- **Configuration files** for simple behavior changes
+
+---
+
+## 3. Observer Pattern 👁️
+
+### When to Use Criteria
+- **Model-View architectures** - Views need to update when model changes
+- **Event-driven systems** - User actions, system events, notifications
+- **Real-time updates** - Stock prices, chat applications, live dashboards
+- **One-to-many relationships** - One subject, many observers
+
+### When NOT to Use Criteria
+- **Simple data binding** - Direct references might be simpler
+- **Performance critical** - Observer pattern adds notification overhead
+- **Complex update sequences** - Order dependencies make it confusing
+- **Only one observer** - Direct method calls are clearer
+
+### Performance Considerations
+- **Push vs Pull models** - Push is efficient, Pull is flexible
+- **Large observer lists** - Consider asynchronous notifications
+- **Memory leaks** - Ensure observers are properly removed
+
+### Threading Implications
+- **Thread-safe notifications** - Protect observer list with locks
+- **Separate lock for data** - Don't block notifications while updating data
+- **Async event handling** - Consider event queues for complex scenarios
+
+### Common Mistakes
+- **Forgetting to unsubscribe** - Leads to memory leaks
+- **Circular dependencies** - Observer A updates Observer B which updates A
+- **Complex update chains** - Hard to debug event propagation
+
+---
+
+## 4. Strategy Pattern 🎯
+
+### When to Use Criteria
+- **3+ algorithms** for the same problem (sorting, compression, pathfinding)
+- **Runtime algorithm switching** - Choose based on data or user preference
+- **Eliminating conditionals** - Replace long if/else chains with strategies
+- **A/B testing** - Easily switch between different implementations
+
+### Complexity Thresholds
+- **Use when you have 3+ algorithms** solving the same problem
+- **Consider if/else for 2-3 cases** - Strategy pattern valuable at 3+ options
+- **Data-driven selection** - Algorithm choice depends on input characteristics
+
+### When NOT to Use Criteria
+- **Only one algorithm** - Don't create strategies for single implementations
+- **Simple variations** - Use parameters instead of separate strategies
+- **Algorithms rarely change** - If you'll never switch, don't add overhead
+- **Performance critical** - Strategy pattern adds method call overhead
+
+### Decision Criteria
+- **Multiple sorting algorithms** - Choose based on data size
+- **Different compression strategies** - Select based on file type and priorities
+- **Smart strategy selection** - Automatic choice based on context
+
+### Alternative Solutions
+- **Function parameters** for small variations
+- **Configuration objects** for behavior customization
+- **Template methods** for algorithms with similar structure
+
+### Testing Benefits
+- **Individual strategy testing** - Each algorithm can be tested separately
+- **Easy mocking** - Mock strategies for unit testing context
+- **A/B testing support** - Switch strategies for performance comparison
+
+---
+
+## 5. Decorator Pattern 🎨
+
+### When to Use Criteria
+- **Add responsibilities dynamically** - Wrap objects with additional behavior
+- **Multiple feature combinations** - Avoid class explosion
+- **Transparent enhancement** - Client doesn't need to know about decoration
+- **Composable behaviors** - Stack multiple decorators
+
+### When NOT to Use Criteria
+- **Component interface is too complex** - Decorators need to implement all methods
+- **Fixed set of combinations** - Regular inheritance might be simpler
+- **Performance critical** - Each decorator adds indirection layer
+- **Simple objects** - Don't over-engineer basic data
+
+### Complexity Thresholds
+- **3+ optional features** - Decorator becomes valuable
+- **Avoid for simple objects** - Don't decorate basic data containers
+- **Consider inheritance for 2-3 features** - Decorator overhead not worth it
+
+### Real-world Applications
+- **Text processing pipelines** - Clean, format, validate text
+- **I/O streams** - BufferedReader, DataInputStream
+- **Web middleware** - Authentication, logging, compression
+- **Coffee shop example** - Add milk, sugar, whip cream combinations
+
+### Testing Implications
+- **Test individual decorators** - Each decorator can be tested separately
+- **Test decorator combinations** - Verify stacking works correctly
+- **Mock underlying components** - Test decorator logic in isolation
+
+---
+
+## 6. Command Pattern 🎮
+
+### When to Use Criteria
+- **Undo/redo operations** - Commands store state for reversal
+- **Macro recording** - Combine multiple commands
+- **Queue operations** - Store commands for later execution
+- **Logging and auditing** - Track all operations performed
+
+### When NOT to Use Criteria
+- **Simple operations** - Don't create commands for basic method calls
+- **No undo needed** - If operations are irreversible and logging not needed
+- **Performance critical** - Command objects add overhead
+- **Tight coupling acceptable** - When invoker can directly call receiver
+
+### Complexity Thresholds
+- **Use for complex operations** that need undo/redo
+- **Overkill for simple actions** like basic getters/setters
+- **Valuable for GUI applications** with menu/button actions
+
+### Advanced Scenarios
+- **Macro commands** - Combine multiple commands for complex operations
+- **Command queues** - Store and execute commands asynchronously
+- **Transaction support** - Group commands with rollback capability
+
+### Testing Benefits
+- **Individual command testing** - Each command can be tested separately
+- **Mock receivers** - Test command logic without real receivers
+- **Undo testing** - Verify commands can be properly reversed
+
+---
+
+## 7. Repository Pattern 📚
+
+### When to Use Criteria
+- **Centralize data access logic** - Single place for all database operations
+- **Multiple data sources** - Switch between SQL, NoSQL, files, APIs
+- **Domain-driven design** - Separate business logic from data concerns
+- **Extensive unit testing** - Mock repositories for business logic tests
+
+### When NOT to Use Criteria
+- **Simple applications** with minimal data access
+- **ORM already provides abstraction** - Don't add another layer
+- **Very specific queries** tightly coupled to database
+- **Performance critical** - Repository pattern adds abstraction overhead
+
+### Testing Benefits
+- **Easy mocking** - Mock repositories for unit tests
+- **In-memory testing** - Use in-memory repositories for fast tests
+- **Business logic isolation** - Test business rules without database
+
+### Multiple Implementation Examples
+- **SqliteUserRepository** - SQLite database implementation
+- **InMemoryUserRepository** - Fast in-memory testing
+- **JsonFileUserRepository** - File-based storage
+- **ExternalAPIRepository** - Remote API integration
+
+### Advanced Patterns
+- **Unit of Work** - Manage transactions across repositories
+- **Specification pattern** - Build complex queries dynamically
+- **Repository aggregates** - Handle related entities together
+
+---
+
+## 8. Builder Pattern 🏗️
+
+### When to Use Criteria
+- **Many optional parameters** - More than 4-5 constructor parameters
+- **Complex object construction** - Multi-step construction process
+- **Different object representations** - Same construction, different results
+- **Immutable objects** with complex initialization
+
+### When NOT to Use Criteria
+- **Few properties** - Simple constructor or factory method sufficient
+- **Construction doesn't vary** - If building process is always the same
+- **Simple objects** - Don't over-engineer basic data containers
+
+### Complexity Thresholds
+- **5+ constructor parameters** - Builder becomes valuable
+- **3+ optional features** - Builder better than multiple constructors
+- **Validation at each step** - Builder allows incremental validation
+
+### Advanced Features
+- **Fluent interface** - Method chaining for readability
+- **Validation builders** - Check constraints during construction
+- **SQL Query builders** - Dynamic query construction
+- **Configuration builders** - Complex configuration objects
+
+### Testing Benefits
+- **Step-by-step testing** - Test each building step separately
+- **Validation testing** - Verify constraints at each step
+- **Different configurations** - Easy to test various object configurations
+
+---
+
+## 9. Adapter Pattern 🔌
+
+### When to Use Criteria
+- **Incompatible interfaces** - Existing class with wrong interface
+- **Third-party library integration** - Adapt external libraries
+- **Legacy system integration** - Make old systems work with new code
+- **Multiple data formats** - Convert between different formats
+
+### When NOT to Use Criteria
+- **Interfaces already compatible** - No adaptation needed
+- **Can modify existing classes** - Direct modification is simpler
+- **Adaptation logic too complex** - Better handled differently
+- **Performance overhead significant** - Direct integration preferred
+
+### Types of Adapters
+- **Object Adapter** (composition) - More flexible, can't override adaptee methods
+- **Class Adapter** (inheritance) - Less flexible, can override adaptee methods
+- **Two-way Adapter** - Works in both directions
+
+### Real-world Applications
+- **Database drivers** - JDBC, ODBC adapters
+- **File format converters** - CSV to JSON, XML to JSON
+- **Payment gateways** - Unify different payment APIs
+- **Media players** - Support multiple audio/video formats
+
+### Testing Benefits
+- **Mock adaptees** - Test adapter logic without real dependencies
+- **Interface compliance** - Verify adapter implements target interface correctly
+- **Error handling** - Test adapter behavior with invalid input
+
+---
+
+## 10. State Pattern 🎰
+
+### When to Use Criteria
+- **Behavior depends on state** - Object acts differently based on internal state
+- **Complex state transitions** - Well-defined rules for state changes
+- **Eliminate state conditionals** - Replace complex if/else chains
+- **Finite state machines** - Clear, enumerable states
+
+### When NOT to Use Criteria
+- **Few states** with simple behavior
+- **State changes are rare** or logic is simple
+- **Simple conditional logic** - If/else might be clearer
+- **No clear state transitions** - States don't follow defined rules
+
+### Complexity Thresholds
+- **3+ states** with different behaviors - State pattern becomes valuable
+- **Complex transition rules** - State pattern clarifies relationships
+- **State-specific data** - Each state needs different information
+
+### Advanced Scenarios
+- **State machines** - Formal finite state machine implementation
+- **Workflow systems** - Document approval, order processing
+- **Game development** - Player states, AI behaviors
+- **UI components** - Button states (normal, hover, pressed, disabled)
+
+### Common Mistakes
+- **Too many small states** - Don't create state for every minor variation
+- **States knowing too much** - Keep states focused on their behavior
+- **Missing transitions** - Ensure all valid state changes are handled
+
+---
+
+## Pattern Selection Decision Tree
+
+### Start Here: What Are You Trying To Achieve?
+
+#### 🎯 **Object Creation**
+- **Complex objects with many parameters** → Builder Pattern
+- **Family of related objects** → Abstract Factory
+- **Choose implementation at runtime** → Factory Method
+- **Single instance needed** → Singleton (if truly needed)
+
+#### 🔗 **Object Relationships**
+- **Incompatible interfaces** → Adapter Pattern
+- **Add behavior dynamically** → Decorator Pattern
+- **One-to-many notifications** → Observer Pattern
+
+#### ⚙️ **Behavior Management**
+- **Multiple algorithms for same problem** → Strategy Pattern
+- **Object behavior changes with state** → State Pattern
+- **Encapsulate requests as objects** → Command Pattern
+
+#### 💾 **Data Access**
+- **Centralize data access logic** → Repository Pattern
+- **Multiple data sources** → Repository with different implementations
+
+### Red Flags - When NOT to Use Patterns
+
+#### ❌ **Over-engineering Indicators**
+- Only 1-2 simple classes
+- No variation in behavior
+- Performance is critical
+- Simple if/else is clearer
+- Won't need flexibility
+
+#### ❌ **Testing Difficulties**
+- Singleton makes testing hard
+- Complex state transitions hard to test
+- Too many abstraction layers
+
+#### ❌ **Maintenance Issues**
+- Pattern adds more complexity than it solves
+- Team unfamiliar with pattern
+- Premature optimization
+
+---
+
+## Performance Considerations
+
+### Low Overhead Patterns
+- **Factory** - Minimal overhead, one-time cost
+- **Builder** - Construction-time cost only
+- **Repository** - Abstraction layer, minimal runtime cost
+
+### Medium Overhead Patterns
+- **Strategy** - Method call indirection
+- **State** - Object delegation per operation
+- **Command** - Object creation per operation
+
+### Higher Overhead Patterns
+- **Observer** - Notification to multiple observers
+- **Decorator** - Multiple layers of indirection
+- **Adapter** - Translation overhead
+
+### Optimization Strategies
+- **Pool Command objects** - Reuse command instances
+- **Async Observer notifications** - Don't block for slow observers
+- **Cache Strategy instances** - Reuse strategy objects
+- **Lazy initialization** - Create states/decorators only when needed
+
+---
+
+## Testing Strategies by Pattern
+
+### Easy to Test
+- **Strategy** - Mock strategies, test context independently
+- **Command** - Mock receivers, test commands separately
+- **Repository** - Mock repositories, use in-memory implementations
+
+### Moderate Testing Complexity
+- **Observer** - Mock observers, test notification logic
+- **State** - Test state transitions, mock state actions
+- **Factory** - Test creation logic, verify correct instances
+
+### Challenging to Test
+- **Singleton** - Global state, hard to isolate
+- **Decorator** - Multiple layers, complex interaction testing
+- **Adapter** - Integration testing required
+
+### Testing Best Practices
+1. **Use dependency injection** instead of Singletons
+2. **Mock external dependencies** in adapters
+3. **Test state transitions** explicitly in State pattern
+4. **Verify observer cleanup** to prevent memory leaks
+5. **Test decorator combinations** for proper behavior
+
+---
+
+## Conclusion
+
+This guidance provides specific, actionable criteria for pattern selection based on:
+- **Specific complexity thresholds** (3+ algorithms, 5+ parameters)
+- **Clear anti-patterns** (avoid for simple objects, single instances)
+- **Performance implications** (overhead levels, optimization strategies)
+- **Testing considerations** (easy vs. hard to test patterns)
+- **Real-world examples** (specific use cases and applications)
+
+Use this as a reference for intelligent pattern recommendation systems that can suggest appropriate patterns based on specific project characteristics and requirements.
\ No newline at end of file
diff --git a/learning-resources/guides/pattern_decision_guide.md b/learning-resources/guides/pattern_decision_guide.md
new file mode 100644
index 0000000..7082f28
--- /dev/null
+++ b/learning-resources/guides/pattern_decision_guide.md
@@ -0,0 +1,406 @@
+# Pattern Decision Guide
+
+A comprehensive guide for choosing the right design pattern based on real-world scenarios and requirements.
+
+## Quick Pattern Selection
+
+### Start Here: What Are You Trying To Do?
+
+#### 🏗️ Creating Objects
+- **One instance needed globally?** → [Singleton Pattern](#singleton-pattern)
+- **Multiple similar objects?** → [Factory Pattern](#factory-pattern)  
+- **Complex object construction?** → [Builder Pattern](#builder-pattern)
+
+#### 🔄 Managing Behavior
+- **Multiple algorithms for same task?** → [Strategy Pattern](#strategy-pattern)
+- **Behavior changes based on state?** → [State Pattern](#state-pattern)
+- **Need undo/redo functionality?** → [Command Pattern](#command-pattern)
+
+#### 🔗 Connecting Components
+- **Incompatible interfaces?** → [Adapter Pattern](#adapter-pattern)
+- **Add features dynamically?** → [Decorator Pattern](#decorator-pattern)
+- **One-to-many notifications?** → [Observer Pattern](#observer-pattern)
+
+#### 💾 Data Access
+- **Centralize data access logic?** → [Repository Pattern](#repository-pattern)
+
+---
+
+## Detailed Decision Trees
+
+### Singleton Pattern
+
+```
+Do you need exactly ONE instance of a class?
+├─ YES
+│  ├─ Is it expensive to create? (database connections, file handles)
+│  │  ├─ YES → ✅ Use Singleton
+│  │  └─ NO → Is global access truly needed?
+│  │     ├─ YES → ✅ Use Singleton (with caution)
+│  │     └─ NO → ❌ Use regular class or module-level variable
+│  └─ NO → ❌ DON'T use Singleton
+│
+Special Cases:
+├─ Configuration data → ✅ Singleton is good
+├─ Logging system → ✅ Singleton is good  
+├─ User/Product/Order entities → ❌ NEVER use Singleton
+└─ "For consistency" → ❌ Bad reason for Singleton
+```
+
+**Complexity Threshold**: Use when object creation is expensive OR truly global access needed
+**Thread Safety**: Required for multi-threaded apps (use double-check locking)
+
+### Factory Pattern
+
+```
+Are you creating objects based on some criteria?
+├─ YES
+│  ├─ How many different types? 
+│  │  ├─ 1-2 types → ❌ Simple if/else is better
+│  │  ├─ 3+ types → ✅ Factory Pattern
+│  │  └─ Many related families → ✅ Abstract Factory
+│  └─ Is creation logic complex?
+│     ├─ YES (>5 lines) → ✅ Factory Pattern
+│     └─ NO → ❌ Direct instantiation is fine
+└─ NO → ❌ Don't use Factory
+```
+
+**Complexity Threshold**: 3+ similar classes OR complex creation logic
+**When NOT to use**: Single class, simple creation, "just in case" scenarios
+
+### Strategy Pattern
+
+```
+Do you have multiple ways to do the same thing?
+├─ YES
+│  ├─ How many algorithms/approaches?
+│  │  ├─ 1-2 → ❌ Simple if/else or parameters
+│  │  ├─ 3+ → ✅ Strategy Pattern
+│  │  └─ Need runtime switching? → ✅ Strategy Pattern
+│  └─ Are algorithms likely to change/grow?
+│     ├─ YES → ✅ Strategy Pattern  
+│     └─ NO → ❌ Simple conditionals OK
+└─ NO → ❌ Don't use Strategy
+```
+
+**Complexity Threshold**: 3+ algorithms OR runtime algorithm selection needed
+**Signs**: Long if/elif chains, "switch algorithm based on data" requirements
+
+### Observer Pattern  
+
+```
+Do multiple objects need to know about changes?
+├─ YES
+│  ├─ How many observers?
+│  │  ├─ 1 → ❌ Direct method call is simpler
+│  │  ├─ 2+ → ✅ Observer Pattern
+│  │  └─ Dynamic add/remove needed? → ✅ Observer Pattern
+│  └─ Is loose coupling important?
+│     ├─ YES → ✅ Observer Pattern
+│     └─ NO → ❌ Direct coupling might be OK
+└─ NO → ❌ Don't use Observer
+```
+
+**Complexity Threshold**: 2+ observers OR dynamic subscription needed
+**Performance Note**: Adds notification overhead - consider for non-critical paths
+
+### Builder Pattern
+
+```
+Does object construction have many parameters?
+├─ YES
+│  ├─ How many constructor parameters?
+│  │  ├─ <5 → ❌ Regular constructor OK
+│  │  ├─ 5-7 → ✅ Consider Builder
+│  │  └─ 8+ → ✅ Definitely use Builder
+│  └─ Are many parameters optional?
+│     ├─ YES (3+ optional) → ✅ Builder Pattern
+│     └─ NO → ❌ Regular constructor with defaults
+└─ NO → ❌ Don't use Builder
+```
+
+**Complexity Threshold**: 5+ constructor parameters OR complex validation needed
+**Alternative**: Dataclasses with defaults for simple cases
+
+### Command Pattern
+
+```
+Do you need to do more than just execute an operation?
+├─ YES
+│  ├─ Need undo functionality? → ✅ Command Pattern
+│  ├─ Need to queue operations? → ✅ Command Pattern  
+│  ├─ Need to log operations? → ✅ Command Pattern
+│  └─ Need macro recording? → ✅ Command Pattern
+└─ NO → ❌ Direct method calls are simpler
+```
+
+**Complexity Threshold**: Any undo/redo, queuing, or operation logging needs
+**Overkill for**: Simple getters/setters, basic operations
+
+---
+
+## Real-World Scenarios
+
+### E-Commerce System
+
+**Scenario**: Building an online store
+
+**Pattern Recommendations**:
+- **User Management**: Regular classes (NOT Singleton)
+- **Product Catalog**: Factory for different product types
+- **Shopping Cart**: Observer for cart change notifications
+- **Payment Processing**: Strategy for different payment methods
+- **Order Processing**: Command for undo/tracking
+- **Data Access**: Repository for product/order data
+
+### Game Development
+
+**Scenario**: Building a role-playing game
+
+**Pattern Recommendations**:
+- **Game Settings**: Singleton for global configuration
+- **Character Creation**: Builder for complex character setup
+- **Character Abilities**: Strategy for different skill sets
+- **Character States**: State pattern (combat/stealth/exploration)
+- **UI Updates**: Observer for character stat changes
+- **Actions**: Command for undo/macro support
+
+### Web Application
+
+**Scenario**: Building a web service
+
+**Pattern Recommendations**:
+- **Database Connection**: Singleton (thread-safe)
+- **API Response Formats**: Strategy for JSON/XML/CSV
+- **Authentication**: Decorator for adding auth to endpoints
+- **Data Access**: Repository for clean data layer
+- **Event Notifications**: Observer for user actions
+- **Request Processing**: Chain of responsibility
+
+---
+
+## Anti-Pattern Detection
+
+### 🚨 Red Flags - When NOT to Use Patterns
+
+#### Singleton Anti-Patterns
+```python
+# ❌ BAD: Data models as singletons
+class User(metaclass=SingletonMeta):
+    def __init__(self, name, email):
+        self.name = name
+        self.email = email
+
+# ✅ GOOD: Regular class
+class User:
+    def __init__(self, name, email):
+        self.name = name
+        self.email = email
+```
+
+#### Factory Anti-Patterns
+```python
+# ❌ BAD: Factory for single class
+class UserFactory:
+    @staticmethod
+    def create_user(name, email):
+        return User(name, email)
+
+# ✅ GOOD: Direct instantiation
+user = User(name, email)
+```
+
+#### Strategy Anti-Patterns
+```python
+# ❌ BAD: Strategy for 2 simple cases
+class TaxStrategy(ABC):
+    @abstractmethod
+    def calculate(self, amount): pass
+
+class USStrategy(TaxStrategy):
+    def calculate(self, amount): return amount * 0.08
+
+class EUStrategy(TaxStrategy):
+    def calculate(self, amount): return amount * 0.20
+
+# ✅ GOOD: Simple function
+def calculate_tax(amount, region):
+    return amount * (0.08 if region == 'US' else 0.20)
+```
+
+### When to Prefer Simple Solutions
+
+1. **2-3 variations**: Use if/else instead of Strategy/Factory
+2. **Simple objects**: Use regular constructors instead of Builder
+3. **Single observer**: Use direct method calls instead of Observer
+4. **No undo needed**: Use direct operations instead of Command
+5. **Can modify interfaces**: Use direct inheritance instead of Adapter
+
+---
+
+## Pattern Combinations
+
+### Common Pattern Combinations
+
+#### Factory + Strategy
+```python
+# Create strategies through factory
+strategy = StrategyFactory.create(algorithm_type)
+result = strategy.execute(data)
+```
+
+#### Observer + Command  
+```python
+# Event sourcing: commands create events, observers handle them
+command = CreateOrderCommand(order_data)
+command.execute()  # Triggers observers via events
+```
+
+#### Repository + Factory
+```python
+# Repository creates domain objects via factory
+user_repo = UserRepository()
+user = user_repo.find_by_id(123)  # Uses factory internally
+```
+
+#### Builder + Strategy
+```python
+# Complex objects with algorithmic variations
+query = (QueryBuilder()
+         .select("*")
+         .from_table("users")
+         .with_strategy(OptimizedStrategy())
+         .build())
+```
+
+---
+
+## Performance Considerations
+
+### Pattern Overhead
+
+| Pattern | Performance Impact | When to Worry |
+|---------|-------------------|---------------|
+| Singleton | Minimal (after creation) | High-frequency access |
+| Factory | Small method call overhead | Object creation in tight loops |
+| Strategy | Small delegation overhead | CPU-intensive algorithms |
+| Observer | Notification loop overhead | Many observers or frequent updates |
+| Command | Object creation overhead | Simple operations in hot paths |
+| Builder | Method chaining overhead | Simple object creation |
+
+### Optimization Strategies
+
+1. **Singleton**: Use eager initialization for frequently accessed singletons
+2. **Factory**: Cache created objects when possible
+3. **Strategy**: Profile algorithm performance differences
+4. **Observer**: Use async notifications for non-critical updates
+5. **Command**: Implement object pooling for frequently used commands
+6. **Builder**: Consider fluent interfaces only for complex objects
+
+---
+
+## Testing Implications
+
+### Testing Challenges by Pattern
+
+#### Singleton
+- **Problem**: Global state makes tests interdependent
+- **Solution**: Reset mechanism or dependency injection
+- **Test**: Verify singleton property, thread safety
+
+#### Factory  
+- **Problem**: Testing all creation paths
+- **Solution**: Mock factory for client testing
+- **Test**: Each factory method, error conditions
+
+#### Strategy
+- **Problem**: Testing strategy selection logic
+- **Solution**: Test strategies individually, then context
+- **Test**: Each strategy, selection algorithm
+
+#### Observer
+- **Problem**: Testing notification sequences
+- **Solution**: Mock observers, verify notification order
+- **Test**: Registration, notification, cleanup
+
+#### Command
+- **Problem**: Testing undo/redo sequences
+- **Solution**: Test execute/undo separately
+- **Test**: Command execution, undo logic, history management
+
+#### Builder
+- **Problem**: Testing all construction paths
+- **Solution**: Test required vs optional parameters
+- **Test**: Validation, different build sequences
+
+---
+
+## Decision Checklist
+
+Before implementing any pattern, ask:
+
+### ✅ Pre-Implementation Checklist
+
+1. **Complexity Justified?**
+   - [ ] Problem meets pattern's complexity threshold
+   - [ ] Simple solution considered and rejected
+   - [ ] Pattern adds real value, not just structure
+
+2. **Requirements Match?**
+   - [ ] Current requirements align with pattern benefits
+   - [ ] Future requirements likely to benefit from pattern
+   - [ ] Pattern doesn't solve imaginary future problems
+
+3. **Team Ready?**
+   - [ ] Team understands the pattern
+   - [ ] Documentation and examples available
+   - [ ] Maintenance plan in place
+
+4. **Performance Acceptable?**
+   - [ ] Pattern overhead measured and acceptable
+   - [ ] Alternative solutions compared
+   - [ ] Performance requirements still met
+
+5. **Testing Feasible?**
+   - [ ] Pattern can be properly unit tested
+   - [ ] Mocking strategy identified
+   - [ ] Integration testing plan exists
+
+### 🚫 Stop Signs - Don't Implement If:
+
+- [ ] "We might need it later" is the main justification
+- [ ] Pattern makes simple code complex without clear benefit
+- [ ] Team doesn't understand the pattern well
+- [ ] No clear way to test the implementation
+- [ ] Simpler solution would work just as well
+- [ ] Pattern is being used "for consistency" without benefit
+
+---
+
+## Quick Reference
+
+### Pattern Selection Flowchart
+
+```
+Start Here: What's Your Main Goal?
+│
+├─ Create Objects
+│  ├─ One global instance → Singleton
+│  ├─ Choose type at runtime → Factory  
+│  └─ Complex construction → Builder
+│
+├─ Manage Behavior
+│  ├─ Multiple algorithms → Strategy
+│  ├─ State-dependent behavior → State
+│  └─ Need undo/redo → Command
+│
+├─ Connect Components  
+│  ├─ Incompatible interfaces → Adapter
+│  ├─ Add features dynamically → Decorator
+│  └─ Notify multiple objects → Observer
+│
+└─ Access Data
+   └─ Centralize data logic → Repository
+
+Remember: When in doubt, choose the simpler solution!
+```
\ No newline at end of file
diff --git a/notebooks/01_singleton_pattern.ipynb b/learning-resources/notebooks/01_singleton_pattern.ipynb
similarity index 100%
rename from notebooks/01_singleton_pattern.ipynb
rename to learning-resources/notebooks/01_singleton_pattern.ipynb
diff --git a/notebooks/02_factory_pattern.ipynb b/learning-resources/notebooks/02_factory_pattern.ipynb
similarity index 100%
rename from notebooks/02_factory_pattern.ipynb
rename to learning-resources/notebooks/02_factory_pattern.ipynb
diff --git a/notebooks/03_observer_pattern.ipynb b/learning-resources/notebooks/03_observer_pattern.ipynb
similarity index 100%
rename from notebooks/03_observer_pattern.ipynb
rename to learning-resources/notebooks/03_observer_pattern.ipynb
diff --git a/notebooks/04_strategy_pattern.ipynb b/learning-resources/notebooks/04_strategy_pattern.ipynb
similarity index 100%
rename from notebooks/04_strategy_pattern.ipynb
rename to learning-resources/notebooks/04_strategy_pattern.ipynb
diff --git a/notebooks/05_decorator_pattern.ipynb b/learning-resources/notebooks/05_decorator_pattern.ipynb
similarity index 100%
rename from notebooks/05_decorator_pattern.ipynb
rename to learning-resources/notebooks/05_decorator_pattern.ipynb
diff --git a/notebooks/06_command_pattern.ipynb b/learning-resources/notebooks/06_command_pattern.ipynb
similarity index 100%
rename from notebooks/06_command_pattern.ipynb
rename to learning-resources/notebooks/06_command_pattern.ipynb
diff --git a/notebooks/07_repository_pattern.ipynb b/learning-resources/notebooks/07_repository_pattern.ipynb
similarity index 100%
rename from notebooks/07_repository_pattern.ipynb
rename to learning-resources/notebooks/07_repository_pattern.ipynb
diff --git a/notebooks/08_builder_pattern.ipynb b/learning-resources/notebooks/08_builder_pattern.ipynb
similarity index 100%
rename from notebooks/08_builder_pattern.ipynb
rename to learning-resources/notebooks/08_builder_pattern.ipynb
diff --git a/notebooks/09_adapter_pattern.ipynb b/learning-resources/notebooks/09_adapter_pattern.ipynb
similarity index 100%
rename from notebooks/09_adapter_pattern.ipynb
rename to learning-resources/notebooks/09_adapter_pattern.ipynb
diff --git a/notebooks/10_state_pattern.ipynb b/learning-resources/notebooks/10_state_pattern.ipynb
similarity index 100%
rename from notebooks/10_state_pattern.ipynb
rename to learning-resources/notebooks/10_state_pattern.ipynb
diff --git a/pyproject.toml b/pyproject.toml
index 462d2bc..f6e04fc 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -3,9 +3,9 @@ requires = ["setuptools>=65", "wheel"]
 build-backend = "setuptools.build_meta"
 
 [project]
-name = "design-patterns-tutorial"
+name = "ai-architecture-advisor"
 version = "1.0.0"
-description = "A comprehensive tutorial on design patterns with interactive Jupyter notebooks"
+description = "AI-powered architecture advisor that provides expert recommendations on design patterns and architectural decisions"
 readme = "README.md"
 requires-python = ">=3.11"
 license = {text = "MIT"}
@@ -50,9 +50,9 @@ dev = [
 ]
 
 [project.urls]
-"Homepage" = "https://github.com/yourusername/design-patterns-tutorial"
-"Bug Reports" = "https://github.com/yourusername/design-patterns-tutorial/issues"
-"Source" = "https://github.com/yourusername/design-patterns-tutorial"
+"Homepage" = "https://github.com/ahmadhasan2k8/ai-architecture-advisor"
+"Bug Reports" = "https://github.com/ahmadhasan2k8/ai-architecture-advisor/issues"
+"Source" = "https://github.com/ahmadhasan2k8/ai-architecture-advisor"
 
 [tool.black]
 line-length = 88
diff --git a/simple_test_runner.py b/simple_test_runner.py
index 8aab463..a0833f5 100644
--- a/simple_test_runner.py
+++ b/simple_test_runner.py
@@ -10,8 +10,8 @@
 import json
 from pathlib import Path
 
-# Add src to path
-sys.path.insert(0, 'src')
+# Add implementations to path
+sys.path.insert(0, 'learning-resources/examples/implementations')
 
 def test_singleton_basic():
     """Test singleton pattern basic functionality."""
diff --git a/test_notebooks.py b/test_notebooks.py
index 878f736..a282975 100755
--- a/test_notebooks.py
+++ b/test_notebooks.py
@@ -13,7 +13,7 @@ def test_notebook_execution():
     """Test if notebooks can be executed properly."""
     print("🔍 Testing notebook execution...")
     
-    notebooks_dir = Path("notebooks")
+    notebooks_dir = Path("learning-resources/notebooks")
     notebooks = sorted([f for f in notebooks_dir.glob("*.ipynb") if ".ipynb_checkpoints" not in str(f)])
     
     print(f"Found {len(notebooks)} notebooks to test")
@@ -83,7 +83,7 @@ def clear_notebook_outputs():
     """Clear outputs from notebooks if they exist."""
     print("\n🔍 Clearing notebook outputs...")
     
-    notebooks_dir = Path("notebooks")
+    notebooks_dir = Path("learning-resources/notebooks")
     notebooks = sorted([f for f in notebooks_dir.glob("*.ipynb") if ".ipynb_checkpoints" not in str(f)])
     
     cleared_count = 0
diff --git a/validate.py b/validate.py
index 62052b4..2a62889 100644
--- a/validate.py
+++ b/validate.py
@@ -12,15 +12,15 @@
 from pathlib import Path
 from typing import Dict, List, Tuple, Any
 
-# Add src to path for imports
-sys.path.insert(0, str(Path(__file__).parent / "src"))
+# Add learning-resources path for imports
+sys.path.insert(0, str(Path(__file__).parent / "learning-resources" / "examples" / "implementations"))
 
 def validate_notebooks() -> Tuple[bool, List[str]]:
     """Validate all Jupyter notebooks."""
     print("🔍 Validating Jupyter notebooks...")
     
     errors = []
-    notebooks_dir = Path("notebooks")
+    notebooks_dir = Path("learning-resources/notebooks")
     
     if not notebooks_dir.exists():
         errors.append("notebooks directory does not exist")
@@ -89,11 +89,11 @@ def validate_source_code() -> Tuple[bool, List[str]]:
     print("🔍 Validating source code implementations...")
     
     errors = []
-    src_dir = Path("src")
+    src_dir = Path("learning-resources/examples/implementations")
     patterns_dir = src_dir / "patterns"
     
     if not patterns_dir.exists():
-        errors.append("src/patterns directory does not exist")
+        errors.append("learning-resources/examples/implementations/patterns directory does not exist")
         return False, errors
     
     expected_patterns = [
@@ -168,10 +168,10 @@ def validate_tests() -> Tuple[bool, List[str]]:
     print("🔍 Validating test files...")
     
     errors = []
-    tests_dir = Path("tests") / "test_patterns"
+    tests_dir = Path("learning-resources/examples/tests") / "test_patterns"
     
     if not tests_dir.exists():
-        errors.append("tests/test_patterns directory does not exist")
+        errors.append("learning-resources/examples/tests/test_patterns directory does not exist")
         return False, errors
     
     expected_tests = [
@@ -252,12 +252,14 @@ def validate_project_structure() -> Tuple[bool, List[str]]:
     errors = []
     
     expected_dirs = [
-        "src",
-        "src/patterns", 
-        "tests",
-        "tests/test_patterns",
-        "notebooks",
-        "docs",
+        "learning-resources/examples/implementations",
+        "learning-resources/examples/implementations/patterns", 
+        "learning-resources/examples/tests",
+        "learning-resources/examples/tests/test_patterns",
+        "learning-resources/notebooks",
+        "learning-resources/guides",
+        "ai-engine",
+        "commands",
         "data"
     ]
     
@@ -273,10 +275,11 @@ def validate_project_structure() -> Tuple[bool, List[str]]:
         "Dockerfile",
         "docker-compose.yml",
         "CLAUDE.md",
-        "src/__init__.py",
-        "src/patterns/__init__.py",
-        "tests/__init__.py",
-        "tests/conftest.py"
+        "learning-resources/examples/implementations/__init__.py",
+        "learning-resources/examples/implementations/patterns/__init__.py",
+        "learning-resources/examples/tests/__init__.py",
+        "learning-resources/examples/tests/conftest.py",
+        "QUICK_START.md"
     ]
     
     for file_path in expected_files: