adaptive-memory-multi-model-router 2.14.46 → 2.14.47

package/docs/ARCHITECTURAL-IMPROVEMENTS-REVISED-2025.md

@@ -1,1051 +0,0 @@
-# TMLPD v2.0: Revised Architecture Based on Anthropic's Latest Research
-## Aligned with AI Engineer Summit 2025 Insights
-
-**Document Version:** 2.0 (Revised)
-**Last Updated:** January 2025
-**Based On:** Anthropic's "Building Effective Agents" & "Agent Skills" (Dec 2024)
-
----
-
-## ⚠️ MAJOR PARADIGM SHIFT
-
-After reviewing Anthropic's latest research from the AI Engineer Summit 2025, **the original architectural plan needs significant revision**.
-
-### Key Insight from Barry Zhang (Anthropic):
-
-> **"Don't Build Agents, Build Skills Instead"**
->
-> Stop building "omnipotent agents" for every niche. Focus on building **modular, composable Skills** that can be mixed and matched.
-
-**Sources:**
-- [Building Effective Agents - Anthropic](https://www.anthropic.com/research/building-effective-agents) (Dec 19, 2024)
-- [Agent Skills - Anthropic Engineering](https://www.anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills) (Dec 18, 2024)
-- [How We Build Effective Agents: Barry Zhang](https://www.youtube.com/watch?v=D7_ipDqhtwk) (AI Engineer Summit 2025)
-- [LinkedIn Discussion: Skills vs Agents](https://www.linkedin.com/posts/barry-z_building-effective-agents-activity-7275576927984267264-Tpms)
-
----
-
-## Part 1: What Anthropic Actually Says
-
-### The Core Message: **Simplicity Over Complexity**
-
-```
-┌─────────────────────────────────────────────────────────────┐
-│                                                             │
-│   OLD THINKING (Complex)              NEW THINKING (Simple)  │
-│                                                             │
-│   ❌ Build complex agent networks    ✅ Start with simple   │
-│   ❌ Multi-agent orchestration      ✅ Single LLM call     │
-│   ❌ Elaborate memory systems        ✅ Workflows for       │
-│   ❌ Cross-agent communication      ✅   predictable tasks │
-│   ❌ Framework-heavy                 ✅ Agents only when     │
-│                                       ✅   necessary        │
-│                                                             │
-└─────────────────────────────────────────────────────────────┘
-```
-
-### Anthropic's Decision Tree
-
-```
-Should I build an agentic system?
-         │
-         ▼
-    Can a single optimized LLM call solve it?
-         │
-         ├── YES → Use single LLM call ✅ (80% of cases)
-         │
-         └── NO → Is the task predictable?
-                   │
-                   ├── YES → Use WORKFLOW ✅ (15% of cases)
-                   │        • Chaining
-                   │        • Routing
-                   │        • Parallelization
-                   │        • Orchestrator-Workers
-                   │        • Evaluator-Optimizer
-                   │
-                   └── NO → Use AGENT ⚠️ (5% of cases)
-                            • Only when unpredictable
-                            • When LLM needs autonomy
-                            • Open-ended problems
-```
-
-### Statistics from Anthropic's Research
-
-**Most successful implementations:**
-- 80%: Single LLM call with retrieval
-- 15%: Simple workflows (chaining, routing)
-- 4%: Orchestrator-workers
-- 1%: True autonomous agents
-
-**Key Finding:** Complex multi-agent systems were rarely the best solution.
-
----
-
-## Part 2: Revised TMLPD Architecture
-
-### Original Plan (Over-engineered)
-
-❌ **What I originally proposed:**
-1. Complex memory hierarchy (3 tiers)
-2. Agentic RAG with multi-step retrieval
-3. Cross-agent communication protocols
-4. Elaborate state management
-5. Multi-agent coordination frameworks
-
-**Problem:** This violates Anthropic's core principle of simplicity.
-
-### Revised Plan (Aligned with Anthropic)
-
-✅ **What TMLPD v2.0 should actually be:**
-
-**Instead of "Multi-Agent Orchestration" → Focus on "Workflow Optimization"**
-
-```
-TMLPD v2.0 = Skills + Workflows (NOT complex agents)
-```
-
----
-
-## Part 3: Agent Skills Integration (Highest Priority)
-
-### What Are Agent Skills?
-
-From Anthropic's definition:
-> "Agent Skills are organized folders of instructions, scripts, and resources that agents can discover and load dynamically to perform better at specific tasks."
-
-**Key Concept:** Progressive Disclosure
-```
-Level 1: Metadata (name, description)
-    ↓
-Level 2: SKILL.md (main instructions)
-    ↓
-Level 3: Additional files (details as needed)
-```
-
-### Example Skill Structure
-
-```
-tmlpd-skills/
-├── frontend/
-│   ├── SKILL.md
-│   ├── react-best-practices.md
-│   ├── component-templates.md
-│   └── scripts/
-│       └── generate-component.py
-├── backend/
-│   ├── SKILL.md
-│   ├── api-patterns.md
-│   └── testing-guidelines.md
-└── testing/
-    ├── SKILL.md
-    ├── jest-patterns.md
-    └── test-templates.md
-```
-
-### SKILL.md Format
-
-```yaml
----
-name: "React Frontend Development"
-description: "Best practices for building React components with TypeScript, testing, and state management"
----
-
-# React Frontend Skill
-
-## Core Principles
-
-1. **Type Safety**: Always use TypeScript with strict mode
-2. **Component Design**: Favor composition over inheritance
-3. **State Management**: Use Zustand for local state, Redux for global
-
-## Common Patterns
-
-### Component Structure
-
-See `react-best-practices.md` for detailed component architecture.
-
-### Testing
-
-Always write tests before implementation (TDD approach).
-
-## Scripts
-
-Use `scripts/generate-component.py` to scaffold new components with:
-- TypeScript types
-- Jest test file
-- Storybook story
-- CSS modules
-
-## When to Use This Skill
-
-Trigger this skill when:
-- Building React components
-- Implementing UI features
-- Creating frontend layouts
-- Writing frontend tests
-```
-
-### Implementation
-
-```python
-# File: src/skills/skill_manager.py
-
-from pathlib import Path
-import yaml
-from typing import Dict, List, Optional
-from dataclasses import dataclass
-
-@dataclass
-class Skill:
-    """Represents an Agent Skill"""
-    name: str
-    description: str
-    directory: Path
-    metadata: Dict[str, str]
-    content: Optional[str] = None
-
-class SkillManager:
-    """
-    Manages Agent Skills following Anthropic's specification.
-    Implements progressive disclosure.
-    """
-
-    def __init__(self, skills_dir: str = "tmlpd-skills"):
-        self.skills_dir = Path(skills_dir)
-        self.skills: Dict[str, Skill] = {}
-        self._load_skills_metadata()
-
-    def _load_skills_metadata(self):
-        """
-        Load Level 1: Metadata only (name, description)
-        This is loaded into system prompt at startup
-        """
-
-        if not self.skills_dir.exists():
-            return
-
-        for skill_dir in self.skills_dir.iterdir():
-            if not skill_dir.is_dir():
-                continue
-
-            skill_md = skill_dir / "SKILL.md"
-
-            if not skill_md.exists():
-                continue
-
-            # Parse YAML frontmatter
-            with open(skill_md, "r") as f:
-                content = f.read()
-
-            # Extract YAML frontmatter
-            if content.startswith("---"):
-                _, frontmatter, _ = content.split("---", 2)
-                metadata = yaml.safe_load(frontmatter)
-            else:
-                continue
-
-            self.skills[metadata["name"]] = Skill(
-                name=metadata["name"],
-                description=metadata["description"],
-                directory=skill_dir,
-                metadata=metadata
-            )
-
-    def list_skills(self) -> List[str]:
-        """List all available skills (Level 1 metadata)"""
-        return list(self.skills.keys())
-
-    def get_relevant_skills(self, task: str, top_k: int = 3) -> List[str]:
-        """
-        Find relevant skills based on task description.
-        Uses simple keyword matching (can upgrade to semantic search later).
-        """
-
-        task_lower = task.lower()
-        relevant = []
-
-        for skill_name, skill in self.skills.items():
-            # Check if task keywords match skill description
-            skill_desc_lower = skill.description.lower()
-
-            # Simple keyword matching
-            common_words = set(task_lower.split()) & set(skill_desc_lower.split())
-
-            if common_words:
-                relevance = len(common_words)
-                relevant.append((skill_name, relevance))
-
-        # Sort by relevance and return top_k
-        relevant.sort(key=lambda x: x[1], reverse=True)
-        return [skill_name for skill_name, _ in relevant[:top_k]]
-
-    def load_skill(self, skill_name: str) -> Skill:
-        """
-        Load Level 2: Full SKILL.md content
-        Called only when skill is relevant to current task
-        """
-
-        if skill_name not in self.skills:
-            raise ValueError(f"Skill {skill_name} not found")
-
-        skill = self.skills[skill_name]
-        skill_md = skill.directory / "SKILL.md"
-
-        with open(skill_md, "r") as f:
-            # Skip YAML frontmatter, get content
-            content = f.read()
-            if "---" in content:
-                _, _, content = content.split("---", 2)
-
-        skill.content = content.strip()
-        return skill
-
-    def load_additional_file(self, skill_name: str, filename: str) -> str:
-        """
-        Load Level 3: Additional files from skill
-        Progressive disclosure - load only when needed
-        """
-
-        if skill_name not in self.skills:
-            raise ValueError(f"Skill {skill_name} not found")
-
-        skill = self.skills[skill_name]
-        additional_file = skill.directory / filename
-
-        if not additional_file.exists():
-            raise FileNotFoundError(f"File {filename} not found in skill {skill_name}")
-
-        with open(additional_file, "r") as f:
-            return f.read()
-
-# Usage Example
-class TMLEnhancedAgent:
-    """Agent with Skill capabilities"""
-
-    def __init__(self):
-        self.skill_manager = SkillManager()
-
-    def execute_task(self, task: str) -> str:
-        """Execute task using relevant skills"""
-
-        # Step 1: Find relevant skills
-        relevant_skills = self.skill_manager.get_relevant_skills(task)
-
-        # Step 2: Build context from skills
-        context_parts = []
-
-        for skill_name in relevant_skills:
-            skill = self.skill_manager.load_skill(skill_name)
-            context_parts.append(f"## {skill.name}\n{skill.content}")
-
-        # Step 3: Combine with task
-        full_context = "\n\n".join(context_parts)
-        prompt = f"""
-Task: {task}
-
-Relevant Skills:
-{full_context}
-
-Please complete the task following the guidance from the relevant skills.
-"""
-
-        # Step 4: Execute LLM call
-        return self._llm_call(prompt)
-```
-
----
-
-## Part 4: Workflow Patterns (Instead of Complex Agents)
-
-### Pattern 1: Parallelization (What TMLPD Already Does!)
-
-```python
-# This IS the right approach! ✅
-
-class ParallelWorkflow:
-    """
-    Anthropic's "Parallelization: Sectioning" pattern
-    This is exactly what TMLPD v1.0 does!
-    """
-
-    def execute(self, tasks: List[Dict]) -> Dict[str, Any]:
-        """
-        Break task into independent subtasks, run in parallel.
-        This is a WORKFLOW, not a complex agent system.
-        """
-
-        # This is simple, predictable, and effective
-        with ThreadPoolExecutor() as executor:
-            futures = {
-                executor.submit(self._execute_single_task, task): task
-                for task in tasks
-            }
-
-            results = {}
-            for future in as_completed(futures):
-                task = futures[future]
-                try:
-                    results[task["id"]] = future.result()
-                except Exception as e:
-                    results[task["id"]] = {"error": str(e)}
-
-        return results
-```
-
-**This is GOOD!** TMLPD v1.0 already follows Anthropic's recommendation.
-
-### Pattern 2: Routing (Add to TMLPD v2.0)
-
-```python
-# File: src/workflows/router.py
-
-class TaskRouter:
-    """
-    Anthropic's "Routing" workflow.
-    Classify tasks and route to specialized handlers.
-    """
-
-    def __init__(self):
-        self.routes = {
-            "frontend": FrontendSkill(),
-            "backend": BackendSkill(),
-            "testing": TestingSkill(),
-            "documentation": DocumentationSkill()
-        }
-
-    def route_and_execute(self, task: str) -> str:
-        """
-        Step 1: Classify task type
-        Step 2: Route to appropriate skill
-        Step 3: Execute with specialized context
-        """
-
-        # Simple classification (can use LLM)
-        task_type = self._classify_task(task)
-
-        # Get relevant skill
-        skill = self.routes[task_type]
-
-        # Load skill context
-        skill_context = skill.load_full_context()
-
-        # Execute with skill
-        return skill.execute_with_context(task, skill_context)
-
-    def _classify_task(self, task: str) -> str:
-        """Classify task into frontend/backend/testing/docs"""
-
-        task_lower = task.lower()
-
-        if any(word in task_lower for word in ["ui", "component", "frontend", "react", "vue"]):
-            return "frontend"
-        elif any(word in task_lower for word in ["api", "endpoint", "backend", "server", "database"]):
-            return "backend"
-        elif any(word in task_lower for word in ["test", "spec", "coverage", "jest"]):
-            return "testing"
-        elif any(word in task_lower for word in ["doc", "readme", "guide", "tutorial"]):
-            return "documentation"
-        else:
-            return "frontend"  # default
-```
-
-### Pattern 3: Orchestrator-Workers (For Complex Tasks)
-
-```python
-# File: src/workflows/orchestrator.py
-
-class OrchestratorWorkflow:
-    """
-    Anthropic's "Orchestrator-Workers" pattern.
-    For complex tasks where subtasks aren't predictable.
-
-    NOTE: Only use this for truly complex, unpredictable tasks!
-    """
-
-    def __init__(self, skill_manager: SkillManager):
-        self.skill_manager = skill_manager
-
-    def execute(self, complex_task: str) -> str:
-        """
-        Step 1: Orchestrator breaks down task into subtasks
-        Step 2: Delegate to workers with relevant skills
-        Step 3: Synthesize results
-        """
-
-        # Step 1: Break down task (LLM-driven)
-        subtasks = self._breakdown_task(complex_task)
-
-        # Step 2: Assign skills and execute
-        results = []
-        for subtask in subtasks:
-            # Find relevant skill
-            relevant_skill = self.skill_manager.get_relevant_skills(
-                subtask["description"],
-                top_k=1
-            )[0]
-
-            # Load skill
-            skill = self.skill_manager.load_skill(relevant_skill)
-
-            # Execute with skill context
-            result = self._execute_with_skill(subtask, skill)
-            results.append(result)
-
-        # Step 3: Synthesize
-        return self._synthesize_results(complex_task, results)
-
-    def _breakdown_task(self, task: str) -> List[Dict]:
-        """Use LLM to break task into subtasks"""
-
-        prompt = f"""
-Break down the following task into subtasks:
-{task}
-
-Return as JSON list:
-[
-  {{"description": "...", "type": "frontend/backend/testing/docs"}},
-  ...
-]
-"""
-
-        response = self._llm_call(prompt)
-        return json.loads(response)
-
-    def _execute_with_skill(self, subtask: Dict, skill: Skill) -> str:
-        """Execute subtask with skill context"""
-
-        prompt = f"""
-Subtask: {subtask['description']}
-
-Skill Context:
-{skill.content}
-
-Complete the subtask following the skill's guidance.
-"""
-
-        return self._llm_call(prompt)
-
-    def _synthesize_results(self, original_task: str, results: List[str]) -> str:
-        """Synthesize worker results into final output"""
-
-        prompt = f"""
-Original Task: {original_task}
-
-Worker Results:
-{json.dumps(results, indent=2)}
-
-Synthesize these results into a coherent response.
-"""
-
-        return self._llm_call(prompt)
-```
-
----
-
-## Part 5: Simplified Memory (If Needed)
-
-### Do You Really Need Persistent Memory?
-
-**Anthropic's guidance:** Probably not for most use cases.
-
-**When you DO need memory:**
-- Long-running projects
-- Multi-session work
-- Learning from patterns
-
-### Simple Memory Approach (Not Complex Hierarchy)
-
-```python
-# File: src/memory/simple_memory.py
-
-class SimpleProjectMemory:
-    """
-    Simplified memory system aligned with Anthropic's principles.
-    No complex hierarchies - just project-level context.
-    """
-
-    def __init__(self, project_dir: str):
-        self.project_dir = Path(project_dir)
-        self.memory_file = self.project_dir / ".tmlpd-memory.json"
-
-        self.memory = self._load_memory()
-
-    def _load_memory(self) -> Dict:
-        """Load project memory"""
-
-        if not self.memory_file.exists():
-            return {
-                "project_context": "",
-                "successful_patterns": [],
-                "common_issues": [],
-                "decisions": []
-            }
-
-        with open(self.memory_file, "r") as f:
-            return json.load(f)
-
-    def save_memory(self):
-        """Save project memory"""
-
-        with open(self.memory_file, "w") as f:
-            json.dump(self.memory, f, indent=2)
-
-    def remember_success(self, pattern: str, context: str):
-        """Remember a successful pattern"""
-
-        self.memory["successful_patterns"].append({
-            "pattern": pattern,
-            "context": context,
-            "timestamp": datetime.now().isoformat()
-        })
-
-        self.save_memory()
-
-    def recall_similar(self, current_task: str) -> List[Dict]:
-        """Recall similar successful patterns"""
-
-        # Simple keyword matching (can upgrade to semantic search)
-        current_lower = current_task.lower()
-        similar = []
-
-        for pattern in self.memory["successful_patterns"]:
-            pattern_lower = pattern["pattern"].lower()
-
-            # Check for keyword overlap
-            if any(word in pattern_lower for word in current_lower.split()):
-                similar.append(pattern)
-
-        return similar[:5]  # Return top 5
-
-    def get_context_string(self) -> str:
-        """Get context for LLM prompt"""
-
-        parts = []
-
-        if self.memory["project_context"]:
-            parts.append(f"## Project Context\n{self.memory['project_context']}")
-
-        if self.memory["successful_patterns"]:
-            parts.append("## Successful Patterns")
-            for pattern in self.memory["successful_patterns"][-5:]:
-                parts.append(f"- {pattern['pattern']}")
-
-        return "\n\n".join(parts)
-```
-
-**This is SIMPLE** - just a JSON file with project learning. No vector databases, no complex hierarchies.
-
----
-
-## Part 6: Enhanced Checkpointing (Simplified)
-
-### From LangGraph-Inspired to Simpler Approach
-
-```python
-# File: src/state/simple_checkpoint.py
-
-class SimpleCheckpoint:
-    """
-    Simplified checkpointing following Anthropic's principles.
-    No complex versioning - just save state for recovery.
-    """
-
-    def __init__(self, project_dir: str):
-        self.checkpoint_dir = Path(project_dir) / ".tmlpd-checkpoints"
-        self.checkpoint_dir.mkdir(exist_ok=True)
-
-    def save_checkpoint(self, task_id: str, state: Dict):
-        """Save task state"""
-
-        checkpoint_file = self.checkpoint_dir / f"{task_id}.json"
-
-        with open(checkpoint_file, "w") as f:
-            json.dump({
-                "task_id": task_id,
-                "state": state,
-                "timestamp": datetime.now().isoformat()
-            }, f, indent=2)
-
-    def load_checkpoint(self, task_id: str) -> Optional[Dict]:
-        """Load task state"""
-
-        checkpoint_file = self.checkpoint_dir / f"{task_id}.json"
-
-        if not checkpoint_file.exists():
-            return None
-
-        with open(checkpoint_file, "r") as f:
-            data = json.load(f)
-            return data["state"]
-
-    def list_checkpoints(self) -> List[str]:
-        """List all available checkpoints"""
-
-        return [
-            f.stem for f in self.checkpoint_dir.glob("*.json")
-        ]
-```
-
----
-
-## Part 7: Revised YAML Config
-
-### TMLPD v2.0 Config (Skills-Based)
-
-```yaml
-# tmlpd-v2.yml
-
-deployment:
-  name: "Full-Stack Development with Skills"
-
-  # v1.0: Still works
-  agents:
-    - id: "frontend"
-      provider: "anthropic"
-      model: "claude-sonnet-4"
-      focus: "UI components"
-
-    - id: "backend"
-      provider: "openai"
-      model: "gpt-4-turbo"
-      focus: "API endpoints"
-
-  # v2.0 NEW: Skills integration
-  skills:
-    enabled: true
-    directory: "tmlpd-skills"
-
-    # Auto-discover and load relevant skills
-    auto_load: true
-
-    # Progressive disclosure
-    load_on_demand: true  # Load SKILL.md only when relevant
-
-    # Skills to use per agent
-    agent_skills:
-      frontend:
-        - "React Frontend Development"
-        - "TypeScript Best Practices"
-        - "CSS-Styled Components"
-
-      backend:
-        - "Node.js API Development"
-        - "Database Modeling"
-        - "API Testing"
-
-      testing:
-        - "Jest Testing Framework"
-        - "Test-Driven Development"
-
-  # v2.0 NEW: Workflows (instead of complex orchestration)
-  workflows:
-    enabled: true
-
-    # Routing workflow
-    routing:
-      enabled: true
-      # Route tasks to appropriate agents based on type
-
-    # Parallelization workflow (already in v1.0)
-    parallelization:
-      enabled: true
-      max_parallel_tasks: 4
-
-    # Orchestrator-workers (for complex tasks only)
-    orchestrator:
-      enabled: false  # Only enable for truly complex tasks
-      max_subtasks: 10
-
-  # v2.0 NEW: Simple project memory (no complex hierarchy)
-  memory:
-    enabled: true
-    type: "simple"  # Options: "simple" | "none"
-
-    storage:
-      type: "file"  # Options: "file" | "redis"
-
-    retention:
-      successful_patterns: 50  # Remember last 50 successful patterns
-      decisions: 20  # Remember last 20 decisions
-
-  # v2.0 NEW: Checkpointing (simplified)
-  checkpointing:
-    enabled: true
-    interval_minutes: 10
-    max_checkpoints: 5  # Keep last 5 checkpoints
-```
-
----
-
-## Part 8: Revised Implementation Roadmap
-
-### Phase 1: Agent Skills (Weeks 1-4) ⭐ HIGHEST PRIORITY
-
-**Why:** This is Anthropic's #1 recommendation for 2025.
-
-- [ ] Implement `SkillManager` class
-- [ ] Create SKILL.md format specification
-- [ ] Build progressive disclosure system
-- [ ] Create sample skills (frontend, backend, testing)
-- [ ] Integrate with existing agents
-- [ ] Add skill discovery system
-
-**Deliverables:**
-- Working Skills framework
-- 5-10 example skills
-- Documentation on creating skills
-- Integration with YAML config
-
-### Phase 2: Routing Workflow (Weeks 5-6)
-
-**Why:** Simple workflow for predictable task classification.
-
-- [ ] Implement `TaskRouter` class
-- [ ] Add task classification (LLM-based or keyword)
-- [ ] Route to relevant skills
-- [ ] Add fallback to default skill
-- [ ] Testing and validation
-
-**Deliverables:**
-- Working routing system
-- Improved task-accuracy routing
-- Performance benchmarks
-
-### Phase 3: Simple Memory (Weeks 7-8)
-
-**Why:** Project-level learning without complexity.
-
-- [ ] Implement `SimpleProjectMemory` class
-- [ ] Add JSON-based storage
-- [ ] Remember successful patterns
-- [ ] Recall similar patterns
-- [ ] Integration with agents
-
-**Deliverables:**
-- Working memory system
-- Pattern learning from past executions
-- Documentation
-
-### Phase 4: Enhanced Checkpointing (Weeks 9-10)
-
-**Why:** Better state management for reliability.
-
-- [ ] Implement `SimpleCheckpoint` class
-- [ ] Add JSON-based checkpoints
-- [ ] Automatic checkpoint saving
-- [ ] Recovery from checkpoints
-- [ ] Integration with existing system
-
-**Deliverables:**
-- Robust checkpointing
-- Recovery functionality
-- Testing
-
-### Phase 5: Orchestrator-Workers (Weeks 11-12) - OPTIONAL
-
-**Why:** Only for truly complex, unpredictable tasks.
-
-- [ ] Implement `OrchestratorWorkflow` class
-- [ ] LLM-based task breakdown
-- [ ] Skill delegation
-- [ ] Result synthesis
-- [ ] Testing and validation
-
-**Deliverables:**
-- Working orchestrator system
-- Documentation on when to use
-- Performance benchmarks
-
-**Decision Criteria:**
-Only use orchestrator-workers if:
-- Tasks are highly unpredictable
-- Can't use parallelization (subtasks unknown)
-- Need dynamic task breakdown
-- Have budget for LLM costs
-
----
-
-## Part 9: What NOT to Build (Important!)
-
-Based on Anthropic's research, **avoid building:**
-
-❌ **Complex Memory Hierarchies**
-- Don't build 3-tier memory systems
-- Don't use vector databases for simple projects
-- Don't implement episodic memory unless necessary
-- **Reason:** Most projects don't need this complexity
-
-❌ **Cross-Agent Communication Protocols**
-- Don't build message buses
-- Don't implement agent-to-agent messaging
-- Don't create shared memory spaces
-- **Reason:** Workflows + Skills are simpler and more effective
-
-❌ **Agentic RAG (Multi-Step)**
-- Don't build multi-step retrieval loops
-- Don't implement query reformulation
-- Don't add sufficiency assessment
-- **Reason:** Single-shot RAG is sufficient for most cases
-
-❌ **Complex State Management**
-- Don't build versioned state systems
-- Don't implement rollback capabilities
-- Don't create state diffing
-- **Reason:** Simple JSON checkpoints are enough
-
-❌ **Multi-Agent Orchestration Frameworks**
-- Don't build frameworks for agent coordination
-- Don't implement agent discovery protocols
-- Don't create agent registries
-- **Reason:** Workflows are predictable, simpler, and more effective
-
----
-
-## Part 10: Decision Framework
-
-### When to Use What
-
-```
-Task arrives
-    │
-    ▼
-Can single LLM call solve it?
-    │
-    ├── YES → Use single LLM + Skills ✅
-    │
-    └── NO → Are subtasks predictable?
-              │
-              ├── YES → Use WORKFLOW ✅
-              │         • Routing: Classify and route
-              │         • Parallelization: Independent tasks
-              │         • Chaining: Sequential steps
-              │         • Orchestrator-Workers: Dynamic breakdown
-              │
-              └── NO → Use simple AGENT ⚠️
-                       (Only 5% of cases)
-```
-
-### Examples
-
-**Single LLM + Skills:**
-- "Build a React login form" → Use React skill
-- "Write API tests" → Use Testing skill
-- "Create documentation" → Use Docs skill
-
-**Routing Workflow:**
-- "Fix bug in authentication" → Route to backend skill
-- "Add new UI feature" → Route to frontend skill
-
-**Parallelization Workflow:**
-- "Build CRUD app" → Frontend + Backend in parallel
-- "Test all components" → Test files in parallel
-
-**Orchestrator-Workers (Rare):**
-- "Refactor entire codebase" → Break down, delegate, synthesize
-- "Implement complex feature across 20 files" → Dynamic breakdown
-
----
-
-## Part 11: Key Takeaways
-
-### From Anthropic's Research:
-
-1. **Simplicity > Complexity**
-   - Start with single LLM call
-   - Add workflows only when needed
-   - Use agents as last resort
-
-2. **Skills > Agents**
-   - Build modular, composable skills
-   - Use progressive disclosure
-   - Share skills across projects
-
-3. **Workflows > Orchestration**
-   - Use predefined patterns
-   - Keep it predictable
-   - Test and iterate
-
-4. **Transparency > Magic**
-   - Show planning steps
-   - Make decisions explicit
-   - Debuggable system
-
-### For TMLPD v2.0:
-
-**DO:**
-- ✅ Implement Agent Skills framework
-- ✅ Add routing workflow
-- ✅ Enhance parallelization workflow
-- ✅ Simple project memory
-- ✅ Better checkpointing
-
-**DON'T:**
-- ❌ Complex memory hierarchies
-- ❌ Cross-agent communication
-- ❌ Agentic RAG (multi-step)
-- ❌ Complex state management
-- ❌ Multi-agent orchestration
-
----
-
-## Part 12: Research Sources
-
-### Primary Sources (Anthropic):
-
-1. **[Building Effective Agents](https://www.anthropic.com/research/building-effective-agents)** (Dec 19, 2024)
-   - Erik Schluntz, Barry Zhang
-   - Core principles: Simplicity, Transparency, ACI
-
-2. **[Agent Skills](https://www.anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills)** (Dec 18, 2024)
-   - Barry Zhang, Keith Lazuka, Mahesh Murag
-   - Progressive disclosure, skill format
-
-3. **[How We Build Effective Agents: Barry Zhang](https://www.youtube.com/watch?v=D7_ipDqhtwk)** (AI Engineer Summit 2025)
-   - "Don't build agents, build skills instead"
-
-4. **[LinkedIn: Building Effective Agents](https://www.linkedin.com/posts/barry-z_building-effective-agents-activity-7275576927984267264-Tpms)**
-   - Discussion and insights
-
-### Supporting Sources:
-
-5. **[Architecting Multi-Agent Systems - Andrew Ng](https://www.youtube.com/watch?v=yi7doi-QGJI)** (Hypergrowth 2025)
-   - Multi-agent patterns
-
-6. **[AI Engineer World's Fair 2025](https://www.youtube.com/playlist?list=PLcfpQ4tk2k0WzqWDdWkN2DnZOhtYI9jyI)**
-   - Latest agent engineering practices
-
-7. **[LLM Agents in Production: Why Go](https://www.youtube.com/watch?v=3mvD_Ud7HLY)**
-   - Production considerations
-
----
-
-## Conclusion
-
-The revised TMLPD v2.0 architecture:
-
-1. **Focuses on Skills** (not complex agents)
-2. **Uses Workflows** (not orchestration frameworks)
-3. **Keeps it Simple** (following Anthropic's principles)
-4. **Adds Progressive Capability** (not premature complexity)
-
-**Expected Impact:**
-- ✅ Faster implementation (simpler code)
-- ✅ Easier debugging (predictable patterns)
-- ✅ Better adoption (follows industry best practices)
-- ✅ Lower costs (fewer LLM calls)
-- ✅ More maintainable (less complexity)
-
-**Key Insight:**
-> "Success isn't about building the most sophisticated system. It's about building the RIGHT system for your needs."
-> — Anthropic, Dec 2024
-
-The "RIGHT" system for TMLPD is **Skills + Workflows**, not complex multi-agent orchestration.
-
----
-
-**Next Steps:**
-1. Review and validate this approach
-2. Begin Phase 1: Agent Skills implementation
-3. Create sample skills for common tasks
-4. Test with real projects
-5. Gather feedback and iterate